The OpenSim API

Organization of the OpenSim API

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 ^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 Simbody users guide can be found  and can help new users to understand the structure of OpenSim.

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).

System, Study and State

Simulations are a product of a System, Study and States. A System contains models of physical objects and is a mathematical representation of the physical world. Each Subsystem specifies the set of behaviors (variables) whose values can affect the overall System behavior. The System is made up of a number of Subsystems. The values of the these variables are stored within the State. The State object contains everything variable about the System. Time, position, velocity and excitation are all examples of states. Each Subsystem can have its own States along with the System itself.  Finally, a Study couples a System and one or more of its states, and represents a computational experiment intended to reveal something about the System. Inverse Kinematics for example is a Study of a models (Systems) set of generalized coordinates (States) that are required to minimize marker tracking error. By design the results of any study can be expressed as a state value or set of state values which satisfies some pre-specified criteria, along with results which the System can calculate directly from those state variables. Such a set of state variables is often called to as a trajectory.

OpenSim Model and Model Components

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. The model can therefore be viewed as a structure of many components, all of which can contribute to the state. Model components have knowledge about the parts they add to the multibody System (e.g., rigid bodies, 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. The States from the components are calculated in order going from time to acceleration. Each new State is used as an input for the System at the next point in time, thereby calculating a new set of States and so on and so on until the Study is over. The process of taking a new set of States and performing the the computations that those new values enable is known as realize.

All model components in OpenSim have a similar responsibility to add their underlying system representation (addToSystem()) to the underlying Multibody system. A connectToModel() method ensures that a model is appropriately defined (e.g., a Body is being connected to a parent that exists) before adding the body to 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 properties, such as its initial conditions. For example, a Coordinate's default may indicate that it should be locked, in which case its initStateFromProperties 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 setPropertiesFromState(state) will update the Coordinate's default values (which are properties) for the coordinate value from the desired state. Next time the model is initialized, it will be in the desired pose.

The figure above shows the 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.

Classes and Objects 

		Systems and Studies are defined and built through the interaction of numerous OpenSim classes. Their Objects (components) inherit the properties of their parent classes as well as any dependent classes. Using computer science methods to define the relationships between classes and objects (described in brief here ), we see that all components are built directly from parent Classes. Whether it be adding new components or altering characteristics of existing components, an interaction with either the Class or Object itself is required. Each Class has a constructor method that defines the ways a object can be built from that class. XML files are a convenient way of storing the characteristics that a class can use to generate an object. They provide a method for storing, editing and sharing the variable information for an objects construction. Their are a number of other methods for constructing Objects that can be found on each classes Doxygen page. The created Objects (components) can then be amalgamated to form the model.

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.