Forward Dynamics Setup Files and XML Tags

The topics covered in this section include:

Setup File and XML Tag Definitions

These sample XML files are from the examples/Gait2354_Simbody directory and are part of the OpenSim distribution.

Example: XML file for the setup file for forward dynamics

<?xml version="1.0" encoding="UTF-8"?> 
<OpenSimDocument Version="20302"> 
<ForwardTool name="subject01_walk1"> 

  <!-- OpenSim Model --> 
  <model_file> subject01_adjusted.osim </model_file> 
  <force_set_files> gait2354_CMC_Actuators.xml </force_set_files> 
  <replace_force_set> false </replace_force_set>

  <!-- Times over which to run forward --> 
  <initial_time> 0.80 </initial_time> 
  <final_time> 1.18 </final_time> 

  <!-- Integrator Settings --> 
  <maximum_number_of_integrator_steps> 30000 </maximum_number_of_integrator_steps> 
  <maximum_integrator_step_size> 0.00025 </maximum_integrator_step_size> 
  <integrator_error_tolerance> 5e-006 </integrator_error_tolerance> 
  <use_specified_dt> true </use_specified_dt> 

  <!--Analyses and Results --> 
  <results_directory> ./ResultsForward </results_directory> 
  <output_precision> 20 </output_precision> 
  <AnalysisSet name="Analyses"> 
    <objects> 
      <Kinematics name="Kinematics"> 
         <on> true </on> 
        <step_interval> 10 </step_interval> 
        <in_degrees> true </in_degrees> 
      </Kinematics> 

      <Actuation name="Actuation"> 
        <on> true </on> 
        <step_interval> 10 </step_interval> 
        <in_degrees> true </in_degrees> 
      </Actuation> 

      <BodyKinematics name="BodyKinematics"> 
        <on> true </on> 
        <step_interval> 10 </step_interval> 
        <in_degrees> true </in_degrees> 
      </BodyKinematics> 
    </objects> 
  </AnalysisSet> 


  <!-- Initial states and controls --> 
  <states_file> ResultsCMC/subject01_walk1_states.sto</states_file> 
  <ControllerSet name="Controllers"> 
    <objects> 
      <ControlSetController name=""> 
        <!--A list of actuators that this controller will control. The keyword ALL indicates the controller will control all the acuators in the model--> 
        <actuator_list> </actuator_list> 
        <!--Flag (true or false) indicating whether or not the controller is enabled (ON) should--> 
        <enable_controller> ALL </enable_controller> 
        <!--XML file containing the controls for the controlSet.--> 
        <controls_file> ResultsCMC/subject01_walk1_controls.xml </controls_file> 
      </ControlSetController> 
    </objects> 
  </ControllerSet> 
 
  <!-- External Loads --> 
  <external_loads_file> subject01_walk1.xml</external_loads_file> 
 
</ForwardTool> 
</OpenSimDocument>

Specifying an Execution Name

The properties for the Forward Dynamics Tool are enclosed inside the opening and closing tags <ForwardTool> and </ForwardTool>. The name attribute name="subject01_walk1" specifies the execution name. The names of results files generated will be prefixed with this name.

Specifying the Model

If using controls from CMC, the model specification for the Forward Dynamics Tool must match. Visit Computed Muscle Control for more information.

Specifying Initial and Final Times

The properties <initial_time> and <final_time> specify the time interval over which a forward simulation is to be run. As explained in How Forward Dynamics Works, the initial time may be adjusted to the nearest time for which state values are available, as these state values (typically from CMC) will be used to initialize the forward simulation.

Specifying Integrator Settings

If using controls from CMC, as explained in How Forward Dynamics Works, setting <use_specified_dt> to true (which is recommended) ensures that the Forward Dynamics Tool uses the same integrator time steps as that for CMC. It does this by matching the time steps found in the <initial_states_file>. In this case, the values set for the remaining properties (<maximum_number_of_integrator_steps>, <maximum_integrator_step_size>, <integrator_error_tolerance>, and <integrator_fine_ tolerance>) are ignored. If <use_specified_dt> is set to false then the integrator properties are used to determine the adaptive time step sizes (see Chapter 4 on CMC chapter for how these are used).

Specifying Analyses and Results

Any number of available analyses can be added to a forward dynamics run. To get a listing of available analyses, run the command forward -PropertyInfo.
There are several properties associated with the analyses results. <results_directory> specifies the directory where results should be written. <output_precision> specifies how many decimal places should be used when writing results. A value of 20 is sufficient to avoid round-off error when reading results back in during other steps in the workflow. <step_interval> specifies how often to record results during numerical integration. A value of 10 means record results every 10 integration steps.

Specifying Initial States and Controls

Running a forward simulation requires that the states be set to initial values at the beginning of the simulation, and that the actuator control values (e.g., muscle excitations) are updated throughout the simulation. Both of these are optional with default behavior as explained in Getting Started with Forward Dynamics. Often, the initial states and the control values used to drive the forward simulation are those computed during the CMC step, in these cases the <initial_states_file> property should be set to the states output from CMC (an .sto storage file), and <controls_file> should be set to the controls output from CMC (the .xml file, not the controls .sto file that is also written by CMC). The <initial_states_file> is used to (a) determine a valid initial time for the forward simulation (it has to coincide with a time for which state values are available), (b) supply the initial state values, and (c) if <use_specified_dt> is set to true, then it is also used to determine the integration time intervals used by CMC (in order to match CMC results as much as possible).

Specifying External Loads

The file containing the external loads applied to the model during a simulation is specified using the property <external_loads_file>. Please refer to section Forward Dynamics Setup Files and XML Tags for details about the contents of this file.