repository·main·Indexed 22 days ago
https://github.com/opensim-org/opensim-coreA software suite for developing musculoskeletal models and creating dynamic simulations of movement. It provides C++ libraries, command-line applications, and bindings for Python, Java, and Matlab. The system features a Component architecture using Sockets, Inputs, and Outputs to build modular models. Documentation covers installation via GUI, Conda, or source, as well as API usage for model initialization, simulation via the Manager class, and data extraction using TimeSeriesTable.
OpenSim is an extensible software system used for developing musculoskeletal models and creating dynamic simulations of movement. The Python bindings allow developers to interface with the OpenSim core library using Python.
Starting with version 4.6, the Python bindings are distributed as part of the OpenSim API releases. Note that for versions prior to 4.6, the bindings were provided exclusively via conda packages.
The Sandbox folder contains experimental code, prototypes, and conceptual explorations for the future of OpenSim. It serves as a space for ideas ranging from high-level explorations to nearly-complete prototypes.
Files in this directory may include:
.cpp, .h).py).m).md) for expressing ideas using a mix of text and pseudocode.Note: Files starting with pseudo*.cpp are intended for non-compiling pseudocode.
A Component is the fundamental unit of modeling and computing in OpenSim. It serves as an abstraction for a unit of computing or modeling used to compose a Model.
Key characteristics:
SimTK::MultibodySystem, which implements the mathematical/numerical system of equations (kinematics, dynamics, etc.).Model is itself a Component and can contain other components (subcomponents), which in turn can contain their own subcomponents.When a Model::initSystem() is called, the component makes its contribution to the underlying system, and all variables in the system equations appear in the State.
// Adding a subcomponent to a component
CoordinateActuator* act = new CoordinateActuator();
act->setName("motor");
device.addComponent(act);
// Accessing subcomponents by name
// As abstract Component
Component& c = device.updComponent("motor");
// As concrete Component
auto& a = device.updComponent<CoordinateActuator>("motor");
// Iterating through all subcomponents (recursively)
for (const auto& c : device.getComponentList()) {
c.getFullPathName();
}
// Iterating through specific types of subcomponents
for (const Body& b : device.getComponentList<Body>()) {
double mass = b.getMass();
}The OpenSim 4.0 API utilizes a Component architecture that enables the construction of complex models through modularity. Key concepts include:
Sockets.Inputs and Outputs.For detailed technical specifications, refer to the OpenSim Doxygen documentation for the Component class.
To perform simulations, OpenSim distinguishes between the mathematical equations and the variables they solve for:
SimTK::System): The mathematical system of differential equations representing the model dynamics. It is generated from an OpenSim Model.SimTK::State): A set of values for all unknowns (variables) in the System's equations. This includes time, generalized coordinates ($Q$, e.g., joint angles), and generalized speeds ($U$, e.g., joint velocities).Key Usage Rule: Any OpenSim method that performs a calculation depending on the current pose or dynamic variables (e.g., mass center position, muscle fiber velocity) requires a SimTK::State object as an argument.
// Generate the System and State that implements the model
SimTK::State state = model.initSystem();
int nq = state.getNQ(); // Number of generalized coordinates
SimTK::Vector q = state.getQ(); // Values of generalized coordinates
SimTK::Vector qdot = state.getQDot(); // Derivatives of generalized coordinates
// Methods requiring state for dynamic calculations
model.getMassCenter(state); OpenSim models are composed of various Component types, categorized by their role in the computational system:
+, -, max/min, delay), and produce Outputs. They have no dependencies on other components and do not require a Model to operate.TableSource holds a TimeSeriesTable and exposes columns as outputs.double, Vec3), meaning one reporter instance handles one specific type.PhysicalFrame, Joint, Constraint, Force, Actuator, Controller, and Probe.A Point represents a location in space and can be used to define physical structures (like muscle attachments) or embody spatial calculation results (like a center-of-pressure). Points provide location, velocity, and acceleration in the Ground frame based on the Model's state.
Point that is fixed to a PhysicalFrame. Stations are defined by a Vec3 relative to their parent frame and can have constraints or forces attached to them.Station specifically representing a motion capture marker from an experiment.A Frame represents a reference frame used to describe the spatial location and orientation of other frames. Every Model includes a Ground frame as the global reference. Frames allow for easy spatial calculations and linking components in chains or trees.
Body.PhysicalFrame where all other frames and points are measured.PhysicalFrame with inertia, defined by mass, a center-of-mass, and a moment of inertia tensor.PhysicalFrame whose transform is a constant offset from a parent PhysicalFrame. Often used to locate joints or constraints on a body.Every Frame can provide its Transform (translation and orientation) relative to the Ground frame as a function of the Model's State.
OpenSim uses XML files (.osim or .xml) to store models and analysis objects. Backward compatibility is maintained through a versioning system and the updateFromXMLNode hook.
<OpenSimDocument Version="NNNNN">). This number must be monotonically increasing and must match the content of the file. The version is managed in XMLDocument.cpp.OpenSim_DECLARE_UNNAMED_PROPERTY to handle XML layout. If you change a property name or layout, you must increment the version number and update the deserialization code.updateFromXMLNode Hook: This is the primary mechanism for handling format changes. When an object is instantiated from XML, updateFromXMLNode(SimTK::Xml::Element& node, int versionNumber) is called. Developers can use this method to manipulate the node (the XML element) to match the current code's expected schema before calling the base class implementation.If an object requires format updates, implement updateFromXMLNode as follows:
void XXX::updateFromXMLNode(SimTK::Xml::Element& node, int versionNumber)
{
// Guard against re-converting already updated files
if ( versionNumber < XMLDocument::getLatestVersion()) {
if (versionNumber <= 20301) {
// convert node from version 20301 or prior to the next version
……
}
if (versionNumber < 30500) {
// Convert versions before 30500
}
}
// At this point, node is on the latest XML format.
// Call base class to populate Property values.
Super::updateFromXMLNode(node, versionNumber);
}void XXX::updateFromXMLNode(SimTK::Xml::Element& node, int versionNumber)
{
if ( versionNumber < XMLDocument::getLatestVersion()) {
if (versionNumber <= 20301) {
// convert node from version 20301 or prior to the next version
……
}
if (versionNumber < 30500) {
// Convert versions before 30500
}
}
Super::updateFromXMLNode(node, versionNumber);
}While OpenSim typically uses explicit differential equations (ydot = f(y)), it is proposing an interface for implicit differential equations (f(y, ydot) = 0). This is useful for numerical stability and avoiding issues like division by zero.
ydot = f(y) approach used by Simbody integrators. Derivatives are computed during the Acceleration stage and cached in the SimTK::State.StateVariable and StateVariableInfo classes.CoordinateStateVariable and SpeedStateVariable. Their derivatives are managed by Simbody.AddedStateVariable. Their derivatives are computed by the component and stored in a cache (e.g., activation_deriv).The Hopper Device example utilizes the OpenSim 4.0 Component architecture to manage complex models. This architecture relies on two primary mechanisms:
For detailed technical specifications of these interfaces, refer to the OpenSim Doxygen documentation.
OpenSim uses the composite design pattern to manage the assembly of neuromusculoskeletal systems.