 |
API
4.2
For MATLAB, Python, Java, and C++ users
|
|
API
4.2
For MATLAB, Python, Java, and C++ users
|
This guide is recommended for those who desire in-depth knowledge of musculoskeletal modeling and simulation with OpenSim and wish to use the Application Programming Interface (API) to create or contribute novel models or algorithms not currently supported by the OpenSim application. The guide also expects that you are familiar with multibody dynamics and biomechanics.
The OpenSim software has a variety of interfaces: GUI, command line, XML, Python scripting, MATLAB scripting, and C++. This guide is designed for developers using the last 3 of these interfaces. Programming experience in C++ will be helpful in understanding the API architecture, but we have tried to make this guide accessible to those with only Matlab or Python experience, as well.
The purpose of OpenSim is to provide anyone interested in human or animal movement with high-performance software to create computer models of the neuromusculoskeletal system, analyze experimental movement data, and simulate movement dynamics to gain insights about the anatomy, physiology, mechanics and control of movement. The software is used in a variety of applications, including neuroscience research, biomechanical analysis, surgical design, and ergonomic analysis, and bioengineering education, just to name a few. Our goal is to provide physically accurate models and tools that provide a solid foundation for scientific inquiry.
The OpenSim Application Programming Interface (OpenSim API) serves the OpenSim application, with its graphical user interface (GUI), and also enables advanced users and developers to write their own programs to extend the capabilities of OpenSim, including customized analyses and workflows, Components, and OpenSim plug-ins.
The ethos of the OpenSim API is that the code is modular, reusable, and easily extensible. To enable the assembly of neuromusculoskeletal systems from constituent biomechanical elements, OpenSim has adopted the composite design pattern to systematically define, organize, and manage the elements (components) of a neuromusculoskeletal system.
OpenSim is built on SimTK computational and simulation libraries that provide 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, 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 here and can help new users to understand the structure of OpenSim.
OpenSim (opensim-core) is essentially a set of libraries for building simple to complex musculoskeletal systems with complex actuators (e.g., muscles) and other forces (e.g., foot-ground contact), and enabling the motion (kinematics) of highly articulated bodies (bones). Torque, linear and physiological actuators such as muscles can 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 algorithms for performing calculations with the model and to report results. At the highest level, these blocks are assembled into specialized applications (e.g., the opensim-cmd command-line application) 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 via an interactive graphical user interface (GUI).
In OpenSim, a Component is a computational model element that describes some physical phenomenon. As a neuromusculoskeletal simulator, OpenSim components represent bodies, joints, muscles, and other physical structures, as well as sensors, controllers, and feedback circuits that describe human and animal dynamics. The purpose of a Component is to both capture the physical phenomenon (degrees-of-freedom, constraints, actuation, control) of interest and to enable the systematic composition of complex behaviors (dynamical models) from simpler components.
To illustrate this point, think of two biomechanists, Gary Gait and Norma Knee. Gary is interested in the actions of individual muscles during gait and other forms of locomotion. Norma wants to understand how loads are distributed within the knee and their effect on cartilage wear and health. For Gary, a model represents a patient’s musculoskeletal dynamics and is capable of muscle-driven gait that reproduces human-like performance. In Norma’s case, a model consists of a femur, a tibia, a patella, contact between articulating surfaces, ligaments, and muscles, so that she can compute contact forces. Gary and Norma’s "models" may have similar complexity but their concepts of a model are fundamentally different (i.e., whole body vs. a knee). Gary may model knees as pin joints and attain reasonable answers about the action of leg muscles during different types of gait. Norma cannot justify the same simplification. A more accurate knee model may result in more realistic muscle forces for Gary, and simulated muscle forces (that reproduce human gait) may provide better boundary conditions for Norma’s estimates of knee loads. However, for these researchers to benefit directly from each other’s work, their models must be interoperable. In order for their models to talk to one another and be systematically combined, both models must have constructs in common. This modularity and interoperability is the main purpose of the Component API.
Figure 1. Overview of the OpenSim Modeling Framework. Aspects of the musculoskeletal system (Physical System) such as bones, joints, and muscles, and its neurocontrol composed of spinal circuits, muscle spindle and Golgi tendon organs are represented as Components in the Modeling Framework. The specification of the types and arrangement of Components in a Model reflect the physical system being modeled and is the main task of the Modeler. From the assembly of Components (the Model) the corresponding computational System (system of equations readily solved by a computer) is automatically created and ready for numerical simulation and analysis. All System unknowns (variables) and their values are in the State.
To get a taste of what the OpenSim API looks like, here is a complete example of building and simulating a simple arm whose elbow is actuated by a muscle (this example is in C++; you can find a Python version at Bindings/Python/examples/build_simple_arm_model.py):
This code produces the following animation:
Simple Arm Model. A two-body pendulum with single muscle actuator.
and prints the following information to the console:
A SimTK::System is the computational (mathematical) system of equations that represents the model dynamics, in a way that a computer can solve. In OpenSim, the model is formed by rigid bodies (e.g. bones) and connected by joints. A State is a set of values for all the unknowns (variables) of the System’s equations. The State contains all values necessary to fully evaluate the system of equations. The SimTK::State includes time and the generalized coordinates (Q; the joint angles and displacements) and the generalized speeds (U) of the multibody system. Any Component can add to the System (and State). For example, Muscles add their activation and fiber length variables to the State with their corresponding differential equations in the System. An OpenSim Model generates a System in order to perform calculations and solve for unknowns of interest to the modeler.
Figure 2. An illustration of the difference between the model's System and a State object. Static model parameters (gravity, mass, inertia, muscle-tendon properties, etc.) are accessible directly via the Model, while methods that return state-dependent values (mass center position, muscle fiber velocity, etc.) require a State object argument.
A StatesTrajectory is a sequence of States that satisfy the dynamical system of equations through time.
Any method in OpenSim that performs a calculation that doesn’t simply depend on constants takes a SimTK::State object as the first argument.
Object is the base class for all OpenSim Components, general containers like Set, and Tools that require serialization - that is having their attributes written out to file. Objects use Properties to serialize (write to file) and deserialize (read from file) their attributes, which are parameters and settings that define the behavior of the Object.
A Component is the basic "unit" of modelling and computing in OpenSim. It is our abstraction to capture a fundamental unit of computing and/or modeling used to compose a Model and form its computational system of equations. It is the base class that provides the supporting infrastructure for building up a hierarchically structured model with interconnections and numerous inputs and outputs, but is represented by a single computationally efficient (mathematical/numerical) system. That computational system is a SimTK::MultibodySystem and it is the computer implementation (think system of equations) of the multibody kinematics and dynamics plus any additional dynamics (ordinary differential equations, e.g. muscle activation dynamics) that need to be solved simultaneously. Any conceptual element that has to compute something typically requires the System and must be a Component in OpenSim. Component also provides the resources for reading and writing (also known as serializing, which it inherits from Object) the attributes/parameters that define the behavior of the component and adding in its dynamics (equations). The serializable attributes of a Component are called properties in OpenSim. 
Figure 3. Illustration of a generic component object, with property, input, output, and socket attributes.
A Component has the following defining attributes:
The common task for a Component (as part of a Model) is to make its contribution to the System (e.g. when Model::initSystem() if called). When the underlying System is built all the variables in the system equations appear in the State. As a unit of computation, the Component has the following computational attributes:
A Component encapsulates (all or part of the) system dynamics (of a model or element of a model) and provides (computes) values of interest. A component adds its dynamics and allocates necessary resources (state, cache, and other variables). It defines parameters (see Properties below) that specify its behavior/function and defines dependencies on any other Components (see Sockets below) via its Inputs and Outputs.
Components of a Model form a rooted directed tree topology of ownership (Components own and know about their subcomponents). Subcomponents of a component are the descendants in the tree. A root component (the top level Model) contains all the necessary Components to define the System. Components in the tree are uniquely identified by their full path name from the root (like a file path)
A branch in the ownership tree of a Model can be a complete subassembly representing a Device, a Leg or another FullBody Model.
This Component architecture means that:
You can add a subcomponent to another Component like so:
You can access existing subcomponents by name:
You can also iterate through all subcomponents of a component, recursively (e.g., each subcomponent’s subcomponents):
A Property is a fixed parameter of the model that does not change as a simulation evolves over time (i.e., is not part of or dependent on the State). A Property is a serializable (as XML) container of common data types (e.g., doubles and strings) as well as Objects (e.g., Functions) and even other Components which include properties themselves. A serialized model is the XML counterpart of the Model and its Components (as Properties).
For each Property, there are several methods for accessing or modifying the value of the Property. For example, a Body’s mass property has the following related methods:
The properties available in any class are listed on Doxygen, the GUI (Help > XML Browser), and the command line tool (opensim-cmd info Model).
An OpenSim::Socket defines the dependency of a Component on another Component (the "connectee"). The type of the connectee must be specified (e.g., Body, Joint). The dependency is specified by the connectee’s relative or absolute path name. A Socket finds and connects to the dependency when finalizeConnections() is called. The Socket provides the status of the connection (connected or not) and a reference to to the "connectee" when connected. All of a class’ Sockets are listed on the Doxygen page for that class.
You can query a Component for the number of Sockets it has, as well as for their names:
You can get a reference to a specific Socket of a Component using its name:
Once you have a Socket, you can see what types of Components it can be connected to, and if its connection is satisfied:
You can specify which Component the Socket should connect to. Here, we tell a Joint that its parent frame is Ground:
Alternatively, Components with Sockets provide convenience connectSocket_<name>() methods for connecting them:
To access the connectee itself, you can call the following method on the Component:
Inputs and Outputs specify data flow. An Output is any Component "computed" value as a function of the state. An Output is used to pass results of computation from one Component to any other, provide fast access to Component calculations (same as a member function call), and collect results without needing to know the details of the source Component and/or its methods.
Figure 4. Illustration of the relationship between outputs from one component to the inputs of another components. Here, the activation, force, and length outputs from Muscle object are wired to the inputs of a Reporter object, which then become easily accessible to the user after the simulation completes (see the "Reporter" section below).
An [Input](OpenSim::Input) is a "slot" that accepts an Output of a specified type. The Input verifies that the Output can be evaluated/consumed as an Input. Inputs allow for a Component to have dependencies on Outputs (that can come from any Component or user-specified Data) rather than a specific Component type (as specified by a Socket<C>).
An [Output](OpenSim::Output) is a value of interest generated by a Component (e.g. Muscle has Outputs for its fiber-length and its tension). Outputs are accessed by name and evaluated given a State. Outputs are typed by their value type (e.g. double, Vec3, SpatialVec, Vector).
The Input provides its status as being connected (to an Output) or not. Thus, if an Input is connected to an Output, the Input triggers the evaluation of the Output by the Component to which the Output belongs. If an Output is not needed by any Input it is never evaluated.
Vec3, Mat33, double, etc)All of a class’s Inputs and Outputs are listed on the Doxygen page for the class.
You can access the number of inputs a Component has, as well as their names:
Once you have their names, you can access a specific Input:
You can ask a specific Input for its data type and whether or not it is connected:
You can connect an Input to an Output like so:
If an Input is connected to an Output, you can ask for its value:
There are similar methods for Outputs:
List Outputs may have multiple Channels:
If so, then you could connect individual Channels to an Input:
If you have a List Input, then you can wire it to multiple Channels (from both one-value and list Outputs):
There are cases where an Input might need to "rename" an Output. For example, an InverseKinematics Solver could have a List Input for experimental marker locations, and could require its connectees to be named after markers in the Model. But say the experimental marker that corresponds to the Model’s "toe" marker is called "foot." One can "rename" an output using "annotations":
An Operator is used to describe a purely functional/mathematical Component. An Operator requires a set of one or more Inputs, it computes on them, and sends its results to a set of one or more Outputs. An Operator has no dependencies on other Components (i.e. Sockets) and does not require a Model to operate (just Inputs). Some examples are arithmetic operations (+,-,*,/), max/min, a delay, and de/multiplexer. They are useful for manipulating the Outputs of other Components, for example, to delay an Output or report its max or min value.
Note: OpenSim does not yet contain any built-in Operator components.
A Source is a category of components that serves as a source of Outputs (signals) to satisfy model Inputs and that does not itself have any Inputs.
TableSource is one such Component which holds a TimeSeriesTable (see below) and exposes a List Output which contains a Channel for each column of the table.
A Reporter collects the results of Model computations. It can take any Outputs from a Model (and its Components) as its Inputs. Whether it reports to the terminal, file, or a port is dependent on the concrete Reporter type. Reporters are templated on the datatype of the reported Output<T> type (i.e., a single Reporter can only output one type of data, such as double or Vec3), but there is no limit to the number of Reporters a Model can have.
Figure 5. Illustration of the Reporter class. As described previously, a Reporter uses inputs to accept quantities outputted from other components. Here, a TableReporter object accepts a Muscle object's quanities as inputs and internally store the data in a TimeSeriesTable. The data can then be accessed by outputting the data to a file (via a FileAdapter) or through the TimeSeriesTable directly.
A ModelComponent is the base type for all components that can be used to compose a Model. The most common types of ModelComponents are the following:
OpenSim contains built-in model components for each type above, but users can also create their own model components.
Frame is an OpenSim representation of a reference frame in which the spatial location and orientation of other Frames can be described. Every Model has a Ground frame in which all other Frames can be measured. A Frame consists of a right-handed set of three orthogonal axes and an origin point. Frames provide a convenient way to locate physical structures, such as joints and muscle attachments. Frames also provide a convenient basis for performing spatial calculations. For example, if your system includes contact, you might define a Frame that is aligned with the normal direction of a contact surface and whose origin is at the center-of-pressure. You can then easily report the contact forces normal to the contact surface and the location of the center-of-pressure, without repeatedly performing the transformations in your main or analysis code.
There are several types of Frames:
The following diagram illustrates how each type of PhysicalFrame might appear in a model.
(Note: "ComputedFrame" does not yet exist in OpenSim, but you could create it yourself!)
Every Frame is capable of providing its Transform (translation of the origin and the orientation of its axes) in the Ground frame as a function of the State and provides convenience methods for re-expressing vectors from one Frame to another.
It is perhaps less evident that Frames can be extremely useful for linking a multitude of reference frames together to form chains and trees. For example, a Frame to specify muscle attachments (M) and a Frame to specify a joint location (J) could themselves be specified in an anatomical Frame (A) defined by bony landmarks identified by surface markers or tagged on CT or MRI images. The body (B), to which the anatomical frame (A) is attached, can be thought of as a "Base" frame or a root of a tree from which a set of descendant frames arise. In particular, a Base frame and all its descendants have the property that they share the same angular velocity, since they are affixed to the same underlying Frame (in this case a Body).
Given this tree, both the muscle attachment points (in M) and the joint axes, J, change when the anatomical frame, A, changes with respect to the base, B, without requiring muscle attachments and joint axes to be manually adjusted. Consequently, a useful concept is that of a Base frame, and a Frame can always provide its Base frame. If a Frame is not affixed to another frame, its Base frame is itself.
A Point is an OpenSim representation of any location in space. Points can be used to define and compute the location of physical structures (such as points of constraints and points of muscle attachments). Points can also embody the results of spatial calculations. For example, if your system involves contact, you can define a Point that describes the location of the center-of-pressure as one element rolls over another.
A Point provides its location, velocity, and acceleration in the Ground frame as a function of the Model’s state, as long as the state has been realized to the appropriate stage (Position, Velocity, or Acceleration)
OpenSim Stations are Points defined in Euclidian space. They are defined with a three element column vector (Vec3), relative to their parent Frame. Stations are thus analogous to PhysicalOffsetFrames in that constraints and forces can be attached and/or applied to them.
DataTable is an in-memory storage container for data with support for holding metadata. DataTables provide a single, unified method for storing and accessing data, such as results generated by Components. Reporter and Source components may use DataTables internally. They provide fast access to numerical elements and to complete rows and columns of data, by index and by column names. DataTables are independent of any particular file format.
DataTables contain a single "independent" column and a set of dependent columns. The independent column can be any scalar data type (e.g., int, float, double). The dependent columns can be of any data type (double, Vec3, Mat33, SpatialVec, etc.). All of the dependent columns must be of the same data type. Each independent and dependent column, as well as the entire table, can contain metadata.
DataAdapter is an abstract class that defines an interface for reading and writing the contents of a DataTable.
The DataAdapter separates use of a DataTable from the various sources of data, including streams, files, databases, and devices. A DataAdapter is how you read from or write to different sources of data. Concrete classes handle the particular interface and format of a given data source.
FileAdapter offers an interface to read and write files through the following methods.
Based on the extension part of the filename, these methods invoke one of the following concrete FileAdapters to perform the read/write.
While it is possible to invoke the concrete FileAdapters above for reading data files, it is often more intuitive to think about what type of DataTable you want to read, rather than which Adapter class to use. Thus we provide constructors to create tables from files using the appropriate FileAdapters internally. For example, to read a TimeSeriesTableVec3 of marker data from a TRC file you can use:
A Solver is an abstraction to capture an algorithm/process to compute System unknowns of a Model. For example, the InverseKinematicsSolver operates on the System underlying a Model to determine the generalized coordinate (state variable) values that satisfy external measurements (Markers). The MomentArmSolver evaluates a muscle path to determine the effectiveness of a muscle to generate a generalized force about or along a coordinate.
The Manager currently serves as a "ForwardDynamics" Solver which integrates the System dynamics forward in time. We intend to provide a ForwardDynamicsSolver that returns a StatesTrajectory. In the meantime, you can generate a StatesTrajectory by implementing your own simulation function, like this:
The main task for Components (as part of a Model) is to generate a System. When the underlying System is built, all the variables in the system of equations appear in the State. A Component, therefore, is responsible for adding state variables to the system and providing access to those variables. The system can (and typically does) obtain default values for state variables from the Component’s properties.
OpenSim_DECLARE_PROPERTY macros, which you use to specify the name, type and description of the property. NOTE: your class automatically has get/set_<property_name>() methods when you apply the macro, and the properties and corresponding methods are inherited from its parent class. constructProperty_<property_name>() methods for each property you have declared and assign them default values in each constructor. If you have multiple properties and constructors it is convenient to create a function void constructProperties() as a private method that can be called from each constructor. OpenSim_DECLARE_SOCKET macro with the Socket name and type of the dependency. For example, a Joint has two sockets of type PhysicalFrame and their names are parent_frame and child_frame respectively. Sockets automatically generate properties with socket type and name as part of the XML tag. The expected XML value is the full path name of the dependency component. OpenSim can now check the existence of the dependency, and ensure it is of the correct type. If the dependency is not satisfied, OpenSim will provide meaningful error messages. OpenSim_DECLARE_OUTPUT macro with the name of the output, its value type, and the member function of your component that produces the value of the output. Similarly, use the OpenSim_DECLARE_INPUT macro to create a named slot for the Output of another component to plug in. All components are given the opportunity finalize their specification from their properties, which occurs during OpenSim::Component::finalizeFromProperties(). The base (Component) implementation also makes sure Components that are properties (e.g. a BodySet, JointSet) are included as subcomponents. As subcomponents, any actions invoked on the top-level component invokes its subcomponents, automatically. For example, finalizeFromProperties() is invoked on the subcomponents. To add custom functionality to your Component:
OpenSim::Component::extendFinalizeFromProperties() to perform any data loading or conversions that the Component will need during a simulation. For example, the Body component has a property that contains six numbers intended to be the moments and products of inertia of a physical body. Body overrides extendFinalizeFromProperties() to convert those 6 numbers to a proper SimTK::Inertia, which will throw pertinent exceptions about the validity of those numbers to form a physical inertia tensor. Note, that the base Component::finalizeFromProperties() marks the component as being up-to-date with its properties. We indicate virtual methods intended for Component writers to extend the basic operations of a Component by using "extend" in the virtual function name. void OpenSim::Component::extendAddToSystem(SimTK::MultibodySystem& system) const and add Simbody elements to the System. It is important to note that you must maintain the underlying indices so your component can access the Simbody elements later if necessary. Classes like Joint, Constraint, and Force provide methods to help you create new types of these Components and manage the indices for you. Ask for help if you want to expose state variables allocated by underlying Simbody elements.extendAddToSystem() by invoking addStateVariable(). If you can express your component dynamics as a function of the state: zdot = F(state), then z is the state variable added by your component.void OpenSim::Component::computeStateVariableDerivatives(const SimTK::State& s) const, which you override.OpenSim::Component::addDiscreteVariable() and must be set before the dynamics of the Component are realized. void OpenSim::Component::extendInitStateFromProperties(SimTK::State& state) const, which you can override to initialize all the component's state variables from properties. void OpenSim::Component::extendSetPropertiesFromState(const SimTK::State& state) enables you to perform the inverse operation and to update the property (e.g., the default_value) from the value in the State, for instance after a forward simulation. Ideally, your component should enable a simulation to be stopped, the state values held as properties, the model saved, then reloaded, initialized from its properties and the simulation resumed, such that concatenation of the two simulations is identical to performing a single simulation of longer duration. While testing the dynamics of your Component and its results is best left to you, the Component builder, OpenSim provides a test harness for testing the structure and integrity of your Component. The test program in testComponents.cpp instantiates and performs some standard checks on each Component in its queue, to which you can add your Component, to test:
OpenSim::Model::initSystem()) and its impact on memory
1.9.1