User Guide

Running the GUI

You can launch the GUI by running a scripts via the command:

$ python CellModeller/Scripts/CellModellerGUI.py

This should open a window like this: There are 5 buttons here:
Load Model - this will load a file dialog where you can select models to run.
Load Pickle - Pickles are how a simulation saves data (more details below). This will load a simulation from a saved state.
Reset Simulation - This will reset the simulation to the starting point. Note that if the model file was changed, these changes will be picked up by CellModeller, making it easier to tweak models on the fly.
Run - Click this to get the simulation started.
Save Pickle - This toggles whether the simulation is saving data or not.

You can now load and run models from the GUI, for a guide please see tutorials (also in ~/cellmodeller/Examples).

You can also run a specific model from the command line like this:

$ python CellModeller/Scripts/CellModellerGUI.py Examples/Tutorial_1/Tutorial_1a.py

Once in a model, pressing Shift and clicking on a cell will select it and display its properties.

OpenCL settings

When you load a model, CellModeller will ask you which OpenCL platform and device you want to use. Most users will have one platform (e.g. "Apple"), but you might have multiple devices (e.g. CPU and GPU). More details can be found in OpenCL configuration.

Running simulations in batch mode

The batch script (cellmodeller/Scripts/batch.py) is a simple example of creating and stepping a simulation in python, e.g.:

$ python CellModeller/Scripts/batch.py CellModeller/Examples/ex1_simpleGrowth.py

Although your model file might create display renderers, when run without the GUI these are not called - so you won't see any graphical output, and the computational cost of rendering is removed. There are variants on this script for running sequences of simulations, e.g. scanning parameters. Have a look in ~/cellmodeller/Scripts.

Saving and loading data

Saving data

By default CellModeller will save simulation data in ~/cellmodeller/data. Each time you run a simulation (either in the GUI or directly via python) a new directory is created with the model name and data/time of the run. The directory will also contain a file with the model in it, for reference. Periodically the state of the simulation is saved here in a pickle file. The pickle will save the all of the details of the cells and signals, as well as the simulation parameters.

In the model specification you can choose how often (if at all) to save data, e.g.

def setup(sim):
    # Set up your model here
    # ...

    # Specify how often to save data
    sim.pickleSteps = 10

specifies to save every 10th simulation step. Beware that data can take up a lot of disk space - we are looking into more efficient ways to store this.

Loading data

User interface

In the GUI you can load any saved pickle file by clicking the "Load pickle file" button. Each pickle also contains the model that generated it, so you can now continue to simulate by pressing the "Run" button. Note that this means that you cannot change the model parameters when it is loaded from a pickle.

Python

Outside of the GUI you can also load saved pickle files and analyse or visualise the state of the simulation. Scripts/Draw2DPDF.py loads a pickle in this way and uses the data to generate a PDF figure. We hope to create a utility module to contain many of these common script functions, and many more useful scripts will be added soon.

Creating figures and videos

PDF

To generate PDFs you will need to install the reportlab package:

$ conda install -n cellmodeller reportlab

The saved pickle files mentioned above can be used to create high quality PDF figures (see here for an example) using Scripts/Draw2DPDF.py as follows:

$ python CellModeller/Scripts/Draw2DPDF.py <data file>.pickle

where .pickle is the path to your saved data. You can also create figures from a set of pickles, in particular all the files saved from a given simulation (~/cellmodeller/data) like this:

$ python CellModeller/Scripts/Draw2DPDF.py ~/cellmodeller/data/<dir name>/*.pickle

where <dir name> is the directory name of your simulation run.

To frame your simulations properly you might need to change the world size in Draw2DPDF.py - this specifies the page size in simulation units (usually microns). By default it is setup to frame your cells to fill the page. You can change this by editing:

(w,h) = pdf.computeBox()

to specify you desired framing, e.g.:

(w,h) = (200,200)

specifies a fixed size of 200x200 units.

Video

We generate video using ffmpeg to process image sequences based on the PDFs generated by Draw2DPDF.py. You will need to install ffmpeg:

$ conda install -n cellmodeller ffmpeg

Here is an example 1080p video generated from each step of a simulation:

[![alt text][2]][1] Click image to view video. [1]: https://www.youtube.com/embed/6fgO-Qz_vZw [2]: https://github.com/HaseloffLab/CellModeller4/blob/gh-pages/OtherImages/colors_sm.jpg]

You will probably want to set the frame size to some fixed values as mentioned above. You can then run Scripts/video.sh like this:

$ cd <image dir>
$ ~/cellmodeller/Scripts/video.sh <output>.mp4

This script uses ImageMagick to convert PDFs to high resolution images via Ghostscript and then ffmpeg to generate a video file. You'll need to install these tools, the easiest way on Mac OSX is via Homebrew, on Linux use your package manager (e.g. synaptic).