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.)

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.

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 functionality with plugins. Available standard on most platforms. Note that full SCISim test suite requires the installation of the numpy and h5py Python packages.

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.

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

1. Install Qt4 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!

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 ..

• 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 ..
    

  To build using homebrew's python use:

        cmake -DUSE_QT4=ON -DUSE_HDF5=ON -DUSE_PYTHON=ON -DPYTHON_LIBRARY=/usr/local/Cellar/python//2.7.13/Frameworks/Python.framework/Versions/2.7/lib/libpython2.7.dylib -DPYTHON_INCLUDE_DIR=/usr/local/Cellar/python//2.7.13/Frameworks/Python.framework/Headers ..
  

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

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:

• Reflections on Simultaneous Impact
  Breannan Smith, Danny M. Kaufman, Etienne Vouga, Rasmus Tamstorf, Eitan Grinspun

  • Describes the Generalized Reflections and Generalized Restitution impact models.

• Staggered Projections for Frictional Contact in Multibody Systems
  Danny M. Kaufman, Shinjiro Sueda, Doug L. James, Dinesh K. Pai

  • Describes the globally coupled Staggered Projections friction solver.