search

StructuresComp / dismech-rods

DisMech: A discrete differential geometry-based physical simulator for soft robots and structures
GNU General Public License v3.0
24 stars 6 forks source link
deformable-solids robotics simulation-framework simulations soft-robotics

readme

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

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.

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.

Ongoing

High priority

Low priority

COMPLETED

Dependencies

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.

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.

Running Examples in C++

DisMech is setup so that simulation environments can be instantiated using a single cpp file called robotDescription.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/cantileverExample.cpp robotDescription.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 robotDescription.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/spiderExample

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.

Running Examples in Python

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/spiderExample.py

Creating Custom Simulation Environments

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 robotDescription.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 globalDefinitions.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)
  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:

Citation

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

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.