Building your first Neuromechanic Model

From neuromechanicwiki
Jump to: navigation, search

Overview

After you have installed Neuromechanic, you can try to build your first Neuromechanic model. In this tutorial we will:

  1. Build a pendulum in an nmcb file (use any plain text, or better yet, XML editor).
  2. Load the pendulum in Neuromechanic GUI and use the GUI tools to manipulate it.
  3. Run our first simulation!

Anatomy of an NMCB File

We will be using XML to describe our pendulum model. In short, this means we will be writing a text based file using special keywords or tags to describe the elements of our model. A glossary of these tags is found here.

In XML an element is composed of an opening and closing tag. For example to identify our file as a Neuromechanic file we always start with the <NeuromechanicFile> opening tag and then close the file with </NeuromechanicFile>. This pair of tags then results in our <NeuromechanicFile> element:

  1.    <NeuromechanicFile>
  2.    </NeuromechanicFile>

Elements provide a way for grouping necessary information in a hierarchical form. Thus, everything pertaining to this Neuromechanic file will now be a sub-element of <NeuromechanicFile>. For example, all <Bodies> will be defined within the <NeuromechanicFile> element:

  1.    <NeuromechanicFile>
  2.       <Bodies>
  3.       </Bodies>
  4.    </NeuromechanicFile>

Sub-elements can continue to be defined until the content of the element is informational. For example we see on line 4 of the following code that the <Mass> element has numeric content. In this way the XML tags form elements that define the hierarchical structure of a file as well as the informational content.

  1.    <NeuromechanicFile>
  2.       <Bodies>
  3.          <RigidBody Name="Base">
  4.             <Mass>12</Mass>
  5.             <Inertia>1 1 1 0 0 0</Inertia>
  6.             <CenterOfMass>0 0 0</CenterOfMass>
  7.          </RigidBody>
  8.       </Bodies>
  9.    </NeuromechanicFile>

A final feature of XML is that elements may also have attributes that define unique properties for a given element. You may have noticed this on line 3 of the code from above. Element attributes are defined within the opening tag itself and can be thought of as descriptors that make that particular element unique. As we make more complicated models it is likely that we will have many <RigidBody> elements, so to uniquely identify each rigid body we give each a unique name by specifying it in the attribute Name.

  1.   ...
  2.      <RigidBody Name="BodyOne">
  3.      </RigidBody>
  4.      ...
  5.      <RigidBody Name="BodyTwoMillion">
  6.      </RigidBody>
  7.   ...


Now using these principles we can start our NMCB file! Open a new file in a text editor, Neuromechanic's Source View or your favorite XML editor (notepad++ (win), textwrangler (osx), gedit (win,osx,linux), etc). In your text editor start the file with the opening element that defines this XML file as a Neuromechanic file:

  1.    <NeuromechanicFile>
  2.    </NeuromechanicFile>

Then save the file as pendulum.nmcb. Make sure to specify the .nmcb extension if you are using an editor that isn't Neuromechanic's Source View.

Rigid Bodies

RigidBodyBasics.png

Next, we will add rigid bodies to our NMCB file, which are the basic building blocks that give structure to our model. They are, if you will, the skeleton of the model. Rigid bodies are defined as sub-elements of the <Bodies> element, which itself resides within the top level element <NeuromechanicFile>. So, to continue our file, add the <Bodies> element to your file and one <RigidBody> sub-element, as follows:

  1.    <NeuromechanicFile>
  2.       <Bodies>
  3.          <RigidBody>
  4.          </RigidBody>
  5.       </Bodies>
  6.    </NeuromechanicFile>

In an attempt to improve readability from hereon the enclosing or parent element will not necessarily be shown, but if there is any confusion you can look at the complete file, which is listed at the end of this tutorial.


We now go over some basic theory, which will help in understanding how to define rigid bodies in the NMCB file. There are two basic aspects to a system of rigid bodies, the inertia of the individual bodies and the connectivity between bodies. These aren't by themselves too complicated but to describe them mathematically requires coordinate systems that can be tricky.

Inertia

No matter how complicated the shape or distribution of the mass of a rigid body, its inertia can be described in an arbitrary coordinate frame with exactly 10 numbers. Those numbers are the scalar mass, the six components of the rotational inertia (also known as moment of inertia), and a vector from the origin of the coordinate system to the mass center of the rigid body. These must be specified for every rigid body in Neuromechanic using the sub-element tags <Mass>, <Inertia>, and <CenterOfMass>.

If you are building a rough estimate of a model and don't have exact values it may be possible to ballpark some of those numbers, but six of them, the rotational inertia, are not intuitive. Those six and the mass could also obtained from the density and geometric description (size and orientation) of an equivalent object which is uniformly dense. If you are modeling a potato, imagine how big and how dense an ellipsoid would be that would feel like it had the same inertia as the potato when you heft it. You can use mass instead of density but if you're modeling an animal then the density of water is not too bad of a guess for almost any size animal. The mass and moment of inertia about the center of mass are then:

[math]mass = \dfrac{4πρabc}{3}[/math]
[math]I_{xx}=\dfrac{mass\left(b^2+c^2\right)}{5}[/math]
[math]I_{yy}=\dfrac{mass\left(a^2+c^2\right)}{5}[/math]
[math]I_{zz}=\dfrac{mass\left(b^2+a^2\right)}{5}[/math]
[math]I_{xy}=I_{yz}=I_{xz}=0[/math]

We're leaving orientation out of it for the moment and assuming that the ellipsoid is aligned with the coordinate system such that semi-principal axis with length [math]a[/math], is aligned with the x-axis, semi-principal axis with length [math]b[/math], is aligned with the y-axis, and semi-principal axis with length [math]c[/math], is aligned with the z-axis.

Enough theory. Let's build two rigid bodies for our pendulum. The first body will be welded to the ground and have no dynamics. It's not necessary but we want to see how to link bodies together so we'll include it.

I imagine my pendulum to have equivalent ellipsoids like those in the figure to the right. One is a little sphere of about 1 cm radius. The other (the pendulum) has a long dimension of 10 cm and two short dimensions of 2 cm each. Lets say the long dimension of the pendulum is in the y-direction. This gives

[math]mass = \dfrac{4π 1000kg/m^3 \cdot 0.1m \cdot 0.02m \cdot 0.02m}{3} = 0.1676kg[/math]
[math]I_{yy}=\dfrac{0.1676kg\left(0.02m^2+0.02m^2\right)}{5}=2.6808\cdot10^{-5}kg \cdot m^2[/math]
[math]I_{xx}=I_{zz}=\dfrac{0.1676kg\left(0.1m^2+0.02m^2\right)}{5}=3.4851\cdot10^{-4}kg \cdot m^2[/math]

Modify your <RigidBody> tag to include an attribute Name defined as "Pendulum1" and add the sub-elements <Mass> and <Inertia>.

  1.    <RigidBody Name="Pendulum1">
  2.       <Mass>0.1676</Mass>
  3.       <Inertia>3.4851e-004 2.6808e-005 3.4851e-004 0 0 0</Inertia>
  4.    </RigidBody>

Notice there are no units in the nmcb file. Because units are not specified it is up to the user to maintain consistency. If length is specified in meters in one place it must be specified in meters everywhere. If length is meters, mass is kilograms, and time is seconds, then force must be Newtons.

Now, let's add another <RigidBody> tag as a sub-element of <Bodies> for the sphere that we are going to use for the base, having the following form based on calculating the mass and inertia properties:

  1.    <RigidBody Name="Base">
  2.       <Mass>0.00418</Mass>
  3.       <Inertia>1.6755e-007 1.6755e-007 1.6755e-007 0 0 0</Inertia>
  4.    </RigidBody>

But wait! Aren't we missing an important part, the <CenterOfMass>? This must be specified to make a complete rigid body. However, the center of mass vector isn't a description of the inertia; rather it is a way to define it in a given coordinate system. We'll come back to it when we've talked more about coordinate systems.

Joints

Joints describe how rigid bodies can move relative to one another. There are many kinds of joints and several ways of describing them. In Neuromechanic the joints are made up of 1 to 6 kinematic degrees of freedom and are specified using the <DegreeOfFreedom> tag as a sub-element of the <RigidBody> element. Each degree of freedom has only a few required features. Each must have an attribute with a unique name. Also, each must have an attribute specifying one of two types, translational or rotational. Then, each has an element <Axis> that describes a unit vector axis in the direction of motion and a <State> element that defines the position and velocity of the motion along the axis direction, which comprise the "state" of the degree of freedom. Finally, we allow for joints to be locked using the <Locked> element. The general structure of a <DegreeOfFreedom> element looks like:

  1.    <RigidBody>
  2.       <DegreeOfFreedom Name="..." Type="rotation|translation">
  3.          <Axis>...</Axis>
  4.          <State Type="Kinematic">...</State>
  5.          <Locked>true|false</Locked>
  6.       </DegreeOfFreedom>
  7.    </RigidBody>

In this tutorial we are building a pendulum which can only rotate about a single axis. That means the rigid body has a joint with 1 rotational degree of freedom. This kind of joint is often called a hinge joint. In the figure above imagine that the pendulum can rotate about an axis coming out of the picture at the yellow dot by the red arrow labeled FL2. The semi-transparency shows what a positive (right hand rule) displacement of the ellipse about its joint would look like.

To specify this in our file we will add a <DegreeOfFreedom> sub-element to our rigid body that we named "pendulum1". Define the attributes for this joint with its name as "pendulum1z" and its type as "rotation". Its axis is in the z-direction (Line 4) and we'll set its state with zero displacement and velocity (Line 5). It is not locked meaning that it is free to move in a dynamic simulation, so we set the <Locked> as false (Line 6).

  1.    <RigidBody name="pendulum1">
  2.       ...
  3.       <DegreeOfFreedom Name="pendulum1z" Type="rotation">
  4.          <Axis>0 0 1</Axis>
  5.          <State Type="Kinematic">0 0</State>
  6.          <Locked>false</Locked>
  7.       </DegreeOfFreedom>
  8.       ...
  9.    </RigidBody>

Next, let us also define the motion of our base. Here we want the base to be able to be able to move in all possible ways, so we define all six elementary degrees of freedom allowing translation and rotation in three dimensions:

  1.    <RigidBody name="base">
  2.       ...
  3.       <DegreeOfFreedom Name="base1tx" Type="translation">
  4.          <Axis>1 0 0</Axis>
  5.          <State Type="Kinematic">0 0</State>
  6.          <Locked>true</Locked>
  7.       </DegreeOfFreedom>
  8.       <DegreeOfFreedom Name="base1ty" Type="translation">
  9.          <Axis>0 1 0</Axis>
  10.          <State Type="Kinematic">0 0</State>
  11.          <Locked>true</Locked>
  12.       </DegreeOfFreedom>
  13.       <DegreeOfFreedom Name="base1tz" Type="translation">
  14.          <Axis>0 0 1</Axis>
  15.          <State Type="Kinematic">0 0</State>
  16.          <Locked>true</Locked>
  17.       </DegreeOfFreedom>
  18.       <DegreeOfFreedom Name="base1rx" Type="rotation">
  19.          <Axis>1 0 0</Axis>
  20.          <State Type="Kinematic">0 0</State>
  21.          <Locked>true</Locked>
  22.       </DegreeOfFreedom>
  23.       <DegreeOfFreedom Name="base1ry" Type="rotation">
  24.          <Axis>0 1 0</Axis>
  25.          <State Type="Kinematic">0 0</State>
  26.          <Locked>true</Locked>
  27.       </DegreeOfFreedom>
  28.       <DegreeOfFreedom Name="base1rz" Type="rotation">
  29.          <Axis>0 0 1</Axis>
  30.          <State Type="Kinematic">0 0</State>
  31.          <Locked>true</Locked>
  32.       </DegreeOfFreedom>
  33.       ...
  34.    </RigidBody>

Notice that all degrees of freedom for the base are locked. This means that the base can't move! So why did we define all of these degrees of freedom? This is actually very important, in Neuromechanic one rigid body in the simulation must have all six degrees of freedom defined in order to solve the equations of motion. These degrees of freedom can be locked, but they must all be specified. Therefore, we really don't want the base to move, we just want to study the motion of the pendulum.

So now we have a base that doesn't move and a pendulum that can only rotate about a single axis. But what is the pendulum rotating about? We only have a two body system, so the likely candidate is to have the pendulum rotate about the base. Then, I could pick up the base and wave it all around the pendulum would still only rotate about a single axis relative to the base.

To define this relationship, lets assemble the system. We have to define the parent for each rigid body and where to place the joint of the body relative to the origin of the parent (FL1 and FL2 for the base and pendulum respectively in the figure). By defining the parent we are describing what the degrees of freedom for the child rigid body will be moving relative to. Let's begin with the "base" rigid body. We would like its motion to be relative to the inertial or fixed frame. We do this by adding a sub-element <FrameLocation> to the <RigidBody> tag and specifying its Parent attribute as "ground" (Line 3). Ground is a special name that refers to the inertial frame. We then define the location of the degree of freedom coordinate frame using a vector that is defined in the parent's coordinates, which in this case is the inertial frame coordinate system. Next, we define the "pendulum1" rigid body to be relative to the "base" rigid body by specifying "pendulum1" <FrameLocation> (Line 8). Notice that here we specify the Parent attribute as "base", which is the name of the rigid body that we want "pendulum1" motion to be relative to.

  1.    <RigidBody name="base">
  2.       ...
  3.       <FrameLocation Parent="ground">0 0 0</FrameLocation>
  4.       ...
  5.    </RigidBody>
  6.    <RigidBody name="pendulum1">
  7.       ...
  8.       <FrameLocation Parent="base">0 0 0</FrameLocation>
  9.       ...
  10.    </RigidBody>

The above specification results in the joints for both bodies being located at the global or "ground" origin. We now return to defining where to put the center of mass of a body relative to the joint of that body (CoM1 and CoM2 for the base and pendulum respectively in the figure). We do this by adding a sub-element <CenterOfMass> to the <RigidBody> element. Its contents are a vector specifying the location of the center of mass in the rigid body's coordinate frame whose location is specified based on the contents of <FrameLocation>.

  1.    <RigidBody name="base">
  2.       ...
  3.       <CenterOfMass>0 0 0</CenterOfMass>
  4.       ...
  5.    </RigidBody>
  6.    <RigidBody name="pendulum1">
  7.       ...
  8.       <CenterOfMass>0 0.12 0</CenterOfMass>
  9.       ...
  10.    </RigidBody>

The center of mass of the base is located a the origin of the joint. Recall that the long axis of the pendulum is in the y-direction and the total length of the equivalent ellipsoid is 20cm. If we define the center of mass to be 12 cm in the y-direction. Then the final configuration of the linked system of rigid bodies looks like the far right of the figure.

And that's it. We put all this in a couple of special elements for it to be recognized. Save the file as pendulum.nmcb and load it into Neuromechanic

<NeuromechanicFile>
   <Bodies>
      <RigidBody name="base">
         <FrameLocation Parent="ground">0 0 0</FrameLocation>
         <DegreeOfFreedom Name="base1tx" Type="translation">
            <Axis>1 0 0</Axis>
            <State Type="Kinematic">0 0</State>
            <Locked>true</Locked>
         </DegreeOfFreedom>
         <DegreeOfFreedom Name="base1ty" Type="translation">
            <Axis>0 1 0</Axis>
            <State Type="Kinematic">0 0</State>
            <Locked>true</Locked>
         </DegreeOfFreedom>
         <DegreeOfFreedom Name="base1tz" Type="translation">
            <Axis>0 0 1</Axis>
            <State Type="Kinematic">0 0</State>
            <Locked>true</Locked>
         </DegreeOfFreedom>
         <DegreeOfFreedom Name="base1rx" Type="rotation">
            <Axis>1 0 0</Axis>
            <State Type="Kinematic">0 0</State>
            <Locked>true</Locked>
         </DegreeOfFreedom>
         <DegreeOfFreedom Name="base1ry" Type="rotation">
            <Axis>0 1 0</Axis>
            <State Type="Kinematic">0 0</State>
            <Locked>true</Locked>
         </DegreeOfFreedom>
         <DegreeOfFreedom Name="base1rz" Type="rotation">
            <Axis>0 0 1</Axis>
            <State Type="Kinematic">0 0</State>
            <Locked>true</Locked>
         </DegreeOfFreedom>
         <Mass>0.00418</Mass>
         <Inertia>1.6755e-007 1.6755e-007 1.6755e-007 0 0 0</Inertia>
         <CenterOfMass>0 0 0</CenterOfMass>
      </RigidBody>
      <RigidBody name="pendulum">
         <FrameLocation Parent="base">0 0 0</FrameLocation>
         <DegreeOfFreedom Name="pendulum1z" Type="rotation">
            <Axis>0 0 1</Axis>
            <State Type="Kinematic">0 0</State>
            <Locked>false</Locked>
         </DegreeOfFreedom>
         <Mass>0.1676</Mass>
         <Inertia>3.4851e-004 2.6808e-005 3.4851e-004 0 0 0</Inertia>
         <CenterOfMass>0 0.12 0</CenterOfMass>
      </RigidBody>
   </Bodies>
</NeuromechanicFile>

Neuromechanic GUI tools for manipulating the model

NeuromechanicGUI.png

Open Neuromechanic and load pendulum.nmcb. This is likely the first time you have run Neuromechanic so you have to do some setup work to be able to view the model. File->Preferences (Windows) or neuromechanic->Preferences (Max OSX) (ctrl-,[?-,]) opens a window that lets you change the way the model is rendered. There are two tabs in the window, make sure Rendering is selected.

  • Change Environment->ReferenceAxesVisible to true.
  • Change Model->Bodies->BodyFrameVisible to true.
  • Change Model->Bodies->InertialEllipsoidsVisible to true.
  • Select the checkbox next to Model->Bodies->BodyColor.
  • Save changes and close the window by clicking OK

Now lets get oriented to the gui. In addition to the menus at the top of the gui there are 6 major elements. Starting at the top and going counter clockwise they are:

  1. The simulation toolbar
  2. The model tree
  3. Editors
  4. Log window
  5. The viewing windows / source editor / script editor (tabbed)

The log window

If something unexpected happens. The first place to look for answers is the log window. All the information in the log window is printed to a file "neuromechaniclog.txt" which is stored in the Local app data folder $LOCALAPPDATA$\Neuromechanic in Windows and on OSX inside the bundled application under the folder $NEUROMECHANIC_INSTALL_DIR$/Resources. This is useful if something unexpected and nasty happens so that Neuromechanic crashes and the log window is not available.

When you load a file it prints a summary of what the model is, scroll up a bit in this window and you'll see this:

 ===============Loaded Model Summary=================
Number of rigid bodies                        2
Number of muscles                             0
Number of kinematic Degrees of Freedom        7
Number of Constrained degrees of freedom      0
Number of locked degrees of freedom           6
 ____________________________________________________
Number of RigidBodyStates                    14
+ Number of MuscleStates                      0
+ Number of EnvironmentStates                 0
+ Number of NeuronStates                      0
= Total Number of States                     14
 ____________________________________________________
Total Number of control states                0
 ==============Loaded Model Summary==================
  TOTAL MASS =              0.17178
 =================Muscle Summary=====================
  -INDEX-            -MUSCLE NAME-    -MTL-     -LF- -LF/LF0-
  MUSCLE MASS =              0.00000
 =================Muscle Summary=====================

Which can be helpful if you got a model from someone else and want some quick insight.

The viewing windows

TutorialPendulumInGUI.png

There are up to four viewing windows. The borders can be resized if you would like to see fewer. Here is a summary of how to manipulate the viewing windows.

  • To use any of the following tools, click somewhere in the viewing window to give that window focus
  • Two-dimensional "ortho" projections in the global xy, yz, and xz planes can be selected by pressing the two desired keys. For example, to view the global xy plane with x as the horizontal axis and y as the vertical axis, press the "x" key and hold it while also pressing the "y" key. To view the zx plane with z as horizontal and x as vertical press "z" and hold while pressing "x". To swap the direction of an axis, press that key again. For example if the "ortho" xy plane is being viewed with positive x to the right and positive y up you can press "x" which will change the positive x axis to the left without affecting the y-axis.
  • Three-dimensional "perspective" views can be selected by pressing "x", "y" and "z" together.
  • Pan - left mouse click and drag
  • Zoom - middle mouse click and drag or scroll. shift-drag or shift-scroll to zoom faster.
  • Rotate - ("perspective" view only) right mouse click and drag


Source view

Above the viewing windows are two tabs: Model and Source. You are currently in Model view. Click the Source tab. That's the XML definition of the current model. You may notice that Neuromechanic added some parts. For now we're not going to worry about what Neuromechanic adds except to say that there are certain required children of many Elements in the XML including some children of the <NeuromechanicFile> element. Neuromechanic adds required children that as long as they do not affect the intent of the original file. For other required children Neuromechanic will stop loading the file and prompt you to fill in the missing required element. When you save the nmcb file, all additions will remain in the saved file. Lets go back to Model view.

Model Tree

The model tree lists certain recognized children elements of the <NeuromechanicFile>. Editors can be loaded by clicking on certain of the elements. Click, for example on Bodies. This loads the Degree of freedom editor. We will discuss the other uses of the model tree in future tutorials

Degree of freedom editor

The degree of freedom editor allows the user to configure the kinematic degrees of freedom from the gui. The name of the degree of freedom and the body to which it belongs is listed with a checkbox, slider, and entry boxes. The checkboxes can be selected/deselected to control whether or not the degree of freedom is locked. The sliders and entry boxes are used to control the position of the state. The last degree of freedom for our model is the hinge. Move it to 30 degrees. At this point you should be able to manipulate the view to get the same thing as the image above.

Running our first simulation

Alright, we're almost ready to run a simulation. We just need to add one more thing to the model. Click on the source tab and look through the children of <NeuromechanicFile>. One of them will be named <Environment> which will have a child named <Gravity>. This is the acceleration of gravity in the global frame of reference. Change it to


  1.    <Gravity>0 -9.80665 0</Gravity>

Then save the file (ctrl-s [?-s]) and switch back to model view. In the model tree, click on Parameters. This will open the simulation editor

Simulation editor

Remember I said that Neuromechanic adds some things that are required if they are not provided by the user? Some of those things are simulation parameters. You can edit them directly in the XML file (under <Parameters>) or here in the simulation editor. These things include the start time of the simulation, the end time, how big of integration steps to take, what kind of integrator to use and other things that the numerical integrator might need. For this simulation we'll just hope that Neuromechanic picked reasonable values (it did). It also contains an option to save the output of the simulation. Scroll down a bit to where there is a checkbox called "Save Output" and select it. You can change the file name of the simulation output file if you like. If you don't change it the file will be saved as the same name and directory as the nmcb file except the extension will be nmco (so pendulum.nmco for us). There is a lot of information about a simulation that you can export in your nmco file. These are listed in the output variables section right below the "save output" check box. For now we're just going to run the simulation without exporting any of them.

Simulation toolbar

{{#ev:youtube|kHlc_tc_n7E|400|right|Pendulum Simulation}} We're all set. Press the Simulate button on the simulation toolbar. If you set it up like I did you'll see the pendulum make a bit less than one complete cycle. And that's pretty much it for the simulation. If you opened the pendulum.nmco file in a text editor at the bottom you would see a bunch of <Dynamics> elements.

  1.   <Dynamics>
  2.     <Time>9.7E-1</Time>
  3.     <ModelState>0. 0. 0. 0. 0. 0. 3.348382819431 0. 0. 0. 0. 0. 0. -1.623156227434E1</ModelState>
  4.     <SavedVariables></SavedVariables>
  5.     <ContactForce/>
  6.     <NeuronOutput></NeuronOutput>
  7.   </Dynamics>

This is the simulation output. A <Dynamics> element is created at each reporting interval of the simulation. The <Dynamics> element will always have , <ModelState>, and <SavedVariables> elements. These, along with the parameters stored in the body file at the beginning of the simulation, are sufficient to completely describe the dynamics of the simulation. You may notice that there are 14 numbers in <ModelState>. Recall that the model has seven degrees of freedom. Six for the base and one for the pendulum. The first seven numbers of <ModelState> correspond to the position of the degrees of freedom at that time. The second seven correspond to the velocities. These are the only state variables for this model. In some of the tutorials to come we'll add more state variables for muscles and neurons.

Let's close the file (ctrl-w [?-w]) and load the simulation output file (probably pendulum.nmco unless you renamed it). Press the playback button on the simulation toolbar. The simulation will replay. When that finishes drag the slider on the simulation toolbar around. The slider controls which point in time of the simulation is loaded and visible in the viewing windows.

Notice that there are a few things different about the gui with an output file loaded. The source tab is no longer selectable. In addition you won't be able to save this file. The reason is this:

NMCO files contain a copy of the original model that was used to run the simulation as well as the results of the simulation (e.g. degree of freedom values over the course of the simulation). The results of the simulation depend entirely on the parameters of the model used to run the simulation. To maintain the integrity of the output files, no simulation parameters in an output file should be changed. Therefore, simulation parameters are not allowed to be changed and the NMCO file is not allowed to be saved. This should remove the problem of mismatch between simulation parameters and simulation results.

Basically we're trying to make it harder to foul things up. There are only a few things in the NMCO file which can safely be changed without compromising the integrity of the output file (viewing parameters for example). We'll talk about these later, the bottom line for now is that Neuromechanic attempts to cause no integral changes to the simulation results of the NMCO file within the Neuromechanic environment.

Click on Parameters in the model tree. Scroll down to that "Save output" and check it again. This time, rename the output to pendulum1.nmco for example. In the output variables right below that checkbox the first output you can select is ModelDState. Make sure to check it. Now press Playback in the simulation toolbar. Now, if you did a diff on the pendulum.nmco and pendulum1.nmco the <Dynamics> element will look like this.

  1.   <Dynamics>
  2.     <Time>9.7E-1</Time>
  3.     <ModelState>0. 0. 0. 0. 0. 0. 3.348382819431 0. 0. 0. 0. 0. 0. -1.623156227434E1</ModelState>
  4.     <SavedVariables></SavedVariables>
  5.     <ContactForce/>
  6.     <NeuronOutput></NeuronOutput>
  7.     <ModelDState>0. 0. 0. 0. 0. 0. -1.623156227434E1 0. 0. 0. 0. 0. 0. -1.466190333711E1</ModelDState>
  8.   </Dynamics>

Basically what we have done is taken the original simulation and played it again to get additional information about the file. <ModelDState> is the time derivative of <ModelState>, so the first seven values are degree of freedom velocities and the second seven are degree of freedom accelerations. If you run a batch of simulations and forget to export something (for example musculotendon lengths) you don't need to re-run the simulations, you just need to replay them, which can save a lot of time.

That's enough for this tutorial. Thanks for playing.