OpenSim has a broad range of capabilities for generating and analyzing musculoskeletal models and dynamic simulations. This chapter provides an overview of these capabilities and a list of resources to find more information about each component of the OpenSim workflow.

The OpenSim Model

One of the major goals of the OpenSim project is to provide a common platform for creating and sharing models of the musculoskeletal system. Thus, the first component of any analysis is an OpenSim model. An OpenSim model represents the dynamics of a system of rigid bodies and joints that are acted upon by forces to produce motion. The OpenSim model file is made up of components corresponding to parts of the physical system. These parts include bodies, joints, forces, constraints, and controllers.

Additional information is also available in the section on OpenSim Models. A large repository of existing models is available at SimTK.org (https://simtk.org/home/nmblmodels). This library includes models of the lower extremity, head and neck, spine, and wrist. We encourage you to contribute your own models to this library to enable other researchers to build on your work and further advance the field. For example, in a model used for simulation of human walking, the bodies represent the geometry and inertial properties of the body segments. The joints specify the articulations at the pelvis, hip, knee, and ankle joints, while a constraint could be used, for example, to couple the motion of the patella with the model’s knee flexion angle. The forces in the model include both internal forces from muscles and ligaments and external forces from interaction with the ground. Finally, the model’s controller determines the activation of muscles (e.g., computed muscle control).

Importing Experimental Data

In many cases, you will use OpenSim to analyze experimental data that you have collected in your laboratory. This data typically includes:

• Marker trajectories or joint angles from motion capture
• Force data, typically ground reaction forces and moments and/or centers of pressure
• Electromyography

See Preparing Your Data for detailed information about preparing and importing your experimental data.

Scaling

If you are using a generic model from the existing library of models, the next step is to scale the model to match the experimental data collected for your subject—functionality provided by the Scale Tool in OpenSim. The purpose of scaling a generic musculoskeletal model is to modify the anthropometry, or physical dimensions, of the generic model so that it matches the anthropometry of a particular subject. Scaling is one of the most important steps in solving inverse kinematics and inverse dynamics problems because these solutions are sensitive to the accuracy of the scaling step. In OpenSim, the scaling step adjusts both the mass properties (mass and inertia tensor), as well as the dimensions of the body segments.

See the section on Scaling for more details. Tutorial 3 - Scaling, Inverse Kinematics, and Inverse Dynamics includes an example using the Scale Tool. This tutorial is also accessible from the OpenSim application Help menu.

The Inverse Problem

OpenSim enables researchers to solve the Inverse Dynamics problem, using experimental measured subject motion and forces to generate the kinematics and kinetics of a musculoskeletal model (see figure below).

In inverse dynamics, experimentally measured marker trajectories and force data are use to estimate a model’s kinematics and kinetics.

Inverse Kinematics

The Inverse Kinematics (IK) Tool in OpenSim finds values for the generalized coordinates (joint angles and positions) in the model that best match the experimental kinematics recorded for a particular subject (see figure below). The experimental kinematics targeted by IK can include experimental marker positions, as well as experimental generalized coordinate values (joint angles). The IK Tool goes through each time step of motion and computes generalized coordinate values which position the model in a pose that "best matches" experimental marker and coordinate values for that time step. Mathematically, the "best match" is expressed as a weighted least-squares problem, whose solution aims to minimize both marker and coordinate errors.



Experimental markers are matched by model markers throughout the motion by varying the generalized coordinates (e.g., joint angles) through time. See Inverse Kinematics for full documentation on running IK in OpenSim. Tutorial 3 - Scaling, Inverse Kinematics, and Inverse Dynamics walks through an example of using Inverse Kinematics for human walking.

Inverse Dynamics

Dynamics is the study of motion and the forces and moments that produce that motion. The Inverse Dynamics (ID) Tool determines the generalized forces (e.g., net forces and torques) that cause a particular motion, and its results can be used to infer how muscles are actuated to generate that motion. To determine these internal forces and moments, the equations of motion for the system are solved with external forces (e.g., ground reaction forces) and accelerations given (estimated by differentiating angles and positions twice). The equations of motion are automatically formulated using the kinematic description and mass properties of a musculoskeletal model in Simbody™.

See Inverse Dynamics for full documentation on running ID in OpenSim. Tutorial 3 - Scaling, Inverse Kinematics, and Inverse Dynamics walks through an example of using ID for human walking.

Static Optimization

Static optimization is an extension of inverse dynamics that further resolves the net joint moments into individual muscle forces at each instant in time based on some performance criteria, like minimizing the sum of squared muscle forces. See Static Optimization for more details.

The Forward Problem

OpenSim is also capable of generating muscle-driven forward simulations of gait and other movements (see figure below).

In a forward dynamic simulation of motion, simulated muscle excitations are used to drive the motion of a model to follow some observed movement.

The Forward Dynamics Tool takes a set of controls (e.g., muscle excitations) to drive a model's motion by integrating forward in time. Typically, muscle excitations are generated using the Computed Muscle Control (CMC) Tool. As a pre-cursor to running CMC, the Residual Reduction Algorithm (RRA) is used to minimize the effects of modeling and marker data processing errors that aggregate and lead to large nonphysical compensatory forces called "residuals". Specifically, RRA 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. Thus, the typical workflow for generating a muscle-driven simulation after importing experimental data is Scale → IK → RRA → CMC → Forward Dynamics (see figure below).

Full documentation of Forward Dynamics, the Residual Reduction Algorithm, and Computed Muscle Control is available in the respective sections.

Analyzing Simulations

Answering your research questions often requires delving deeper into the details of a simulation. Thus, OpenSim includes an Analyze Tool that allows you to estimate, for example, muscle fiber or tendon lengths during a motion, or the loads on the knee joint. The Analyze Tool enables you to analyze a model or simulation based on a number of inputs that can include time histories of model states, controls, and external loads applied to the model. The following analyses are available in OpenSim:

1. Body Kinematics: Reports the spatial kinematics (position and orientation, linear and angular velocity, linear and angular acceleration) of specified bodies for the duration of the analysis.
2. Point Kinematics: Reports the global position, velocity and acceleration of a point defined local to a body during a simulation.
3. Muscle Analysis: Reports all attributes of all muscles (including fiber length and velocity, normalized fiber length, pennation angle, active-fiber force, passive-fiber force, tendon force, and more).
4. Joint Reactions: Reports joint reaction forces. These are forces that enforce the motion of the joint. The force applied to either parent or child and expressed relative to ground, parent or child can be reported.
5. Induced Acceleration: Computes accelerations caused or "induced" by individual forces acting on a model—for example, the contribution of individual muscle forces to the mass center acceleration.
6. Force Reporter: Reports all forces acting in the model. For ligaments and muscles, the tension along the path is reported; for ideal actuators, the scalar force or torque is reported. For all other forces, the resultant body forces (force and moment acting at the center of mass of the body) are reported. For example, contact forces from an ElasticFoundationForce element yield the resultant body force on the contacting bodies separately, expressed in the ground frame. For constraints, the same is true, except the forces are expressed relative to the most distal common ancestor body. Whenever a constraint involves ground, this is the ground body; however, if (for example) a model of the arm has a hand with fingers touching via a point constraint, then the forces are expressed in the nearest common ancestor, which would be the palm (if modeled as a single body).

More details about the analyses available in OpenSim are available in the sections Analyses, Joint Reactions Analysis, and Induced Acceleration Analysis.

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.

gait2345_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). 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 = λ² 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).

gait2345_RRA_ControlConstraints.xml: Contains limits on the RRA actuators. The actuator constraints file specifying the maximum and minimum "excitation" (i.e., control signal) for each actuator. A few key considerations:

1. 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.
2. Joint torques (and muscles) have a maximum magnitude of 1.
3. 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.

gait2345_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_forces.sto: Actuator forces and torques (i.e., joint torques corresponding to adjusted kinematics).

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

Best Practices and Troubleshooting

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?

Overview

OpenSim provides several mechanisms for extending its existing capabilities by either adding new model elements, computing new quantities, or computing existing quantities in a new way. For example, you may want to model the drag acting on bodies moving through a fluid, which OpenSim does not provide. Another example is being able to extract the linear and angular momenta of the model during a simulation. In order to extend OpenSim, it is important to know what functionality exists and have a sense of where to add new functionality.

Organization of OpenSim

OpenSim is built on the computational and simulation core provided by SimTK. This core includes low-level, efficient math and matrix algebra libraries, such as LAPACK, as well as the infrastructure for defining a dynamic system and its state. One can think of the system as the set of differential equations, and the state as its variables.

Empowering the computational layer is Simbody^TM, an efficient multibody dynamics solver, which provides an extensible multibody system and state. The OpenSim modeling layer maps biomechanical structures (bones, muscles, tendons, etc.) into bodies and forces so that the dynamics of the system can be computed by Simbody.

The three interface layers of OpenSim built on SimTK:

OpenSim is essentially a set of modeling libraries for building complex actuators (e.g., muscles) and other forces (e.g., contact), and enabling the motion (kinematics) of highly articulated bodies (bones). Actuators can then be controlled by model controllers (e.g., Computed Muscle Control) to estimate the neural control and muscle forces required to reproduce human movement. An analysis layer is equipped with solvers and optimization resources for performing calculations with the model and to report results. At the highest level, these blocks are assembled into specialized applications (ik.exe, forward.exe, analyze.exe) to simulate and analyze model movement and internal dynamics. The OpenSim application is a Java-based program that calls Tools, Models, and underlying computations in SimTK to provide an interactive graphical user interface (GUI).

OpenSim Model and ModelComponents

The job of an OpenSim::Model is to organize (hierarchically) the pieces (components) of a musculoskeletal system and to create a representative computational (mathematical) system that can be solved accurately and efficiently using Simbody and the flat SimTK::System framework.

Organizational Context vs. Computation

By separating the contextual organization of a model from its computational representation, OpenSim can exploit the conceptual benefits of hierarchically-organized models and software without sacrificing computational efficiency. One can then think of the system as the set of system equations, while the state is a coherent set of system variable values that satisfies the system equations. Model components know about the parts they add to the multibody system (e.g., another rigid body, a force, or a constraint) and are free to mix and match. For example, a Coordinate component knows how to access its underlying degree-of-freedom value, velocity, and even its acceleration, provided the system has been "solved" for accelerations. A Coordinate also adds different constraints to the underlying system, in the case that Coordinate is locked or if its motion is prescribed. It provides context to organize locking constraints with the Coordinates being locked, but computationally it is just another constraint equation. The Coordinate, therefore, acts to manage the bookkeeping (which degree-of-freedom, constraint, etc.) and provide an interface that has context.

OpenSim Model and its ModelComponents

All model components in OpenSim have a similar responsibility to create their underlying system representation (createSystem()). A setup() method ensures that a model is appropriately defined (e.g., a Body is being connected to a parent that exists) before creating the system. Two additional methods allow the ModelComponent to initialize the state of the system (from default properties) and also to hold the existing state in the ModelComponent's defaults. For example, a Coordinate's default may indicate that it should be locked, in which case its initState would set the state of its underlying constraint as "enabled". Similarly, after performing an analysis to find the coordinates to satisfy a static pose, calling setDefaultsFromState(state) will update the Coordinate's default values for the coordinate value from the desired state. Next time the model is initialized, it will be in the desired pose.

OpenSim Application Programming Interface (API)

In order to build custom components, it is necessary to have a general understanding of which objects (classes) are responsible for which actions/behaviors. The functions (methods) that OpenSim's public classes provide (that other applications/programs can call) define its Application Programming Interface, or API.

We have already seen four methods that a model component must implement to behave as a ModelComponent in OpenSim. This defines the ModelComponent interface. Each type of ModelComponent, in turn, specifies additional methods in order to satisfy that type of component. For example, a Force in OpenSim must implement a computeForce() method (in addition to the ModelComponent methods), a Controller must implement computeControls(), etc. The set of all Classes and their interfaces defines the OpenSim API.

The OpenSim API is undergoing rapid development and improvement. We, therefore, rely on Doxygen to automatically generate .html documentation of the latest source, which describes the classes that are available and the accessible methods. The Doxygen pages can be viewed using a web browser and are available with your OpenSim installation in: <OpenSim_Install_Dir>/sdk/doc/index.html. This provides the latest organization of the available classes where one can see the list of available controllers, for example.

Example Doxygen documentation for available controllers:

What is an OpenSim plug-in?

When creating a new component (e.g., a force controller) or a new analysis, you may want to include it in an existing model, run it with existing tools, and/or share your contribution with colleagues. An OpenSim plug-in is a way of packaging your code in a dynamically linked library so that an existing OpenSim application can recognize it, load it, and make your code "runnable". For an example of creating an analysis as a plug-in, see <OpenSim_Install_Dir>/sdk/examples/plugin.

What is an OpenSim "main" program?

A main program in C/C++ results in a standalone executable that you can run from a command prompt or by double-clicking in Windows. All C/C++ programs have a main() function, which can be as simple as printing "Hello World", or it can invoke several libraries to produce complex applications (e.g., Microsoft® Word and Excel). By including the OpenSim libraries, your main program can call the OpenSim API, and you may also include any other (C++) libraries that provide additional computational and/or visualization resources. Main programs are extremely flexible, but they are particularly useful for streamlining/automating processes independent of the GUI. For example, ik.exe, id.exe, and cmc.exe (available with the OpenSim distribution) are main programs that take setup files and perform tasks related to the OpenSim workflow. Alternatively, users have created their own main programs to systematically scale strengths of all muscles in a model, run forward simulations with their own controllers, perform design optimizations, etc. An advantage of a main program (compared to a plug-in) is that any classes you define in the project are immediately useable by your program. This can make prototyping and testing of your new component or analysis faster and easier without having to wrap, load, and call your plug-in from the GUI.

OpenSim Developer's Guide

The developer's guide provides a step-by-step example of calling the OpenSim API to build a model, including muscles and contact forces, and to perform a simulation in a main program. Please refer to the OpenSim Developer's Guide for more details.

Command-line Utilities

All of the OpenSim Tools are available as command-line utilities that take as input the same setup (or settings) file loaded into or saved from the OpenSim GUI application. For example, to perform Inverse Kinematics from the command line (the Command Prompt in Windows), one can execute the following command:

ik –S arm26_Setup_InverseKinematics.xml

Similarly, these command line arguments work for CMC or any other tool, with the complete set of command-line executables available in <OpenSim_Install_Dir>/bin. In addition to the –Setup option, there are –Help, –PrintSetup and –PropertyInfo options. Help provides this list of options. Print Setup prints a default setup file for that Tool with all available properties (XML tags) for Tool settings.

The –PropertyInfo option can be a very handy resource to obtain information about existing settings for Tools and ModelComponents, including the XML tags needed in the model and/or setup file. This is the same information listed in the "Available Objects…" panel under the Help menu in the OpenSim GUI. Executing ik –PI lists all the available classes (components, analyses, utilities and tools) available in OpenSim. For more information about a particular object, such as adding a point constraint to the model, executing

ik –PI PointConstraint

yields:

PROPERTIES FOR PointConstraint (5)
1. isDisabled
2. body_1
3. body_2
4. location_body_1
5. location_body_2

The information returned lists the properties for defining a point constraint in OpenSim.

MATLAB Utilities for Data Import

There are several MATLAB® scripts for reading .trc, .c3d, .mot, and .sto files into MATLAB and writing out the data file formats required by OpenSim. Scripts provided by the Neuromuscular Biomechanics Lab at Stanford University are available on the OpenSim Utilities project on SimTK.org: https://simtk.org/home/opensim-utils. Additional utilities by OpenSim users are posted on SimTK.org and can be found using the search tool on SimTK.org.