Skip to main content

Tutorial 4 – Neural Control Personalization

Tutorial Developers: Robert Salati, B.J. Fregly Rice Computational Neuromechanics Lab, Rice University

Last Updated: 11/4/2025

Download the files for this tutorial at https://simtk.org/projects/nmsm

The Neural Control Model Personalization tool finds muscle synergies that are as consistent as possible with ID joint moments and, when available, MTP-estimated muscle activations. The NCP tool fits muscle synergies at the level of muscle activations (i.e., after electromechanical delay and activation dynamics) for regions of the body where either all muscle activations are available from the MTP tool (e.g., the right lower extremity) or no muscle activations are available.

The inputs to the NCP tool are a post-JMP OpenSim model as well as data for IK motions, ID loads, muscle–tendon lengths and velocities, muscle moment arms, and, optionally, MTP-calculated muscle activations from one or more motion trials of interest.

Before running NCP:​

  1. Open the OpenSim model UF_Subject_3_reduced_muscles.osim in the OpenSim GUI.

  2. Under the Forces tab on the model, explore the muscles available.

  3. Take note of the extra groups added. These are added for organization so that MTP/NCP knows which model muscles to group together in the optimization. The four important groups are:

    • Activation Muscle Groups – Muscles that we would expect to have similar activation profiles (ie lateral hamstrings; BFSH and BFLH will have similar activations to each other). These groups are used in both MTP and NCP.

    • Normalized Fiber Length Muscle Groups – Muscles that we would expect to have similar normalized fiber lengths. These groups are used in both MTP and NCP.

    • Collected EMG Muscle Groups – Muscle groups that we do have experimental EMG data for. These must have the same name as the respective EMG channel name your EMG data file (preprocessed\EMGData\gait_1.sto). These groups are only used in MTP.

    • Missing EMG Muscle Groups – Muscle groups that we do not have experimental EMG data for. These groups are only used in MTP.

    info

    These groups need to be created manually in a text editor such as Notepad++. More information can be found here but we have example groups for lower limb models in the NMSM Article download on SimTK: https://simtk.org/frs/?group_id=2397

Setting up an NCP settings file:​

  1. Activate the NMSM GUI in OpenSim by navigating to Tools>User Plugins, and click rcnlPlugin.dll.

  2. With UF_Subject_3_reduced_muscles.osim selected in the OpenSim GUI, navigate to Tools>Model Personalization>Neural Control Personalization.

    a. The following window should be opened:

    image

  3. Set the input Osimx file to mtpResults\UF_Subject_3_reduced_muscles_mtp.osimx

  4. Set the data directory to preprocessed.

  5. Set the results directory to NCPResultsV1.

  6. For the coordinate list, select: hip_flexion_r, knee_angle_r, ankle_angle_r

  7. For activation muscle groups, select HipFlexorsActivationGroupR, GlutmaxActivationGroupR, HamslatActivationGroupR, VasActivationGroupR, GasActivationGroupR

    tip

    The filter box at the top is very helpful to filter muscle groups.

  8. For normalized fiber length groups, select GlutmaxNormalizedFiberLengthGroupR, HamsNormalizedFiberLengthGroupR, VasNormalizedFiberLengthGroupR, GasNormalizedFiberLengthGroupR

  9. Keep Muscle Tendon Length Initialization disabled.

  10. Set the MTP results directory to mtpResults

  11. Include RightLeg in the synergy set with 3 synergies.

  12. Save this settings file as NCPSettingsV1.xml

  13. Open NCPSettingsV1.xml in a text editor of your choice and explore the settings file.

Running NCP:​

  1. Open MATLAB and open runNCP.m in your tutorial directory.

  2. Open the project file Project.prj inside your installation of nmsm-core.

  3. Run the MATLAB section labelled Run NCP V1

    a. With the section selected, press shift+enter to run a section.

Post NCP Analysis:​

  1. Look through the plots created by the script. If everything was done correctly, there should be 3 plots.

    Plot 1 – Muscle Activations: Muscle activations produced by NCP synergies compared to the input MTP muscle activations.

    Plot 2 – Synergy Matching Quality: Variance accounted for (VAF) and root mean squared error (RMSE) for the synergy decomposition of muscle activations.

    Plot 3 – Joint Moment Matching: Joint moments generated by muscle forces compared to Inverse Dynamics joint moments

Experiment with different numbers of synergies:​

  1. Create a copy of NCPSettingsV1.xml and name it NCPSettingsV2.xml

  2. Open NCPSettingsV2.xml in a text editor of your choice.

  3. Change <results_directory> to NCPResultsV2.

  4. Inside <RCNLSynergySet>, change <num_synergies> to 4.

  5. Save this settings file as NCPSettingsV2.xml

  6. Run the MATLAB section labelled Run NCP V2

    a. With the section selected, press shift+enter to run a section.

Experiment with activation minimization:​

  1. Create a copy of NCPSettingsV1.xml and name it NCPSettingsV3.xml

  2. Open NCPSettingsV3.xml in a text editor of your choice.

  3. Change the <results_directory> to NCPResultsV3.

  4. Inside <RCNLCostTermSet>, change <is_enabled> to false for the activation_tracking term.

  5. Inside <RCNLCostTermSet>, change <is_enabled> to true for the activation_minimization term.

  6. Save this settings file as NCPSettingsV3.xml

  7. Run the MATLAB section labelled Run NCP V3

    a. With the section selected, press shift+enter to run a section.