Sibernetic is physical simulator of biomechanical matter (membranes, elastic matter, contractile matter) and environments (liquids, solids and elastic matter with variable physical properties) developed for simulations of C. elegans physical body dynamics within the OpenWorm project by Andrey Palyanov, Sergey Khayrulin and Mike Vella (development of a Python module for external muscle activating signals generation and input) as part of the OpenWorm team. At its core, Sibernetic is built as an extension to Predictive-Corrective Incompressible Smoothed Particle Hydrodynamics (PCISPH). It is primarily written in C++ and OpenCL, which makes possible to run simulations on CPUs or GPUs, and has 3D visualization support built on top of OpenGL.
There is a separate effort lead by Giovanni Idili and Sergey Khayrulin to port this code to Java, as part of the Geppetto simulation framework.
Linux
Install OpenCL on Ubuntu. We suggest you initially go with AMD OpenCL drivers as we have found these to be the most stable and complete. You can also try Intel's drivers. This step often causes problems, contact the openworm-discuss mailing list if you encounter issues. The AMD drivers include samples in /opt/AMDAPP/samples/opencl/bin
which you can use to verify your OpenCL support is working.
You'll also need a variety of libraries. In ubuntu, install the dependencies with:
sudo apt-get install g++ python-dev freeglut3-dev nvidia-opencl-dev libglu1-mesa-dev libglew-dev python-numpy
Next, from the sibernetic/
directory run:
make clean
make all
Also you may need to set some enviromat variables like path to OpenCL lib or header for to do this
you can fix your LD_LIBRARY_PATH
as this:
export LD_LIBRARY_PATH=/path/to/opencl_lib/folder/:$LD_LIBRARY_PATH
e.g.
export LD_LIBRARY_PATH=/usr/local/cuda/lib64/:$LD_LIBRARY_PATH
You can find OpenCL lib in CUDA folder if you're using NVIDIA (/usr/local/cuda/lib64/
) or run this command.
ldconfig -p | grep opencl
Also you may need to give compiler path to OpenCL header files usually you can find them in /usr/include/CL
if they there than you don't need do anything. In othe case you can edit makefile directly and add directory to OpenCL headers by adding options -I/path/to/opencl_includes/
or you can copy folder with header into /usr/include/
but you should have root permission for doing that.
Mac: stay in the top-level folder. You need before run export several environment variables:
export PYTHONHEADERDIR=/usr/local/Cellar/python/<version_of_installed_pythonFramework>/Python.framework/Headers/
export PYTHONLIBDIR=/usr/local/lib/python2...
export PYTHONFRAMEWORKDIR=/usr/local/Frameworks/
Then
make clean -f makefile.OSX
make all -f makefile.OSX
You should see an output which looks something like this:
Building file: ../src/PyramidalSimulation.cpp
Invoking: GCC C++ Compiler
....
more stuff...
....
Building target: Sibernetic
Invoking: GCC C++ Linker
g++ -L/usr/lib -L/usr/lib/python2.7 -o "Sibernetic" ./src/PyramidalSimulation.o ./src/main.o ./src/owHelper.o ./src/owOpenCLSolver.o ./src/owPhysicsFluidSimulator.o ./src/owWorldSimulation.o -lOpenCL -lpython2.7 -lrt -lglut -lGL -lGLU
Finished building target:Sibernetic
Then navigate to the top-level folder in the hierarchy (e.g Sibernetic
) and set your PYTHONPATH
:
export PYTHONPATH=$PYTHONPATH:.
Finally, to run, run the command:
Linux:
./Release/Sibernetic
Mac:
./Release/Sibernetic
You may need to make ./Release/Sibernetic
executable like so:
chmod +x ./Release/Sibernetic
If you do not run from the top-level folder you will see an error which looks something like this:
Compilation failed:
"/tmp/OCLQ1BaOw.cl", line 8: catastrophic error: cannot open source file
"src//owOpenCLConstant.h"
#include "src//owOpenCLConstant.h"
Physical Algorithms:
There are two demo scenes generated for Sibernetic. The first one contains an elastic cube covered with liquid-impermeable membranes and liquid inside. The second one contains two elastic membranes attached to a boundary (one of them has liquid-impermeable membranes covering them and the other one doesn't).
To switch between demos you need to press the 1 or 2 keys respectively. To pause simulation you may press space bar.
References
To start Sibernetic with argument print in command prompt next `./Release/Sibernetic -whatever Available options:
-no_g Run without graphics
-l_to Save simulation results to disk.
-export_vtk Save simulation results to VTK files.
logstep=<value> Log every <value> steps
-l_from Load simulation results from disk.
lpath=<value> Indicates path to the directory (not the file) where result of simulation will be stored.
This option work only for -l_to and -l_from options
-test Run some physical tests.
-f <filename> Load configuration from file <filename>.
device=<device_type> Trying to init OpenCL on device <type> it could be cpu or gpu
default-ALL (it will try to init most powerful available device).
timestep=<value> Start simulation with time step = <value> in seconds.
timelimit=<value> Run simulation until <value> will be reached in seconds.
leapfrog Use for integration LeapFrog method
oclsourcepath=<value> You can indicate path to you'r OpenCL program just using this option
-nrn <value> Indicates that you plan run simulation with NEURON simulation = <value> value should be a file which
can be run by NEURON simulator and also you should have installed neuron and sibernetic_neuron bridge.
-help Print this information on screen.
Leapfrog is second order method insted of Semi-implicid Euler which we are using as default method for integration. For run simulation with Leapfro integration medhod print run command
./Release/Sibernetic leapfrog
All configuration is stored in the configuration folder. There are two demo configurations demo1 and demo2 (demo1 is the default configuration). You can switch between two demo configurations directly inside the working Sibernetic - just push button '1' or '2' respectively. To run your configuration put your configuration file into the configuration folder and run Sibernetic using:
./Release/Sibernetic -f <configuration_file_name>.
To run the worm body simulation you need run Sibernetic with key:
./Release/Sibernetic -f worm
It loads the worm body configuration and initialises and runs the Python module which is responsible for muscle signal updating. For run simulation with crawling worm on carpet like surface or swimming in deep water you need run sibenretic with next command arguments:
./Release/Sibernetic -f worm_crawling oclsourcepath=src/sphFluid_crawling.cl
./Release/Sibernetic -f worm_deep_water oclsourcepath=src/sphFluid_crawling.cl
If you run Sibernetic with graphics you can work with scene rotation and scaling using the mouse. There are also several control button options available:
'Space' - pause the simulation
's' - save current configuration into file
./configuration/snapshot/configuration_name_current_time_and_date you can run this
than (./Release/Sibernetic -f ./configuration/snapshot/configuration_default).
'q' or 'Esc' - quit the sibernetic
'1' - run demo1 configuration
'2' - run demo2 configuration
'r' - reset current configuration and start from begining
The configuration file consists of: First block is an optional if you didn't indicate this block then sibernetic will init consts by default value which you can find in owPhysicsConstant.h .
[physical parameters]
mass: 5.4e-14
timeStep: 5.0e-06
simulationScale: 2.46e-06
viscosity: 5.0e-05
surfTensCoeff: 1.21948e+27
elasticityCoefficient: 5.55556e+08
Next 6 lines is a spatial description of boundary box
[simulation box]
xmin
xmax
ymin
ymax
zmin
zmax
[position] - contains information about position of all particles e.g.
1 0 0 1
1 0 1 1
...
[velocity] - contains information about velocities of all particles e.g.
0 0 0 1
0 0 0 1
...
[connection] - contains information about elastic connection of all elastic particles e.g.
1 1.58649939377 1.1 0.0
7 1.58649939377 1.1 0.0
...
[membranes] - contains information about membranes e.g.
0 1 7
7 8 1
...
[particleMemIndex] - contains information about in which membranes elastic particle is includes e.g.
0
144
288
-1
...
Position and velocity are represented as 4D vectors which contains information about x, y, z of particle in space and information about particle's type (it could be liquid - 1, elastic - 2 or boundary - 3). Each elastic particle has 32 places allocated in connections buffer. Each connection is represented like a 4D vector
ID of particle to connected to
stedy-state lenght of connection
id of muscle if this connection is a muscle fiber
and unused data - need for vectorization.
Connections buffer stored in memory like 1D vector: length of each is equal to NUM_OF_ELASTIC_PARTICLES * 32 * 4
. So for each particular elastic particle you can find information for elastic its connections simply get sub-buffer of connection from INTRESTING_PARTICLE_ID * 32 * 4
to INTRESTING_PARTICLE_ID * 32 * 4 + 32 * 4
.
Each membrane is defined by 3 elastic particles and contains 3 IDs of this particles. particleMemIndex - contains IDs of membrane in which each elastic particle is included we suppose that max numbers of membrane for one particle is 7 so particleMemIndex contains 7 * NUM_OF_ELASTIC_PARTICLES
and you can get interesting information from this buffer just get sub-buffer from indexes INTRESTING_PARTICLE_ID * 7
to INTRESTING_PARTICLE_ID * 7 + 7
.
You can run Sibernetic on GPU. For this you should start Sibernetic with key:
./Release/Sibernetic device=gpu
You may wish to save simulations to disk rather than visualise them (WARNING: This is buggy)
To record configurations to file you need to run simulation with key -l_to:
./Release/Sibernetic -l_to
This create 3 new files in the folder ./buffers
:
For view result you should run simulation with:
./Release/Sibernetic -l_from
It get positions from position_buffer.txt file and displays the evolution of system in time
Results of the simulation can be saved to the VTK files, allowing visualisation e.g. in Paraview.
To save the VTK files, run the program with the parameter -export_vtk
,
./Release/Sibernetic -export_vtk
For each saved timestep number N a file state_N.vtp
is created in the directory ./buffers
. Storing interval is given by the parameter logstep
.
Now it's possible to run the physical and neuronal simulations together. For this you need
sibernetic_NEURON also. Don't forget to
add the path of sibernetic_NEURON into your PYTHONPATH
. You just need to run Sibernetic with
command argument '-nrn
If you have Sibernetic and NEURON (with Python support) correctly installed, the following should be sufficient to get this running:
git clone https://github.com/openworm/sibernetic_NEURON.git
export PYTHONPATH=./sibernetic_NEURON:./src
./Release/Sibernetic -nrn ./sibernetic_NEURON/models/celegans/_ria.hoc -f worm
You can run Sibernetic with c302 providing the input which will drive the contraction of the muscle cells.
If you have Sibernetic, NEURON (with Python support) and pyNeuroML correctly installed, the following should be sufficient to get this running:
git clone https://github.com/openworm/CElegansNeuroML.git
export C302_HOME=./CElegansNeuroML/CElegans/pythonScripts/c302
export PYTHONPATH=$PYTHONPATH:$C302_HOME:./src
python sibernetic_c302.py
This will generate the NEURON code for the c302 simulation (using pyNeuroML), run Sibernetic with the neuronal simulation of c302 running in Python Neuron in the background, and save the results to files in the simulations directory (no Sibernetic gui will be shown). The simulation can be rerun with:
./Release/Sibernetic -l_from lpath=simulations/SimulationName_SimulationDate
For more information on options type:
python sibernetic_c302.py -?
If you run a simulation you may be interested in recording the graphical output. You can either save the results to VTK files and use Paraview to create the video, or create the video using the default OpenGL visualisation. Making such videos is a bit tricky because they need to be speeded up, so far I have found the following two commands do a decent job (change folder names accordingly) after you have used a screen record program:
If your video is in OGV format (if you used recordmydesktop for instance), use the following script to convert to avi:
#!/bin/bash
# ogv to avi
# Call this with multiple arguments
# for example : ls *.{ogv,OGV} | xargs ogv2avi
N=$#;
echo "Converting $N files !"
for ((i=0; i<=(N-1); i++))
do
echo "converting" $1
filename=${1%.*}
mencoder "$1" -ovc xvid -oac mp3lame -xvidencopts pass=1 -o $filename.avi
shift 1
done
#make images from video
ffmpeg -i crawley_6.avi -r 0.05 -f image2 ~/Documents/tmp/output-%06d.jpg
#re-encode into video
ffmpeg -r 100 -i output-%06d.jpg -r 100 -vb 60M speeded_worm.mp4
If you have any question or have a problem with running Sibernetic please contact with us. Email me on skhayrulin@openworm.org or info@openworm.org. Or you can create an issue on GitHub.