plan-fabricsOptimizeToCustomRobot

Prompt file imported from vinhbui720/fabric_optimize (.github/prompts/plan-fabricsOptimizeToCustomRobot.prompt.md). Copyright stays with the author.

Plan: Build Your Own Fabrics Pipeline

Create a staged route from mathematical intuition (NumPy/CasADi plots) to a custom robot simulation using the existing Fabrics architecture. The plan is structured so each phase has a clear acceptance gate before moving on.

Steps

1. Phase 1 - Foundations and Equation Validation.
2. Run and inspect tutorial/definition_5_1.py, tutorial/proposition_4_22.py, and tutorial/section_10_3.py to lock in the three core equations: geometry xddot + h = 0, Euler-Lagrange spec M xddot + f = 0, and speed-control terms (alpha, beta, eta).
3. Reproduce one minimal 2D script from scratch (outside framework internals) with CasADi to validate each term independently: geometry only, geometry+attractor, geometry+attractor+damper.
4. Acceptance gate: behavior matches theory (convergence, obstacle bending, damping reduces oscillation).
5. Phase 2 - Pullback and Composition Mechanics.
6. Trace phi, J, Jdot, M, f, h, alpha through fabrics/diffGeometry/diffMap.py, fabrics/diffGeometry/spec.py, fabrics/diffGeometry/geometry.py, fabrics/diffGeometry/energy.py, and fabrics/diffGeometry/energized_geometry.py.
7. Build your own symbol-to-runtime map for compute_action arguments, including dynamic reference terms: x_ref, xdot_ref, xddot_ref.
8. Acceptance gate: you can explain one full path from task leaf definition to final acceleration action.
9. Phase 3 - Baseline Planner on Simple Robot.
10. Use examples/point_robot_urdf.py as the baseline template with one static goal + one obstacle.
11. Tune key parameters: collision_geometry, collision_finsler, attractor_potential, attractor_metric, damper_beta, damper_eta.
12. Add moving obstacles only after static behavior is stable, using examples/point_robot_dynamic.py.
13. Acceptance gate: stable horizon rollout, no NaNs/explosions, consistent obstacle clearance.
14. Phase 4 - Path Following (Dynamic Goal).
15. Switch from staticSubGoal to analyticSubGoal first (then optional splineSubGoal) using examples/panda_trajectory_following.py pattern.
16. Update sensor goal mask to include velocity and pass x_ref_goal_0_leaf, xdot_ref_goal_0_leaf, xddot_ref_goal_0_leaf, weight_goal_0.
17. Validate tracking before adding extra complexity.
18. Acceptance gate: bounded tracking lag on curved paths.
19. Phase 5 - Non-Holonomic Mobile Base.
20. Start from examples/boxer.py or examples/albert.py with NonHolonomicParameterizedFabricPlanner.
21. Merge dynamic goal/path-following pattern and keep non-holonomic inputs (qudot, m_rot, m_base_x, m_base_y).
22. Tune l_offset, damping, and mass terms for smooth steering and heading stability.
23. Acceptance gate: path following + obstacle avoidance without sustained heading oscillations.
24. Phase 6 - Build Your Own Scenario.
25. Define final robot scope: URDF, collision links, goal/path format, action/state mode.
26. Create a custom example in examples/ by cloning the closest template and replacing robot/FK/leaf arguments incrementally.
27. Add instrumentation: tracking error, minimum obstacle distance, action norm, convergence time.
28. Acceptance gate: repeatable runs meeting your target metrics.
29. Phase 7 - Verification and Hardening.
30. Add short-horizon tests in examples/test_examples.py (and planner unit tests if needed).
31. Stress test with sharper curvature, tighter obstacle corridors, perturbed initial states.
32. Validate serialization/export if needed.
33. Final gate: short automated test pass + visual validation + reproducible parameter set.

Relevant files

• /home/vinbui/HCMUT/fabric/fabrics/tutorial/definition_5_1.py
• /home/vinbui/HCMUT/fabric/fabrics/tutorial/proposition_4_22.py
• /home/vinbui/HCMUT/fabric/fabrics/tutorial/section_10_3.py
• /home/vinbui/HCMUT/fabric/fabrics/tutorial/casadi_class.py
• /home/vinbui/HCMUT/fabric/fabrics/fabrics/diffGeometry/diffMap.py
• /home/vinbui/HCMUT/fabric/fabrics/fabrics/diffGeometry/spec.py
• /home/vinbui/HCMUT/fabric/fabrics/fabrics/diffGeometry/geometry.py
• /home/vinbui/HCMUT/fabric/fabrics/fabrics/diffGeometry/energy.py
• /home/vinbui/HCMUT/fabric/fabrics/fabrics/diffGeometry/energized_geometry.py
• /home/vinbui/HCMUT/fabric/fabrics/fabrics/planner/parameterized_planner.py
• /home/vinbui/HCMUT/fabric/fabrics/fabrics/planner/non_holonomic_parameterized_planner.py
• /home/vinbui/HCMUT/fabric/fabrics/examples/point_robot_urdf.py
• /home/vinbui/HCMUT/fabric/fabrics/examples/point_robot_dynamic.py
• /home/vinbui/HCMUT/fabric/fabrics/examples/panda_trajectory_following.py
• /home/vinbui/HCMUT/fabric/fabrics/examples/boxer.py
• /home/vinbui/HCMUT/fabric/fabrics/examples/albert.py
• /home/vinbui/HCMUT/fabric/fabrics/examples/test_examples.py

Verification

1. Enforce each phase acceptance gate before advancing.
2. Do non-render short rollouts first, then render checks.
3. Track 3 metrics every run: path error, minimum obstacle distance, action norm.
4. Confirm no planner guardrail clipping due to tiny/huge action magnitudes.
5. Add at least one automated short test for your custom scenario.

Decisions

• Included: full concept-to-custom-sim path inside this repo.
• Excluded: ROS/hardware deployment for now.
• Recommended progression: point robot first, then non-holonomic, then your final custom robot.
• Recommended dynamic goal mode: analyticSubGoal first, splineSubGoal after stable baseline.