DisMech: A Discrete Differential Geometry-based Physical Simulator for Soft Robots and Structures

Logo	Spider robot dropped onto an incline
Active entanglement gripper	Helix oscillating under gravity
	Real2Sim soft manipulator modelling
RL-trained policy for dynamic end-effector target following.	RL-trained policy for target reaching through 3D obstacles

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.

---

Dependencies

DisMech has been tested on Ubuntu 20.04-24.04 with Python3.8+. For other operating systems you should be able to modify the commands below, but support is not guaranteed.

Users wishing to run the code can either use the available docker build (Thanks to PR #15!), with more instructions in docker/README.md. If wanting to compile via source, please install the follow dependencies.

• Eigen 3.4.0

  • Eigen is used for various linear algebra operations.
  • 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.
  • Before installing SymEngine, LLVM is required which can be installed most easily via a package manager via sudo apt-get install llvm
  • 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

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

    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 viasudo apt-get install libglu1-mesa-dev freeglut3-dev mesa-common-dev

• Pybind11

  • DisMech offers Python bindings via pybind11. Users can either install by source or via pip install pybind11. All available bindings can be seen in app.cpp. Users can expect heavy development for expanding the python bindings as time goes on.

Afterward, DisMech can be built as follows

mkdir build && cd build
cmake ..
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

Optional Dependencies

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.

---

Running Examples in Python

Several examples can be found in py_examples/. To run, simply run the provided scripts: Note that the Pardiso solver can be parallelized by setting the env variable OMP_NUM_THREADS > 1. For all the systems defined in /py_examples, the 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 and see if parallelization is worth it for larger systems through profiling.

export OMP_NUM_THREADS=1
python py_examples/spider_case/spider_example.py

For those interested in using DisMech with reinforcement learning, a repo containing several examples for training and evaluating soft robot policies can be found at https://github.com/QuantuMope/dismech-rl.

---

Creating Custom Simulation Environments

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.

---

TODO

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 install

Ongoing

• Expand Python bindings. PR #13

High priority

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

Low priority

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

COMPLETED

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

---

Citation

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

@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},
}

---

Acknowledgements

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.