Users have several choices as far as the CompuCell3D running modes:
1. They can run CompuCell3D through console
2. They can run CompuCell3D using Player with GUI being displayed
3. They can run CompuCell3D using Player in silent mode – no GUI is displayed then
Let's go over all the modes and shoe examples of the commands that run CompuCell3D
in each of those modes:
1. Console mode
Console mode currently allows users to run only those CompuCell3D simulation that
require xml file only. No Python scripting support is available in this mode at
this moment. The console mode is probably not the best way to run current version
of CompuCell3D because users need to write extension modules responsible for
outputting results of simulation. In any case, in the one of the future releases we
will implement the ability to run Python from console mode if users request it.
The syntax of a command to run CompuCell3D in console mode looks as below:
./compucell3d.sh –-console -i <xmlFile>
The real command could look like that:
./compucell3d.sh –-console -i cellsort_2D.xml
2. To run CompuCell3D simulations through the GUI all you need to do is to type
./compucell3d.sh
You do not need to even specify command line arguments. After typing this comand
the GUI will pop up and you will have an opportunity to specify xml and
(optionally) Python scripts from File->Open Simulation ... pull-down menu.
Now, you may want to save yourself many clicks by doing all of those tasks from
command line. The most general syntax to start simulations in GUI mode is the
following:
./compucell3d.sh -i <xmlFile> -p <pythonScript>
For example
./compucell3d.sh -i plasticitytest.xml -p plasticitytest.py
As mentioned before, specifying python script is optional. So for example to run
simple simulation such as cellsorting in 2D you would type:
./compucell3d.sh -i cellsort_2D.xml
3. Running in silent mode. This mode is useful if you want to run simulation with
or without python scripts and take screenshots of lattices but not display the GUI.
The prerequisite for this mode is to have a screenshot description file. This file
is generated automatically by the Player when you run a simulation in the GUI mode.
This is how you do it:
Open up your simulation in the Player. Start running it. Hit “Pause” button to
pause the simulation. For each lattice view you want to be saved independently of
what is displayed on the screen push the “Camera” located on the main toolbar.
Simply switch to different view and hit camera button. Every configuration that was
marked with camera button will be saved
up to 20 different configurations (this
it is too restrictive). After following
generate screenshot description file is
... to save screenshot description.
once the simulation resumes. You may save
limitation can be changed if users decide
the steps above, all you need to do to
to go to File->Save Screenshot Description
Now that you have the screenshot description file generated you will be using the
following syntax to run simulations in the silent mode;
./compucell3d.sh –-silent -i <xmlFile> -p <pythonScript> -s
<screenshotDescriptingFile>
As it was the case before, Python script is optional.
The example command could look like that:
./compucell3d.sh –-silent -i plasticitytest.xml -p plasticitytest.py -s
plasticityScreenshots.txt
or without Python script
./compucell3d.sh –-silent -i cellsort_2D.xml
-s cellsort_2D_Screenshots.txt
We have assumed here that plasticityScreenshots.txt and cellsort_2D_Screenshots.txt
were the names of generated screenshot description files for plasticity and cell
sorting simulations respectively.
X-Server Issues
When running in the silent mode users can opt not to
linux/Unix platforms. This is important when running
X-server installed for e.g. security reasons. To run
without connecting to X-server all you need to do is
command line - --noXServer. For example:
connect to X-server on
on clusters that do not have
CompuCell3D in silent mode
to include extra switch in the
./compucell3d.sh –-silent -i plasticitytest.xml -p plasticitytest.py -s
plasticityScreenshots.txt --noXServer
If you run CompuCell3D on a machine without X-server and do not specify –noXServer
option you will get an error saying that connection to X-server cannot be
established.
For most users who run CompuCell3D on their desktops, X-server issue can be
neglected.
All of above command lines can be augumented with the following two options:
--noOutput – it runs the simulation but does not save any outputting
-o <outputDirectory> - allowas users to specify directory where to store simulation
results
Example usage:
./compucell3d.sh -i plasticitytest.xml -p plasticitytest.py -–noOutput
will run plasticity test (using Python interface) and will not save any output.
./compucell3d.sh -i plasticitytest.xml -p plasticitytest.py -o plasticitytest
will run plasticity test (using Python interface) and will store output in
'plasticity' directory.