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.

mattialab/elastica