Skip to main content

How to Use TO

Check that you have all the necessary inputs​

OpenSim Model
You will need to have a scaled, post-JMP OpenSim model.

NMSM Pipeline Model File (Optional)
If you have ran MTP, NCP, or GCP, you should include the .osimx file with your TO run. TO will parse this file for muscle model parameters, synergy control groups, and ground contact model parameters.

Processed Data
You need a data folder with all your preprocessed data. It is recommended to do this through the data preprocessing tool.

NCP Results (Optional)
If you are using synergy controls for your TO run, you should set your initial_guess_directory to be your NCP results directory. TO will use the synergy controls created by NCP as an initial guess, and can also track them if desired.

Create your XML settings file and modify necessary parameters​

You can create a TO settings file using the NMSM Pipeline GUI plugin in OpenSim. Alternatively, you may use the Treatment Optimization Reference to build a settings file from scratch, but this is not recommended. An exhaustive list of all cost and constraint terms can be viewed in the cost term reference and constraint term reference.

*You will need an XML file for both your TO settings and for your GPOPS-II settings. You can create a GPOPS-II settings file using the NMSM Pipeline GUI plugin in OpenSim in the Tracking Optimization window.

Create your MATLAB file to run TO​

You may now create a MATLAB script to run TO. This file should call the function TrackingOptimizationTool("settingsFileName.xml")

Make sure the nmsm-core project is running in MATLAB​

If it is not already running, double click on ‘Project.prj’ in the root of the nmsm-core folder to open it up.

Press run in MATLAB​

Analyze your results​

Tracking Optimization will output its results in a folder specified by the results_directory field in your settings file. To plot these results, run the code plotTreatmentOptimizationResultsFromSettingsFile("settingsFileName.xml"). This function will output plots depending on what elements your TO run included. For more details on the plots, go to the plotting results page.

Getting a good TO result is the hardest part of the NMSM Pipeline. We recommend that you start with an initial settings file that is very simple and easy to converge and progressively modify the settings until you get a result you like. You can start with a tight set of periodicity and kinetic consistency constraints. These constraints should remain the same for all of your TO iterations. You can then start with a loose residual load reduction constraint, and loose tracking cost terms for joint angles, joint velocities, joint loads, external forces and moments, and muscle activations. The goal with this initial run is simply to get it to converge. If your TO run doesn't converge with loose cost terms, it is likely that your constraints are conflicting with each other, or your data has an issue. If your TO doesn't converge, we recommend you slowly peel back cost or constraint terms until you get a converged solution. This will help you diagnose exactly where the issue is coming from.

Once your initial TO has converged, you can start your next iterations by progressively tightening your residual load reduction constraint, tightening cost terms, and adding new cost or constraint terms as you see fit. You may want to use previous TO runs as an initial guess for subsequent TO runs, but this is not required. You should almost always be tracking your preprocessed data for every TO run.