Logo	Spider robot dropped onto an incline
Active entanglement gripper	Helix oscillating under gravity
	Real2Sim soft manipulator modelling

DisMech is a discrete differential geometry-based physical simulator for elastic rod-like structures and soft robots. Based on the Discrete Elastic Rods framework, it can be used to simulate soft structures for a wide variety of purposes such as robotic deformable material manipulation and soft robot control.

If you'd like DisMech to support a new feature, feel free create an issue, and we'll add it to the list here. For those looking to contribute, PRs are always welcome! Please make sure pre-commit is installed before contributing to adhere to style guidelines.

pip install pre-commit
pre-commit install1

• Expand Python bindings. PR #13

• Add extension control via natural length manipulation.
• Add shell functionality.
• Improve robustness of friction.
• Add contact logic for joints.

• Possibly replace floor contact force (currently uses IMC) with modified mass method.
• Add knot tying case.
• Add detailed documentation for all examples.
• Add time varying boundary condition logic.
• Add more controller types.

• Add a more sophisticated renderer. PR #12
• Add per-limb friction coefficient logic. PR #5
• Add active entanglement example code.
• Add limb self-contact option.
• Add forward Euler integration scheme.
• Add contact logic for limbs.

There are some dependencies required prior to compilation. Instructions for macOS and Ubuntu are similar (presented below). For other operating systems you should be able to modify the commands below appropriately. There is also a docker build available (Thanks to PR #15!), with more instructions in docker/README.md.

• macOS: Because this uses the MKL, it's not certain to run on Apple silicone.

• macOS: If you're running a mac, it's highly recommended you use a package manager like MacPorts or homebrew. Instructions below are for MacPorts.

• Note: Some of these packages are installed to the system library for convenience. You may want to install locally to e.g., ~/.local to avoid conflicts with system libraries. Add the cmake flag: -D CMAKE_INSTALL_PREFIX=~/.local. Then sudo is not required to install. You'll need to ensure subsequent builds know where to find the build libraries.

• X11

  • An X11 (xorg) server is necessary to use the freeglut library. This exists already on Linux.
  • macOS: This can be installed with MacPorts: sudo port install xorg-server. Then log out and back in.

• Eigen 3.4.0

  • Eigen is used for various linear algebra operations.
  • macOS: You can install this version with MacPorts: sudo port install eigen3. Otherwise, build instructions are below.
  • DisMech is built with Eigen version 3.4.0 which can be downloaded here. After downloading the source code, install through cmake as follows.

    cd eigen-3.4.0 && mkdir build && cd build
    cmake ..
    sudo make install

• Flexible Collision Library (FCL)

  • The FCL library is used to perform both broadphase and narrowphase collision detection with each discrete rod represented as a chain of cylinders.
  • FCL depends on both Eigen (instructions above) and libccd. Install libccd with the following commands, making sure to build shared libraries:

    git clone https://github.com/danfis/libccd
    cd libccd
    cmake -G "Unix Makefiles" -DBUILD_SHARED_LIBS=ON ..
    make -j4
    sudo make install

  • Next, install FCL from source using the following commands:

    git clone https://github.com/flexible-collision-library/fcl
    cd fcl && mkdir build && cd build
    cmake ..
    make -j4
    sudo make install

• SymEngine

  • SymEngine is used for symbolic differentiation and function generation.
  • macOS: SymEngine with LLVM can be installed with MacPorts: sudo port install symengine.
  • Before installing SymEngine, LLVM is required which can be installed most easily via a package manager:
    • Ubuntu: sudo apt-get install llvm
    • macOS: sudo port install llvm-15
  • Afterwards, install SymEngine from source using the following commands:

    git clone https://github.com/symengine/symengine
    cd symengine && mkdir build && cd build
    cmake -D WITH_LLVM=on -D BUILD_BENCHMARKS=off -D BUILD_TESTS=off ..
    make -j4
    sudo make install

  • macOS: You'll need to provide the LLVM root to the build with -D CMAKE_PREFIX_PATH=/opt/local/libexec/llvm-15 (if installed via MacPorts).

• Intel oneAPI Math Kernel Library (oneMKL)

  • Necessary for access to Pardiso, which is used as a sparse matrix solver.
  • Intel MKL is also used as the BLAS / LAPACK backend for Eigen.
  • macOS: Download from Intel and use the install script.
  • Ubuntu: Follow the below steps.

    cd /tmp
    wget https://registrationcenter-download.intel.com/akdlm/irc_nas/18483/l_onemkl_p_2022.0.2.136.sh
    
    # This runs an installer, simply follow the instructions.
    sudo sh ./l_onemkl_p_2022.0.2.136.sh

  • Add one of the following to your .bashrc so that cmake can find the MKL library. Change the directory accordingly if your MKL version is different. Note that older versions require setting MKLROOT while newer versions require MKL_DIR. You can find out which one from the cmake error message.

    export MKLROOT=/opt/intel/oneapi/mkl/2022.0.2   # for older versions
    export MKL_DIR=/opt/intel/oneapi/mkl/2024.2     # for newer versions

• OpenGL / GLUT

  • OpenGL / GLUT is used for barebones rendering through simple line graphics.
  • Simply install through apt package manager:
    • Ubuntu: sudo apt-get install libglu1-mesa-dev freeglut3-dev mesa-common-dev
    • macOS: sudo port install freeglut pkgconfig (Note: pkgconfig is necessary to avoid finding system GLUT instead of freeglut.)

• Lapack (included in MKL)

The default renderer used in DisMech is simply an isometric view of lines depicting rod centerlines using a barebones implementation based on OpenGL. For users wishing to have more advanced rendering with camera pose manipulation via the mouse, they can install and build with the Magnum Engine. Below is an example rendering.

• Magnum Engine
  • Before downloading magnum, users must first build and install Magnum's utility library Corrade. Install instructions for various platforms can be found here.
  • After installing Corrade, install instructions for Magnum can similarly be found here.
  • Finally, Magnum allows users to save each rendered frame as a png file which can be used to create videos such as ffmpeg. For this feature, we must download and build magnum-plugins as follows.

    sudo apt-get install libpng-dev  # a dependency of magnum-plugins' PngImageConverter
    git clone https://github.com/mosra/magnum-plugins
    cd magnum-plugins && mkdir build && cd build
    cmake -DWITH_PNGIMAGECONVERTER=ON ..
    make -j$(nproc)
    sudo make install

  • Once Corrade and Magnum are properly installed, users can build DisMech with the following additional cmake build flag:

    mkdir build && cd build
    cmake -DWITH_MAGNUM=ON ..
    make -j$(nproc)

  • For those wishing to customize the rendering settings, users can take a look and adjust the source code in MagnumSimEnv.cpp accordingly.
• Pybind11
  • DisMech also offers Python bindings via pybind11. Users can either install by source or via pip install pybind11. Afterward, the bindings can be built as follows:

    mkdir build && cd build
    cmake -DWITH_PYBIND=on ..
    make -j$(nproc)
    cd ..
    pip install -e .  # this will install py_dismech

  • Note that when building with older versions of MKL with Python, it may be possible to run into the following static linkage bug. Users can either upgrade their MKL version or specify their LD_PRELOAD explicitly to include the following .so files.

    export LD_PRELOAD=$MKL_LIB/libmkl_def.so.2:\
                      $MKL_LIB/libmkl_avx2.so.2:\
                      $MKL_LIB/libmkl_core.so.2:\
                      $MKL_LIB/libmkl_intel_lp64.so.2:\
                      $MKL_LIB/libmkl_intel_thread.so.2:\
                      /usr/lib/x86_64-linux-gnu/libiomp5.so

  • All available bindings can be seen in app.cpp. Users can expect heavy development for expanding the python bindings as time goes on.

DisMech is setup so that simulation environments can be instantiated using a single cpp file called robot_description.cpp.

Several example of working DisMech simulations can be seen in the examples/ directory. In order to run an example, copy the example cpp file into the main directory and then compile DisMech. For example, using the cantilever beam example:

cp examples/cantilever_case/cantilever_example.cpp robot_description.cpp
mkdir build && cd build
cmake ..
make -j$(nproc)
cd ..

Afterwards, simply run the simulation using the dismech.sh script.

./dismech.sh

Modifications to the examples can be made easily by changing the parameters shown below. If you want to run another example, simply replace the robot_description.cpp file and recompile. Users can also simply build all examples from the start. To do so, run the following:

mkdir build && cd build
cmake -DCREATE_EXAMPLES=on ..
make -j$(nproc)
cd ..
# Make sure to run from the main directory as some examples use relative paths
OMP_NUM_THREADS=1 ./examples/spider_case/spider_example_exec

The Pardiso solver can be parallelized by setting the env variable OMP_NUM_THREADS > 1. For all the systems defined in /examples, their Jacobian matrices are small enough that any amount of parallelization actually slows down the simulation. Therefore, it is recommended to set OMP_NUM_THREADS=1 (dismech.sh does this as automatically) and see if parallelization is worth it for larger systems through profiling.

Python versions of certain examples can be found in py_examples/. To run, simply run the provided scripts:

OMP_NUM_THREADS=1 python py_examples/spider_case/spider_example.py

In case you want to create a custom simulation environment, take a look at the provided examples on how to do so.

Model and environment parameters such as defining the soft structure(s) / robot(s), boundary conditions, forces, and logging are done solely in robot_description.cpp to avoid large recompile times.

In addition, various simulation and rendering parameters can be set through the SimParams and RenderParams structs, respectively. Both are shown below with default values and brief descriptions. For in-depth descriptions, please take a look at documentation in global_definitions.h. Note that parameters with a * have additional explanations below. Parameters with a ^ only apply when an implicit numerical integration scheme is chosen and are otherwise ignored.

struct SimParams {

  struct MaxIterations {
      int num_iters = 500;                       //   Number of iters to attempt solve
      bool terminate_at_max = true;              //   Whether to terminate after num_iters
  };

  double sim_time = 10;                          //    Total time for simulation [s]
  double dt = 1e-3;                              //    Time step size [s]
  IntegratorMethod integrator = BACKWARD_EULER;  // *  Numerical integration scheme
  double dtol = 1e-2;                            // *^ Dynamics tolerance [m/s]
  double ftol = 1e-4;                            // *^ Force tolerance
  MaxIterations max_iter;                        // ^  Maximum iterations for a time step
  LineSearchType line_search = GOLDSTEIN;        // *^ Specify line search algorithm
  int adaptive_time_stepping = 0;                // *^ Adaptive time stepping
  bool enable_2d_sim = false;                    //    Lock z and theta DOFs
};

struct RenderParams {
  RenderEngine renderer = OPENGL;                // *  Renderer type
  double render_scale = 1.0;                     //    Rendering scale
  int cmd_line_per = 1;                          //    Command line sim info output period
  int render_per = 1;                            //    Rendering period (only for Magnum)
  std::string render_record_path;                     //    Rendering frames recording path (only for Magnum).
  bool show_mat_frames = false;                  //    Render material frames (only for OpenGL)
};

Detailed parameter explanations:

• renderer - Determines the renderer. Currently, available options are

  • HEADLESS: No rendering. Fastest and best for rapid data generation.
  • OPENGL: Fixed isometric view rendering. Renders centerlines of rods as simple lines. Relatively low computational overhead. Recommended for general use and debugging.
  • MAGNUM: Camera pose manipulation via mouse. Renders rod and environment with 3D meshes and shading. Higher computational overhead. Recommended only for creating videos.

• integrator - Determines the numerical integration scheme. Currently, available options are

  • FORWARD_EULER: https://en.wikipedia.org/wiki/Euler_method
  • VERLET_POSITION: https://en.wikipedia.org/wiki/Verlet_integration
  • BACKWARD_EULER: https://en.wikipedia.org/wiki/Backward_Euler_method
  • IMPLICIT_MIDPOINT: https://en.wikipedia.org/wiki/Midpoint_method

• LineSearchType - Determines the line search method. Currently, available options are

  • NO_LS: Do not use line search.
  • GOLDSTEIN: https://en.wikipedia.org/wiki/Backtracking_line_search
  • WOLFE: https://en.wikipedia.org/wiki/Wolfe_conditions

• dtol - A dynamics tolerance. Considers Newton's method to converge if the infinity norm of the DOF update at iter $n$ divided by time step size for Cartesian positions is less than dtol:

  $$\dfrac{|| \Delta \mathbf q^{(n)} ||_{\infty}} {\Delta t} < \textrm{dtol}$$

  Note that we ignore $\theta$ DOFs due to difference in scaling.

• ftol - A force tolerance. Considers Newton's method to converge if the cumulative force norm at iteration $n$ becomes less than the starting force norm times ftol:

  $${||\mathbf{f^{(n)}}||} < {||\mathbf f^{(0)}||} \cdot \textrm{ftol}$$

• adaptive_time_stepping - Turns on adaptive time stepping which halves the time step size if failure to converge after set number of iterations. Set to 0 to disable.

If our work has helped your research, please cite the following paper.

@article{choi2023dismech,
    author={Choi, Andrew and Jing, Ran and Sabelhaus, Andrew P. and Jawed, Mohammad Khalid},
    journal={IEEE Robotics and Automation Letters},
    title={DisMech: A Discrete Differential Geometry-Based Physical Simulator for Soft Robots and Structures},
    year={2024},
    volume={9},
    number={4},
    pages={3483-3490},
    doi={10.1109/LRA.2024.3365292}
}

@article{choi2021imc,
    author = {Choi, Andrew and Tong, Dezhong and Jawed, Mohammad K. and Joo, Jungseock},
    title = "{Implicit Contact Model for Discrete Elastic Rods in Knot Tying}",
    journal = {Journal of Applied Mechanics},
    volume = {88},
    number = {5},
    year = {2021},
    month = {03},
    issn = {0021-8936},
    doi = {10.1115/1.4050238},
    url = {https://doi.org/10.1115/1.4050238},
}

@article{tong2022imc,
    author = {Dezhong Tong and Andrew Choi and Jungseock Joo and M. Khalid Jawed},
    title = {A fully implicit method for robust frictional contact handling in elastic rods},
    journal = {Extreme Mechanics Letters},
    volume = {58},
    pages = {101924},
    year = {2023},
    issn = {2352-4316},
    doi = {https://doi.org/10.1016/j.eml.2022.101924},
    url = {https://www.sciencedirect.com/science/article/pii/S2352431622002000},
}

This material is based upon work supported by the National Science Foundation. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.