Using Petri

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

Running with MPI

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.

The run Command

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

The batch Command

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

The graph Command

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

Table Of Contents

Previous topic

Running Pykaryote

Next topic

Deprecated Scripts

This Page