/scisim

A 2D and 3D rigid body simulation framework with a focus on preserving core physical properties.

Primary LanguageC++Apache License 2.0Apache-2.0

The Structured Contact Impact Simulator

Build Status Circle CI

Welcome to SCISim (pronounced skiz-em), the Structured Contact Impact Simulator! SCISim is a C++14 software package designed to simulate systems of rigid bodies where the evolution is dominated by collisions. SCISim respects essential symmetries and structures from the continuous setting at coarse temporal discretizations through the use of geometric integrators for the unconstrained and constrained dynamics. In practice, this leads to stable and predictable behavior across timesteps. For a preview of the types of simulations that SCISim can perform, please see our demo reel. (Coming soon. Until then, please see videos from a few papers that use SCISim.)

To resolve collisions between volumetric objects, SCISim employs precomputed implicit distance fields. We provide a tool to compute these distance fields from a triangle mesh in a separate repository.

Required Dependencies

SCISim requires three dependencies for a minimal build:

  • RapidXML: An XML parser to read simulation descriptions.

  • Eigen: A linear algebra library used internally.

  • So-bogus: A non-smooth Coulomb friction solver.

We provide a 'get_dependencies.sh' script to automatically download, verify, and extract the supported versions of these libraries.

Recommended Dependencies

We recommend a few dependencies for full featured builds:

  • Qt4: A user interface library to provide graphical front ends. Available through most standard package managers.

  • HDF5: A binary file format for configuration and force output. Available through most standard package managers.

  • Ipopt: A nonlinear optimization package for global LCP solves, for the Staggered Projections friction solver, and for the Generalized Reflections and Generalized Restitution impact models. Ipopt requires a Fortran compiler. See the included Ipopt build instructions.

  • HSL2013: A collection of sparse linear solvers suggested for use with Ipopt.

  • Python: An interpreted language used for extending SCISim's behavior with plugins. Python is primarily used to script the motion of kinematic bodies and to set custom parameters in the contact model. If these fall outside your intended use case, you can safely omit the Python dependency. Available standard on most platforms. Note that full SCISim test suite requires the installation of the numpy and h5py Python packages.

Optional Dependencies

SCISim optionally supports other numerical solvers:

  • QL: A quadratic program solver useful for small to medium problems. To use QL, place the file ql.for under SCISim/Math/QL and rebuild. QL requires a Fortran compiler, and is available for academic use.

Quickstart Guide

To obtain a minimal demo build that simulates colliding triangle meshes:

  1. Install Qt4, HDF5, and CMake. These packages are available from most standard package managers.

  2. Clone this repository and change into the project root:

     git clone https://github.com/breannansmith/scisim.git
 cd scisim

  3. From the project root, run the script get_dependencies.sh to download, extract, and verify the required dependencies. Note that this script requires the md5 or md5sum utility:

     ./get_dependencies.sh

  4. Create a build directory under the project root and change into this directory:

     mkdir build
 cd build

  5. Run CMake to create the build system with Qt4 and HDF5 enabled:

     cmake -DUSE_QT4=ON -DUSE_HDF5=ON ..

  6. Build SCISim:

     make

  7. Run the example simulation:

    1. With *nix:

       cd rigidbody3dqt4
 ./rigidbody3d_qt4 assets/tests_serialization/two_dragon_drop.xml

    2. With OS X:

       cd rigidbody3dqt4
 ./rigidbody3d_qt4.app/Contents/MacOS/rigidbody3d_qt4 assets/tests_serialization/two_dragon_drop.xml

  8. Press space to run the simulation!

Building SCISim

SCISim uses the CMake build system. SCISim is tested regularly against recent versions of the GCC, LLVM, and Intel compiler toolchains on both Linux and OS X. A minimal SCISim build requires only a C and C++ compiler. The optional QL and Ipopt dependencies require an additional Fortran compiler.

As an example, to build SCISim with an optional Fortran compiler using the Intel toolchain, from a build directory, run:

CC=icc CXX=icpc FC=ifort cmake ..

Substitute out the compiler names as required by your platform. The build system can be configured via the command line by running

ccmake ..

from the build directory.

Options of note include:

  • CMAKE_BUILD_TYPE: General build type that enables various optimization and compiler flags. Options are: Debug, Release, RelWithDebInfo, MinSizeRel

  • STRICT_BUILD: Enables aggressive warnings and treats warnings as errors. Recommended for development.

  • USE_HDF5: Enables state and force output via HDF5 files.

  • USE_IPOPT: Enables the Ipopt nonlinear solver.

  • USE_OPENMP: Enables OpenMP support. Highly recommend for the So-bogus solver.

  • USE_QT4: Enables support for graphical front ends using Qt4.

  • USE_PYTHON: Enables support for embedded Python language scripting. Required for kinematic scripting.

  • SANITIZER: Enables support for compiler sanitizer modes. Options are: none, address, undefined

To enable the build system to find Ipopt, prefix the cmake command with CMAKE_PREFIX_PATH set to your Ipopt installation directory:

CMAKE_PREFIX_PATH=/path/to/ipopt/install CC=gcc CXX=g++ FC=gfortran cmake -DUSE_IPOPT=ON ..

Platform Specific Issues

  • OS X

    • There are performance regressions with GCC and So-bogus when building with the GCC toolchain provided by MacPorts.

    • There are a number of strange behaviors with the Qt4 frontend when building against the version from MacPorts. I intend to upgrade to Qt5, which should remedy these issues.

    • Building Ipopt with GCC is incompatible with building SCISim with Clang.

    • CMake will often pull in different versions of the Python interpreter and the Python library, requiring the user to explicitly pass the location of the Python library to CMake. For example, to build with MacPorts' Python 2.7:

          cmake -DPYTHON_LIBRARY=/opt/local/lib/libpython2.7.dylib -DPYTHON_INCLUDE_DIR=/opt/local/Library/Frameworks/Python.framework/Headers ..

Note that the python2.7-config tool is useful for locating the library and include directory.

Relevant Citations

If this library helped you in a publication, please cite our Reflections on Simultaneous Impact paper so others can find our code and benefit as well. For further details on the algorithms and models available in SCISim, see the following publications: