Simbody [![Appveyor][buildstatus_image_appveyor]][appveyorci] [![Codecov][buildstatus_image_codecov]][codecovci]

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][thy]. 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][flores]:

[![Sam Flores' Simbody RNA simulation][rna]][simbios]

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.
    system.setUseUniformBackground(true);
    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 20 seconds.
    RungeKuttaMersonIntegrator integ(system);
    TimeStepper ts(system, integ);
    ts.initialize(state);
    ts.stepTo(20.0);
}

![Double-pendulum simulation in Simbody][doublePendulum]

See [Simbody's User Guide][user] 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, interior point, and global (CMA) optimizers.
A variety of numerical integrators with error control.
Visualizer, using OpenGL

You want to...

install Simbody.
[use Simbody in your own program][user].
view API documentation.
learn the theory behind Simbody.
extend Simbody.
get support at the Simbody Forum.
report a bug or suggest a feature.

Dependencies

Simbody depends on the following:

cross-platform building: CMake 3.21 or later.
compiler: Visual Studio 2015, 2017, or 2019 (Windows only), gcc 4.9.0 or later (typically on Linux), Clang 3.4 or later, or Apple Clang (Xcode) 8 or later.
linear algebra: LAPACK 3.6.0 or later and BLAS
visualization (optional): FreeGLUT, Xi and Xmu
API documentation (optional): Doxygen 1.8.6 or later; we recommend at least 1.8.8.

Using Simbody

Creating your own Simbody-using project with CMake To get started with your own Simbody-using project, check out the cmake/SampleCMakeLists.txt file.

Installing

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

Windows: build from source using Microsoft Visual Studio.
Linux or Mac (make): build from source using gcc or Clang with make.
Mac (Homebrew): automated build/install with Homebrew.
Ubuntu/Debian: install pre-built binaries with apt-get.
FreeBSD: install pre-built binaries with pkg.
Windows using MinGW: build from source using MinGW.
Windows/Mac/Linux: install pre-built binaries with the Conda package manager.
Install using vcpkg: download and install simbody using the vcpkg dependency manager

If you use Linux, check Repology to see if your distribution provides a package for Simbody.

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

Windows using Visual Studio

Get the dependencies

All needed library dependencies are provided with the Simbody installation on Windows, including linear algebra and visualization dependencies.

Download and install Microsoft Visual Studio, version 2015, 2017, or 2019. The Community edition is free and sufficient.

2015: By default, Visual Studio 2015 does not provide C++ support; when installing, be sure to select Custom, and check Programming Languages > Visual C++ > Common Tools for Visual C++ 2015. If you have already installed Visual Studio without C++ support, simply re-run the installer and select Modify.
2017 and later: In the installer, select the Desktop development with C++ workload.
Any other C++ code you plan to use with Simbody should be compiled with the same compiler as used for Simbody.

Download and install CMake, version 3.21 or higher.
(optional) If you want to build API documentation, download and install Doxygen, version 1.8.8 or higher.

Download the Simbody 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 C:/Simbody-source.
Method 2: Clone the git repository.
1. Get git. There are many options:
  - Git for Windows (most advanced),
  - TortoiseGit (intermediate; good for TortoiseSVN users),
  - GitHub Desktop (easiest).
2. Clone the github repository into C:/Simbody-source. Run the following in a Git Bash / Git Shell, or find a way to run the equivalent commands in a GUI client:
```
 $ git clone https://github.com/simbody/simbody.git C:/Simbody-source
 $ git checkout Simbody-3.8
```
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.
  
  To see the set of releases and checkout a specific version, you can use the following commands:
```
 $ git tag
 $ git checkout Simbody-X.Y.Z
```

Configure and generate project files

Open CMake.
In the field Where is the source code, specify C:/Simbody-source.
In the Preset dropdown, choose Default MSVC build configuration. Presets specify a set of standard build variables. The Default MSVC build configuration is the recommended build preset for most users. Preset build directories are located at ${simbody-source-dir}/out/build/${preset-name}.
- If desired, custom build settings can be applied after choosing a preset.
Click the Configure button.
1. When prompted to select a generator, in the dropdown for Optional platform for generator, choose x64 to build 64-bit binaries or leave blank to build 32-bit binaries. In older versions of CMake, select a generator ending with Win64 to build 64-bit binaries (e.g., Visual Studio 14 2015 Win64 or Visual Studio 15 2017 Win64), or select one without Win64 to build 32-bit binaries (e.g., Visual Studio 14 2015 or Visual Studio 15 2017).
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. If you choose a different installation location, make sure to use yours where w

Simbody

Install / Use

README