overview
team
downloads
documentation
wiki
publications
forums
advanced

Successful Simulations

This page is for topics related to running tools such as inverse kinematics, inverse dynamics, RRA, CMC, etc in Open Sim. For help getting raw data into Open Sim or doing something with your results, see PreProcessing and PostProcessing, respectively. The title represents a general spirit of optimism and preference for alliteration.

Table of Contents

Running OpenSim in the Command Line

Many people get started with OpenSim in the GUI, but using the command line can be more efficient for rapid iteration of setup files and debugging. If your simulations are crashing the GUI and you don't know why, using the command line instead means you'll at least get an out.log file and some output to the command window that you can use to debug. Here's how to do it.

In Windows, go the the Start menu, select Run, type "cmd", and click "OK" to open a command window.

Navigate to the folder where your setup file is. (e.g. "cd My Documents\mysimulation\setupfiles"; the "cd" just stands for "change directory")

Type the path to the tool you want to use, followed by -S and the name of the setup file. c:\Program Files\yourverisonofopensim\bin\thetoolyouwant -S nameofyoursetupfile

e.g. to use version 2.0 and the cmc tool it looks like this:

c:\Program Files\OpenSim 2.0\bin\cmc.exe -S mySetupFile_RRA.xml

Hit Enter. If nothing happens, check your command for typos and try using tab-completion.

Running Opensim out of Matlab

Writing a script in Matlab to run Open Sim is very useful for setting up batch processing. Once you know how to call a tool from Matlab it's just a matter of writing a loop to go through all the setup files you want to process. Here's an example for how to run IK on a setup file called mysetupfile.xml

Change directory to be where your setup file is

setupDir = 'C:\Documents and Settings\mysetupfiles';
cd(setupDir);

Make a string with your setup file name.

setupfile = 'mysetupfile.xml';

Write a string with the file path to the tool you want to use (in this case IK), followed by -S to indicate that you're using a setup file, followed by the string with the setup file name.

   Command = ['c:/OpenSim2.2/bin/ik.exe -S ' setupfile];

Execute the command

   system(Command);

That's it! You can do this with any of the opensim tools.

Batch Processing OpenSim Tools

Scenario: you have a well scaled model, clean marker data, a setup files for inverse kinematics and an analysis with appropriate settings for your data that you've successfully run in the command line, and results for the marker data from one trial of your experiment... now you have to repeat this 150 times.

This would be very cumbersome if you had to make a new setup file for every trial, but with a few handy xml reading and writing functions from matlab, you can automate the process of generating setup files and running tools. Sample files demonstrating this and instructions are available on the downloads page here: BatchOpenSimInMatlab.

Creating and Using Plug-ins in OpenSim

The OpenSim Developer's Guide is an extremely good resource for anyone first starting out (available at https://simtk.org/docman/?group_id=91) so most of the stuff here is just meant to supplement what's there. It's meant for topics related to creating and using your own plug-ins to extend the existing capabilities available in OpenSim and consists of a hodgepodge of tips for making your plug-in as awesome as you know it can be. :)

Creating a plugin

Got suggestions for this? Add them here!

Adding a plug-in and running it using the Command Window

If you've created a plug-in in OpenSim (for example, to apply a custom force to a body), and you want to make sure that whatever analysis tool you're using includes your plug-in, then follow the steps detailed in the Running OpenSim from the Command Line section on the SuccessfulSimulations page, but tell the tool to load your plugin as well by tacking on a "-L WhateverYouNamedYourPlugin.dll" to the end of it. That is, if you want to run the cmc tool using Version 2.X of OpenSim, you would write

c:\Program Files\OpenSim2.X\bin\cmc.exe -S mySetupFile_RRA.xml -L myPlugin.dll

replacing "myPlugin.dll" with whatever you named your plug-in.

For example, say you created a custom force called "myCustomForce" that applies a combination spring-damper force between two bodies along a specified axis. That is, to Fq = k*q + c*qdot, where q is the coordinate along the axis of interest. Here is an example of the OpenSim model xml code that utilizes this "myCustomForce" plug-in to apply the force between two bodies, B1 and B2, along the x-axis,

<myCustomForce name="B1_B2_SpringDamper">
       <body_1> B1 </body_1>
       <body_2>  B2 </body_2>
       <location_body_1> 0.0 0.0 0.0 </location_body_1>
       <location_body_2> 0.0 0.0 0.0 </location_body_2>
       <axis>   1.0 0.0 0.0 </axis>
       <stiffness_constant> 5 </stiffness_constant>
       <damping_constant> 10 </damping_constant>
</myCustomForce>

To determine the forces on bodies B1 and B2 due to this custom force, you could use the "ForceReporter" tool available in the "Analyze" toolbox. Doing that is simple enough via the GUI, but for better error reporting and debugging information, running it via the command line is the way to go ( {OK} {OK} {OK} :) ). To do this, include the "ForceReporter" tool in your "Analyze" setup file, and then type

c:\Program Files\OpenSim2.X\bin\analyze.exe -S mySetupFile_Analyze.xml -L myPlugin.dll

replacing "myPlugin.dll" with whatever you called your plug-in (e.g. myAwesomeCustomForce.dll, etc). Note that the default install path for user-created plug-ins in OpenSim is in the "OpenSim2.X\plugins" folder, so you'll need to copy and paste the plugin into your current folder to run it from the command window as defined above. If you'd rather not, then just include the full path name to the plugin when including it via the command line. I.e.

c:\Program Files\OpenSim2.X\bin\analyze.exe -S mySetupFile_Analyze.xml -L c:\Program Files\OpenSim2.X\plugins\myPlugin.dll

Some Random Notes

  • the name of your plug-in, your solution and your Class do not have to be the same. For example, I can name my class "myCustomForce (defined in "myCustomForce.h" and my "CustomForce.cpp"), tell CMake to build the solution file and name it "anAwesomeForce", and to name the plugin "anAwesomeForcePlugin". Of course, it might make things easier to track if you named everything similarly, but you don't have to.

Some Troubleshooting Tips

By far, he most efficient way to run things is to do everything via a C++ "main" program instead of creating a plug-in since you can

  • call the OpenSim API and include any other C++ libraries that provide additional computational and/or visualization resources

  • test your new component/analysis faster and easier without having to wrap, load, and call your plug-in from the GUI or command line

However, creating a plug-in has its own benefits. It makes sharing what you've created with other users who have minimal C++ programming experience a lot easier since they won't need to know any amount of C++ to use it. Additionally, for the case where you are tacking on your own custom force, actuator, controller, joint, or whatever else you've come up with, to the xml code of a pre-existing OpenSim model (for example, applying a CustomForce between the 5th Lumbar (L5) and Sacrum (S1) bodies in the OpenSim lumbar spine model ), creating a plug-in will save you a lot more time since you won't have to re-write the (xml) code for your model in C++. Instead, you just need to

  • write the code for your plug-in in C++
  • go through the steps to Build + Install the plugin detailed in the Developer's Guide
  • employ it in your model's xml code (or the xml code of the model you're using)

This section details some troubleshooting tips for the case where you've decided to go with the plug-in option instead of running everything via a main() function in C++.

  • If you're doing things via the GUI, make sure you load your plug-in before load/open your model. OpenSim has no way of knowing that your (awesome) plug-in exists otherwise.

  • To get better insight with regards to where your plug-in might be messing up, there's a nice way of adding breakpoints to your C++ code and "attaching" it to the OpenSim analysis. To do this,

    1. Run your OpenSim GUI, install your plug-in (Tools --> User Plugins --> YourAwesomePlugin.dll) and load your model

    2. Open your solution file (e.g. myAwesomeForce.sln) in C++

    3. In C++, click on Tools --> Attach to Process --> Click on OpenSim under "Title." picture1lv

    4. Now, you can attach breakpoints to different sections of your code in C++. When you run your analysis in OpenSim, either via the GUI, or the command line, it will stop at your specified breakpoint(s) and you'll be able to see if the values of the variables correspond to what you expect them to be. I.e. stuff like, "are they the numbers you set them to, or are they NaNs", etc. You can also check to see if it's accessing a specified function by putting a break point in the function and checking to see if it calls it. Remember though, that every time you change/fix something in your C++ code, you have to build + install your plug-in again, and reload the plug-in into OpenSim. Otherwise, it'll just use your older version.

Inverse Kinematics

Also see ToolTips.

Topics!

Replace this text with something neat.

Inverse Dynamics

Also see ToolTips.

Topics!

Replace this text with something neat.

Residual Reduction Algorithm

Also see ToolTips.

Topics!

Replace this text with something neat.

Computed Muscle Control

Also see ToolTips.

Increasing Model Strength for CMC

Adapted from forum conversation https://simtk.org/forum/message.php?msg_id=5069 and email discussion.

Often models that are strong enough to reproduce isometric joint moment curves are not strong enough to track a motion such as walking in a dynamic simulation. This topic will cover how to tell if your model is strong enough and discuss the implications of boosting model strength.

How can I tell if my model's strong enough?

There are a lot of steps that have to go right before getting to CMC, so let's assume you've completed scaling, IK, and RRA. You have a model with adjusted segment masses, torso center of mass, and joint moments that track IK joint angles adequately. The first CMC simulation to try is one with unconstrained control constraints (you still have to have a control constraints file, there just won't be anything in it) and strong reserve actuators. Once this complete, look at the contributions to joint moments and activations of key muscles and reserve actuators. It can be helpful to have an ID simulation to compare to.

Example

The plot below shows the activation of tibialis anterior (a dorsiflexor) and the ankle dorsiflexion reserve actuator moement during a CMC simulation of a single gait cycle. Toe-off is at 60 on the x axis. During swing there should be a dorsiflexion moment (positive), based on literature and the ID simulation run on this data. Since tibialis anterior is the biggest dorsiflexor it should be on somewhat, but in this simulation it is maxed out (activation = 1) and the reserve actuator is on A LOT. This is a red flag that the dorsiflexor muscles are not strong enough. This is one example but the same behavior occurred in all muscle groups, so the model was too weak.

There may be other reasons that the model relies so heavily on the reserve actuators. If they're so strong that they're much cheaper for the optimizer than the muscles, so you might observe that there are large moments from the reserves and little activation of the muscles. So before changing the model it might be helpful to make them less strong (by changing <optimal_force> in the actuator file) and seeing if that fixes things. However, in this example, the muscle activations were also high.

How do I make a muscle stronger?

Make <max_isometric_force> in the .osim model file larger. The OpenSim API can handle this easily if you'd rather automate it.

How much stronger?

As with all models, the answer is: it depends.

The model gait_2392.osim is based on the original Delp 1990 model but each muscle group (knee_flexors, ankle_dorsiflexors, etc) is strengthened by some multiplier, up to 3x.

The 2-legged version of the model by Arnold et al. (here) is available with all muscles (except the back muscles which came from gait_2392) strengthened by 1.5x (50% stronger).

Arguments for augmenting strength by a consistent multiplier for all muscles:

  • This problem probably stems from the experimental measurement of joint moment. It's likely that subjects are not reaching their true maximum force generation when they're just pushing against the machine, with someone yelling "push push push!" but they CAN produce high torques in a coordinated movement.
  • This the closest physiologically to the idea that the MVC measurements of torque are submaximally activated consistently across the entire range. This makes the boosted strength both a quick fix, and physiologically reasonable.
  • When making models, keep assumptions as simple as possible unless there is data to support something more intricate. A single multiplier for all muscles was simple, and it's easy to play around with the value to make the model only as strong as it needed to be to walk.

Caveats It is important to remember that the way this model is set up, tendon strain is scaled to F_max, so changing F_max does effectively change tendon stiffness (stronger model -> higher F_max -> stiffer tendon). You could make the muscles 10x as strong, and the model could do anything, but the tendons would be unrealistically stiff. If you find the model needs to be a lot stronger for your application, you should consider modifying the tendon curve.

SuccessfulSimulations (last edited 2011-08-25 00:55:57 by emarnold)