Files
rc_yacht/docs/physical_simulation_plan.md

9.4 KiB

Physical Simulation Plan

Goal: Replace the current manually calculated rudder sweep with a solver-driven simulation in which the macro commands only the servo angle and the physics engine moves the linkage and rudder automatically.

Architecture: FreeCAD remains the CAD source and visualizer. Project Chrono Multibody solves rigid-body motion, joints, motors, contacts, friction, mass, and inertia. Chrono FSI is added later for water and fluid-structure interaction. A bridge transfers the commanded servo angle to Chrono and returns body transforms and diagnostic forces to FreeCAD.

Target repository: org1/rc_yacht


Scope and acceptance criteria

The first milestone is the dry rudder mechanism, not the complete yacht hydrodynamics.

The first milestone must prove:

  • the FreeCAD macro sends only a servo target angle;
  • the servo motor joint is the only commanded degree of freedom;
  • the physics solver moves the horn, pushrod, tiller, rudder stock, and rudder;
  • the hull, servo mount, ESP32 tray, and electronics remain fixed;
  • the pushrod remains connected at both ends;
  • revolute-joint limits are enforced;
  • collision detection reports no forbidden intersections across the servo range;
  • returned transforms can be displayed in the remote FreeCAD document;
  • the result is explicitly classified as solver-driven rigid-body simulation, not as the existing placement sweep.

The later water milestone must additionally prove that Chrono FSI applies water forces to the hull and submerged appendages with a documented fluid domain, resolution, timestep, material model, and convergence checks.


Phase 1: Freeze and inspect the CAD interface

  1. Treat the current RudderMechanism group as the CAD interface.
  2. Record the coordinate system, units, rotation axes, attachment points, and neutral placements.
  3. Separate visual CAD shapes from solver collision shapes.
  4. Define the fixed bodies:
    • hull;
    • rudder servo housing and mount;
    • ESP32 tray and board envelope;
    • other structural parts that must not move.
  5. Define the moving bodies:
    • servo horn;
    • pushrod;
    • tiller;
    • rudder stock;
    • rudder.
  6. Add a machine-readable mechanism specification under parameters/ containing body IDs, joint IDs, axes, attachment points, limits, masses, and inertias.

Validation:

  • all body IDs resolve to existing FreeCAD objects;
  • every joint has explicit frames on both bodies;
  • the neutral configuration matches the validated CAD model;
  • no body is silently both fixed and dynamic.

Likely files:

  • parameters/design_parameters.json;
  • new parameters/rudder_mechanism.json;
  • MiniMaxHull.FCStd;
  • reports/virtual_simulation_report.json.

Phase 2: Build a Chrono Multibody dry mechanism

  1. Select the Chrono version and Python/C++ API available on the simulation host.
  2. Build fixed and dynamic rigid bodies from simplified collision geometry.
  3. Add a motorized revolute joint for the servo horn.
  4. Add a revolute joint for the rudder stock.
  5. Add the pushrod as a rigid body with appropriate endpoint constraints.
  6. Add the tiller and horn attachment constraints.
  7. Set masses, centers of mass, inertias, gravity, joint limits, solver tolerances, and timestep.
  8. Define the servo command as a target angle or target position only.
  9. Record solver positions, velocities, constraint errors, reaction forces, and collision events at every timestep.

Validation:

  • at servo angle zero, the solver configuration matches the CAD neutral pose;
  • the solver can reach both mechanical endpoints;
  • constraint errors remain below a defined tolerance;
  • the pushrod length remains within the declared tolerance;
  • fixed bodies have zero velocity and zero displacement;
  • no forbidden collision occurs.

Likely files:

  • new simulation/chrono_rudder.py or simulation/chrono_rudder.cpp;
  • new simulation/chrono_model.py;
  • new simulation/requirements or build configuration;
  • new solver diagnostics under reports/.

Phase 3: Connect the solver to FreeCAD

  1. Define a small bridge protocol carrying:
    • model identifier;
    • servo target angle;
    • simulation timestep or number of steps;
    • returned body transforms;
    • joint errors;
    • reaction forces;
    • collision results;
    • solver status.
  2. Keep the physics process independent from the FreeCAD GUI process.
  3. Use the existing remote FreeCAD XML-RPC access only for CAD inspection and transform application, unless a direct local bridge is proven more reliable.
  4. Replace the current manual Placement loop with a bridge client that sends the servo angle.
  5. Apply only solver-returned transforms to moving FreeCAD objects.
  6. Keep static FreeCAD objects unchanged and verify their placements before and after each step.
  7. Add a dry-run mode that uses a deterministic mock solver for bridge testing.

Validation:

  • changing the macro input changes only the servo command;
  • the FreeCAD macro does not calculate the rudder angle from the servo angle;
  • every moving transform comes from solver output;
  • a disconnected or failed solver produces FAIL, not a plausible-looking CAD motion;
  • repeated runs with the same initial state and command produce reproducible results.

Likely files:

  • scripts/RudderMotionSweep.FCMacro;
  • new scripts/ChronoRudderBridge.FCMacro;
  • new simulation/bridge_protocol.py;
  • reports/virtual_simulation_report.json.

Phase 4: Add collision and contact qualification

  1. Use simplified collision shapes for solver stability.
  2. Use the detailed FreeCAD B-rep shapes for post-step geometric intersection checks.
  3. Check collisions at every solver step, not only at endpoint angles.
  4. Distinguish intended interfaces from forbidden collisions.
  5. Record minimum clearances and maximum intersection volumes.
  6. Test the mechanism with nominal and perturbed joint geometry.
  7. Test servo range, hard-stop range, and out-of-range commands.

Acceptance:

  • forbidden collision volume is zero or below a documented numerical tolerance;
  • intended interfaces are listed separately;
  • joint limits prevent impossible configurations;
  • the mechanism fails safely when constraints cannot converge.

Phase 5: Add Chrono FSI for the water model

Chrono FSI is a later layer, not a replacement for Chrono Multibody. The FSI module must be evaluated using the actual Chrono build and backend available on the simulation host.

  1. Select the FSI backend and document whether the model uses SPH or TDPF.
  2. Create a fluid domain with documented dimensions and resolution.
  3. Define water density, viscosity, gravity, free-surface level, and initial conditions.
  4. Couple the hull and appendages to the fluid solver.
  5. Include the mass, inertia, center of gravity, and ballast configuration from the CAD qualification model.
  6. Start with a static buoyancy test.
  7. Add controlled rudder motion in still water.
  8. Add prescribed wind and wave inputs only after the static and still-water tests converge.
  9. Compare buoyancy, draft, pitch, roll, and rudder forces with the existing preliminary estimates.
  10. Record timestep, particle spacing or grid resolution, boundary conditions, convergence criteria, and computational cost.

FSI acceptance is not established by a running animation. It requires mesh/particle and timestep sensitivity evidence plus comparison to a known static or analytical result.

Likely files:

  • new simulation/chrono_fsi_hydrostatics.py or C++ equivalent;
  • parameters/design_parameters.json;
  • new parameters/fsi_parameters.json;
  • reports/virtual_simulation_report.json;
  • new docs/chrono_fsi_validation.md.

Phase 6: Verification and reporting

Run the following checks before classifying the result as qualified:

python3 -m json.tool reports/virtual_simulation_report.json

git diff --check

FreeCAD geometry validation
Chrono solver convergence validation
Joint-limit validation
Pushrod-length validation
Fixed-body displacement validation
Forbidden-collision sweep
Repeatability run

Report separate statuses:

cad_geometry
kinematic_reference
chrono_multibody
bridge
contact_and_collision
chrono_fsi
physical_validation

The overall status must remain PASS_WITH_REVIEW until the solver and FSI results are independently validated against physical measurements.


Risks and decisions

  • Chrono FSI is a separate solver module, not a FreeCAD workbench button.
  • FSI does not automatically create the servo linkage; Multibody joints must be defined first.
  • A visually plausible animation is not evidence of physical correctness.
  • FreeCAD B-rep geometry should not be used blindly as high-resolution collision geometry.
  • The current SG90 model is an envelope, not a validated motor torque model.
  • The current water and wind calculations are preliminary and cannot serve as full FSI validation.
  • The remote FreeCAD host may not have Chrono, its Python bindings, or the required FSI backend installed.
  • The first implementation should therefore be a dry Chrono Multibody proof before any FSI installation or water simulation.

Definition of done

The plan is complete only when:

  1. a reproducible Chrono Multibody environment is available;
  2. the servo angle is the only command issued by the FreeCAD macro;
  3. Chrono moves the remaining mechanism bodies through constraints;
  4. FreeCAD displays the solver transforms;
  5. joint errors, contacts, collisions, and fixed-body invariants are recorded;
  6. Chrono FSI is separately enabled and validated for the water phase;
  7. all limitations and numerical parameters are recorded in the repository report.