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:

 J = \sum_{i=1}^{nx} x_i^2 + \sum_{j=1}^{nq} w_j \left( \ddot{q}_j\,^* - \ddot{q}_j \right)^2

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_simbody.osim true gait2354_RRA_Actuators.xml ResultsRRA/ 8 0.75000000 0.78000000 false 20000 0.00100000 0.00000001 0.00010000 subject01_externalForces.xml subject01_walk1_ik.mot gait2354_RRA_Tasks.xml gait2354_RRA_ControlConstraints.xml -1.00000000 ipopt 0.00010000 0.00000100 true -1.00000000 -1.00000000 torso subject01_RRA_adjusted.osim false 

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

                   10000.000     -10000.000     1000.00000000          0.000 0.000 0.000     1.000 0.000 0.000               1000.000     -1000.000     300.00000000          1.000 0.000 0.000                    1000.000     -1000.000     300.00000000                                    4.00000000     pelvis     -0.0724376 0.00000000 0.00000000     false     1 0 0     true               8.00000000     pelvis     -0.0724376 0.00000000 0.00000000     false     0 1 0     true               4.00000000     pelvis     -0.0724376 0.00000000 0.00000000     false     0 0 1     true               2.0     pelvis     1.000 0.000 0.000     ground               2.0     pelvis     0.000 1.000 0.000     ground               2.0     pelvis     0.000 0.000 1.000     ground                     hip_flexion_r     300.0           tags cut for brevity..->          

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

         true   true   -1.0   1.0   false           -20.0   20.0       -20.0   20.0       -20.0   20.0       -50.0   50.0       -50.0   50.0       -50.0   50.0                                       

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

                   false     -1     -1     false false false     1 1 1     1 1 1     1 1 1     1 1 1          0                               -1     -1     true     true false false     5.0e0     100.0     20.0     pelvis_tz              -1     -1     true     true false false     5.0e0     100.0     20.0     pelvis_tx               -1     -1     true     true false false     5.0e0     100.0     20.0     pelvis_ty                     
 Previous: How to Use the RRA Tool