Skip to main content

How To Use NCP

Check that you have all the necessary inputs:​

Scaled OpenSim Model
You will need to have a scaled OpenSim model. Preferably one that has already been run through JMP to have accurate joint geometries.

NMSM Pipeline Model File (Optional)
It is strongly recommended that you run NCP after MTP, and as such have an .osimx file that contains muscle model parameters. NCP will use the muscle model parameters in this .osimx file to get more accurate joint loads.

Processed Data
You need a data folder with all your preprocessed data. It is recommended to do this through the data preprocessing tool. Specifically, you need inverse dynamics joint moments.

MTP Results (optional, but recommended)
If you ran MTP before NCP, you should include your MTP muscle activations, and .osimx file containing Hill-type muscle model parameters.

Create your XML settings file and modify necessary parameters​

You can create an NCP settings file using the NMSM Pipeline GUI plugin in OpenSim. Alternatively, you may use the NCPReference to build a settings file from scratch. This file contains an exhaustive list of all NCP settings file elements.

If creating an NCP settings file in the GUI, one NCP task will be automatically created that tracks muscle activations and joint moments. We recommend running this initial settings file, and iterating your max allowable errors and error centers to get the best solution.

If using MTLI those settings will be built into the XML file that you are using for NCP.

Create your MATLAB file to run NCP​

You may now create a MATLAB script to run NCP. This file should call the function NeuralControlPersonalizationTool("settingsFileName.xml") NCP is thread-safe, so you can use a "threads" parallel process.

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​

The key outputs to an NCP optimization are the muscle synergies. The synergy commands and activations are stored in separate files inside your NCP results directory:

  • synergyCommands.sto: Time varying synergy commands produced by NCP
  • synergyWeights.sto: Corresponding time invariant synergy weights produced by NCP

NCP also outputs a new .osimx that specifies which .osim muscle groups are in the synergy sets, and how many synergies are in each synergy set.

In addition to the above files that will be used later in the NMSM Pipeline, NCP also generates files that can be used to analyze results. You cna plot these files using the function plotNcpResultsFromSettingsFile("settingsFileName.xml"). This function generates plots for:

  • Joint moment matching
  • Muscle activation matching
  • Synergy commands
  • Synergy weights
  • Box plot for synergy tracking quality

Some extra files used in these plots are:

  • combinedActivations.sto:
  • modelMoments\modeledMomentsNcp.sto:
  • modelMoments\modeledMomentsMtpNcpCombined.sto:

For more detail, visit the hands-on NCP Tutorial.