WELCOME TO THE NEW PLATFORM FOR THE OPENSIM DOCUMENTATION

Remember to update your bookmarks with our new URL.
If you find missing content or broken links, let us know: opensim@stanford.edu

Guide to OpenSim Workflow and Tools

Owned by Jennifer Hicks
Last updated: Aug 16, 2012Version comment
1 min read

Overview of the OpenSim Workflow

Unable to render {include} The included page could not be found.

Scaling

The Scale Tool alters the anthropometry of a model so that it matches a particular subject as closely as possible. Scaling is typically performed by comparing experimental marker data to virtual markers placed on a model. In addition to scaling a model, the Scale Tool can be used to adjust the locations of virtual markers so that they better match the experimental data.

The Scale Tool is accessed by selecting Tools → Scale Model… from the OpenSim main menu bar. Like all tools, the operations performed by the Scale Tool apply to the current model.

Overview

The figure below shows the required inputs and outputs for the Scale Tool. Each is described in more detail in the following sections.

Inputs and Outputs of the Scale Tool. Experimental data are shown in green; OpenSim files (.osim) are shown in red; settings files are shown in blue.

The file names are examples that can be found in the Models/Gait2354_Simbody directory installed with the OpenSim distribution.

Settings Files

The subject01_Setup_Scale.xml file is the setup file for the Scale Tool. It contains settings, described in detail in How Scaling Works. The setup file can include the following information:

  • ScaleTasks: Inverse kinematics tasks for the Scale Tool. In addition to scaling the model, the Scale Tool moves the virtual markers on the model so that their positions match the experimental marker locations. To do this, the Scale Tool must position the model so that it best matches the position of the subject. This requires an inverse kinematics problem to be solved. This file contains the inverse kinematics tasks describing which virtual and experimental markers should be matched up during the inverse kinematics phase. The file also contains marker weights, which are relative and determine how "well" the virtual markers track experimental markers (a larger weight will result in less error between the corresponding virtual and experimental marker positions).
  • ScaleMeasurementSet: Measurement set for the Scale Tool. It contains pairs of experimental markers, the distance between which are used to scale the generic musculoskeletal model. 
  • ScaleScaleSet Scale set for the Scale Tool. It contains a set of manual scale factors to be applied to the generic musculoskeletal model.

As of 3.0.1 these settings are contained in a single file. If you had old setups with multiple files, they will be merged upon Open/Save of settings in the Scale Tool.

ScaleMarkerSet.xml: Marker set for the Scale Tool. It contains the set of virtual markers that are placed on the body segments of the model.

Inputs

Two data files are required by the Scale Tool:

subject01_static.trc: Experimental marker trajectories for a static trial. A static trial is usually several seconds of data with the subject posed in a known static position. A segment of a regular motion file can be used as a static trial if desired, but this is not typically done. The static pose should include the subject wearing the full marker set. The marker trajectories are specified in the global frame. You can find more information about collecting and preparing motion data in the section on Preparing Your Data.

gait2354_simbody.osim: OpenSim musculoskeletal model. This generic model will be scaled to match the anthropometry of your subject.

You can also provide an additional, optional file:

subject01_static.mot: Experimental generalized coordinate values (joint angles) for a trial obtained from alternative motion capture devices or other specialized algorithms. You can specify coordinate weights in the Tasks file, if joint angles are known a priori. Coordinate weights are also relative and determine how "well" a joint angle will track the specified angle.

Outputs

The Scale Tool generates a single file:

subject01_simbody.osim: OpenSim musculoskeletal model scaled to the dimensions of the subject.

Best Practices and Troubleshooting

Data Collection and Other Preparation:

  1. When collecting data, take pictures of your subjects in the static pose. These pictures are valuable for evaluating the results of the Scale Tool.
  2. Measure subject specifics, like height, mass, body segment lengths, mass distribution (if DXA is available), and strength (if a Biodex is available). You can use this data, along with marker positions, to best match the generic model to a specific subject.
  3. Have your subjects perform movements to calculate functional joint centers at the hip, knee, ankle, and/or shoulders, and append the joint centers to your static trial data (see Associating Data with a Motion).
  4. These are just a few tips. Also review our full guide to Collecting Experimental Data.

Scale Settings:

  1. Rely on markers that correspond to anatomical landmarks and functional joint centers (FJC) to position and scale the generic model.
    1. See How to Use the Scale Tool for information about defining the measurement set for scaling and setting weights when positioning the model in the static pose.
  2. Some segments, like the pelvis and torso, are often best scaled non-uniformly. For example, see the torso scale settings in the section on the Scale Factors Pane in How to Use the Scale Tool.
  3. Review How Scaling Works for more information about Scale Settings.

Evaluating your Results:

  1. Scaling a model is an iterative process. Use the "preview static pose" option in the GUI. See the section on "Previewing Scale" in the How to Use the Scale Tool section for more information. After running preview, perform steps 2 to 5 described below.
  2. Check the "Messages" window, which has information about the results of scaling, including the overal RMS marker error and the maximum marker error.
    1. In general, maximum marker errors for bony landmarks should be less than 2 cm.
    2. RMS error should typically be less than 1 cm.
    3. Pay close attention to errors in the bony landmark and FJC markers when assessing the quality of your scaling results.
  3. Visualize the scaled model's anatomical marker positions relative to the corresponding experimental markers to see how well the model "fits" the data. Use the pictures you took to assess the results, comparing the joint angles in the "Coordinates" window to the angles you observe in the pictures.
    1. Do the hip, knee, and ankle angles after scaling match what you observe in the picture?
    2. Are there any large mismatches between experimental and model markers? Can these mismatches be explained by examining the pictures you took?
    3. If pictures aren't available, use what you know about a typical static pose capture. For example, the ankle angle is generally less than 5º and hip flexion angle is less than 10º.
    4. Again, pay close attention to errors in the landmark and FJC markers when assessing the quality of your scaling results.
  4. After examining the "Messages" window and performing a visual comparison, adjust the virtual markers and marker weightings to improve your results.
    1. Again, avoid adjusting the positions of the landmark and FJC virtual markers to match the experimental markers.
  5. Once you've adjusted the virtual marker positions and the scale settings, preview the new static pose. Reassess your results using steps 2 to 4 above. Once you are happy with your results, hit "Run" to generate a scaled model and adjust the virtual markers on the model to match all of the experimental markers.

Troubleshooting Tips:

  1. It is common to iterate through Scale and Inverse Kinematics to fine-tune segment dimensions and marker positions that yield low marker errors for the task of interest.
  2. Use coordinate tasks (Static Pose Weights) to set joint angles for troublesome joints that are very sensitive to how the markers are placed (commonly the ankle joint and lumbar joint). For example, if it is known that the foot is flat, an ankle angle can be provided and then the markers can be adjusted in order to match the known pose.
  3. If using coordinates from a motion capture system, make sure that the joint/coordinate definitions match—otherwise, you may cause more harm than good.
  4. The model has a built-in assumption that the global Y-axis is up. If your data doesn't fit this assumption, then consider transforming your data. You can use Previewing Motion Capture (Mocap) Data to determine the proper transform to apply.

Video Tutorials

Setting up the scale tool:

https://www.youtube.com/watch?v=V5f7OMkfRBs


Evaluating your results:

https://www.youtube.com/watch?v=7STRMJefzpI


Next: How Scaling Works

Home: Scaling

Inverse Kinematics

The Inverse Kinematics (IK) Tool steps through each time frame of experimental data and positions the model in a pose that "best matches" experimental marker and coordinate data for that time step. This "best match" is the pose that minimizes a sum of weighted squared errors of markers and/or coordinates. Obtaining accurate results from the IK Tool is essential for using later tools like Static Optimization, Residual Reduction Algorithm, and Computed Muscle Control.

To launch the IK Tool, select Tools → Inverse Kinematics from the OpenSim main menu bar.

Inverse Kinematics (IK) Tool Overview. Experimental markers are matched by model markers throughout the motion by varying the joint angles (generalized coordinates) through time.

Overview

Inputs and Outputs of the IK Tool. Experimental data are shown in green; OpenSim files (.osim) are shown in red; settings files are shown in blue.

 

The file names are examples that can be found in the Models/Gait2354_Simbody directory installed with the OpenSim distribution.

 

Inputs

The primary inputs to IK are the following files:

  1. 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.
  2. subject01_walk1.trc: Experimental marker trajectories for a trial obtained from a motion capture system, along with the time range of interest.
  3. gait2354_Setup_IK.xml: A file containing all the settings information for the IK tool, including marker weightings (IK tasks). As in the Scale Tool, marker weights are relative and determine how "well" the virtual markers track experimental markers (a larger weight for a given marker will mean less error–the distance between the virtual and experimental representations of a marker–for that marker).
  4. subject01_coords.mot (optional): Experimental generalized coordinate values (joint angles) for a trial obtained from alternative motion capture devices or other specialized algorithms. You can optionally specify relative coordinate weights in the Tasks file, if joint angles are known a priori.

Outputs

  1. subject01_walk1_ik.mot: A motion file containing the generalized coordinate trajectories (joint angles and/or translations) computed by IK.

Best Practices and Troubleshooting

Data Collection and Other Preparation:

  1. When collecting experimental data, place three non-collinear markers per body segment that you want to track. You need at least three markers to track the 6-degree-of-freedom motion (position and orientation) of a body segment.
  2. Place markers on anatomical locations with minimum skin/muscle motion.
  3. These are just a few tips. Also review our full guide to Collecting Experimental Data.

Inverse Kinematics Settings:

  1. Weight "motion" segment markers (from a triad placed on the thigh segment, for example) more heavily than anatomical markers affixed to landmarks like the greater trochanter and the acromion, which can be helpful for scaling, but are influenced by muscle and other soft tissue movements during motion.
  2. Relative marker weightings are more important than their absolute values. Therefore, a weighting of 10 vs. 1 is 10 times more important, whereas 20 vs. 10 is only twice as important. Markers are not necessarily tracked better because they both have higher weightings.
  3. See How Inverse Kinematics Works and How to Use the IK Tool for more information about IK settings.

Evaluating your Results:

  1. Total RMS and maximum marker errors are reported in the "Messages" window. Use these values to guide changes in weightings or, if necessary, to redo marker placement and possibly scaling. Maximum marker error should generally be less than 2-4 cm, and RMS under 2 cm is achievable. These guidelines will vary depending on the nature of the model and the motion being examined.
  2. If using coordinates from a motion capture system, make sure that the joint/coordinate definitions match—otherwise, you may cause more harm than good.
  3. Compare your results to similar data reported in the literature. Your results from an unimpaired average adult should generally be within one standard deviation.
  4. If you are unsatisfied with the results, recheck the results of scaling.

 

Next: How Inverse Kinematics Works

Home: Inverse Kinematics

 

 

Inverse Dynamics

The Inverse Dynamics (ID) Tool determines the generalized forces (e.g., net forces and torques) at each joint responsible for a given movement. Given the kinematics (e.g., states or motion) describing the movement of a model and perhaps a portion of the kinetics (e.g., external loads) applied to the model, the ID Tool uses these data to perform an inverse dynamic analysis. Classical mechanics mathematically expresses the mass-dependent relationship between force and acceleration, F = ma, with equations of motion. The Inverse Dynamics Tool solves these equations, in the inverse dynamics sense, to yield the net forces and torques at each joint which produce the movement.

To launch the ID Tool, select Tools → Inverse Dynamics from the OpenSim main menu bar.

Overview

This figure shows the required inputs and outputs for the Inverse Dynamics Tool.

Inputs and Outputs of the Inverse Dynamics Tool. 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.

The file names are examples that can be found in the examples/Gait2354_Simbody directory installed with the OpenSim distribution.

Settings File

The subject01_Setup_InverseDynamics.xml file is the setup file for the Inverse Dynamics Tool. It contains settings, as described in detail in How to Use the Inverse Dynamics Tool.

Inputs

Three data files are required as input by the Inverse Dynamics Tool:

subject01_walk1_ik.mot: Motion file containing the time histories of generalized coordinates that describe the movement of the model. This file could be generated by the Inverse Kinematics Tool, or manually. The file does not need to contain values for all coordinates. The coordinates that were not specified are assumed to have default values.

subject01_walk1_grf.xml: External load data (i.e., ground reaction forces, moments, and center of pressure location). Note that it is necessary to measure and apply or model all external forces acting on a subject during the motion to calculate accurate joint torques and forces. This file includes the name of the ground reaction force data file (e.g., subject01_grf.mot) as well as the names of the bodies to which they are applied. Options to specify the forces, points of application, and torques in a global or local body frame (relative to the body to which the force is being applied) are also defined here. Details are provided in How to Use the Inverse Dynamics Tool. 

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. Note that forces such as contact, ligaments, bushings, and even muscles will be applied to the model based on the kinematic state of the model and defaults for the muscle states, unless these forces are specifically excluded in the calculation.

Outputs

The Inverse Dynamics Tool generates a single file in a folder specified in the setup file:
subject01_walk1_InverseDynamics_force.sto: Storage file containing the time histories of the net joint torques and forces acting along the coordinate axes that produce the accelerations estimated (via double differentiation) from your measured experimental motion and the external forces applied.

Best Practices and Troubleshooting

  1. Filter your raw coordinate data, since noise is amplified by differentiation. Without filtering, the calculated forces and torques will be very noisy.
  2. Compare your results to data reported in the literature. Your results should be within one standard deviation of reported values.
  3. Inspect results from Inverse Dynamics to check whether ground reaction forces were applied correctly or not. Are there large and unexpected forces at the pelvis? For gait, applying ground reaction forces should help reduce the forces computed by Inverse Dynamics at the pelvis.
  4. See How Inverse Dynamics Works and How to Use the Inverse Dynamics Tool for more information about using the Inverse Dynamics Tool.

Next: How Inverse Dynamics Works

Home: Inverse Dynamics

Static Optimization

Static optimization is an extension to inverse dynamics that further resolves the net joint moments into individual muscle forces at each instant in time. The muscle forces are resolved by minimizing the sum of squared (or other power) muscle activations.

To launch the Static Optimization Tool, select Static Optimization… from the Tools menu. The Static Optimization Tool dialog window, like all other OpenSim tools, operates on the current model open and selected in OpenSim.

Overview

The figure below shows the required inputs and outputs for the Static Optimization Tool. Each is described in more detail in the following sections.

 

Inputs and Outputs of the Static Optimization Tool. 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. To run static optimization, you use the analyze command.

The file names are examples that can be found in the examples/Gait2354_Simbody directory installed with the OpenSim distribution.

Inputs

Three files are required as input by the Static Optimization Tool:

subject01_walk1_ik.mot: Motion file containing the time histories of generalized coordinates that describe the movement of the model. This can be kinematic data (i.e., joint angles) from IK or states (i.e., joint angles AND velocities) from RRA for the time range of interest.

subject01_walk1_grf.xml: External load data (i.e., ground reaction forces, moments, and center of pressure location). Note that you must measure or model all external forces acting on a subject during the motion to calculate accurate muscle forces. The .xml file describes how to apply the measured ground reaction forces to the model during the analysis.

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 (segment masses, etc.).

x: The exponent for the activation-based cost function to be minimized (i.e., the criterion used to solve the muscle force distribution problem).

Outputs

The Static Optimization Tool generates three files in a specified folder:

subject01_walk1_StaticOptimization_controls.xml: Contains the time histories of muscle activations. These controls were minimized by the Static Optimization Tool.

subject01_walk1_StaticOptimization_activation.sto: Storage file containing the time histories of muscle activations.

subject01_walk1_StaticOptimization_force.sto: Storage file containing the time histories of muscle forces. As of version OpenSim 3.3, this file also includes the time history of any other forces applied to the model (e.g., passive elements or constraint forces).

Best Practices and Troubleshooting

Static Optimization Settings:

  1. You can use IK or RRA results as input kinematics. If using IK results, you usually need to filter them, either externally or using the OpenSim analyze/static optimization field; if using RRA results, you usually do not have to filter.
  2. For gait and many other motions, you need to add (append) residual actuators to the first free joint in the model (typically the ground-pelvis joint).
    1. There should be one actuator for each degree-of-freedom (i.e., FX, FY, FZ, MX, MY, MZ).
    2. These residual actuators are required because there is dynamic inconsistency between the estimated model accelerations and the measured ground reaction forces. This inconsistency can result from marker measurement error, differences between the geometry of the model and the subject, and inertial parameters.
    3. Running RRA will reduce—but not eliminate—these residuals. Thus, appending actuators is still necessary.
  3. See How Static Optimization Works and How to Use the Static Optimization Tool for more information.

Troubleshooting:

  1. If the residual actuators or the model's muscles are weak, the optimization will take a long time to converge or will never converge at all.
    1. If the residual actuators are weak, increase the maximum control value of a residual, while lowering its maximum force. This allows the optimizer to generate a large force (if necessary) to match accelerations, but large control values are penalized more heavily. In static optimization, ideal actuator excitations are treated as activations in the cost function.
    2. If the muscles are weak, append Coordinate Actuators to the model at the joints in the model. This will allow you to see how much "reserve" actuation is required at a given joint and then strengthen the muscles in your model accordingly.
    3. If troubleshooting a weak model and optimization is slow each time, try reducing the parameter that defines the maximum number of iterations.
  2. Static optimization works internally by solving the inverse dynamics problem, then trying to solve the redundancy problem for actuators/muscles using the accelerations from the inverse dynamics solution as a constraint. If a constraint violation is reported, this could be a sign that the optimizer couldn't solve for muscle forces while enforcing the inverse dynamics solution.
    1. This likely means that there is noise in the data or there is a sudden jump in accelerations in one frame.
    2. In this case, you should examine the inverse dynamics solution to determine the problematic frame, and fix/interpolate the data during this portion of the motion.
  3. If your model has passive elements (e.g., ligaments or springs), you should use OpenSim version 3.3 or later. Prior to version 3.3, the forces generated by passive elements were not properly accounted for.

Evaluating your Results:

  1. Are there any large or unexpected residual actuator forces?
  2. Find EMG or muscle activation data for comparison with your simulated activations. Does the timing of muscle activation/deactivation match? Are the magnitudes and patterns in good agreement?

 

Next: How Static Optimization Works

Home: Static Optimization

Residual Reduction Algorithm

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.

Next: How RRA Works

Home: Residual Reduction Algorithm

Computed Muscle Control

The purpose of Computed Muscle Control (CMC) is to compute a set of muscle excitations (or, more generally, actuator controls) that will drive a dynamic musculoskeletal model to track a set of desired kinematics in the presence of applied external forces (if applicable).

The Computed Muscle Control Tool is accessed by selecting Tools → Computed Muscle Control… from the OpenSim main menu bar. Like all tools, the operations performed by the Computed Muscle Control Tool apply to the current model.

Overview

The figure below shows the required inputs and outputs for the Computed Muscle Control Tool. Each is described in more detail in the following sections.


Each of the files in this figure can be categorized as either experimental data, an OpenSim file (.osim), a settings file, or a file generated by the workflow.

The file names are examples that can be found in the examples/Gait2354_Simbody directory installed with the OpenSim distribution.

Settings File

The subject01_Setup_CMC.xml file is a setup file for the CMC Tool, which specifies settings, inputs, and outputs that affect the behavior of the tracking controller to determine actuator (including muscles) controls. These can be defined using the GUI or by hand. Details of the settings are described in the section on the Graphical User Interface.

The setup file identifies the actuators (i.e., the residual actuators, as required for dynamic consistency) as well as the kinematic tracking tasks. Furthermore, control constraints on the actuators (to limit the maximum residual force) can be specified.

Inputs

Several data files are required as input by the Computed Muscle Control Tool:

subject01_walk1_RRA_Kinematics_q.sto: Contains the time histories of model kinematics, including the joint angles and pelvis translations from RRA.

gait2345_CMC_Tasks.xml: The 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 RRA).

gait2345_CMC_ControlConstraints.xml: Contains limits on model actuators, which include muscles, reserve and residual actuators. The control constraints file specifies the maximum and minimum "excitation" (i.e., control signal) for each actuator. Control constraints can also be used to enforce when certain actuators are "on" or "off" and the range in which they can operate.

subject01_walk1_grf.xml: External load data (i.e., ground reaction forces, moments, and center of pressure location). See Inverse Dynamics for more details.

subject01_simbody_adjusted.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. The model should have an adjusted torso center of mass to reduce residuals.

gait2345_CMC_Actuators.xml: Contains the residual and reserve actuators, as in RRA.

Outputs

The Computed Muscle Control Tool primarily reports the necessary controls:

subject01_walk1_controls.xml: Contains the excitations to individual muscles as well as controls for any residual and/or reserve actuators.

subject01_CMC_forces.sto (not shown): Muscle forces and reserve/residual forces and torques.

subject01_walk1_states.sto (not shown): Model states and muscle states of the simulated motion (i.e., joint angles AND velocities, muscle fiber lengths AND activations).

Best Practices and Troubleshooting Tips

 

CMC Settings:

  1. The reserve actuators are torques that are added about each joint to augment the actuator’s force in order to enable the simulation to run (reserves turn on when an actuator cannot produce the needed force at a given time point). To help minimize reserve torques, make an initial pass with default inputs, and then check reserves, residuals, and joint angle errors. To reduce reserves further, decrease tracking weights on coordinates with low error.
  2. Optimal forces for reserves should be low to prevent the optimizer from "wanting" to use reserve actuators (an actuator with a large optimal force and a low excitation is "cheap" in the optimizer cost). If larger forces are needed for a successful simulation, increase the maximum control value of residuals. The residuals will then be able to generate sufficient force, but will be penalized for doing so.
  3. If you are still getting high reserves for a particular degree-of-freedom during a particular time range in the simulation, it may be useful to examine more closely the muscles which span the degree-of-freedom during that time region (see TipsForDebuggingMuscleActuatedSimulations.pdf). In particular:
    1. Check passive muscle forces (e.g., quadriceps). Large passive forces (from large knee flexion angles) may induce active forces in the antagonistic muscles (e.g., hamstrings, gastrocnemius), which may not be desired. Passive forces cannot be controlled in CMC; they are purely a function of the whole-body kinematics of the motion. Although tempting, do not increase the maximum isometric force excessively unless you know its consequences in the muscle model. Since the passive muscle force is modeled as a function of maximum isometric force, if you increase the maximum isometric force in the hope of making your active muscles stronger, you will also be increasing the passive forces in the muscles as well, thereby not helping the situation. To decrease passive muscle forces, you want to reduce the passive muscle stiffness property of muscle (or, more specifically, increase the FmaxMuscleStrain parameter in the Thelen2003Muscle).
    2. Check normalized fiber length during the motion (using the Plotter Tool). Is the muscle acting at suboptimal fiber lengths (i.e., less than 0.8 or greater than 1.2) at the time where the reserves are being generated? If so, then you may consider modifying either the tendon slack length or the optimal fiber length of the muscle so that it is operating more optimally (and, thus, capable of generating a greater force) during this time in the simulation. Although many cadaver studies report the optimal fiber length of a muscle, the tendon slack length is almost never reported, even though it is especially sensitive to the operating region on the force-length curve. Small adjustments to the tendon slack lengths can, therefore, be justified in reducing the reserves on the basis that we don't have as much confidence in this value to begin with.
  4. You should almost always use the "fast" target for CMC. Note that this is the default (e.g. if you run CMC through the GUI). You can only change this value in the xml setup file for the tool. The fast target requires the joint accelerations at each time step to be matched to the RRA results. "Fast" target should work for normal subjects; "slow" target may be needed for subjects with pathologies.
  5. Start CMC at least 0.03 seconds before the point where you want to start analyzing your data, as CMC requires 0.03 seconds to initialize.
  6. See How CMC Works and How to Use the CMC Tool for more information.

CMC Troubleshooting:

  1. If CMC is failing, try increasing the maximum excitation for reserves and residuals by orders of magnitude until the simulation runs, then try working your way back down while also "relaxing" tracking weights on coordinates.

Evaluating your Results:

  1. Peak reserve actuator torques should typically be less than 10% of the peak joint torque.
  2. Peak residual forces should typically be less than 10-20 N; peak residual moments, less than 75 Nm (depending on the type of motion).
  3. Double-check your kinematics in comparison to RRA. Generally, they should match well as long as you are using the "fast" target.
  4. If performing an Induced Acceleration Analysis, you should verify that reserves and residuals contribute less than 5% to the net acceleration of interest.

  5. Compare the simulated activations to experimental EMG data (either recorded from your subject or from the literature). Activations should exhibit similar timing and magnitude to EMG data. You can also compare your muscle activations and/or forces to other simulations from SimTK or the literature.

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


Next: How CMC Works

Home: Computed Muscle Control

Forward Dynamics

Given the controls (e.g., muscle excitations) computed by the Computed Muscle Control (CMC) or another approach, the Forward Dynamics Tool can drive a forward dynamic simulation. A forward dynamics simulation is the solution (integration) of the differential equations that define the dynamics of a musculoskeletal model. By focusing on specific time intervals of interest, and by using different analyses, more detailed biomechanical data for the trial in question can be collected.

To launch the Forward Dynamics Tool select Forward Dynamics… from the Tools menu. The Forward Dynamics Tool dialog, like all other OpenSim tools, operates on the Current Model open and selected in OpenSim.

Overview

The figure shows the required inputs and outputs for the Forward Dynamics Tool. Each is described in more detail in the following sections.

Inputs and Outputs of the Forward Dynamics Tool. 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.

The file names are examples that can be found in the examples/Gait2354_Simbody directory installed with the OpenSim distribution. These inputs correspond to a typical OpenSim workflow and may be different for your own research application.

Inputs

Four data files are used as input by the Forward Dynamics Tool:

subject01_walk1_controls.xml: Contains the time histories of the model controls (e.g., muscle excitations) to the muscles and/or joint torques. It is possible to specify the controls as .sto files instead, with columns corresponding to desired excitations. This file may be generated by the user, the Static Optimization Tool, or the Computed Muscle Control Tool. If no controls are provided, they are assumed to be zero for any actuators in the model.

subject01_walk1_states.sto: Contains the time histories of model states, including joint angles, joint speeds, muscle activations, muscle fiber lengths, and more. These states are used by the Forward Dynamics Tool to set the initial states of the model for forward integration. If you are running a forward simulation using the controls from CMC, you should specify the states file outputted from CMC here. Muscle states can be estimated by solving for tendon and muscle fiber force equilibrium when the Solve for equilibrium for actuator states is checked.

  • If you are running the forward tool in the GUI and no initial states files is specified, the simulation will start from the model's current pose. 
  • If you are running the forward tool from the command line and no initial states file is specified, the simulation will begin from the default pose of the model. 

subject01_walk1_grf.xml: An .xml file describing the external loads applied, based (for example) on measured ground reaction forces that should be applied to the model during the simulation.

subject01_simbody_adjusted.osim: 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 (segment masses, etc.).

The subject01_Setup_Forward.xml file is the setup file for the Forward Dynamics Tool. It contains settings, as described in How to Use the Forward Dynamics Tool, and refers to another settings file, gait2354_CMC_Actuators.xml, which contains a set of actuators that supplement the muscles of the model. Refer to Computed Muscle Control for more details. These actuators must be included in the forward simulation so that the CMC solution can be reproduced.

Outputs

The Forward Dynamics Tool generates results in a folder specified in the setup file.

Results: Additional data can be generated and written to files by adding analyses to the Forward Dynamics Tool. These analyses are specified in the setup file (subject01_Setup_Forward.xml) and are discussed in the Analyses section.

Best Practices and Troubleshooting Tips

  1. Forward dynamics simulations are sensitive to initial conditions, and it is good practice to double-check that the initial conditions are appropriate for the desired simulation.
  2. If the Forward Dynamics Tool fails gracefully (i.e., without crashing OpenSim) or the output of the Tool drifts too much (i.e., the model "goes crazy"), shorten the interval over which the Forward Dynamics Tool runs (i.e., make initial_time and final_time closer to each other in the Forward Dynamics Tool setup dialog box or setup file). Open-loop forward dynamics tends to drift over time due to the accumulation of numerical errors during integration.
  3. Forward dynamics will be slow and generate very large results files if the problem is stiff and the integrator has to take many small time steps. Some common cases that result in stiff problems:
    1. Bodies with small masses relative to other model bodies make the system stiff. Small masses combined with large forces can also make the problem stiff.
    2. If there's a contact model, check the settings. Try reducing the "transition_velocity" if forward dynamics is slow. Also having lots of damping in the contact model combined with a high stiffness value can also lead to problems. 
  4. Having many wrapping surfaces in your model can increase computation time. Cylindrical wrapping surfaces tend to have better performance that ellipsoidal wrapping surfaces.


Next: How Forward Dynamics Works

Home: Forward Dynamics

 

Checklist - Evaluating your Simulation

The following is a list of necessary, but not sufficient, questions for evaluating your simulation. You may not be able to answer "yes" to all of these questions, but if the answer is "no", you should be able to provide a plausible explanation to convince yourself (and reviewers) that your results are meaningful.

Scaling

  1. If you are using any coordinates from a motion capture system, do the definitions match your model?
  2. Is the maximum marker error for bony landmarks and functional joint centers less than 2 cm?
  3. Is the RMS error less than ~1 cm?
  4. Do the joint coordinates in the static pose match your knowledge about experimental data collection (comparison to photos, etc.)?

Inverse Kinematics

  1. If you are using any coordinates from a motion capture system, do the definitions match your model?
  2. Is the maximum marker error less than 4 cm?
  3. Is the RMS error less than ~2 cm?
  4. Is there data for similar motions in the literature or other past studies? Are your results within 1 standard deviation?

Inverse Dynamics

  1. Are there any large or unexpected forces at the pelvis (how large)?
  2. Is there data for similar motions in the literature or from other past studies? Are your results within 1 standard deviation?

Static Optimization

  1. Are there any large or unexpected residual actuator forces?
  2. Find EMG or muscle activation data for comparison with your simulated activations. Do the timings of muscle activations/deactivations match? Are the magnitudes and patterns in good agreement?

RRA

  1. Is the RMS difference between experimental and simulated joint angles less than 2-5º (or less than 2 cm for translations)?
  2. Are the peak residual forces less than 10-25 N? Are the RMS residual forces less than 5-15 N?
  3. Are the peak residual moments less than 75 Nm? Are the RMS residual moments less than 50 Nm?
  4. Are the residual moments reduced 30-50% compared to inverse dynamics?
  5. Is there joint torque data for similar motions in the literature or from other past studies? Are your results within 1 standard deviation?

CMC

  1. Are the peak reserve actuator torques less than 10% of the corresponding peak joint torques?
  2. Is the RMS difference between experimental and simulated joint angles less than 2-5º (or less than 2 cm for translations)?
  3. Are the peak residual forces less than 10-20 N? Are the average residual forces less than 5-10 N?
  4. Are the peak residual moments less than 75 Nm? Are the average residual moments less than 50 Nm?
  5. Find EMG or muscle activation data for comparison with your simulated activations. Do the timings of muscle activations/deactivations match? Are the magnitudes and patterns in good agreement?

Extending the Capabilities of OpenSim

Unable to render {include} The included page could not be found.

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.