You are viewing the documentation for OpenSim 3.x. Are you looking for the latest OpenSim 4.0 Documentation?

Getting Started with RRA

The purpose of residual reduction is to minimize the effects of modeling and marker data processing errors that aggregate and lead to large nonphysical compensatory forces called residuals. Specifically, residual reduction alters the torso mass center of a subject-specific model and permits the kinematics of the model from Inverse Kinematics to vary in order to be more dynamically consistent with the ground reaction force data.

The Residual Reduction Algorithm (RRA) Tool is accessed by selecting Tools → Residual Reduction Algorithm… from the OpenSim main menu bar. Like all tools, the operations performed by the Residual Reduction Algorithm Tool apply to the current model.

Overview

The figure below shows the required inputs and outputs for performing the residual reduction algorithm. Each is described in more detail below.

Inputs and Outputs for performing residual reduction. Experimental data are shown in green; OpenSim files (.osim) are shown in red; settings files are shown in blue; files generated by the workflow are shown in purple.

Settings File

The subject01_Setup_RRA.xml file is a setup file for the RRA Tool, which specifies settings, inputs, and outputs that affect the behavior of the residual reduction algorithm, which can be defined using the GUI or by hand. Details of the settings are described in the section on using the Graphical User Interface.

The setup file identifies the actuators (i.e., the ideal residual and reserve joint actuators required by RRA) as well as the kinematic tracking tasks. Furthermore, control constraints on the actuators (to limit the maximum residual force) can be specified.

Inputs

Several files are required as input to the RRA Tool to perform residual reduction:

subject01_walk1_ik.mot: Contains the time histories of model kinematics, including the joint angles and pelvis translations.

gait2354_RRA_Tasks.xml: A tracking tasks file specifying which coordinates to track and the corresponding tracking weight (weights are relative and determine how "well" a joint angle will track the specified joint angle from IK). Use this file to additionally specify any constraints on the RRA actuators. Two key considerations:

  1. Selection of kp and kv are not arbitrary; they define the behavior of the error dynamics for each q as a second-order linear system. We can write the kp and kv for the desired system behavior in terms of system poles. For a (stable) critically-damped system (real negative poles), kp = λ2 and kv = -2λ.
  2. This enables kinematics of joints (coordinates) for which we have high confidence (e.g., knee flexion, hip flexion) to be weighted more heavily compared to those of less confidence (e.g., hip internal rotation and ankle inversion).
  3. Note that the maximum/minimum force or torque generated by an ideal actuator is the product of the maximum/minimum force and maximum/minimum excitation.
  4. Joint torques (and muscles) have a maximum magnitude of 1.
  5. Residuals have bounds exceeding their anticipated force requirement. Weightings are implicit in this description. A high optimal_force means that a large output force (torque) does not require a large control value (i.e., low cost). Conversely, residuals with low optimal force require high control values that incur higher costs.

subject01_walk1_grf.xml: ExternalLoads file specifying the measured ground reaction forces that should be applied to the model during simulation and how to apply them.

subject01_simbody.osim: A subject-specific OpenSim model generated by scaling a generic model with the Scale Tool or by other means, along with an associated marker set containing adjusted virtual markers. The model must include inertial parameters.

gait2354_RRA_Actuators.xml: Ideal joint actuators used to replace muscles. The Actuator Set specifies the residual and reserve actuators to be applied and their parameters, such as maximum/minimum force and body, joint, or location (depending on the actuator type). A few key considerations:

  1. Each degree-of-freedom (DOF) in the model should have an ideal torque or force (reserve) actuator. This includes the 6 DOFs of the model's base segment, which are called the "residual actuators".
  2. In most circumstances, these ideal joint actuators are used to replace the muscles in the model (by checking "Replace model actuators" in the Actuators tab).
  3. Optimal forces are the maximum output of ideal actuators (torques, linear forces). Torque (force) applied is optimal_force*control_value.
  4. Residual at the pelvis should be applied at the scaled COM location.

Outputs

The Residual Reduction Algorithm Tool generates the following outputs:

subject01_RRA_states.sto: Adjusted kinematics (i.e., joint angles) and corresponding model states of the simulated motion (i.e., joint angles AND velocities).

subject01_adjusted.osim (optional): A model with adjusted mass properties.

subject01_RRA_controls.xml: Actuator excitations (i.e., control signals needed to generate actuator forces and torques).

subject01_RRA_Actuation ... (not shown in figure): Actuator forces and torques (i.e., joint torques corresponding to adjusted kinematics).

subject01_RRA_Kinematics ... (not shown in figure)Joint angles, velocities, and accelerations

subject01_RRA_avgResiduals ... (not shown in figure): Summary of the average residual values (FX, FY, FZ, MX, MY, MZ) for the trial

subject01_RRA_Kinematics ... (not shown in figure)Joint angles, velocities, and accelerations

subject01_RRA_pErr ... (not shown in figure)Position errors for each of the model's generalized coordinates during the trial

Best Practices and Troubleshooting

RRA Settings:

  1. You should replace the muscles in your model with residual actuators and ideal joint actuators. Residual reduction is a form of forward dynamics simulation that utilizes a tracking controller to follow model kinematics determined from the inverse kinematics. Computed Muscle Control (CMC) serves as the controller, but without muscles, the skeleton of the model can be used to determine a mass distribution and joint kinematics that are more consistent with ground reaction forces.
  2. Optimal forces for residuals should be low to prevent the optimizer from "wanting" to use residual actuators (an actuator with large optimal force and low excitation is "cheap" in the optimizer cost).
  3. To help minimize residuals, make an initial pass with default inputs, then check residuals and coordinate errors. To reduce residuals further, decrease tracking weights on coordinates with low error. You can also try decreasing the maximum excitation on residuals or the actuator optimal force.
  4. Typically, you should "lock" the subtalar and mtp joints in the *.osim file.
  5. Make sure "use_fast_optimization_target" is false. This allows the kinematics to be slightly adjusted to account for dynamic inconsistencies. This is the default in the settings files distributed with OpenSim or created from the GUI. See How CMC Works for a comparison of the "slow" and "fast" targets. In the GUI, this option is hidden for RRA and can be viewed by opening the xml settings file.
  6. The "cmc_time_window" in the settings file should be 0.001 s for RRA. This is the default in the settings files distributed with OpenSim or created from the GUI.
  7. See How RRA Works and How to Use the RRA Tool for more information about RRA settings.

Troubleshooting:

  1. Check the pelvis COM location in the Actuator files.
  2. If RRA is failing, try increasing the maximum excitation for residuals by orders of magnitude until the simulation runs, then try working your way back down while also "relaxing" tracking weights on coordinates.
  3. If residuals are very large (typically, this is greater than 2-3 times body weight, depending on the motion), there is probably something wrong with either (i) the scaled model, (ii) the IK solution, or (iii) the applied GRFs. To double-check that forces are being applied properly, visualize GRFs with IK data (you can use the Previewing Motion Capture (Mocap) Data function in the GUI).
  4. If there is pelvis drift and/or FY is not centered around zero, check that the body mass and force calibration are correct.
  5. When using the example RRA Actuators .xml file, you should note that residual forces are applied to the center of mass (COM) of the unscaled pelvis; however, if you scale the model, the COM of the pelvis can change. Although the effect may be small, you should change the location of the residual force actuators in the RRA Actuators file to correspond to the scaled pelvis COM.

Evaluating your Results:

  1. RMS difference in joint angle during the movement should be less than 2-5º (or less than 2 cm for translations).
  2. Peak residual forces should typically be less than 10-20 N. Average residuals should typically be less than 5-10 N.
    1. The size of residuals will depend on the type of motion being studied. For example, residuals for high-speed activities like sprinting will typically be larger than walking.
    2. Residuals will also be larger if there are external forces that you have not accounted for, such as a subject walking with a handrail.
  3. Compare the residual moments from RRA to the moments from Inverse Dynamics. You should see a 30-50% reduction in peak residual moments.
  4. Compare the joint torques/forces to established literature (if available). Try to find data with multiple subjects. Your results should be within one standard deviation of the literature.

The table below shows an example of threshold values used to evaluate RRA results for full-body simulations of walking and running.

OpenSim is supported by the Mobilize Center , an NIH Biomedical Technology Resource Center (grant P41 EB027060); the Restore Center , an NIH-funded Medical Rehabilitation Research Resource Network Center (grant P2C HD101913); and the Wu Tsai Human Performance Alliance through the Joe and Clara Tsai Foundation. See the People page for a list of the many people who have contributed to the OpenSim project over the years. ©2010-2024 OpenSim. All rights reserved.