This section describes the petri command line tool.
Petri contains three sub commands: run, graph, and batch. To list these sub commands, run:
$ petri -h
Petri uses Message Passing Interface (MPI) to distribute batches of comparisons over multiple processors. Each simulation runs on one processor. Use mpirun to execute programs over MPI:
$ mpirun petri run
1 processors found
added comparison: comparison
Total: 0.00% (0/60000)
comparison: 0.00%
(0 running, 0 done, 0 failed, 60 queued)
Top 3 slowest jobs:
all jobs done
runtime: 0:00:00.000070 (hh:mm:ss)
As you can see, the default comparison ran on one processor. However, none of the 60 queued jobs ran. This is because petri requires at least two processors in order to run. One processor is always reserved to coordinate sending and receiving jobs.
mpirun‘s -np flag allows you to specify how many processors to use. Lets try again with two processors:
$ mpirun -np 2 petri run
The previous example uses processors from the same computer. Where MPI shines is its ability to run a program over multiple computers. Pass mpirun a file containing a list of computers, and it will use processors from all of them. If we had a hosts file called mpi_hosts we could run petri on 100 processors:
$ mpirun --hostfile mpi_hosts np 100 petri run
For more information on MPI and the hosts file format, see The Open MPI FAQ.
Note
If you are a researcher at Calvin College, a host file for the Unix Lab is located at extras/unix_lab_mpi_hosts.
Petri’s run command runs a comparison multiple times, automatically averaging and graphing the results.
When run without any options, petri loads settings from its default configuration file in pykaryote/petri/config/petri_settings.cfg. For a detailed description of petri_settings.cfg, see Petri Settings Configuration Files.
Settings from the configuration file can be overwritten with command line arguments. For a list of possible arguments, use the -h flag:
$ petri run -h
usage: petri run [-h] [-s SIM] [-c CMP] [-n NAME] [-r RUNS] [-d DATA] [-k]
optional arguments:
-h, --help show this help message and exit
-s SIM, --sim SIM the template simulation configuration file for the
comparison
-c CMP, --cmp CMP the configuration file for the comparison
-n NAME, --name NAME the name of the comparison
-r RUNS, --runs RUNS the number of times each simulation is run
-d DATA, --data DATA the directory in which to store finished comparisons
-k, --keep-files Do not delete simulation data after graphing
By default, simulation data and graphs are saved to ~/pykaryote. Specify a different output directory with the -d flag:
$ mpirun -np 4 petri run -d ~/my_output_dir
When petri is finished, graphs will be located in ~/my_output_dir/comparison/graphs.
You can also specify the number of times to run each simulation, and the simulation configuration file to use. The default setting of 1000 generations takes a long time to run. Lets limit it to just 5.
Copy the default configuration file from pykaryote/configs/sim.cfg to your current directory. Open it, and change this line:
generation_limit = 1000
to:
generation_limit = 5
run petri with the -r flag to specify a single run and the --sim flag to specify our new configuration file:
$ mpirun -np 2 petri run --sim sim.cfg -r 1
Since comparisons take a long time, it would be nice to be able to queue several comparisons to run overnight. This can be done with the batch command.
For example, if you had a file named cmp_batch.cfg which lists comparisons to run, you could run them with:
$ mpirun --hosts mpi_hosts -np 100 petri batch cmp_batch.cfg
For a description of the batch configuration file format, see Petri Batch Configuration Files.
Again, a list of available arguments:
$ petri batch -h
usage: petri batch [-h] [-d DATA] [-r RUNS] [-k] config
positional arguments:
config the configuration file describing a batch of
comparisons to run
optional arguments:
-h, --help show this help message and exit
-d DATA, --data DATA the directory in which comparisons are stored
-r RUNS, --runs RUNS the number of times each simulation is run
-k, --keep-files Do not delete simulation data after graphing
Sometimes when running a large batch, one of the comparisons fails to graph. This can be because a simulation timed out or was configured incorrectly.
The graph command can be used to graph leftover data from a failed (or successful) comparison. Simply point it in the direction of the failed comparison:
$ petri graph my_failed_comparison
Note
The name of a comparison is always relative to the data directory, which defaults to ~/pykaryote. Thus, the comparison in the previous command is located in ~/pykaryote/my_failed_comparison.
graph does not have many arguments:
$ petri graph --help
usage: petri graph [-h] [-d DATA] [-k] name
positional arguments:
name the name of the comparison to graph
optional arguments:
-h, --help show this help message and exit
-d DATA, --data DATA the directory in which comparisons are stored
-k, --keep-files Do not delete simulation data after graphing