Extending OpenSim’s Capabilities

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.