A. Explore and edit OpenSim model, storage, and controls files

For the following exercise, it is recommended that you have a program capable of recognizing XML tags and folding code (e.g., Notepad++ on Windows, TextMate on Mac).

Tip for new Notepad++ users

To teach Notepad++ to recognize XML tags in .osim files, go to SettingsStyle Configurator…, select "XML" from the Language list, type "osim" in the User ext. box, and click Save & Close. (You will need to re-open your .osim file for the change to take effect.)

The necessary files are located in the "Models/Tug_of_War" folder of the OpenSim Resources directory (by default, C:/Users/<username>/Documents/OpenSim/4.1). Locate the model file 'Tug_of_War_Millard.osim', the controls file 'Tug_of_War_Millard_controls.xml' , and the initial states file 'Tug_of_War_Millard_initial_states.sto' and copy them into your working directory. Copy the model and save it with the filename Tug_of_War_Millard_Iso.osim.

Correction for time constants in OpenSim 4.0 and 4.1

In the Tug_of_War_Millard.osim file packaged with OpenSim 4.0 and 4.1, the activation_time_constant and deactivation_time_constant properties are erroneously within the MuscleFirstOrderActivationDynamicModel element; move these two properties out of MuscleFirstOrderActivationDynamicModel and into Millard2012EquilibriumMuscle. This model file contains the fix: Tug_of_War_Millard.osim

An OpenSim model is created using a series of XML elements. An XML element consists of a start tag, a value, and an end tag. The value between the start and end tags can be a string, a number, or another XML element.

Open the model file 'Tug_of_War_Millard_Iso.osim' in your favorite text editor. At the top of the file, you will find a block that indicates the presence of XML content, then an XML element called OpenSimDocument. Within the OpenSimDocument element is a Model element consisting of several model components. You may recognize the model components as categories shown in the Navigator Pane of the OpenSim GUI.

<?xml version="1.0" encoding="UTF-8" ?>
<OpenSimDocument Version="30000">
    <Model name="Tug_of_War_Millard">
		<BodySet> ... </BodySet>
		<ConstraintSet> ... </ConstraintSet>
		<ForceSet> ... </ForceSet>
		<MarkerSet> ... </MarkerSet>
		<ContactGeometrySet> ... </ContactGeometrySet>
		<ControllerSet> ... </ControllerSet>
		<ComponentSet> ... </ComponentSet>
		<ProbeSet> ... </ProbeSet>

Create a set of files for a single muscle simulation as follows:

  • In the model file (Tug_of_War_Millard_Iso.osim), change the Model name to "Tug_of_War_Millard_Iso". Expand the ForceSet element and remove the (entire) Millard2012EquilibriumMuscle element named "RightMuscle". Expand the Millard2012EquilibriumMuscle element named "LeftMuscle" and set its default_activation property to 0.01.
  • Create a copy of the controls file (Tug_of_War_Millard_controls.xml) and name it "Iso_controls.xml".
  • In the new controls file (Iso_controls.xml), delete the ControlLinear element named "RightMuscle.excitation".
  • Create a copy of the initial states storage file (Tug_of_War_Millard_initial_states.sto) and name it "Iso_initial_states.sto".
  • In the new storage file (Iso_initial_states.sto), delete the columns for "RightMuscle.activation" and "RightMuscle.fiber_length". Update the number of columns (nColumns) to 5.

Open the new Isometric model in the OpenSim GUI.

Configure the Forward Dynamics Tool as follows:

  • In the Input pane, load the controls file (Iso_controls.xml) and the initial states file (Iso_initial_states.sto) and check "Solve for equilibrium for actuator states".
  • Open the Excitation Editor (click the button with a pencil and paper next to the Controls field) and set the LeftMuscle excitation to the maximum value of 1.0 for the entire time range (On Mac, use Ctrl + Shift + Left Click to select a control node; multiple nodes can be selected together). Save the file and close the editor.
  • Set the time range to between 0 and 0.5 seconds.
  • Append "/FWD_Isometric" to the output directory.
  • Open the Analyses tab and add a ForceReporter analysis.
  • Save the Forward Dynamics Tool settings to "Setup_FWD_isometric.xml".

B. Examine the effect of tendon-to-fiber length ratio on isometric contraction simulations

Zajac (1989) showed that the ratio between the tendon slack length and the optimal muscle fiber length (\ell_{\mathrm{s}}^{\mathrm{T}} / \ell_{\mathrm{o}}^{\mathrm{M}}) can have a substantial effect on the mechanical response of a muscle–tendon actuator. In this section, you will vary this ratio and examine the mechanical response of the muscle–tendon actuator during isometric contractions.

Set the block_tz coordinate to zero and lock the coordinate in the GUI.

Run a forward dynamic simulation of isometric contraction using tendon-to-fiber length ratios of 0.5, 1.0, 2.0, 4.0, and 7.0. For each ratio, ensure the sum of the tendon slack length and the optimal fiber length is constant (i.e., \ell_{\mathrm{s}}^{\mathrm{T}} + \ell_{\mathrm{o}}^{\mathrm{M}} = 0.3\,\text{m} ). Perform the following tasks for each tendon-to-fiber length ratio:

  • In the OpenSim GUI, open the Forces element in the Navigator. Expand the Muscles category and then select LeftMuscle to display its information in the Properties pane.
  • Modify the "optimal_fiber_length" and "tendon_slack_length" properties according to the tendon-to-fiber length ratio. Ensure the "default_activation" property is set to 0.01.
  • For the given ratio, create a new initial states storage file where the initial fiber length is set to the optimal fiber length value and the initial activation is 0.01.
  • Run a forward dynamic simulation using the settings file you created in Part A. Ensure that the controls file maximally excites the muscle for the entire simulation, and that the initial states file correctly sets the initial activation and fiber length. Rename the output directory so that you preserve your results for each ratio.
  • Plot the muscle force vs. time for each tendon-to-fiber length ratio and analyze the resulting simulations.

C. Examine the effect of tendon-to-fiber length ratio on isokinetic contraction simulations

In this section, you will evaluate the effect of the ratio between the tendon slack length and the optimal fiber length on an isokinetic (i.e., constant-velocity) contraction. The motion you will be using to calculate muscle forces is 1 second in duration and moves the cube at a speed of 0.1 m/s.

Copy the motion file "Tug_of_War_ConstantVelocity.sto" from the "Models/Tug_of_War" folder into your working directory. Unlock the block_tz coordinate in the OpenSim GUI. Load the motion into the OpenSim GUI and play the animation.

For the same set of tendon-to-fiber length ratios (0.5, 1.0, 2.0, 4.0, and 7.0), you will analyze an isokinetic contraction. For each ratio, ensure the sum of the tendon slack length and the optimal fiber length is constant (i.e., \ell_{\mathrm{s}}^{\mathrm{T}} + \ell_{\mathrm{o}}^{\mathrm{M}} = 0.3\,\text{m}). Use the controls from the previous section. To calculate the muscle forces, you will use the Analyze Tool to recreate the force profiles given the known information. As discussed in the introduction to this example, the activation, fiber length, and fiber shortening/lengthening velocity are needed to calculate the muscle force using a Millard2012EquilibriumMuscle model. The loaded motion for the block kinematics is used to calculate the muscle fiber length and velocity at each time step. The Analyze Tool uses this information to calculate the muscle force applied to the block.

For more background on the Analyze Tool, see the Analyses page in the User Guide.

Perform the following tasks for each tendon-to-fiber length ratio:

  • Before you open the Analyze Tool, ensure the "optimal_fiber_length" and "tendon_slack_length" properties have been set correctly for the LeftMuscle. Also, set "default_activation" to 1.0 for this part (part C) of the lab only.
  • Open the Analyze Tool.
  • In the Input pane, select "Iso_controls.xml" for the controls file.
  • In the Input pane, select Motion and ensure the Loaded Motion is set to the "Tug_of_War_ConstantVelocity" motion.
  • Check the box for "Solve for equilibrium for actuator states".
  • Set the time range to between 0 and 1 second.
  • In the Analyses tab, add a ForceReporter.
  • Run the Analyze Tool. (You may first save the setup file to speed up running the tool for other ratios.)
  • Plot the muscle force of the LeftMuscle vs. time for all tendon-to-fiber length ratios and analyze the resulting simulations.
  • If interested, you can save data from the plot to a file. Right-click on the plot and select "Export Data...". Save the result file as TendonForceVsMotion_Isokinetic.sto.

D. Design your best Tug-of-War competitor

You win the competition by getting the center of the block onto your side of the arena at the end of a 1.0-second simulation. For this competition, start with a copy of the original Tug_of_War_Millard.osim model file. 

The design variables that you can modify to create your competitor are:

  • F_{\mathrm{o}}^{\mathrm{M}} – Maximum isometric muscle fiber force

  • \ell_{\mathrm{o}}^{\mathrm{M}} – Optimal muscle fiber length

  • \ell_{\mathrm{s}}^{\mathrm{T}}  – Tendon slack length

  • \alpha_{\mathrm{o}}  – Muscle fiber pennation angle at optimal fiber length

  • u(t)  – Muscle excitation time history

  • \ell^{\mathrm{MT}} – Total length of muscle–tendon actuator

  • \tau_{\mathrm{act}} – Activation time constant 

  • \tau_{\mathrm{deact}} – Deactivation time constant

  • \tilde{v}_{\mathrm{max}}^{\,\mathrm{M}} – Maximum contraction velocity normalized by optimal fiber length

  • V^{\mathrm{M}} – Muscle volume

  • \text{Z}_{\mathrm{origin}} – The Z-coordinate of the muscle's attachment point on the ground body

The muscle must obey the following physical relationships:

  • \sigma_{\mathrm{o}}^{\mathrm{M}} = \frac{F_{\mathrm{o}}^{\mathrm{M}}}{A^{\mathrm{M}}} = 35\,\text{N}/\text{cm}^2 – The specific tension of the muscle at its maximum isometric force (from Zajac, 1989).

  • V^{\mathrm{M}} = A^{\mathrm{M}} \ell_{\mathrm{o}}^{\mathrm{M}}  

  • \ell_{\mathrm{initial}}^{\mathrm{MT}} = \ell_{\mathrm{s}}^{\mathrm{T}} + \ell_{\mathrm{o}}^{\mathrm{M}}, where \ell_{\mathrm{initial}}^{\mathrm{MT}} is the distance between the origin of the muscle (on the ground) and its attachment point (on the block) at the beginning of the simulation. Note that \text{Z}_{\mathrm{origin}} must be set so this constraint is satisfied.

To be a valid entry for the design competition, your muscle must satisfy the following constraints:

  • V^{\mathrm{M}} \leq 100\,\text{cm}^3

  • F_{\mathrm{o}}^{\mathrm{M}}\,\tilde{v}_{\mathrm{max}}^{\,\mathrm{M}}\,\ell_{\mathrm{o}}^{\mathrm{M}} \leq 175\,\text{W}

  • 0.15\,\text{m} \leq \ell_{\mathrm{initial}}^{\mathrm{MT}} \leq 0.45\,\text{m}   Note that you can adjust \text{Z}_{\mathrm{origin}} to satisfy this constraint.

  • \ell_{\mathrm{s}}^{\mathrm{T}} \geq 0.1\,\text{m}

  • 0.05\,\text{m} \leq \ell_{\mathrm{o}}^{\mathrm{M}} \leq 0.2\,\text{m}

  • 0 \deg \leq \alpha_{\mathrm{o}} \leq 30 \deg

  • 2\,\frac{1}{\text{s}} \leq \tilde{v}_{\mathrm{max}}^{\,\mathrm{M}} \leq 10\,\frac{1}{\text{s}} (i.e., the max_contraction_velocity muscle property must be between 2 and 10)

  • \int_{0}^{1} u(t)\,dt \leq 0.5  (constraint on excitation signal)

  • 10\,\text{ms} \leq \tau_{\mathrm{act}} \leq 20\,\text{ms}

  • 40\,\text{ms} \leq \tau_{\mathrm{deact}} \leq 60\,\text{ms}

  • 30\,\text{ms} \leq \tau_{\mathrm{deact}} - \tau_{\mathrm{act}} \leq 40\,\text{ms}

The initial activation will be 0.01 and the initial fiber length will be determined by the equilibrium condition. To match these conditions in your testing, make sure your muscle's default_activation is 0.01 and enable "Solve for equilibrium for actuator states" when using the ForwardTool.

Before you begin creating muscles, write down your conceptual strategy for building the best muscle possible.

Design your muscle and complete the design report in the questions section.