Go to start of banner

# Settings Files and XML Tag Definitions

The settings files are XML files whose tags specify properties to be used by OpenSim for performing the residual reduction. The tags used for each type of settings file are defined in the following sections:

## RRA Setup File

A setup file provides the high-level information required for the first pass of the residual reduction algorithm. It references three other files: an actuators file, the constraints file, and a tasks file. All of these files are explained in detail below. An example of the setup file is given in Example 1 below.

In the setup file, the property settings for RRA are enclosed in <RRATool>. The types of properties listed in the XML setup files for RRA include model files, actuator and control information, integration parameters, kinematics and ground reaction data files, tracking information, optimization parameters, and output information.

### Model Files

The <model_file> property specifies the name of the .osim file to load. In RRA, the value of this property in the above example is subject01_simbody.osim, the .osim file representing the dynamic subject-specific model. The output of RRA <output_model_file> in Example 1 is subject01_simbody_adjusted.osim.

### Integration Parameters

The <maximum_number_of_integrator_steps> property indicates the maximum number of steps RRA during an entire run before termination. During each integration, the maximum number of seconds that may elapse is specified by <maximum_integrator_step_size>. Increasing the <integrator_error_tolerance> will decrease the integrator step size, while decreasing the <integrator_fine_tolerance> will increase the integrator step size. Other simulation parameters like <initial_time>, <final_time>, and <cmc_time_window> are described earlier in the Simulation section for RRA (How RRA Works).

### Tracking Information

The coordinates that should be followed by the model during RRA are specified within a file, indicated by the <task_set_file> and </task_set_file> tags. In Example 1, that file is gait2354_RRA_Tasks.xml. See RRA Tasks File for information about the property tags used within a task file.

### Actuator and Control Information

A model has some set of actuators that can apply forces to its skeleton. For example, the dynamic subject-specific model in Example 1 has 54 muscles as its default set of actuators. These actuators can be modified using the tag <replace_force_set>. If the value of the property <replace_force_set> is true, then the actuators specified in any file listed under the property <force_set_files> will replace the corresponding model's actuators. If the value of <replace_force_set> is false, then the actuators specified in the files listed under <force_set_files> will be added to the model's existing actuator set. Details about the actuators file are given in RRA Actuators File below.

The <constraints_file> property specifies the name of an XML file containing minimum and maximum values for the control values for the model's actuators. An actuator's actual range of values is equal to the range from the minimum to maximum control values times its optimal force. The maximum and minimum control values, as well as the optimal force, are specified in the constraints file. See Example 3 below for more information about the constraints file and the best method for altering an actuator's range.

### Kinematics and Ground Reaction Data Files

RRA will attempt to make the model follow the kinematics (generalized coordinates as functions of time) specified in the <desired_kinematics_file>, which should be a motion (.mot) or a storage (.sto) file.
Prior to simulation, the kinematics to be tracked by RRA are low-pass filtered at a frequency specified by the tag <lowpass_cutoff_frequency>. The value of this frequency is assumed to be in Hertz (Hz). A negative value for this property leads to no filtering. The default value is –1.0, i.e., no filtering.

There can be multiple sets of ground reaction forces for different locations on the body. These are specified in the file identified by the <external_loads_file> tags. The external loads .xml file specifies the source file for input forces and to which location and body the forces are to be applied. See Inverse Dynamics for additional details for applying any number of external loads as point forces and/or body torques.

### Optimization Parameters

The target consists of an objective function (J) that is a weighted (w) sum of squared actuator controls (x) plus the sum of desired acceleration ($//$) errors:

The first summation minimizes and distributes loads across actuators and the second drives the model accelerations ($//$) toward the desired accelerations ($//$).

The behavior of the optimizer is controlled using three tags: <optimizer_derivative_dx>, <optimizer_convergence_criterion>, <optimizer_max_iterations>.

The <optimizer_derivative_dx> tag determines the perturbation size used by the optimizer to compute numerical derivatives. Valid values for <optimizer_derivative_dx> range from 1.0e-4 to 1.0e-8.

The <optimizer_convergence_criterion> tag specifies the depth of optimization required for convergence. The smaller the value of this property, the better the solution is. But decreasing this value also can increase computation time.

The <optimizer_max_iterations> property limits the number of iterations the optimizer can take at each time step in searching for an optimal solution.

The optimizer can be set to print out details of what it is doing by using the <optimizer_print_level> tag. Valid values for this property are 0, 1, 2, or 3, where a value of 0 means no printing, a value of 3 means detailed printing, and 1 and 2 represent levels in-between.

### Output

Results printed by RRA will be output into the directory specified by the tag <results_directory>. The name of the file that is created is determined by the <output_model_file> tag. By default, the name of the <output_model_file> is adjusted_model.osim. The precision of RRA output is specified in the property <output_precision>, which is 8 by default.

If the <adjust_com_to_reduce_residuals> property is true, the file that is output contains data where the mass center of the body is specified by the tag <adjusted_com_body>. The <adjusted_com_body> should normally be the heaviest segment in the model. For the gait model, torso is usually the best choice. The body name must correspond to the body name in the navigator (or model file). The average residuals computed during RRA will be printed out to a file in the <results_directory>.

## RRA Actuators File

The RRA actuators file uses the <ForceSet> and </ForceSet>tags to describe actuators that replace the model's actuators. Example 2 below shows an actuator file for RRA (gait2354_RRA_Actuators.xml). Forces are specified in newtons and torques in newton-meters.

Each generalized coordinate task contains the following properties: <on>, <wrt_body>, <express_body>, <active>, <weight>, <kp>, <kv>, <ka>, <r0>, <r1>, <r2>, <coordinate>, and <limit>.
<on> indicates whether or not the coordinate(s) specified in the task should be followed or not. The body to which the task is applied is specified using the tags <wrt_body> and </wrt_body>. The reference frame which is used to specify the coordinates to follow is determined by the property <express_body>, which refers to a specific body. For example, if a point on body 2 is to be followed, and the point's coordinates are expressed in the frame of body 1, then <wrt_body> would be 2 and <express_body> would be 1.

The <active> property is an array of three flags, each flag indicating whether a component of a task is active. For example, the trajectory of a point in space could have three components (x, y, z). This allows the tracking of each coordinate of the point to be made active (true) or inactive (false). The definition of a flag depends on the type of coordinate: <CMC_Joint> or <CMC_Point>. For a task that tracks a joint coordinate (like all tasks in Example 34 below), only the first of the three flags is valid.

The tags <kp>, <kv>, < ka> are parameters in the proportional-derivative (PD) control law used to compute desired accelerations for tracking the experimental kinematics computed by the inverse kinematics (IK) solver (see Inverse Kinematics). This control law contains a position error feedback gain (stiffness) and a velocity error feedback gain (damping). The stiffness for each tracked coordinate is specified within the <kp> property, while the damping is specified within the <kv> property. An acceleration feed-forward gain is also allowed, but in the above example, this gain is set to 1, i.e., there is no acceleration gain. The acceleration gain is specified within the <ka> property.

The <r0>, <r1>, and <r2> properties indicate direction vectors for the three components of a task, respectively. These properties are not used for tasks representing tracking of a single joint coordinate, such as the tasks in Example 4 below.

The name of the coordinate to be tracked is specified within the property <coordinate>. The error limit on the tracking accuracy for a coordinate is specified within the <limit> property. If the tracking errors approach this limit during simulation, the weighting for this coordinate is increased.

## RRA Example Files

### Example 1: XML file for the setup file for RRA

subject01_Setup_RRA.xml
<?xml version="1.0" encoding="UTF-8"?>
<OpenSimDocument Version="20300">

<RRATool name="subject01_walk1_RRA">
<!--Name of the .osim file used to construct a model.-->
<model_file> subject01_simbody.osim </model_file>

<!--Replace the model's force set with sets specified in <force_set_files>? If false, the force set is appended to.-->
<replace_force_set> true </replace_force_set>

<!--List of xml files used to construct an force set for the model.-->
<force_set_files> gait2354_RRA_Actuators.xml </force_set_files>

<!--Directory used for writing results.-->
<results_directory> ResultsRRA/ </results_directory>

<!--Output precision. It is 20 by default.-->
<output_precision> 8 </output_precision>

<!--Initial time for the simulation.-->
<initial_time> 0.75000000 </initial_time>

<!--Final time for the simulation.-->
<final_time> 0.78000000 </final_time>

<!--Flag indicating whether or not to compute equilibrium values for states other than the coordinates or speeds.
For example, equilibrium muscle fiber lengths or muscle forces.-->
<solve_for_equilibrium_for_auxiliary_states> false </solve_for_equilibrium_for_auxiliary_states>

<!--Maximum number of integrator steps.-->
<maximum_number_of_integrator_steps> 20000 </maximum_number_of_integrator_steps>

<!--Maximum integration step size.-->
<maximum_integrator_step_size> 0.00100000 </maximum_integrator_step_size>

<!--Minimum integration step size.-->
<minimum_integrator_step_size> 0.00000001 </minimum_integrator_step_size>

<!--Integrator error tolerance. When the error is greater, the integrator step size is decreased.-->
<integrator_error_tolerance> 0.00010000 </integrator_error_tolerance>

<!--Set of analyses to be run during the investigation.-->
<AnalysisSet name="Analyses">
<objects/>
<groups/>
</AnalysisSet>

<!--Controller objects in the model.-->
<ControllerSet name="Controllers">
<objects/>
<groups/>
</ControllerSet>

<!--XML file (.xml) containing the external loads applied to the model as a set of PrescribedForce(s).-->

<!--Motion (.mot) or storage (.sto) file containing the desired point trajectories.-->
<desired_points_file> </desired_points_file>

<!--Motion (.mot) or storage (.sto) file containing the desired kinematic trajectories.-->
<desired_kinematics_file> subject01_walk1_ik.mot </desired_kinematics_file>

<!--File containing the tracking tasks. Which coordinates are tracked and with what weights are specified here.-->

<!--File containing the constraints on the controls.-->
<constraints_file> gait2354_RRA_ControlConstraints.xml </constraints_file>

<!--File containing the controls output by RRA. These can be used to place constraints on the residuals during CMC.-->
<rra_controls_file> </rra_controls_file>

<!--Low-pass cut-off frequency for filtering the desired kinematics. A negative value results in no filtering.
The default value is -1.0, so no filtering.-->
<lowpass_cutoff_frequency> -1.00000000 </lowpass_cutoff_frequency>

<!--Preferred optimizer algorithm (currently support "ipopt" or "cfsqp", the latter requiring the osimFSQP library.-->
<optimizer_algorithm> ipopt </optimizer_algorithm>

<!--Perturbation size used by the optimizer to compute numerical derivatives. A value between 1.0e-4 and 1.0e-8
is usually appropriate.-->
<optimizer_derivative_dx> 0.00010000 </optimizer_derivative_dx>

<!--Convergence criterion for the optimizer. The smaller this value, the deeper the convergence. Decreasing this number
can improve a solution, but will also likely increase computation time.-->
<optimizer_convergence_criterion> 0.00000100 </optimizer_convergence_criterion>

<!--Flag (true or false) indicating whether or not to make an adjustment in the center of mass of a body to reduced DC offsets
in MX and MZ. If true, a new model is writen out that has altered anthropometry.-->

<!--Initial time used when computing average residuals in order to adjust the body's center of mass. If both initial and final
time are set to -1 (their default value) then the main initial and final time settings will be used.-->

<!--Final time used when computing average residuals in order to adjust the body's center of mass.-->

<!--Name of the body whose center of mass is adjusted. The heaviest segment in the model should normally be chosen. For a gait model, the
torso segment is usually the best choice.-->

<!--Name of the output model file (.osim) containing adjustments to anthropometry made to reduce average residuals. This file is written
if the property adjust_com_to_reduce_residuals is set to true. If a name is not specified, the model is written out to a

<!--True-false flag indicating whether or not to turn on verbose printing for cmc.-->
<use_verbose_printing> false </use_verbose_printing>

</RRATool>
</OpenSimDocument>


### Example 2: XML file for the actuator set file for RRA

gait2354_RRA_Actuators.xml
<?xml version="1.0" encoding="UTF-8"?>
<ForceSet name="gait2354_RRA">

<defaults>

<PointActuator name="default">
<max_force> 10000.000 </max_force>
<min_force> -10000.000 </min_force>
<optimal_force> 1000.00000000 </optimal_force>
<body> </body_A>
<point> 0.000 0.000 0.000 </point>
<direction> 1.000 0.000 0.000 </direction>
</PointActuator >

<TorqueActuator name="default">
<max_force> 1000.000 </max_force>
<min_force> -1000.000 </min_force>
<optimal_force> 300.00000000 </optimal_force>
<body_A> </body_A>
<axis> 1.000 0.000 0.000 </axis>
<body_B> </body_B>
</TorqueActuator>

<CoordinateActuator name="default">
<max_force> 1000.000 </max_force>
<min_force> -1000.000 </min_force>
<optimal_force> 300.00000000 </optimal_force>
<coordinate> </coordinate>
</CoordinateActuatorCoordinateActuator>

</defaults>

<objects>

<!-- Residuals -->

<PointActuator name="FX">
<optimal_force> 4.00000000 </optimal_force>
<body> pelvis </body>
<point> -0.0724376 0.00000000 0.00000000 </point>
<point_is_global> false </point_is_global>
<direction> 1 0 0 </direction>
<force_is_global> true </force_is_global>
</PointActuator>

<PointActuator name="FY">
<optimal_force> 8.00000000 </optimal_force>
<body> pelvis </body>
<point> -0.0724376 0.00000000 0.00000000 </point>
<point_is_global> false </point_is_global>
<direction> 0 1 0 </direction>
<force_is_global> true </force_is_global>
</PointActuator>

<PointActuator name="FZ">
<optimal_force> 4.00000000 </optimal_force>
<body> pelvis </body>
<point> -0.0724376 0.00000000 0.00000000 </point>
<point_is_global> false </point_is_global>
<direction> 0 0 1 </direction>
<force_is_global> true </force_is_global>
</PointActuator>

<TorqueActuator name="MX">
<optimal_force> 2.0 </optimal_force>
<body_A> pelvis </body_A>
<axis> 1.000 0.000 0.000 </axis>
<body_B> ground </body_B>
</TorqueActuator>

<TorqueActuator name="MY">
<optimal_force> 2.0 </optimal_force>
<body_A> pelvis </body_A>
<axis> 0.000 1.000 0.000 </axis>
<body_B> ground </body_B>
</TorqueActuator>

<TorqueActuator name="MZ">
<optimal_force> 2.0 </optimal_force>
<body_A> pelvis </body_A>
<axis> 0.000 0.000 1.000 </axis>
<body_B> ground </body_B>
</TorqueActuator>

<!-- Right Leg -->

<CoordinateActuator name="hip_flexion_r">
<coordinate> hip_flexion_r </coordinate>
<optimal_force> 300.0 </optimal_force>
</CoordinateActuator>

<!-..additional <CoordinateActuator> tags cut for brevity..->

</objects>

</ForceSet>

### Example 3: XML file for the control constraints file for RRA

gait2354_RRA_ControlConstraints.xml
<?xml version="1.0" encoding="UTF-8"?>

<ControlSet name="gait2354_RRA">

<defaults>
<ControlLinear name="default">
<is_model_control> true </is_model_control>
<extrapolate> true </extrapolate>
<default_min> -1.0 </default_min>
<default_max> 1.0 </default_max>
<use_steps> false </use_steps>
</ControlLinear>
</defaults>

<objects>
<ControlLinear name="FX.excitation">
<default_min> -20.0 </default_min>
<default_max> 20.0 </default_max>
</ControlLinear>

<ControlLinear name="FY.excitation">
<default_min> -20.0 </default_min>
<default_max> 20.0 </default_max>
</ControlLinear>

<ControlLinear name="FZ.excitation">
<default_min> -20.0 </default_min>
<default_max> 20.0 </default_max>
</ControlLinear>

<ControlLinear name="MX.excitation">
<default_min> -50.0 </default_min>
<default_max> 50.0 </default_max>
</ControlLinear>

<ControlLinear name="MY.excitation">
<default_min> -50.0 </default_min>
<default_max> 50.0 </default_max>
</ControlLinear>

<ControlLinear name="MZ.excitation">
<default_min> -50.0 </default_min>
<default_max> 50.0 </default_max>
</ControlLinear>

<!-- Right Leg -->
<ControlLinear name="hip_flexion_r.excitation" />
<ControlLinear name="hip_rotation_r.excitation" />
<ControlLinear name="knee_angle_r.excitation" />
<ControlLinear name="ankle_angle_r.excitation" />

<!-- Left Leg -->
<ControlLinear name="hip_flexion_l.excitation" />
<ControlLinear name="hip_rotation_l.excitation" />
<ControlLinear name="knee_angle_l.excitation" />
<ControlLinear name="ankle_angle_l.excitation" />

<!-- Back -->
<ControlLinear name="lumbar_extension.excitation" />
<ControlLinear name="lumbar_bending.excitation" />
<ControlLinear name="lumbar_rotation.excitation" />

</objects>

</ControlSet>

### Example 4: XML file for the tasks file for RRA

 <?xml version="1.0" encoding="UTF-8"?>

<defaults>
<CMC_Joint name="default">
<on> false </on>
<wrt_body> -1 </wrt_body>
<express_body> -1 </express_body>
<active> false false false </active>
<weight> 1 1 1 </weight>
<kp> 1 1 1 </kp>
<kv> 1 1 1 </kv>
<ka> 1 1 1 </ka>
<coordinate> </coordinate>
<limit> 0 </limit>
</CMC_Joint>
</defaults>

<objects>

<!-- Pelvis -->

<CMC_Joint name="pelvis_tz">
<wrt_body> -1 </wrt_body>
<express_body> -1 </express_body>
<on> true </on>
<active> true false false </active>
<weight> 5.0e0 </weight>
<kp> 100.0 </kp>
<kv> 20.0 </kv>
<coordinate> pelvis_tz </coordinate>
</CMC_Joint>

<CMC_Joint name="pelvis_tx">
<wrt_body> -1 </wrt_body>
<express_body> -1 </express_body>
<on> true </on>
<active> true false false </active>
<weight> 5.0e0 </weight>
<kp> 100.0 </kp>
<kv> 20.0 </kv>
<coordinate> pelvis_tx </coordinate>
</CMC_Joint>

<CMC_Joint name="pelvis_ty">
<wrt_body> -1 </wrt_body>
<express_body> -1 </express_body>
<on> true </on>
<active> true false false </active>
<weight> 5.0e0 </weight>
<kp> 100.0 </kp>
<kv> 20.0 </kv>
<coordinate> pelvis_ty </coordinate>
</CMC_Joint>

<!-- . . additional <CMC_Joint> tags cut for brevity . . -->

</objects>

</CMC_TaskSet>