Elastica
Elastica is a software to simulate the dynamics of filaments that, at every cross-section, can undergo all six possible modes of deformation, allowing the filament to bend, twist, stretch and shear, while interacting with complex environments via muscular activity, surface contact, friction and hydrodynamics.
This repository provides a prototyping, non-parallel (single threaded, single node)
code in C++
that supplements the paper “Modeling and simulation of complex dynamic musculoskeletal architectures, Nature Communications, 2019.”
The code provided here is meant to be a tutorial into assembling and simulating active architectures similar to the ones in the above paper:
- It presents a single Cosserat rod implementation according to the above paper and “Forward and inverse problems in the mechanics of soft filaments. Royal Society Open Science, 2018.”
- It illustrates the use of a single rod in the case of slithering snakes, and a comparison with the Timoshenko beam deflection to highlight the effect of shear.
- It extends the use of single Cosserat rods to simple assemblies of rods, and presents three toy problems implementing the main joint connections employed in “Modeling and simulation of complex dynamic musculoskeletal architectures, Nat Comm, 2019.”
- It illustrates the assembly and simulation of dynamic musculoskeletal structures similar to those in the Nat Comm, 2019 (although not identical due to the use of a legacy code). An HPC version of Elastica will eventually replace this repository.
The code has been tested with C++-11
-compliant gcc
compilers
from versions 4.9.4
and above on Linux
and MacOS
. This version of the code is
not optimized and non-parallel, so some examples are slow to run, we indicate
this in the scripts provided.
The code itself is distributed with a MIT License, but the authors retain copyright for the examples shown in this repository.
Quick-Use Guide
To understand the code, starting from the fundamental rod model used, boundary conditions, connections between rods, we suggest taking the route below in running and understanding cases (for a complete explanation, see the Commands section below).
Basic tests to check the integrity of the Cosserat rod’s core (individual rod)
- timoshenkobeam in
QuasiStaticTimoshenkoBeam.cpp
- localized helical buckling in
InstabilityHelical.cpp
- snake in
Snake.cpp
Basic examples of rods’ assembly (multiple rods)
- sphericaljoint in
SphericalJoint.cpp
- hingejoint in
HingeJoint.cpp
- fixedjoint in
FixedJoint.cpp
- pullingmuscle in
PullingMuscle.cpp
When you reach this point, you should be able to assemble your own complex structures. The examples below rely on the same concepts as the first six.
More complex architectures similar to the ones in the Nat Comm, 2019 paper
- flagella in
Flagella.cpp
- muscularsnake in
MuscularSnake.cpp
- walker in
Walker.cpp
- elbow in
Elbow.cpp
- wing in
Wing.cpp
For processing and plotting results from these cases, use the
plot_results.py
script found in the scripts
folder (see Visualizing
Results section
below and the README.org
in the scripts
folder for more information.
Usage
While the repo contains code to simulate individual rods by themselves, we organized it to run several examples off-the-shelf.
Prerequisites
Our prerequisites are GNU Make
and a C++-11
compliant gcc
compiler for
running the code (there are known bugs with other compilers, see the section
on Bugs below). For visualizing the date, we use Python3
(any version
should be fine) using numpy,scipy
and matplotlib
as packages (see
README.org
file in the scripts
folder for more details).
Installation
The Makefile provided can be used to compile one of many executables running a specific case, like so:
cd makefiles
make clean
make -j8 # default target is elbow
./<name_of_executable>
For ease of use however, we provide a handy bash script that makes and runs the provided examples:
cd makefiles
./run.sh <name_of_example>
The next section provides more details on using this script.
Commands
Upon running the run.sh
with no arguments, it prints the following
descriptive help message:
usage
-----
./run.sh <case_name>
case_names and explanations
---------------------------
help : Print this help message
timoshenkobeam : Runs a cantilevered slender beam (clamped at the wall at one
end, free at another) bending under the influence of a downward point force.
We compare against analytical results using Timoshenko Beam theory.
helicalbuckling : Runs the localized helical buckling benchmark which tests
the mixed bending modes (two bending modes + twist mode). When an unstretchable
rod is twisted at two ends, a characteristic instability arises which forms a
localized helical shape at the center of the beam. There is an analytical solution
(see Gazzola et. al, RSOS, 2018), which we compare against.
snake : Runs an example of an snake, actuated by a continuum analytical bend-
ing torque profile slithering on a plane-ground with anisotropic friction.
This snake has been optimized for maximal forward speed.
sphericaljoint : Runs an example of two rods connected by a spherical joint
that allows for arbitrary rotations (see SphericalJoint.cpp)
hingejoint : Runs an example of two rods connected by a hinge joint that
allows for motion only along a constrained plane (see HingeJoint.cpp)
fixedjoint : Runs an example of two rods connected by a fixed joint that
does not allow any motion between the rods (see FixedJoint.cpp)
pullingmuscle : Runs an example of two hanging vertical rods (connected to
ground by a hinge) connected to each another's centers by a horizontal
muscle. This muscle is actuated and pulls the rods together.
(see PullingMuscle.cpp)
elbow : Runs the injured elbow (50% Strength) with artificial muscles,
as seen in Fig.7 in Supplementary Material.
flagella : Runs the original biohybrid flagella design seen in Fig.2(a,b).
walker : Runs the original biohybrid walker design at a frequency of 2 Hz,
as seen in Fig.2(e,f). SLOW without parallelization.
muscularsnake : Runs the muscular snake seen in Fig.3. SLOW without parallelization.
wing : Runs the wing seen in Fig.4. EXTREMELY SLOW without parallelization.
case_names
----------
timoshenkobeam, helicalbuckling, sphericaljoint, hingejoint, fixedjoint, pullingmuscle, snake
flagella, muscularsnake, walker, elbow, wing
All results are stored in folder 'run_<case_name>' in the main directory
To run a specific example then (e.g. walker) type ./run.sh walker
.
Visualizing Results
To process the results using plot_results.py
, run
./plot_results.py -c <case_name>
where the case_name
is the same as before. This script visualizes
the data and saves the files automatically. More details in the README.org
file in the scripts
folder.
Known bugs
The code, at the moment, only works with gcc
compiler family (Apple
clang
, source clang
, icc
do not work). This will be corrected in the
near future. All examples in the paper are run with g++ 8.2.0
with -O3
optimization and user warnings.
Troubleshooting
Because of the above bugs, we hard-coded g++
in line 5 of our Makefile
.
In case make
throws an error during compile-time, the user is encouraged to
change the path of the CC
executable in the Makefile
.