Installation instructions

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.

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. .. code-block:: bash
  
  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: .. code-block:: bash
  
  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: .. code-block:: bash
  
  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: .. code-block:: bash
  
  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 the following to your .bashrc. Change the directory accordingly if your MKL version is different.
```
export MKLROOT=/opt/intel/oneapi/mkl/2022.0.2
```
OpenGL / GLUT
- OpenGL / GLUT is used for rendering the knot through a simple graphic.
- 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)

Running Examples

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

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

./dismech.sh

If you want to run another example, simply replace the robotDescription.cpp file and recompile.

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.

Simulation parameters such as defining the soft structure(s) / robot(s), boundary conditions, forces, and logging are done solely in robotDescription.cpp so that large recompiles do not take place.

In addition, many numerical parameters can be set through the simParams struct shown below with default values and descriptions. 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 {
  double sim_time = 10;                              //    Total time for simulation [s]
  double dt = 1e-3;                                  //    Time step size [s]
  bool render = true;                                //    Live OpenGL rendering
  bool show_mat_frames = false;                      //    Render material frames
  double render_scale = 1.0;                         //    Rendering scale
  double dtol = 1e-2;                                // *^ Dynamics tolerance [m/s]
  double ftol = 1e-4;                                // *^ Force tolerance
  int max_iter = 500;                                // ^  Maximum iterations for a time step
  int adaptive_time_stepping = 0;                    // *^ Adaptive time stepping
  int cmd_line_per = 1;                              //    Command line sim info output period
  bool enable_2d_sim = false;                        //    Lock z and theta DOFs
  bool line_search = true;                           // ^  Enable line search method
  numerical_integration_scheme nis = BACKWARD_EULER; // *  Numerical integration scheme
  int debug_verbosity = 1;                           //    Prints certain debug statements
};

Detailed parameter explanations:

numerical_integration_scheme - 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
dtol - A dynamics tolerance. Considers Newton’s method to converge if the infinity norm of the DOF update divided by time step size for Cartesian positions is less than dtol: $$frac{|| Delta mathbf q ||_{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 becomes less than the starting force norm * ftol. $$|| mathbf f || < || mathbf f_0 || * 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.