Skip to content
Elastic Rod and X-Shell Simulation
Jupyter Notebook C++ Python Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
3rdparty Upgrade MeshFEM Version Dec 12, 2019
examples Import Dec 9, 2019
experiments/sparsification/AsymetricWingsPointy Import Dec 9, 2019
grasshopper Import Dec 9, 2019
python Slightly more efficient expression for twisting energy gradient Dec 12, 2019
python_bindings Import Dec 9, 2019
tests Import Dec 9, 2019
tools Import Dec 9, 2019
.gitignore Import Dec 9, 2019
.gitmodules Import Dec 9, 2019
ActuationSparsifier.hh Import Dec 9, 2019
AutomaticDifferentiation.hh Import Dec 9, 2019
CMakeLists.txt Import Dec 9, 2019
ConvergenceReport.hh Import Dec 9, 2019
CrossSection.hh Import Dec 9, 2019
CrossSectionMesh.hh Import Dec 9, 2019
DeploymentPathAnalysis.hh Import Dec 9, 2019 Slightly more efficient expression for twisting energy gradient Dec 12, 2019
ElasticRod.hh Import Dec 9, 2019
ElasticRodHessVec.inl Import Dec 9, 2019
LOMinAngleConstraint.hh Import Dec 9, 2019
LinkageOptimization.hh Import Dec 9, 2019
LinkageTerminalEdgeSensitivity.hh Update README Dec 10, 2019
RectangularBox.hh Import Dec 9, 2019 Import Dec 9, 2019
RodLinkage.hh Import Dec 9, 2019
RodMaterial.hh Import Dec 9, 2019
SparseMatrixOps.hh Import Dec 9, 2019 Import Dec 9, 2019
TargetSurfaceFitter.hh Import Dec 9, 2019
TemplatedTypes.hh Import Dec 9, 2019
TriDiagonalSystem.hh Import Dec 9, 2019
cg_solver.hh Import Dec 9, 2019
compute_equilibrium.hh Import Dec 9, 2019
eigensolver.hh Import Dec 9, 2019 Import Dec 9, 2019
knitro_solver.hh Import Dec 9, 2019 Import Dec 9, 2019
linkage_deformation_analysis.hh Import Dec 9, 2019 Import Dec 9, 2019
newton_optimizer.hh Import Dec 9, 2019
open_linkage.hh Import Dec 9, 2019
restlen_solve.hh Import Dec 9, 2019


A simulation framework for discrete elastic rods and X-Shells written in C++ with Python bindings. This is the codebase for our 2019 Siggraph paper, X-Shells. Check out the section on reproducing the paper figures for pointers to some Jupyter notebooks to try.

Getting Started

C++ Code Dependencies

The C++ code relies on Boost and CHOLMOD/UMFPACK, which must be installed separately. Some parts of the code (actuator sparsification, design optimization) also depend on the commercial optimization package Knitro; these will be omitted from the build if Knitro is not found.

The code also relies on several dependencies that are included as submodules: MeshFEM, libigl, spectra, and visvalingam_simplify.


You can install all the mandatory dependencies on macOS with MacPorts:

# Build/version control tools, C++ code dependencies
sudo port install cmake boost suitesparse ninja
# Dependencies for jupyterlab/notebooks
sudo port install py37-pip
sudo port select --set python python37
sudo port select --set pip3 pip37
sudo port install npm6

Ubuntu 19.04

A few more packages need to be installed on a fresh Ubuntu 19.04 install:

# Build/version control tools
sudo apt install git cmake ninja-build
# Dependencies for C++ code
sudo apt install libboost-filesystem-dev libboost-system-dev libboost-program-options-dev libsuitesparse-dev
# LibIGL/GLFW dependencies
sudo apt install libgl1-mesa-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev
# Dependencies (pybind11, jupyterlab/notebooks)
sudo apt install python3-pip npm
# Ubuntu 19.04 packages an older version of npm that is incompatible with its nodejs version...
sudo npm install npm@latest -g

Obtaining and Building

Clone this repository recursively so that its submodules are also downloaded:

git clone --recursive

Build the C++ code and its Python bindings using cmake and your favorite build system. For example, with ninja:

cd elastic_rods
mkdir build && cd build
cmake .. -GNinja

Running the Jupyter Notebooks

The preferred way to interact with the rods code is in a Jupyter notebook, using the Python bindings.

JuptyerLab and Extensions

To run the Jupyter notebooks, you will need to install JupyterLab and my fork of the pythreejs library. JupyterLab can be installed through pip, and the following commands should set up all the requirements on both macOS and Ubuntu:

pip3 install --user jupyterlab
# If necessary, follow the instructions in the warnings to add the Python user
# bin directory (containing the 'jupyter' binary) to your PATH...
jupyter labextension install @jupyter-widgets/jupyterlab-manager

git clone
cd pythreejs
pip3 install -e . --user
jupyter labextension link ./js

pip3 install matplotlib scipy --user

Launch Jupyter lab from the root python directory:

cd python
jupyter lab

Now try opening and running an example notebook, e.g., python/Demos/MantaRayDemo.ipynb. Several other demo notebooks are included in the same directory to introduce you to some of the features of the codebase.

Reproducing the Paper Figures

Each figure in the paper that includes an X-Shell simulation has corresponding Jupyter notebook(s) in python/XShellSiggraphPaperFigures. Note that these notebooks generate the raw data used to produce the figures, but the final renderings for most figures were produced in Rhino using scripts that are not included in this release. Basic preview renderings are available in the in-notebook viewer.

You can’t perform that action at this time.