OpenSim Moco

Last week we released OpenSim 4.5 which includes the latest Moco release, 1.3.0. This release includes a new class for modeling muscle paths with polynomial functions, new options for configuring MocoGoals, new transcription schemes, updated examples, and plenty of bug fixes.

The new class FunctionBasedPath was introduced to enable computing muscle (and ligament) length, lengthening speed, and moment arms using OpenSim Functions. Function-based muscle wrapping is an important feature of state-of-the-art trajectory optimization codes used in biomechanics research, and we are excited to bring this functionality to Moco. The MultivariatePolynomialFunction class can now be used to define paths using smooth polynomial functions that depend on multiple coordinates. We have also introduced the utility class PolynomialPathFitter to speed the creation of these polynomial functions from models and experimental motion data. Check out the new examples for Matlab and Python included in the OpenSim 4.5 release to learn how to convert your model to use FunctionBasedPaths. Finally, we’ve updated the models in exampleMocoTrack and exampleMocoInverse to use FunctionBasedPaths, and made other minor changes to improve the quality of the muscle activity solutions in these examples.

Other new features have been added to make customizing problems in Moco more flexible. First, all MocoGoals now support the methods setDivideByDisplacement(), setDivideByMass(), and setDivideByDuration(). These methods can be used to normalize the cost or endpoint constraint value in any MocoGoal by the model’s total center-of-mass displacement, the model’s total mass, and the total duration of the MocoProblem. Second, reference ground reaction forces can now be normalized when using MocoContactTrackingGoal, which may be useful for scaling tracking cost terms to similar magnitudes as other costs (e.g., control effort). Finally, foot-ground contact forces can now be optimized (e.g., maximize contact impulse) via MocoOutputGoal using the new Outputs ‘sphere_force’ and ‘half_space_force’ added to SmoothSphereHalfSpaceForce.

Lastly, we added new transcription schemes to MocoCasADiSolver based on state-of-the-art pseudospectral collocation methods. These schemes solve the dynamics of a model with high accuracy for relatively few collocation points, which can help improve convergence. These can be selected by passing “legendre-gauss-#” or “legendre-gauss-radau-#” to set_transcription_scheme(), where “#” is the number of collocation points in each mesh interval between 1 and 9. Note that this somewhat of an experimental feature, since these schemes currently cannot be used with models with kinematic constraints. Support for kinematic constraints with pseudospectral collocation will available soon in an upcoming API release.

Quick links

Get Moco 1.3.0 by downloading the OpenSim 4.5 release from SimTK.

Learn more about the new features in the OpenSim 4.5 release here.

More details about this release can be found in the CHANGELOG.md and CHANGELOG_MOCO.md files.

Read the Moco paper here.

I’ve been receiving lots of questions about MocoOutputGoal on the Moco forum recently, which made me realize that I never sent out an announcement for the latest Moco updates! OpenSim 4.4 with Moco 1.2.0 was released this past summer, and it includes some useful updates to MocoOutputGoal along with some other additions and bug fixes.

In OpenSim, Outputs allow you to query values from a Model that are calculated from a State object. We created MocoOutputGoal to make it easier to build custom cost functions in Moco that depend on Output values. In Moco 1.2.0, we’ve updated MocoOutputGoal to now support not only scalar Output types, but also Vec3 and SpatialVec types, which covers the majority of Outputs offered by OpenSim Components. We’ve also added new MocoGoals which allow you to minimize an Output at the beginning of a trajectory (MocoInitialOutputGoal), an Output at the end of a trajectory (MocoFinalOutputGoal), the error between initial and final Output values (MocoOutputPeriodicityGoal), and the error between an Output and a user-provided trajectory (MocoOutputTrackingGoal). In addition, we added MocoOutputConstraint to allow you to include Output values in a path constraint in your problems. Many users have requested more flexibility in building cost functions in Moco, and these new Output-based goals will give you many more options to do so.

Other updates include fixes for MocoAngularVelocityTrackingGoal and MocoOrientationTrackingGoal, which were not properly supported in Matlab and Python. We fixed a bug that was breaking marker tracking problems when using ‘setMarkersReferenceFromTRC()’ in MocoTrack. We fixed a bug where calculations from MocoStudy’s ‘analyze()’ were incorrect because DeGrooteFregly2016Muscle auxiliary variables were not properly included. Finally, we implemented a fix for DeGrooteFregly2016Muscle so that optimal fiber lengths and tendon slack lengths are scaled when using the ScaleTool.

Get Moco 1.2.0 by downloading the OpenSim 4.4 release from SimTK.

More details about this release can be foudn in the CHANGELOG.md and CHANGELOG_MOCO.md files.

Read the Moco paper here.

OpenSim 4.3 was officially released a few weeks ago, and included is the latest Moco release, version 1.1.0. This release includes a variety of new examples and new features to help you answer a broader set of research questions.

The examples exampleIMUTracking and exampleEMGTracking were added for the recent 2021 meeting of the Technical Group on Computer Simulation (TGCS). The first
example demonstrates how to create a set of synthetic accelerometer signals from a squat-to-stand motion, and then track these signals to reconstruct the original trajectory; this example is a great starting point for incorporating signals from inertial measurement units in your simulations. The second example demonstrates how to solve the muscle redundancy problem using MocoInverse while tracking electromyography signals. This example includes a new feature that allows you to optimize scale factors that allow you to track the shape of the reference EMG signals while scaling their magnitudes.

Two user-contributed examples that expand the popular example2DWalking are featured in this release. A Matlab version of example2DWalkingMetabolics, contributed by Brian Umberger, has been included to make it easier to get started minimizing metabolic cost in a predictive simulation. Russell Johnson contributed example2DWalkingStepAsymmetry which demonstrates how to predict an asymmetric walking pattern with Moco. This example features the new goals MocoStepTimeAsymmetryGoal and MocoStepLengthAsymmetryGoal which allow you to target specified step time asymmetry and step length asymmetry values with terms in the cost function.

Get Moco 1.1.0 by downloading the OpenSim 4.3 release from SimTK.

More details about this release are in the CHANGELOG.md and CHANGELOG_MOCO.md files.

Read the Moco paper here.

Per the recent announcement from Jen Hicks, the newest version of Moco has been released along with OpenSim 4.2! Since Moco is now merged into the core OpenSim codebase, we’re calling this release Moco 1.0.0. It’s been a long wait since the last release, but the time spent unifying the Moco and OpenSim codes will ensure long term stability for the Moco project and will allow for faster development cycles going forward.

Thanks to those who have been active contributors to the Moco forum! Even though Moco releases will now be included with OpenSim releases posted on the main OpenSim SimTK page, the Moco SimTK forum will remain the main hub for all Moco related discussion.

In this release we’ve added the component Bhargava2004SmoothedMuscleMetabolics, a smoothed implementation of the Bhargava et al. (2004) metabolics model designed for gradient-based optimization (contributed by Antoine Falisse). With this component and MocoOutputGoal, you can now include metabolic cost terms in the objective function. Refer to example2DWalkingMetabolics to see how to use this component in your MocoProblems.

We’ve fixed two major bugs related to muscle wrapping where 1) ModOpReplaceMusclesWithDeGrooteFregly2016 did not copy over the original muscle’s PathWrapSet and 2) muscle wrapping wasn’t thread-safe, which disallowed parallelization with MocoCasADiSolver. Muscle wrapping should now work seamlessly without needing to change how you construct your models with ModelProcessor.

We’ve included various small updates in this release. The analyze() utility function has been split into a new analyze() function that takes a StatesTrajectory and an analyzeMocoTrajectory() function that takes a MocoTrajectory. TableProcessor no longer automatically converts tables from degrees to radians; use TableProcessor::processAndConvertToRadians() or TabOpConvertDegreesToRadians instead. An Exception is now thrown if the model includes joints whose generalized speeds do not match the derivative of the generalized coordinates (i.e., BallJoint, FreeJoint, EllipsoidJoint, and ScapulothoracicJoint) since Moco does not support these joint types yet.

Finally, the Moco paper has been published in PLOS Computational Biology! Read the paper here.

More details about this release are in the CHANGELOG.md and CHANGELOG_MOCO.md files.

Get Moco 1.0.0 by downloading the OpenSim 4.2 release from SimTK.

Ross Miller, an expert at predictive simulations of human movement, has created a SimTK project to share his work using Moco: https://simtk.org/projects/umocod. If you’re hoping to get a jump start with Moco, I encourage you to visit his project.

We love when users share their progress with the Moco team and make their work available. Thank you, Ross!

Here is a description of the project by Ross Miller:

The model is designed for optimal control simulations of general musculoskeletal motion and walking specifically. The main differences from Moco’s 2D walking example include tendon compliance in all muscles, a two-segment foot, a patella with kinematic constraints, tracking of human experimental kinematic and ground reaction force data, and simulation of a full stride. A solution to a MocoTrack problem with the model is included and would serve as a good initial guess to predictive simulations. The long-term goal of the project is predictive simulations of muscle strengthening and prosthesis parameter optimization after lower limb loss. The project is a collaboration with Dr. Elizabeth Russell Esposito at the Seattle VA and is funded by the Army Advanced medical Technology Initiative and the Henry M. Jackson Foundation.

This release uses an updated version of opensim-core that includes SmoothSphereHalfSpaceForce, which has now been removed from the Moco codebase. The interface to this class has been updated to use OpenSim’s ContactSphere and ContactHalfSpace classes, so your models must be updated in order to continue using this component. You can refer to the gait model included with example2DWalking for the correct XML syntax and view a file diff of the changes here: https://github.com/opensim-org/opensim-moco/commit/ccd39f82acba5f23ebc3423eb40d2197d6d41d8b#diff-eb627df1f2a265a84a30b7c6b4f92999.

Contact tracking was added as an option to example2Dwalking, and MocoContactTrackingGoal was updated to support contact spheres distributed across multiple bodies. MocoControlTrackingGoal was updated to more easily associate controls to reference data, as demonstrated by a new electromyography tracking option added to exampleMocoInverse. A “projection” setting was added to MocoFrameDistanceConstraint to provide more flexibility in posing this constraint.

DeGrooteFregly2016Muscle’s passive force multiplier now has a stiffness parameter. To support this change, the curve was tweaked slightly. This may have a minor effect on solutions relying on passive fiber forces. The maximum difference between the new and old passive force-length curves is 0.07 (unitless).

Finally, we’ve included various bug fixes in this release:

• Fixed a bug where MocoPeriodicityGoal incorrectly specified control constraints
• Fixed an error that occurs when using ModOpRemoveMuscles
• Fixed some default pelvis and lumbar parameters in createPeriodicTrajectory()
• Added some missing MATLAB and Python commands to the bindings

More details about this release are in the CHANGELOG.md file.

Download this release from SimTK.

Two major additions are included in this release: reporting the breakdown of solution objective terms and contact force tracking.

When using MocoCasADiSolver, MocoSolution now provides a breakdown of the terms in the objective. The portions of the total objective for all terms (including their weights) can be accessed by the methods getObjectiveTerm() and getObjectiveTermByIndex() on MocoSolution, and are also printed to the command line or console window upon arriving at a solution.

MocoContactTrackingGoal was added, allowing minimization of error between model compliant contact forces and experimentally measured contact force data. Currently, this goal does not track torques or centers of pressure, and only supports the SmoothSphereHalfSpaceForce contact element included with Moco.

Other minor changes in this release include renaming exampleSitToStand to exampleSquatToStand, moving the bisection root solver in DeGrooteFregly2016Muscle to a dedicated utility in MocoUtilities, and a bug fix in the report.py report generation tool related to the STOFileAdapter no longer have a read() method due to a recent change in OpenSim’s API.

These changes, and changes from previous releases, are reflected in the CHANGELOG.md file.

Download this release from SimTK.

This release contains a MATLAB version of Moco’s 2D predictive simulation of walking, contributed by Brian Umberger, and examples in MATLAB, Python, and C++ for using the MocoInverse tool. Lastly, we added examples for creating a custom goal in C++; see exampleSlidingMassAdvanced.cpp and exampleMocoCustomEffortGoal.

To easily plot a solution in MATLAB, we introduced the osimMocoTrajectoryReport.m utility.

We updated the versions of Simbody and OpenSim that we bundle with Moco. As a result, this release contains a fix for the simbody-visualizer for macOS Catalina, and contains OpenSim’s support for IMUs.

This release contains the following new modules:

• MocoOutputGoal, for minimizing any scalar output of a model.
• MocoFrameDistanceConstraint, to constrain the distances between frames in the model.
• MocoAngularVelocityTrackingGoal and MocoAccelerationTrackingGoal, added in anticipation of supporting IMU data in the future.

We made minor changes to various parts of Moco’s interface; you may have to make small changes to your code to use this release. For example, converting muscles from Millard2012EquilibriumMuscle to DeGrooteFregly2016Muscle now preserves the fiber damping property, while previously we set fiber damping to 0 during this conversion. To set fiber damping to zero, you can use ModOpFiberDampingDGF.

More details about this release are in the CHANGELOG.md file.

Download this release from SimTK.

We are excited to pilot a new way of providing support for Moco: Virtual Office Hours. Chatting in real-time allows users to get quick and effective help. Virtual Office Hours are 30-minute video conference calls with one or more members of the Moco team. These calls are open to users with any level of experience with Moco, but are intended for two types of support:

• Determine if Moco can help with a given research question, and learn how to apply Moco to this question.
• Troubleshoot complex errors or issues with optimizer convergence for a given problem.

For straightforward questions, use Moco’s SimTK forum instead.

If you are interested, complete our Request for OpenSim Moco Virtual Office Hours form.

The Moco team will evaluate the submission and respond to requests according to their suitability for Virtual Office Hours, the order in which we receive them, and our availability.

We aim to start the office hours in December 2019. If you are selected for office hours, we will contact you with a list of time slots during business hours, Pacific Time.

We request that participants in the Virtual Office Hours make a small contribution back to the Moco project within three weeks after the conference call. Here are examples of how you might contribute:

• Write a forum post explaining your questions and what you learned.
• Submit example code (either in a forum post or on GitHub).
• Improve the documentation (see Moco/doc on GitHub).

OpenSim Moco is a new part of the OpenSim project for solving optimal control problems with OpenSim musculoskeletal models. Moco can solve a wide range of problems, from estimating muscles forces to predicting new motions, without requiring users to have expertise in optimal control methods. Moco is created by the Stanford University Neuromuscular Biomechanics Lab, where OpenSim is developed.

You can download the software and find related links at Moco’s SimTK page.

This is the initial release of OpenSim Moco, and is the version of Moco used to generate results for the bioRxiv preprint on Moco.

Download this release from SimTK.