(procedures_page)=
# Program skeletons




(skeleton_serialchain_sec)=
## Serial-chain/Tree multibody system dynamics simulation

The following is an outline of the major steps involved in setting up a
time-domain simulation for a multibody system with  serial-chain or tree
topology.

1. Create a {{ framectrcls }} instance. See {ref}`recipe_frames_sec` recipes section.

1. Create a {{ mbodycls }} system. 
    1. See {ref}`recipe_rigid_body_sec` recipes section
  for options on creating rigid multibody systems manually,
  procedurally, or from URDF, {{ datastructcls }} etc files. 
    1. See {ref}`recipe_flex_body_sec` recipes section for adding flexible bodies to the  multibody systems.
    
1. Create a  {{ spcls }} instance. See {ref}`recipe_statepropagator_sec` recipes section.
    1.  Use the {py:attr}`TREE_DYNAMICS <Karana.Dynamics.MMSolverType.TREE_DYNAMICS>` solver type
    
1. Create {{ kmodelcls }} instances to apply forces and poll the dynamics. See {ref}`recipe_kmodels_register_sec` recipes section.

1. Set {{ spcls }} initial state. See {ref}`recipe_spstate_sec` recipes section.

1. **[OPTIONAL]** Analysis aids 
    1. Set up 3D graphics visualization. See {ref}`recipe_graphics_sec`.
    1. Set up plotting.  See {ref}`recipe_plotting_sec` recipes section.
    1. Set up data logging.  See {ref}`recipe_datalogging_sec` recipes section.
    
1. **[OPTIONAL]** Set up simulation {{ teventscls }}.  See {ref}`recipe_events_sec` recipes section.

1. Advance simulation time by calling either {py:meth}`advanceTo() <Karana.Dynamics.StatePropagator.advanceTo>` {py:meth} or {py:meth}`advanceBy() <Karana.Dynamics.StatePropagator.advanceBy>` methods of the {{ spcls }} instance.

1. **[OPTIONAL]** Clean up and shutdown the simulation.

1. **[OPTIONAL]** Process data logged output. See {ref}`recipe_datalogging_sec` recipes section.
    
    
(skeleton_closedchain_sec)=
## Closed-chain multibody dynamics simulation

The following is an outline of the major steps involved in setting up a
time-domain simulation for a multibody system with closed-chain
topology, i.e. systems with bilateral constraints between bodies.  The
steps are very similar to those for {ref}`skeleton_serialchain_sec`
section. The differences are highlighted <span class="emphasis">like so</span>.

1. Create a {{ framectrcls }} instance. See {ref}`recipe_frames_sec` recipes section.

1. Create a {{ mbodycls }} system. 
    1. See {ref}`recipe_rigid_body_sec` recipes section
  for options on creating rigid multibody systems manually,
  procedurally, or from URDF, {{ datastructcls }} etc files. 
    1. See {ref}`recipe_flex_body_sec` recipes section for adding flexible bodies to the  multibody systems

1. **[OPTIONAL]** <span class="emphasis">Add any additional {{ biconstraintbasecls }}
   between bodies. See the {ref}`recipe_biconstraints_sec` recipes
   section. This step may not be needed if the model loaded in the
   previous step already sets up the bilateral constraints.</span>

1. **[OPTIONAL]** <span class="emphasis">Do static kinematics
   analysis of the closed-chain multibody system. See the
   {ref}`recipe_pose_constraint_sec` and
   {ref}`recipe_velocity_constraint_sec` recipe sections.</span>  
   <!-- TODO: Add stuff about TUI when it is ready -->

1. Create a  {{ spcls }} instance. See {ref}`recipe_statepropagator_sec` recipes section.
    1.  <span class="emphasis">Use the {py:attr}`TREE_AUGMENTED_DYNAMICS <Karana.Dynamics.MMSolverType.TREE_AUGMENTED_DYNAMICS>` solver type</span>

1. Create {{ kmodelcls }} instances to apply forces and poll the dynamics.   See {ref}`recipe_kmodels_register_sec` recipes section. <!-- TODO: Add comment about using Projection model -->

1. Set {{ spcls }} initial state. See {ref}`recipe_spstate_sec` recipes section.
    1. <span class="emphasis">It is important that the multibody initial state satisfy the {{
       biconstraintbasecls }} at both the pose and velocity levels. You can check the initial errors using the {py:meth}`poseError() <Karana.Dynamics.SubGraph.poseError>` and {py:meth}`velError() <Karana.Dynamics.SubGraph.velError>` methods.</span> discussed in the
   {ref}`recipe_pose_constraint_sec` and
   {ref}`recipe_velocity_constraint_sec` recipe sections.</span>

1. **[OPTIONAL]** Analysis aids 
    1. Set up 3D graphics visualization. See {ref}`recipe_graphics_sec`.
    1. Set up plotting.  See {ref}`recipe_plotting_sec` recipes section.
    1. Set up data logging.  See {ref}`recipe_datalogging_sec` recipes section.

1. **[OPTIONAL]** Set up simulation {{ teventscls }}.  See {ref}`recipe_events_sec` recipes section.

1. Advance simulation time by calling either {py:meth}`advanceTo() <Karana.Dynamics.StatePropagator.advanceTo>`  or {py:meth}`advanceBy() <Karana.Dynamics.StatePropagator.advanceBy>` methods of the {{ spcls }} instance.

1. **[OPTIONAL]** Clean up and shutdown the simulation.

1. **[OPTIONAL]** Process data logged output. See {ref}`recipe_datalogging_sec` recipes section.



(skeleton_contact_sec)=   
## Contact/Collision dynamics simulation

The following is an outline of the major steps involved in setting up a
time-domain simulation with contact and collision dynamics for a
rigid-body multibody system with tree or closed-chain topology.  The steps are very
similar to those for {ref}`skeleton_serialchain_sec` and
{ref}`skeleton_closedchain_sec` sections. The differences are
highlighted in <span class="emphasis">red</span>.



1. Create a {{ framectrcls }} instance. See {ref}`recipe_frames_sec` recipes section.

1. Create a {{ mbodycls }} system. 
    1. See {ref}`recipe_rigid_body_sec` recipes section
  for options on creating rigid multibody systems manually,
  procedurally, or from URDF, {{ datastructcls }} etc files. 

1. <span class="emphasis"> Set up collision data. See
   {ref}`collision_dynamics_sec` in the usage guide.</span>
    1. <span class="emphasis">instantiate a collision scene </span>
    1. <span class="emphasis">add collision geometries for the bodies.  </span>
    1. <span class="emphasis">set up collision filters. </span>
    1. <span class="emphasis">add default or custom contact force models
    </span>
    
1. Create a  {{ spcls }} instance. See {ref}`recipe_statepropagator_sec` recipes section.
    
1. Create {{ kmodelcls }} instances to apply forces and poll the dynamics.   See {ref}`recipe_kmodels_register_sec` recipes section.

1. Set {{ spcls }} initial state. See {ref}`recipe_spstate_sec` recipes section.

1. **[OPTIONAL]** Analysis aids 
    1. Set up 3D graphics visualization. See {ref}`recipe_graphics_sec`.
    1. Set up plotting.  See {ref}`recipe_plotting_sec` recipes section.
    1. Set up data logging.  See {ref}`recipe_datalogging_sec` recipes section.
    
1. **[OPTIONAL]** Set up simulation {{ teventscls }}.  See {ref}`recipe_events_sec` recipes section.

1. Advance simulation time by calling either {py:meth}`advanceTo() <Karana.Dynamics.StatePropagator.advanceTo>` {py:meth} or {py:meth}`advanceBy() <Karana.Dynamics.StatePropagator.advanceBy>` methods of the {{ spcls }} instance.

1. **[OPTIONAL]** Clean up and shutdown the simulation.

1. **[OPTIONAL]** Process data logged output. See {ref}`recipe_datalogging_sec` recipes section.
    

## Closed-loop simulations
- set up platform dynamics simulation (using above approaches)
- pick option for the external s/w - wrapped in a KModel, IPC (e.g., ROS)
- define input/output interfaces for closing the loop



<!--
## static/kinematics analysis of closed loop system
- create frame container
- create  mbody systems  - options manually, procedurally, from
  urdf, DS file
- set mbody state
- call kinematicsAnalysis
    -->
    
## Robotics system analysis
- create frame container
- create  mbody systems  - options manually, procedurally, from
- FK, IK, Jacobian, CM , overall inertia, gravity compensation,
   computed torque, mass matrix, mass matrix inverse, 

## Embedded model manager in control stack
- create frame container
- create  mbody systems  - options manually, procedurally, from
- 

## Training simulator
- create frame container
- create  mbody systems  - options manually, procedurally, from
- set up gymnasium


## Flexible body dynamics simulation

- FEMBridge use
- State equilibration
- State space model generation
- Stress recovery process