OpenSim Core

NOTE: This repository contains OpenSim 4.0 development and cannot be used to build OpenSim 3.x or earlier. For OpenSim 3.x, see here.

OpenSim is software that lets users develop models of musculoskeletal structures and create dynamic simulations of movement, such as this one:

More information can be found at our websites:

• OpenSim website; in particular, the support page.
• SimTK project website

This repository contains the source code for OpenSim's C++ libraries, C++ examples, command-line applications (inverse kinematics, computed muscle control, etc.), and Java and Python wrapping. This repository does not include source code for the OpenSim GUI.

Simple example

Let's simulate a simple arm whose elbow is actuated by a muscle:

#include <OpenSim/OpenSim.h>
using namespace SimTK;
using namespace OpenSim; using OpenSim::Body;
int main() {
    Model model; model.setUseVisualizer(true);
    // Two links, with mass of 1 kg, center of mass at the
    // origin of the body's frame, and moments/products of inertia of zero.
    OpenSim::Body* link1 = new OpenSim::Body("humerus", 1, Vec3(0), Inertia(0));
    OpenSim::Body* link2 = new OpenSim::Body("radius", 1, Vec3(0), Inertia(0));

    // Joints that connect the bodies together.
    PinJoint* joint1 = new PinJoint("shoulder",
            // Parent body, location in parent, orientation in parent.
            model.getGround(), Vec3(0), Vec3(0),
            // Child body, location in child, orientation in child.
            *link1, Vec3(0, 1, 0), Vec3(0));
    PinJoint* joint2 = new PinJoint("elbow",
            *link1, Vec3(0), Vec3(0), *link2, Vec3(0, 1, 0), Vec3(0));

    // Add an actuator that crosses the elbow, and a joint stop.
    Millard2012EquilibriumMuscle* muscle = new
        Millard2012EquilibriumMuscle("biceps", 200, 0.6, 0.55, 0);
    muscle->addNewPathPoint("point1", *link1, Vec3(0, 0.8, 0));
    muscle->addNewPathPoint("point2", *link2, Vec3(0, 0.7, 0));

    // A controller that specifies the excitation of the biceps muscle.
    PrescribedController* brain = new PrescribedController();
    brain->addActuator(*muscle);
    // Muscle excitation is 0.3 for the first 0.5 seconds, and 1.0 thereafter.
    brain->prescribeControlForActuator("biceps",
            new StepFunction(0.5, 3, 0.3, 1));

    // Add bodies and joints to the model.
    model.addBody(link1); model.addBody(link2);
    model.addJoint(joint1); model.addJoint(joint2);
    model.addForce(muscle);
    model.addController(brain);

    // Configure the model.
    State& state = model.initSystem();
    // Fix shoulder joint, flex elbow joint.
    model.updCoordinateSet()[0].setLocked(state, true);
    model.updCoordinateSet()[1].setValue(state, 0.5 * Pi);
    model.equilibrateMuscles(state);

    // Add display geometry.
    model.updMatterSubsystem().setShowDefaultGeometry(true);
    Visualizer& viz = model.updVisualizer().updSimbodyVisualizer();
    viz.setBackgroundColor(Vec3(1, 1, 1));
    // Ellipsoids: 0.5 m radius along y axis, centered 0.5 m up along y axis.
    DecorativeEllipsoid geom(Vec3(0.1, 0.5, 0.1)); Vec3 center(0, 0.5, 0);
    viz.addDecoration(link1->getMobilizedBodyIndex(), Transform(center), geom);
    viz.addDecoration(link2->getMobilizedBodyIndex(), Transform(center), geom);

    // Simulate.
    RungeKuttaMersonIntegrator integrator(model.getSystem());
    Manager manager(model, integrator);
    manager.setInitialTime(0); manager.setFinalTime(10.0);
    manager.integrate(state);
};

This code produces the following animation:

---

Building from the source code

We support a few ways of building OpenSim:

1. On Windows using Microsoft Visual Studio.
2. On Mac OSX using Xcode.
3. On Ubuntu using Unix Makefiles.

On Windows using Visual Studio

Get the dependencies

• operating system: Windows 7 or 8.
• cross-platform build system: CMake >= 3.1.3
• compiler / IDE: Visual Studio 2015.
  • Visual Studio Community 2015 is sufficient and is free for everyone. If you want to use Visual Studio Enterprise 2015, you may be able to get it for free at Dreamspark if you are at an academic institution.
  • Visual Studio 2015 does not install C++ support by default. During the installation you must select Custom, and check Programming Languages > Visual C++ > Common Tools for Visual C++ 2015. You can uncheck all other boxes. If you have already installed Visual Studio without C++ support, simply re-run the installer and select Modify.
• physics engine: Simbody >= 3.6
• API documentation (optional): Doxygen >= 1.8.6
• version control (optional): git. There are many options:
  • Git for Windows, most advanced;
  • TortoiseGit, intermediate; good for TortoiseSVN users;
  • GitHub for Windows, easiest.
• Bindings (optional): SWIG 3.0.5
  • MATLAB scripting (optional): Java development kit 1.7.
  • python scripting (optional):
    • Enthought Canopy, or
    • Anaconda

Download the OpenSim-Core source code

• Method 1; If you want to get going quickly, download the source code from https://github.com/opensim-org/opensim-core/releases, for the version of OpenSim you want. We'll assume you unzipped the source code into C:/opensim-core-source.

• Method 2: If you plan on updating your OpenSim installation or you want to contribute back to the project, clone the opensim-core git repository into C:/opensim-core-source. If using TortoiseGit, open Windows Explorer, right-click in the window, select Git Clone..., and provide the following:

  • URL: https://github.com/opensim-org/opensim-core.git.
  • Directory: C:/opensim-core-source.

  If using a Git Bash or Git Shell, run the following:

    $ git clone https://github.com/opensim-org/opensim-core.git C:/opensim-core-source
  

  This will give you a bleeding-edge version of OpenSim-Core.

Configure and generate project files

1. Open CMake.
2. In the field Where is the source code, specify C:/opensim-core-source.
3. In the field Where to build the binaries, specify something like C:/opensim-core-build, or some other path that is not inside your source directory. This is not where we are installing OpenSim-Core; see below.
4. Click the Configure button.
   1. Choose the Visual Studio 14 generator (for Visual Studio 2015). To build as 64-bit, select Visual Studio 14 Win64.
   2. Click Finish.
5. Where do you want to install OpenSim-Core on your computer? Set this by changing the CMAKE_INSTALL_PREFIX variable. We'll assume you set it to C:/opensim-core. If you choose a different installation location, make sure to use yours where we use C:/opensim-core below.
6. Tell CMake where you installed Simbody by setting the SIMBODY_HOME variable to where you installed Simbody (e.g., C:/Simbody).
7. Set the remaining configuration options.
   • BUILD_EXAMPLES to compile C++ API examples.
   • BUILD_TESTING to ensure that OpenSim works correctly. The tests take a while to build; if you want to build OpenSim quickly, you can turn this off.
   • BUILD_JAVA_WRAPPING if you want to access OpenSim through MATLAB or Java; see dependencies above.
   • BUILD_PYTHON_WRAPPING if you want to access OpenSim through Python; see dependencies above. CMake sets PYTHON_* variables to tell you the Python it will use for building the wrappers.
   • BUILD_API_ONLY if you don't want to build the command-line applications.
   • It is very important to use Java or Python environment binary format compatible with API build (either all 32 or 64 bit).
8. Click the Configure button again. Then, click Generate to make Visual Studio project files in the build directory.

Build and install

1. Open C:/opensim-core-build/OpenSim.sln in Visual Studio.

2. Select your desired Solution configuration from the drop-down at the top.

   • Debug: debugger symbols; no optimizations (more than 10x slower). Library names end with _d.
   • Release: no debugger symbols; optimized.
   • RelWithDebInfo: debugger symbols; optimized. Bigger but not slower than Release; choose this if unsure.
   • MinSizeRel: minimum size; optimized.

   You at least want release libraries (the last 3 count as release), but you can have debug libraries coexist with them. To do this, go through the installation process twice, once for each of the two configurations. You should install the release configuration last to ensure that you use the release version of the command-line applications instead of the slow debug versions.

3. Build the API documentation. This is optional, and you can only do this if you have Doxygen. Build the documentation by right-clicking doxygen and selecting Build.

4. Build the libraries, etc. by right-clicking ALL_BUILD and selecting Build.

5. Run the tests by right-clicking RUN_TESTS_PARALLEL and selecting Build.

6. Install OpenSim-Core by right-clicking INSTALL and selecting Build.

Set environment variables

In order to use the OpenSim-Core command-line applications or use OpenSim-Core libraries in your own application, you must add the OpenSim-Core bin/ directory to your PATH environment variable.

1. In the Start menu (Windows 7) or screen (Windows 8), search environment.
2. Select Edit the system environment variables.
3. Click Environment Variables....
4. Under System variables, click Path, then click Edit.
5. Add C:/opensim-core/bin; to the front of of the text field. Don't forget the semicolon!

On Mac OSX using Xcode

Get the dependencies

• operating system: Mac OSX 10.8 or later.
• cross-platform build system: CMake >= 2.8.8
• compiler / IDE: Xcode >= 5, through the Mac App Store.
• physics engine: Simbody >= 3.6.
• API documentation (optional): Doxygen >= 1.8.6
• version control (optional): git.
  • Xcode Command Line Tools gives you git on the command line.
  • GitHub for Mac, for a simple-to-use GUI.
• Bindings (optional): SWIG 3.0.5
  • MATLAB scripting (optional): Java development kit 1.7.
  • python scripting (optional):
    • Mac OSX comes with python, but you could also use:
    • brew install python,
    • Enthought Canopy, or
    • Anaconda

You can get most of these dependencies using Homebrew:

$ brew install cmake doxygen swig

Download the OpenSim-Core source code

• Method 1; If you want to get going quickly, download the source code from https://github.com/opensim-org/opensim-core/releases, for the version of OpenSim you want. We'll assume you unzipped the source code into ~/opensim-core-source.

• Method 2: If you plan on updating your OpenSim installation or you want to contribute back to the project, clone the opensim-core git repository into ~/opensim-core-source. Run the following in a terminal, or find a way to run the equivalent commands in a GUI client:

    $ git clone https://github.com/opensim-org/opensim-core.git ~/opensim-core-source
  

  This will give you a bleeding-edge version of OpenSim-Core.

Configure and generate project files

1. Open CMake.
2. In the field Where is the source code, specify ~/opensim-core-source.
3. In the field Where to build the binaries, specify something like ~/opensim-core-build, or some other path that is not inside your source directory. This is not where we are installing OpenSim-Core; see below.
4. Click the Configure button. Choose Xcode. Click Finish.
5. Where do you want to install OpenSim-Core on your computer? Set this by changing the CMAKE_INSTALL_PREFIX variable. We'll assume you set it to ~/opensim-core. If you choose a different installation location, make sure to use yours where we use ~/opensim-core below. You should not use /usr/, /usr/local/, etc. (because our installation does not yet conform to the FHS).
6. Tell CMake where you installed Simbody by setting the SIMBODY_HOME variable to where you installed Simbody (e.g., ~/simbody). If you installed Simbody using brew, then CMake will find Simbody automatically.
7. Set the remaining configuration options.
   • BUILD_EXAMPLES to compile C++ API examples.
   • BUILD_TESTING to ensure that OpenSim works correctly. The tests take a while to build; if you want to build OpenSim quickly, you can turn this off.
   • BUILD_JAVA_WRAPPING if you want to access OpenSim through MATLAB or Java; see dependencies above.
   • BUILD_PYTHON_WRAPPING if you want to access OpenSim through Python; see dependencies above. CMake sets PYTHON_* variables to tell you the Python it will use for building the wrappers. (If you installed python with homebrew, CMake will not find the homebrew python libraries on its own; you must set the CMake variable PYTHON_LIBRARIES manually. Use '$(python-config --prefix)/lib/libpython2.7.dylib' in bash to get the correct value.)
   • BUILD_API_ONLY if you don't want to build the command-line applications.
8. Click the Configure button again. Then, click Generate to create Xcode project files in the build directory.

Build and install

1. Open ~/opensim-core-build/OpenSim.xcodeproj in Xcode.

2. Choose your Build Configuration for the ALL_BUILD Scheme by pressing Command-Shift , (or, Command-LessThan), or navigating to Product -> Scheme -> Edit Scheme...; and changing the Build Configuration field.

   • Debug: debugger symbols; no optimizations (more than 10x slower). Library names end with _d.
   • Release: no debugger symbols; optimized.
   • RelWithDebInfo: debugger symbols; optimized. Bigger but not slower than Release; choose this if unsure.
   • MinSizeRel: minimum size; optimized.

   You at least want release libraries (the last 3 count as release), but you can have debug libraries coexist with them. To do this, go through the installation process twice, once for each of the two configurations. You should install the release configuration last to ensure that you use the release version of the command-line applications instead of the slow debug versions.

3. Compile. Run the Scheme ALL_BUILD by clicking the play button in the upper left.

4. Test. Click on ALL_BUILD in the upper left, and select RUN_TESTS_PARALLEL. Change the Build Configuration of this Scheme to the same as you used for ALL_BUILD (using the same instructions as above). Click the play button.

5. Build the API documentation. This is optional, and you can only do this if you have Doxygen. Click on the current Scheme (RUN_TESTS_PARALLEL) and select doxygen. Click the play button.

6. Install. Click on the current Scheme (RUN_TESTS_PARALLEL or doxygen), and select install. Click the play button.

Set environment variables

1. Executables. If you want to run OpenSim-Core's executables from anywhere on your computer, you must update your PATH. Note some of the names of OpenSim-Core executables conflict with some UNIX commands (e.g., id). To give preference to OpenSim-Core's executables, we must prepend OpenSim-Core's bin/ directory to the path. Open a terminal and type:

    $ echo 'export PATH=~/opensim-core/bin:$PATH' >> ~/.bash_profile
   

2. Libraries. Hopefully you can skip this step. This step is required if:

3. You are using CMake version 2.8.11 or older.

4. You plan on building C++ executables or libraries on top of OpenSim, and you plan to "install" them in the CMake sense of the word (that is, you're not going to simply use them from your project's build directory).

5. You plan to use the Java or MATLAB scripting.

If any of these are true, then you must add OpenSim-Core libraries to your linker path. Open a terminal and type:

      $ echo 'export DYLD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/opensim-core/lib' >> ~/.bash_profile

Your changes will only take effect in new terminal windows.

On Ubuntu using Unix Makefiles

Get the dependencies

Most dependencies can be obtained via the Ubuntu software repositories. On each line below, we show the corresponding package.

• operating system: Ubuntu 13.10 or later.
• cross-platform build system: CMake >= 2.8.8; cmake-gui. Ubuntu 12.04 only has 2.8.6 available; download from the website or from this third party PPA.
• compiler: gcc >= 4.8; g++-4.8, or Clang >= 3.4; clang-3.4.
• physics engine: Simbody >= 3.6.
• API documentation (optional): Doxygen >= 1.8.6; doxygen.
• version control (optional): git; git.
• Bindings (optional): SWIG 3.0.5; must get from SWIG website.
  • MATLAB scripting (optional): Java development kit >= 1.7; openjdk-6-jdk or openjdk-7-jdk.
  • python scripting (optional): python-dev.

For example, you could get the required dependencies (except Simbody) via:

$ sudo apt-get install cmake-gui g++-4.8

And you could get all the optional dependencies via:

$ sudo apt-get install doxygen git swig openjdk-7-jdk python-dev

Download the OpenSim-Core source code

• Method 1; If you want to get going quickly, download the source code from https://github.com/opensim-org/opensim-core/releases, for the version of OpenSim you want. We'll assume you unzipped the source code into ~/opensim-core-source.

• Method 2: If you plan on updating your OpenSim installation or you want to contribute back to the project, clone the opensim-core git repository into C:/opensim-core-source. Run the following in a terminal:

    $ git clone https://github.com/opensim-org/opensim-core.git ~/opensim-core-source
  

  This will give you a bleeding-edge version of OpenSim-Core.

Configure and generate project files

1. Open CMake.

2. In the field Where is the source code, specify ~/opensim-core-source.

3. In the field Where to build the binaries, specify something like ~/opensim-core-build, or some other path that is not inside your source directory. This is not where we are installing OpenSim-Core; see below.

4. Click the Configure button. Choose Unix Makefiles. Click Finish.

5. Where do you want to install OpenSim-Core on your computer? Set this by changing the CMAKE_INSTALL_PREFIX variable. We'll assume you set it to ~/opensim-core. If you choose a different installation location, make sure to use yours where we use ~/opensim-core below. You should not use /usr/, /usr/local/, etc. (because our installation does not yet conform to the FHS), but /opt/ is okay.

6. Tell CMake where you installed Simbody by setting the SIMBODY_HOME variable to where you installed Simbody (e.g., ~/simbody). If you installed Simbody using brew, then CMake will find Simbody automatically.

7. Choose your build type by setting CMAKE_BUILD_TYPE to one of the following:

   • Debug: debugger symbols; no optimizations (more than 10x slower). Library names end with _d.
   • Release: no debugger symbols; optimized.
   • RelWithDebInfo: debugger symbols; optimized. Bigger but not slower than Release; choose this if unsure.
   • MinSizeRel: minimum size; optimized.

   You at least want release libraries (the last 3 count as release), but you can have debug libraries coexist with them. To do this, go through the installation process twice, once for each of the two configurations. It is typical to use a different build directory for each build type (e.g., ~/opensim-core-build-debug and ~/opensim-core-build-release). You should install the release configuration last to ensure that you use the release version of the command-line applications instead of the slow debug versions.

8. Set the remaining configuration options.

   • BUILD_EXAMPLES to compile C++ API examples.
   • BUILD_TESTING to ensure that OpenSim works correctly. The tests take a while to build; if you want to build OpenSim quickly, you can turn this off.
   • BUILD_JAVA_WRAPPING if you want to access OpenSim through MATLAB or Java; see dependencies above.
   • BUILD_PYTHON_WRAPPING if you want to access OpenSim through Python; see dependencies above.
   • BUILD_API_ONLY if you don't want to build the command-line applications.
   • OPENSIM_COPY_SIMBODY to decide if Simbody headers and libraries should be installed inside OpenSim; you want this off if you're installing Simbody and OpenSim into /usr/ or /usr/local/.

9. Click the Configure button again. Then, click Generate to create Makefiles in the build directory.

Build and install

1. Open a terminal and navigate to the build directory.

    $ cd ~/opensim-core-build
   

2. Build the API documentation. This is optional, and you can only do this if you have Doxygen.

    $ make doxygen
   

3. Compile. Use the -jn flag to build using n concurrent jobs (potentially in parallel); this will greatly speed up your build. For example:

    $ make -j8
   

4. Run the tests.

    $ ctest -j8
   

5. Install (to ~/opensim-core).

    $ make -j8 install
   

Set environment variables

1. Executables. Add OpenSim-Core's executables to the path so you can access them from any directory on your computer. NOTE that some of the names of OpenSim-Core executables conflict with some UNIX commands (e.g., id). To give preference to OpenSim-Core's executables, we must prepend OpenSim-Core's bin/ directory to the path.

    $ echo 'export PATH=~/opensim-core/bin:$PATH' >> ~/.bashrc
   

2. Libraries. Allow executables to find OpenSim-Core libraries by adding the OpenSim-Core lib/ directory to your linker path.

    $ echo 'export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/opensim-core/lib' >> ~/.bashrc
   

Your changes will only take effect in new terminal windows.