Commit 5fce1e8d authored by nedelec's avatar nedelec

New documentation

parents
This diff is collapsed.
# Cytosim
Cytosim is a cytoskeleton simulation designed to handle large systems of flexible filaments with associated proteins such as molecular motors. It is a versatile base that has been used to study actin and microtubule systems in 1D, 2D and 3D. It is built around a core cross-platform C++ engine. It runs on UNIX, Mac OSX, GNU/Linux and within Cygwin on Windows. The code is modular and extensible, making Cytosim a convenient base that can be customized to meet particular tasks.
![Cytosim](doc/data/cytosim.png)
Cytosim is a suite of command-line tools with simulation and display capabilities. The simulation is specified in a [configuration file](doc/sim/config.md), defining objects, their parameters and a suite of operations, such as advancing time, saving frames or [generating reports](doc/sim/report.md). Here is a basic example:
set simul system
{
time_step = 0.005
viscosity = 0.02
}
set space cell
{
shape = sphere
}
set fiber microtubule
{
rigidity = 20
segmentation = 0.5
confine = inside, 200, cell
}
new cell
{
radius = 5
}
new 5 microtubule
{
length = 11
}
run 5000 system
{
nb_frames = 10
}
The parameters are specified in [units of second, micrometers and pico-Newtons](doc/sim/units.md).
# Documentation
The documentation is formatted with [Markdown](https://en.wikipedia.org/wiki/Markdown).
You can view the files with [MacDown (Mac OSX only)](https://macdown.uranusjr.com) or [Typora (Cross platform)](https://typora.io)
[Link to cytosim documentation](doc/index.md)
The Brownian dynamics approach was described in: [Collective Langevin Dynamics of Flexible Cytoskeletal Fibers (New Journal of Physics)](http://iopscience.iop.org/article/10.1088/1367-2630/9/11/427/meta).
# Installation
Cytosim is distributed as source code and [must be compiled](doc/compile/index.md) before use. On Mac OS X and Linux this should be uncomplicated if you are familiar with compilation in general. On Windows, this is more challenging, and we suggest to [compile within Cygwin](doc/compile/cygwin.md).
To compile, enter these commands in a terminal window:
git clone https://gitlab.com/f.nedelec/cytosim
cd cytosim
make
For more information, please check [the compile instructions](doc/compile/index.md).
Once cytosim is running on your machine, check the tutorials, the page on [running simulations](doc/main/runs.md), and the examples contained in the folder `cym`. Inspect in particular the short configuration files (e.g. fiber.cym, self.cym).
# Contributors
The project was started in 1995, and received its name in 1999.
We hope cytosim can be useful for your research.
Sincerely yours, The Developers of Cytosim:
* Francois Nedelec 1995-
* Dietrich Foethke 2003-2007
* Cleopatra Kozlowski 2003-2007
* Elizabeth Loughlin 2006-2010
* Ludovic Brun 2008-2010
* Beat Rupp 2008-2011
* Jonathan Ward 2008-2014
* Antonio Politi 2010-2012
* Andre-Claude Clapson 2011-2013
* Serge Dmitrieff 2013-
* Gaelle Letort 2014-
* Julio Belmonte 2014-
* Jamie-Li Rickman 2014-
# Contact
Email: [email protected]
NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
This diff is collapsed.
# Cytosim Code Documentation
Cytosim is built around [a core C++ engine](../../src/index.md) under [`src/`](../../src).
Associated [Python scripts](../../python/index.md) are found under [`python/`](../../python).
The [detailed documentation for the C++ code](doxygen/index.html) needs to be generated.
### Generating the documentation
The code documentation is generated by [`doxygen`](http://www.doxygen.nl).
After installing `doxygen` on your machine, in the project root directory, enter:
make doc
The output is dumped into [`doc/code/doxygen/`](doxygen).
### Contact
feedbackATcytosimDOTorg
<doxygenlayout version="1.0">
<!-- Navigation index tabs for HTML output -->
<navindex>
<tab type="mainpage" visible="yes" title=""/>
<tab type="pages" visible="yes" title="" intro=""/>
<tab type="modules" visible="yes" title="" intro=""/>
<tab type="namespaces" visible="yes" title="">
<tab type="namespaces" visible="yes" title="" intro=""/>
<tab type="namespacemembers" visible="yes" title="" intro=""/>
</tab>
<tab type="classes" visible="yes" title="">
<tab type="classes" visible="yes" title="" intro=""/>
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
<tab type="hierarchy" visible="yes" title="" intro=""/>
<tab type="classmembers" visible="yes" title="" intro=""/>
</tab>
<tab type="files" visible="yes" title="">
<tab type="files" visible="yes" title="" intro=""/>
<tab type="globals" visible="yes" title="" intro=""/>
</tab>
<tab type="dirs" visible="yes" title="" intro=""/>
<tab type="examples" visible="yes" title="" intro=""/>
</navindex>
<!-- Layout definition for a class page -->
<class>
<detaileddescription title=""/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<inheritancegraph visible="$CLASS_GRAPH"/>
<collaborationgraph visible="$COLLABORATION_GRAPH"/>
<allmemberslink visible="yes"/>
<memberdecl>
<nestedclasses visible="yes" title=""/>
<publictypes title=""/>
<publicslots title=""/>
<signals title=""/>
<publicmethods title=""/>
<publicstaticmethods title=""/>
<publicattributes title=""/>
<publicstaticattributes title=""/>
<protectedtypes title=""/>
<protectedslots title=""/>
<protectedmethods title=""/>
<protectedstaticmethods title=""/>
<protectedattributes title=""/>
<protectedstaticattributes title=""/>
<packagetypes title=""/>
<packagemethods title=""/>
<packagestaticmethods title=""/>
<packageattributes title=""/>
<packagestaticattributes title=""/>
<properties title=""/>
<events title=""/>
<privatetypes title=""/>
<privateslots title=""/>
<privatemethods title=""/>
<privatestaticmethods title=""/>
<privateattributes title=""/>
<privatestaticattributes title=""/>
<friends title=""/>
<related title="" subtitle=""/>
<membergroups visible="yes"/>
</memberdecl>
<memberdef>
<typedefs title=""/>
<enums title=""/>
<constructors title=""/>
<functions title=""/>
<related title=""/>
<variables title=""/>
<properties title=""/>
<events title=""/>
</memberdef>
<usedfiles visible="$SHOW_USED_FILES"/>
<authorsection visible="yes"/>
</class>
<!-- Layout definition for a namespace page -->
<namespace>
<briefdescription visible="yes"/>
<memberdecl>
<nestednamespaces visible="yes" title=""/>
<classes visible="yes" title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
</memberdef>
<authorsection visible="yes"/>
</namespace>
<!-- Layout definition for a file page -->
<file>
<briefdescription visible="yes"/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<includegraph visible="$INCLUDE_GRAPH"/>
<includedbygraph visible="$INCLUDED_BY_GRAPH"/>
<sourcelink visible="yes"/>
<memberdecl>
<classes visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
</memberdef>
<authorsection/>
</file>
<!-- Layout definition for a group page -->
<group>
<briefdescription visible="yes"/>
<groupgraph visible="$GROUP_GRAPHS"/>
<memberdecl>
<classes visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<dirs visible="yes" title=""/>
<nestedgroups visible="yes" title=""/>
<files visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
<membergroups visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
<memberdef>
<pagedocs/>
<defines title=""/>
<typedefs title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
</memberdef>
<authorsection visible="yes"/>
</group>
<!-- Layout definition for a directory page -->
<directory>
<briefdescription visible="yes"/>
<directorygraph visible="yes"/>
<memberdecl>
<dirs visible="yes"/>
<files visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
</directory>
</doxygenlayout>
@mainpage
# Cytosim
[Cytosim](http://www.cytosim.org) is a simulation of the cytoskeleton.
The project was started in 1995 at Princeton and continued at [ESPCI](http://www.espci.fr) until 1998. The name was coined in 1999 at [EMBL](http://www.embl.org).
Development is conducted by the Nedelec group at Cambridge University.
@date 2009-2018
@version PI - Increased Modularity
@authors
Francois Nedelec 1995-\n
Dietrich Foethke 2003-2007\n
Cleopatra Kozlowski 2003-2007\n
Elizabeth Loughlin 2006-2010\n
Ludovic Brun 2008-2010\n
Beat Rupp 2008-2011\n
Jonathan Ward 2008-2014\n
Antonio Politi 2010-2012\n
Andre-Claude Clapson 2011-2013\n
Serge Dmitrieff 2013-\n
Julio Belmonte 2014-\n
@par Contact:
Email: [email protected]\n
# Simulation Objects
### Simul
The command `set simul` will define the global parameters.
There can only be one `simul` object, and it is automatically created,
so you do not need to call 'new simul'.
Simul - SimulProp - @ref SimulPar
### Surfaces & Volumes
These objects are immobile:
Class | Parameters | Property | Options
--------------|------------------|--------------|-------------------------
Space | @ref SpacePar | SpaceProp | @ref SpaceGroup
Field | @ref FieldPar | FieldProp | @ref FieldSet::newObjects
Event | @ref EventPar | EventProp | (unfinished)
### Mecables
`Mecables` can move or deform. There are 4 basic classes:
Class | Parameters | Property | Options
--------------|------------------|--------------|---------------------------
Fiber | @ref FiberPar | FiberProp | @ref FiberGroup
Bead | @ref SolidPar | SolidProp | @ref BeadSet::newObjects
Solid | @ref SolidPar | SolidProp | @ref SolidSet::newObjects
Sphere | @ref SpherePar | SphereProp | @ref SphereSet::newObjects
### Fibers
@ref FiberGroup
`activity` | Class | Parameters | Property
--------------|---------------------|---------------------------|----------------------
`none` | Fiber | @ref FiberPar | FiberProp
`grow` | GrowingFiber | @ref GrowingFiberPar | GrowingFiberProp
`dynamic` | DynamicFiber | @ref DynamicFiberPar | DynamicFiberProp
`classic` | ClassicFiber | @ref ClassicFiberPar | ClassicFiberProp
`treadmill` | TreadmillingFiber | @ref TreadmillingFiberPar | TreadmillingFiberProp
`tubule` | Tubule (deprecated) | @ref TubulePar | TubuleProp
#### Hands
A `Hand` is an object that can bind to fiber, but it can only be used
as a subpart of `Single` or `Couple`.
@ref HandGroup
`activity` | Class | Parameters | Property |
--------------|---------------|--------------------|---------------
`bind` | Hand | @ref HandPar | HandProp
`move` | Motor | @ref MotorPar | MotorProp
`nucleate` | Nucleator | @ref NucleatorPar | NucleatorProp
`slide` | Slider | @ref SliderPar | SliderProp
`track` | Tracker | @ref TrackerPar | TrackerProp
`rescue` | Rescuer | @ref RescuerPar | RescuerProp
`regulate`* | Regulator | @ref RegulatorPar | RegulatorProp
`cut` | Cutter | @ref CutterPar | CutterProp
`chew` | Chewer | @ref ChewerPar | ChewerProp
`mighty` | Mighty | @ref MightyPar | MightyProp
`act` | Actor | @ref ActorPar | ActorProp
### Digital Hands
`activity` | Class | Parameters | Property |
--------------|---------------|--------------------|---------------
`digit` | Digit | @ref DigitPar | DigitProp
`walk` | Walker | @ref WalkerPar | WalkerProp
`kinesin`* | Kinesin | @ref KinesinPar | KinesinProp
`dynein`* | Dynein | @ref DyneinPar | DyneinProp
`myosin`* | Myosin | @ref MyosinPar | MyosinProp
`*` Unfinished classes.
### Singles
A `Single` contains one `Hand`, and can have different `activity`:
@ref SingleGroup
`activity` | Classes | Parameters | Property |
---------------|-------------------|-----------------|-------------
`diffuse` | Single | @ref SinglePar | SingleProp
`fixed` | Picket PicketLong | @ref SinglePar | SingleProp
not applicable | Wrist WristLong | @ref SinglePar | SingleProp
### Couples
A `Couple` contains two `Hand`, and can have different `activity`:
@ref CoupleGroup
`activity` | Classes | Parameters | Property |
--------------|-------------------------|----------------------|---------------
`diffuse` | Couple CoupleLong | @ref CouplePar | CoupleProp
`crosslink` | Crosslink CrosslinkLong | @ref CrosslinkPar | CrosslinkProp
`bridge` | Bridge | @ref BridgePar | BridgeProp
`duo` | Duo DuoLong | @ref DuoPar | DuoProp
`slide` | Shackle ShackleLong | @ref ShacklePar | ShackleProp
`fork` | Fork | @ref ForkPar | ForkProp
### Organizers
The `Organizers` describe composite objects build from multiple Mecables:
Class | Parameters | Property |
--------------|------------------|---------------
Aster | @ref AsterPar | AsterProp
Fake | @ref FakePar | FakeProp
Bundle | @ref BundlePar | BundleProp
Nucleus | @ref NucleusPar | NucleusProp
## Instructions to run Cytosim on Cygwin
Cytosim runs on Cygwin, but this is not supported. Typically this mode is only used by third parties.
### Installation
Run the Cygwin installer with default settings until you get to the package selection screen. In order to properly compile and run Cytosim
several packages which are not default must be installed:
- gcc (GNU compiler suite including C++)
- make (GNU make)
- libBLAS (Basic Linear Algebra Subprograms)
- libLAPACK (Linear Algebra PACKage)
- X11 (X Window System)
- automake (makefile generator tool)
- cmake (makefile generator tool)
- OpenGL (Open Graphics Library)
- GLEW (OpenGL Extension Wrangler Library)
- python3 (python interpreter for cygwin)
Searching for the keywords provided and selecting items that mention
"devel" or "lib". To select items for installation click the weird icon to the left of "Skip" or "Default" until it reads "Install" instead.
After all packages are selected install Cygwin.
**Tip**: In the view drop-down menu select "Category" which will reorganize packages to show them by category. Rather than go through the Developer
tools line by line, click on the icon between "Devel" and "Default" to change it to "Install". This will install all the developer tools
for Cygwin, which is overkill and will take ~20-30 minutes, but is much easier than figuring out which tools are/aren't neccessary.
### Compilation
Modify the `makefile.inc` to set `MACHINE:=cygwin`, and disable offscreen rendering by setting `HAS_PNG:=0`. Recompile fresh using the toolchain (`gcc` and `make`) provided by cygwin. The procedure is the same as on other platforms (enter `make`). If you experience trouble, please let us know.
### The X Window System (X11)
Finally, all graphical tools included in cytosim (in particular 'play') will use the [X Window System](https://en.wikipedia.org/wiki/X_Window_System) also known as X11 to open a window, and this will work only if a X11 server is running on your local computer. Two X11 implementations can be installed with Cygwin:
[Cygwin/X](https://en.wikipedia.org/wiki/Cygwin/X)
[Xming](https://en.wikipedia.org/wiki/Xming)
We got things to work with the free 2007 version of Xming. Xming can be installed while Cygwin installation is running.
Once Xming is installed run XLaunch to start the X11 window server, and direct your application to this server by setting the `DISPLAY` environment variable.
This will instruct 'play' to send X11 queries to the default X11 server on the local machine. This command should be run once every time a new cygwin terminal is opened, otherwise 'play' will fail with a message "failed to open display".
**Tip**: To debug X11, it may be useful to run standard program such as `xclok`. This way you can test if the X11 server is operational.
### Starting
Cytosim will only work within Cygwin, and not directly under Windows. This means that it cannot be started from the Windows command line, and you can close the Windows/MS-DOS command prompt.
Cytosim should be started from the Cygwin terminal window:
cd cytosim
export DISPLAY=:0
bin/play live
Author: Daniel Cortes and Francois Nedelec, last updated 14 May 2018
\ No newline at end of file
# Dimensionality
Cytosim can perform simulations in 1D, 2D or 3D, but the dimensionality is selected at compilation time!
This means that one executable will only be able to perform simulations for one dimensionality.
### Compilation
The dimension of the simulation is selected in `src/math/dim.h`
#define DIM 2
Save the file and always recompile everything after changing `DIM`:
make clean
make
This will place the executables in `bin/`
You can check the dimensionality of the executable, with:
bin/sim info
bin/play info
Shortcuts are built into the makefile, and you can do:
make bin2/sim
make bin2/play
and similarly
make bin3/sim
make bin3/play
and also:
make bin2
make bin3