Simbody

Simbody is a high-performance, open-source toolkit for science- and engineering-quality simulation of articulated mechanisms, including biomechanical structures such as human and animal skeletons, mechanical systems like robots, vehicles, and machines, and anything else that can be described as a set of rigid bodies interconnected by joints, influenced by forces and motions, and restricted by constraints. Simbody includes a multibody dynamics library for modeling motion in generalized/internal coordinates in O(n) time. This is sometimes called a Featherstone-style physics engine.

Simbody provides a C++ API that is used to build domain-specific applications; it is not a standalone application itself. For example, it is used by biomechanists in OpenSim, by roboticists in Gazebo, and for biomolecular research in MacroMoleculeBuilder (MMB). Here's an artful simulation of several RNA molecules containing thousands of bodies, performed with MMB by Samuel Flores:

Read more about Simbody at the Simbody homepage.

Simple example: a double pendulum

Here's some code to simulate and visualize a 2-link chain:

#include "Simbody.h"
using namespace SimTK;
int main() {
    // Define the system.
    MultibodySystem system;
    SimbodyMatterSubsystem matter(system);
    GeneralForceSubsystem forces(system);
    Force::Gravity gravity(forces, matter, -YAxis, 9.8);

    // Describe mass and visualization properties for a generic body.
    Body::Rigid bodyInfo(MassProperties(1.0, Vec3(0), UnitInertia(1)));
    bodyInfo.addDecoration(Transform(), DecorativeSphere(0.1));

    // Create the moving (mobilized) bodies of the pendulum.
    MobilizedBody::Pin pendulum1(matter.Ground(), Transform(Vec3(0)),
            bodyInfo, Transform(Vec3(0, 1, 0)));
    MobilizedBody::Pin pendulum2(pendulum1, Transform(Vec3(0)),
            bodyInfo, Transform(Vec3(0, 1, 0)));

    // Set up visualization.
    Visualizer viz(system);
    system.addEventReporter(new Visualizer::Reporter(viz, 0.01));

    // Initialize the system and state.
    State state = system.realizeTopology();
    pendulum2.setRate(state, 5.0);

    // Simulate for 50 seconds.
    RungeKuttaMersonIntegrator integ(system);
    TimeStepper ts(system, integ);
    ts.initialize(state);
    ts.stepTo(50.0);
}

See Simbody's User Guide for a step-by-step explanation of this example.

Features

Wide variety of joint, constraint, and force types; easily user-extended.
Forward, inverse, and mixed dynamics. Motion driven by forces or prescribed motion.
Contact (Hertz, Hunt and Crossley models).
Gradient descent and interior point optimizers.
A variety of numerical integrators with error control.
Visualizer, using OpenGL.

You want to...

install Simbody (see also: old Windows and Mac/Linux build instructions, old install instructions).
use Simbody in your own program.
view API documentation.
learn the theory behind Simbody.
extend Simbody.
view the Simbody forum.
report a bug or suggest a feature.
get the source code, or contribute!

Dependencies

Simbody depends on the following:

cross-platform building: CMake 2.8 or greater
compiler: Visual Studio 2010 or 2013 (Windows only), gcc (typically on Linux), or Clang (typically on Mac)
linear algebra: LAPACK and BLAS
visualization (optional): FreeGLUT, Xi and Xmu
API documentation (optional): Doxygen

Installing

Simbody works on Windows, Mac, and Linux. For Windows, you must build from source. For Mac and Linux, you can use a package manager or build from source. In this file, we provide instructions for 4 different ways of installing Simbody:

Windows: build from source using Microsoft Visual Studio
Mac: install with Homebrew
Ubuntu: install with apt-get
UNIX (Mac, Linux): build from source using gcc or Clang with Makefile's

These are not the only ways to install Simbody, however. For example, on a Mac, you could use CMake and Xcode.

Windows and Visual Studio

Get the dependencies

We give the linear algebra dependencies to you, and Windows comes with the visualization dependencies.

Download and install Microsoft Visual Studio. If using an Express (free) version, use Visual Studio Express 2013 for Windows Desktop or Visual C++ 2010 Express.
Download and install CMake.
If you want to build API documentation, download and install Doxygen as well.

Download the Simbody source code

Download the source code from https://github.com/simbody/simbody/releases. Look for the highest-numbered release, click on the .zip button, and unzip it on your computer. We'll assume you unzipped the source code into C:/simbody-source.

Configure and generate project files

Open CMake.
In the field Where is the source code, specify C:/simbody-source.
In the field Where to build the binaries, specify something like C:/simbody-build.
Click the Configure button.
1. Choose a "generator" that corresponds to the Visual Studio you're using. For Visual Studio 2013, select Visual Studio 12. To build as 64-bit, select an option that ends with Win64.
2. Click Finish.
Where do you want to install Simbody on your computer? Set this by changing the CMAKE_INSTALL_PREFIX variable. We'll assume you set it to C:/simbody.
Click the Configure button again. Then, click Generate to make Visual Studio project files.

Build and install

Open C:/simbody-build/Simbody.sln in Visual Studio.
Select your desired Solution configuration from the drop-down at the top.
- Debug: debugger symbols; no optimizations (very slow).
- Release: no debugger symbols; optimized.
- RelWithDebInfo: debugger symbols; optimized. Select this if you don't know.
- MinSizeRel: minimum size; optimized.
Build the project ALL_BUILD by right-clicking it and selecting Build.
Run the tests by right-clicking RUN_TESTS and selecting Build.
Install Simbody by right-clicking INSTALL and selecting Build.

Set environment variables and test the installation

If you are only building Simbody to use it with OpenSim, you can skip this section.

Allow executables to find Simbody libraries (.dll's) by adding the Simbody 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:/simbody/bin; to the front of the text field. Don't forget the semicolon!
Allow Simbody and other projects (e.g., OpenSim) to find Simbody. In the same Environment Variables window: 6. Under User variables for..., click New.... 7. For Variable name, type SIMBODY_HOME. 8. For Variable value, type C:/simbody.
Changes only take effect in newly-opened windows. Close any Windows Explorer or Command Prompt windows.
Test your installation by navigating to C:/simbody/examples/bin and running SimbodyInstallTest.exe or SimbodyInstallTestNoViz.exe.

Layout of installation

How is your Simbody installation organized?

bin/ the visualizer and shared libraries (.dll's, used at runtime).
doc/ a few manuals, as well as API docs (SimbodyAPI.html).
examples/
- src/ the source code for the examples.
- bin/ the examples, compiled into executables; run them!
- simmath/ source code for examples of Simbody's SimTKmath library.
include/ the header (.h) files; necessary for projects that use Simbody.
lib/ "import" libraries, used during linking.
share/ CMake files that are useful for projects that use Simbody.

Mac and Homebrew

If using a Mac and Homebrew, the dependencies are taken care of for you.

With this method, Simbody is built without C++11 (the -std=c++11 compiler flag). Thus, any projects you build on top of Simbody must also NOT use C++11. If you do try to use C++11, you'll run into mysterious errors. See issue #125.

Install

Install Homebrew.
Open a terminal.
Add the Open Source Robotics Foundation's list of repositories to Homebrew:
```
$ brew tap osrf/simulation
```
Install the latest release of Simbody.
```
$ brew install simbody
```
To install from the master branch instead, append --HEAD to the command above.

Where is Simbody installed?

Simbody is now installed to /usr/local/Cellar/simbody/<version>/, where <version> is either the version number (e.g., 3.4), or HEAD if you specified --HEAD above.

Some directories are symlinked (symbolically linked) to /usr/local/, which is where your system typically expects to find executables, shared libraries (.dylib's), headers (.h's), etc. The following directories from the Simbody installation are symlinked:

include/simbody -> /usr/local/include/simbody
lib -> /usr/local/lib
share/doc/simbody -> /usr/local/share/doc/simbody

Layout of installation

What's in the /usr/local/Cellar/simbody/<version>/ directory?

include/simbody/ the header (.h) files; necessary for projects that use Simbody.
lib/ shared libraries (.dylib's), used at runtime.
- cmake/simbody/ CMake files that are useful for projects that use Simbody.
- pkgconfig/ pkg-config files useful for projects that use Simbody.
- simbody/examples/ the examples, compiled into executables; run them!
libexec/simbody/ the simbody-visualizer executable.
share/doc/simbody/ a few manuals, as well as API docs (SimbodyAPI.html).
- examples/ source code for the examples.

Ubuntu and apt-get

You can currently get Simbody via the Open Source Robotics Foundation's Debian repositories. We are currently working on getting Simbody directly into the Debian repositories. apt-get will take care of getting the necessary dependencies.

With this method, Simbody is built without C++11 (the -std=c++11 compiler flag). Thus, any projects you build on top of Simbody must also NOT use C++11. If you do try to use C++11, you'll run into mysterious errors. See issue #125.

Install

Setup your computer to accept software from packages.osrfoundation.org. This step depends on your version of Ubuntu. For more detailed instructions, see OSRF's installation instructions.

12.04:

  sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu precise main" > /etc/apt/sources.list.d/gazebo-latest.list'

13.10:

  sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu saucy main" > /etc/apt/sources.list.d/gazebo-latest.list'

Install Simbody.

 $ sudo apt-get update
 $ sudo apt-get install libsimbody-dev

Layout of installation

Simbody is installed into the usr/ directory.

usr/include/simbody/ the header (.h) files; necessary for projects that use Simbody.
usr/lib/ shared libraries (.so's), used at runtime.
- cmake/simbody/ CMake files that are useful for projects that use Simbody.
- pkgconfig/ pkg-config files useful for projects that use Simbody.
usr/libexec/simbody/ the simbody-visualizer executable.
usr/share/doc/simbody/ a few manuals, as well as API docs (SimbodyAPI.html).

UNIX and Makefiles

These instructions are for building Simbody from source on either a Mac or on Ubuntu.

Get dependencies

On a Mac, the Xcode developer package gives LAPACK and BLAS to you via the Accelerate framework. Mac's come with the visualization dependencies.

On Ubuntu, we need to get the dependencies ourselves. Open a terminal and run the following commands.

Get the necessary dependencies: $ sudo apt-get install cmake liblapack-dev
If you want to use the CMake GUI, install cmake-qt-gui.
For visualization (optional): $ sudo apt-get install freeglut3-dev libxi-dev libxmu-dev
For API documentation (optional): $ sudo apt-get install doxygen

Get the Simbody source code

There are two ways to get the source code.

Method 1: Download the source code from https://github.com/simbody/simbody/releases. Look for the highest-numbered release, click on the .zip button, and unzip it on your computer. We'll assume you unzipped the source code into ~/simbody-source.
Method 2: Clone the git repository.
1. Get git.
  - Mac: You might have it already, especially if you have Xcode, which is free in the App Store. If not, one method is to install Homebrew and run brew install git in a terminal.
  - Ubuntu: run sudo apt-get install git in a terminal.
2. Clone the github repository into ~/simbody-source.
```
 $ git clone https://github.com/simbody/simbody.git ~/simbody-source
 $ git checkout Simbody-3.4
```
3. In the last line above, we assumed you want to build a released version. Feel free to change the version you want to build. If you want to build the latest development version ("bleeding edge") of Simbody off the master branch, you can omit the checkout line.

Configure and generate Makefiles

Create a directory in which we'll build Simbody.

 $ mkdir ~/simbody-build
 $ cd ~/simbody-build

Configure your Simbody build with CMake. We'll use the cmake command but you could also use the interactive tools ccmake or cmake-gui. You have a few configuration options to play with here.
- If you don't want to fuss with any options, run:
```
  $ cmake ~/simbody-source
```
- Where do you want to install Simbody? By default, it is installed to /usr/local/. You can change this via the CMAKE_INSTALL_PREFIX variable. Let's choose ~/simbody:
```
  $ cmake ~/simbody-source -DCMAKE_INSTALL_PREFIX=~/simbody
```
- Do you want to use C++11? By default, Simbody assumes not. If you plan to use Simbody in a project that DOES use C++11, then you must build Simbody with C++11 as well. You can change this via the SIMBODY_STANDARD_11 flag:
```
  $ cmake ~/simbody-source -DSIMBODY_STANDARD_11=on
```
- There are a few other variables you might want to play with:
  - BUILD_EXAMPLES on by default
  - BUILD_TESTING on by default
  - BUILD_VISUALIZER on by default
  You can combine all these options. Here's another example:
```
  $ cmake ~/simbody-source -DCMAKE_INSTALL_PREFIX=~/simbody -DBUILD_VISUALIZER=off 
```

Build and install

Compile. Use the -jn flag to build using n processor cores. For example:
```
 $ make -j8
```
Run the tests.
```
 $ ctest -j8
```
Install. The sudo is there in case your CMAKE_INSTALL_PREFIX is something like /usr/local/ (the default).
```
 $ sudo make -j8 install
```

Just so you know, you can also uninstall (delete all files that CMake placed into CMAKE_INSTALL_PREFIX) if you're in ~/simbody-build.

$ make uninstall

Set environment variables and test the installation

If you are only building Simbody to use it with OpenSim, you can skip this section.

Allow executables to find Simbody libraries (.dylib's or so's) by adding the Simbody lib directory to your linker path. There are two cases in which this is unnecessary:
1. If you chose your CMAKE_INSTALL_PREFIX to be /usr/
2. If you chose your CMAKE_INSTALL_PREFIX to be /usr/local/ (the default), AND your libraries are in /usr/local/lib/. Go check! On recent Ubuntu versions, the libraries are in an additional subdirectory (on Ubuntu 13.10: /usr/local/lib/x86_64-linux-gnu).
  - Mac:
```
  $ sudo echo 'export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:~/simbody/lib' > /etc/profile
```
  - Ubuntu:
```
  $ sudo echo 'export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/simbody/lib/x86_64-linux-gnu' > ~/.bashrc
```
  These commands add a line to a configuration file that is loaded every time you open a new terminal. If using Ubuntu, you may need to replace x86_64-linux-gnu with the appropriate directory on your computer.

Allow Simbody and other projects (e.g., OpenSim) to find Simbody.

Mac:

  $ sudo echo 'export SIMBODY_HOME=~/simbody' > /etc/profile

Ubuntu:

  $ sudo echo 'export SIMBODY_HOME=~/simbody' > ~/.bashrc

Open a new terminal.

Test your installation:

 $ cd ~/simbody/share/doc/simbody/examples/bin
 $ ./SimbodyInstallTest # or ./SimbodyInstallTestNoViz

Layout of installation

The installation creates the following directories in CMAKE_INSTALL_PREFIX. The directory [x86_64-linux-gnu] only exists on recent versions of Ubuntu (e.g., 13.10), and even then may be different.

include/simbody/ the header (.h) files; necessary for projects that use Simbody.
lib/[x86_64-linux-gnu]/ shared libraries (.dylib's or .so's), used at runtime.
- cmake/simbody/ CMake files that are useful for projects that use Simbody.
- pkgconfig/ pkg-config files useful for projects that use Simbody.
- simbody/examples/ the examples, compiled into executables; run them!
libexec/simbody/ the simbody-visualizer executable.
share/doc/simbody/ a few manuals, as well as API docs (SimbodyAPI.html).
- examples/ source code for the examples.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Simbody

Simple example: a double pendulum

Features

You want to...

Dependencies

Installing

Windows and Visual Studio

Get the dependencies

Download the Simbody source code

Configure and generate project files

Build and install

Set environment variables and test the installation

Layout of installation

Mac and Homebrew

Install

Where is Simbody installed?

Layout of installation

Ubuntu and apt-get

Install

Layout of installation

UNIX and Makefiles

Get dependencies

Get the Simbody source code

Configure and generate Makefiles

Build and install

Set environment variables and test the installation

Layout of installation

Files

README.md

Latest commit

History

README.md

File metadata and controls

Simbody

Simple example: a double pendulum

Features

You want to...

Dependencies

Installing

Windows and Visual Studio

Get the dependencies

Download the Simbody source code

Configure and generate project files

Build and install

Set environment variables and test the installation

Layout of installation

Mac and Homebrew

Install

Where is Simbody installed?

Layout of installation

Ubuntu and apt-get

Install

Layout of installation

UNIX and Makefiles

Get dependencies

Get the Simbody source code

Configure and generate Makefiles

Build and install

Set environment variables and test the installation

Layout of installation