New Features in OpenSim 2.4

OpenSim 2.4 includes several improvements to the functionality, usability, and visualization abilities of the software package. We have also added new documentation.

Functionality Improvements

• The quality of results of CMC in 2.4 matches or exceeds results from 1.9.1. Version 1.9.1 of OpenSim had a bug where the user setting for the optimizer convergence criterion was not respected and a default of 1e-6 was being used. In versions 2.0 and later, this bug was corrected, but setup files were not modified to correspond to the default settings. As a result, in versions 2.0 and later, CMC was not converging to solutions of adequate quality when users specified a convergence criterion near 1.  This was often the case, since a criterion near 1 was the setting that was shipped with previous gait23 models and other examples. In OpenSim 2.4, old settings are ignored and default settings are used. It is not recommended that users deviate from the default settings, but in some cases, alternate settings may be required due to cost function scaling or the complexity of the model. The new setting names and their default values are: <numerical_derivative_step_size> 1e-4 and <optimization_convergence_tolerance> 1e-4.  A related issue is the flag for maximum number of iterations. This flag set to 100, for example, may be too small for models with many actuators and tighter convergence tolerance. We recommend that users set <optimizer_print_level> to 1. If you are seeing the optimizer reach the maximum number of iterations, then increase it. Reaching the order of 1000 optimizer iterations can be a sign of an unreachable solution and may occur in instances where the model is under-actuated. 

• Faster and more robust tools for performing inverse kinematics and inverse dynamics. The tools for conducting inverse kinematics and inverse dynamics analyses are some of the core capabilities used by OpenSim users of all types. We redesigned the algorithms underlying these tools, which led to several improvements. First, the new tools are approximately 5X faster, depending on tolerances and the properties of the system being analyzed. Second, the new tools rely on generic solvers that provide a robust programmatic interface for customizing and embedding inverse kinematics and inverse dynamics in user code (components or programs) and future analyses.

• More flexible format for applying external loads to a model. Users now have greater freedom in applying forces from external measurements. This allows users to simulate forces beyond the traditional foot-floor interaction seen in human gait, enabling, for example, simulation of ambulation with walkers and of climbing where forces are applied at the hands.

• Tighter integration of OpenSim and the underlying SimTK/Simbody computation layer and upgrade to Simbody 2.2. This integration allows users and OpenSim developers to access the capabilities for system assembly provided by Simbody. It also increases the speed of generating simulations in OpenSim by leveraging the algorithmic advances made to Simbody. The OpenSim code base also became more streamlined and easier to maintain by removing functionality that is now performed more efficiently by Simbody.

• RRA and CMC no longer require control constraints. The max and min control values for an Actuator are now used by default. If control constraints are provided then they take precedence over the actuator limits.

• Controllers can be disabled in the model (.osim) file as well as through the API. Like Forces and Constraints, every Controller has a corresponding <isDisabled> XML tag as part of a model or setup file that includes a controller. The default value is false (not disabled). The corresponding API call to disable a controller is setDisabled(bool).

• Ability to report model marker locations resulting from your inverse kinematics solution. This enables you, for example, to plot model versus experiment trajectories and compute per marker RMS over a trial. In the inverse kinematics setup file, add the <report_marker_locations> tag and set its value to true. This will output an ik_model_marker_locations.sto file.

• Ability to add a RigidTendonMuscle to your model. Stiff musculotendinous dynamics (due to relatively low muscle forces and high tendon stiffness) leads to poor numerical integrator performance and slow simulations. A RigidTendonMuscle enables you to use a model with a rigid tendon so that the total length change of a muscle-tendon actuator is due only to muscle fiber length changes, which eliminates tendon dynamics completely. This can result in considerable speed up especially for muscles that have short and/or stiff tendons (common in the upper-extremity).

• ModelComponent API for adding states and cache variables. The Model Component API is the underlying interface for defining all the parts (components) of a musculoskeletal model. This interface that allows users of the OpenSim API to augment the internal dynamics of any existing component (e.g. a body, joint, or muscle) or specify the dynamics of any new component they add to the musculoskeletal system being simulated and to specify their states (e.g. muscle activations,fiber lengths, etc.). The software platform's solver tools (e.g. integrators) can then determine how these system states change over time in a simulation. The ability to define and add cache variables improves computational speed by enabling API users to hold values that are computationally expensive to calculate, so that these expensive calculations are performed only once during the evaluation and reporting of system dynamics.

• ModelControls API for setting controls on a model. All of a model's controls are now a single integral entity (vector) in the model's underlying computational system. Controls are no longer managed in an ad-hoc manner by individual actuators that depend on control values. Now an actuator accesses its controls from the model's list of controls. This eliminates the handling of controls by actuators and simplifies the development of new actuators and controllers for API users. The new implementation is capable of scaling up to meet the demands of more complex physiological muscle models with two or more control parameters, such as intensity and rate of motor-unit recruitment. Providing a simpler and more powerful interface has also accelerated the development of a Matlab-Simulink wrapper for OpenSim models, which allows developers to access the controller design capabilities provided by the Simulink package in Matlab.

• Streamlined definition of muscle models. We reorganized the way that models of muscle actuators are defined in OpenSim by simplifying the base Muscle class and introducing several intermediate classes that serve as reusable modules that users can build upon in order to define their own muscle models.

• You can report induced constraint reaction forces from an induced accelerations analysis. The reaction forces (and torques) on the two bodies connected by the contact constraint are reported for each body and expressed in ground. The reaction forces reported are due to individual force contributors corresponding to the induced accelerations. Add the <report_constraint_reactions> tag to your induced accelerations setup and set the value to true to enable the reporting of constraint reaction forces.

• The JointReaction analysis is augmented to also report the location of the internal joint force and moment.  We report the location as a position vector expressed in the same reference frame as the joint force and moment.

Usability

• The Residual Reduction Algorithm (RRA) is now a separate tool in the GUI with a streamlined interface

• Ability to show the XML representation of "Available Objects" that can be used to extend models or define setup files (in the latest format of the software). To see the complete list of available objects, select Help->Available Objects… from the OpenSim menu and this will open a panel with a pull down list of every object (by class name). Selecting an object in the list will display its properties in the space below the list.

• Editing muscle excitations with the Excitation Editor is easier due to several usability improvements.

• Convert tool to update setup, model, and storage files generated in earlier versions of OpenSim to the latest version. See the Upgrade Notes for more information.

Visualization

• You can display the center of mass of the model and individual bodies. In the GUI, right click on the set of Bodies in the Navigator and select "Show Mass Center" for the entire model (green checkered sphere). Select individual bodies to display their individual center of mass locations as smaller green spheres.

• Ligaments and springs now have a visual representation in the GUI.

Bug Fixes

• A problem was fixed with the elastic foundation model in the case where both contacting objects are meshes. We fixed a bug in our underlying ElasticFoundation force for modeling mesh based contact and added more comparisons between the mesh-based (ElasticFoundation) and the well-established Hertz theory. This has lead to significant accuracy and performance improvements using ElasticFoundation.

• A bug in internal coordinate joint (mobilizer) reactions torques was corrected in the underlying Simbody dynamics engine. In the cases where the joint and body frame were not coincident, the reaction torque was likely to be incorrect.

Documentation and Examples

• We have updated the User's Guide, Developer's Guide, and tutorials to be compatible with OpenSim 2.4

• Chapter 22 of the User's Guide describes how to conduct an induced acceleration analysis. Since OpenSim 2.0, we have shifted toward testing and support of the Induced Acceleration Analysis (IAA) as an alternative to Perturb. In our testing, IAA gives better results (i.e., better superposition) for determining muscle contributions to mass center and joint accelerations for both walking and running, and is more than 50X faster than Perturb.

• We have added a chapter to the Developer's Guide that describes how to get started as an OpenSim developer.

• Chapter 16 of the User's Guide now documents how to use the new, flexible tool for associating external forces with a model. An ExternalLoads object connects a data file containing many external forces to individual external forces that can be applied to different bodies, locations, etc. of a model.

• A simple model of the lower extremity and step-by-step guide to help you gain hands-on experience with the OpenSim simulation pipeline. You can find this example in the examples folder. Step by step instructions are available on the OpenSim SimTK project page under "Documents".

• A new API example for adding a Force as a plugin. See the Developer's Guide for instructions on how to find and get started on this and other API examples.