cytosim for 3D actomyosin simulations
=====================================

`Cytosim <https://gitlab.com/f.nedelec/cytosim>`_ is a nice, well tested simulation software
for cytoskeleton mechanics.
This is only a short summary on the steps you have to perform
to get cytosim up and running for the simulations we do. Look for the documentation
on their project page for more details.

Download
--------

Download cytosim via git:

.. code::

   git clone https://gitlab.com/f.nedelec/cytosim
   cd cytosim

Compile
-------
   
Instead of following their default instructions, which would create
cytosim executables for 2D simulations, use

.. code::

   make bin3/sim
   make bin3/play
   make bin3/report

This will put the executables into the folder ``bin3``.

Install
-------

Now that the program is built, you need to install it. It's not strictly necessary, but I
find it much more convenient. Installing a program for command line is equivalent to adding
the executable file to your so called ``PATH``. The ``PATH`` is a list of directories,
in which your command line is searching for executable files.

One option you have, is to permanently add the folder ``bin3`` to your ``PATH``. For that, find out
what the absolute path to the folder ``bin3`` is. You could for example use the command ``pwd``, which
gives you the absolute path to the folder where you currently are in your command line session. Mine
e.g. would yield ``/home/ilyas/Software/cytosim``. So the absolute path to the ``bin3`` folder which
contains the executables is

.. code::

   /home/ilyas/Software/cytosim/bin3

in my case. To add that permanently to your ``PATH``, you need to add one line to the file
``~/.bashrc``. The ``~`` is a short cut to your home folder, in my case that would be ``/home/ilyas``.
The file ``.bashrc`` starts with a dot, which means that it is ignored by many programs, and
is considered a hidden file for most file browsers. So don't worry if you don't see it,
it should be there on most Linux machines. You have to add the line

.. code::

   export PATH=$PATH:/home/ilyas/Software/cytosim/bin3

This sets the new list ``PATH`` to contain the old list plus the ``bin3`` folder.
Replace the path where it is located on my machine (``/home/ilyas/...``) with whereever it
is on yours.

Learn cytosim
-------------

I found that most tutorials also work in 3D, even though they were designed to run in 2D.
After the
`introductory tutorial <https://gitlab.com/f.nedelec/cytosim/-/blob/master/doc/tutorials/tuto_introduction.md>`_
you should continue with the tutorials on actin, e.g.
`this one <https://gitlab.com/f.nedelec/cytosim/-/blob/master/doc/tutorials/tuto_contract_motor.md>`_.

3D Simulation Box with Periodic Boundaries
------------------------------------------

In our lab, we often use a box instead of spheres/cells or similar shapes from the tutorials.
For example:

.. code::
   
   set space box {
       shape = periodic
   }

   new box {
       length = 30, 30, 30
   }

If you also use a periodic box, make sure you set all ``length``\ s of ``couple``\ s to 0.
Otherwise cytosim will produce an error, if a ``couple`` crosses a periodic boundary.