Getting startedΒΆ
Let us assume that you already have a project based on numerical simulation, which you wish to start managing using Sumatra, and that the code for this project is under version control. Note that the following is equally valid if your project is based on data analysis rather than, or as well as, simulation: just mentally replace “simulation” with “analysis” in the following.
Change to the working directory for your project, and then create a new Sumatra
project in this directory using the smt init
command:
$ cd myproject
$ smt init MyProject
where MyProject
is the project name. This creates a sub-directory named .smt
.
Sumatra tracks data files created by your simulation by searching for newly
created files within a given directory tree. By default, it assumes that your
simulation will create files in a sub-directory Data
of your working directory.
(You can change this by providing the --datapath
option to smt init
or
smt configure
.)
Now let’s run a simulation. We will assume that your simulation code is written
in Python, and that you run the simulation by executing a file called main.py
,
passing it the name of a parameter file on the command line, i.e., you would
normally run a simulation using:
$ python main.py default.param
To run it using Sumatra, you would use:
$ smt run --executable=python --main=main.py default.param
Now we can see a list of the simulations we have run:
$ smt list
20121017-114820
This shows the label for each simulation we have run. Since we did not specify
a label, one was automatically generated from the timestamp. To see more detail,
use the --long
option:
$ smt list --long
--------------------------------------------------------------------------------
Label : 20121017-114820
Timestamp : 2012-10-17 11:48:20.421631
Reason :
Outcome :
Duration : 0.119576931
Repository : GitRepository at /path/to/myproject
Main_File : main.py
Version : 560a4afae1565799a29ca259b6a400aa389e59dd
Script_Arguments : <parameters>
Executable : Python (version: 2.7.1) at /usr/local/bin/python
Parameters : seed = 45245
: distr = "uniform"
: n = 100
: tau_m = 20.0
Input_Data : []
Launch_Mode : serial
Output_Data : [output.dat(dcb86788c2c793804a04e683fae99ad0bac8fb99)]
Tags :
(most options also have a short form, -l
in this case.)
It is a bit tedious to have to tell Sumatra which simulator and which file to run every time. Presumably, the name of the main file changes infrequently and the simulator almost never. Therefore, these can be set as defaults for a given project:
$ smt configure --executable=python --main=main.py
(you could also have given these options to smt init
. init
is used to create
a project and configure
to change its configuration later, but they mostly
accept the same arguments).
Now you can run a simulation with a much shorter command line:
$ smt run default.param
To see the current configuration of your project, use the info
command:
$ smt info
Project name : MyProject
Default executable : Python (version: 2.7.1) at /usr/local/bin/python
Default repository : GitRepository at /path/to/my/project
Default main file : main.py
Default launch mode : serial
Data store (output) : ./Data
. (input) : /
Record store : Relational database record store using the Django ORM (database file=/path/to/my/project/.smt/records)
Code change policy : error
Append label to : None
Label generator : timestamp
Sumatra automatically records the identity and versions of the simulation files and the simulator executable, stores links to any files created by the simulation, records any error messages, the date and time at which the simulation was run, and its duration. You may also add your own annotations, in several different ways. On running the simulation, you can specify a unique label, and the reason for which you are running the simulation:
$ smt run --label=haggling --reason="determine whether the gourd is worth 3 or 4 shekels" romans.param
After the simulation is complete, you can add a description of the outcome:
$ smt comment "apparently, it is worth NaN shekels."
This adds the comment to the most recent simulation. You may also describe the outcome of an earlier simulation, by specifying its label:
$ smt comment 20121017-114820 "Eureka! Nobel prize here we come."
You can also tag a simulation record with one or more short keywords:
$ smt tag foobar
$ smt tag barfoo
and remove tags:
$ smt tag --remove barfoo
The parameter file may be in any format - it is your script which is responsible
for reading it. However, if it is in one of the formats that Sumatra understands
then it is possible to modify parameter values
on the command line. Suppose default.param
contains a parameter tau_m = 20.0
, as
well as a number of other parameters, then:
$ smt run --reason="test effect of a smaller time constant" default.param tau_m=10.0
will generate a new parameter file identical to default.param
but with tau_m
equal to 10.0, and then will pass this new parameter file to your script. This
can be very convenient when you wish to study the effects of changing one or two
parameters, without having to edit your parameter file each time.
One of the main aims of Sumatra is to ensure the reproducibility of simulation
results. The repeat
command re-runs a previous simulation, and checks that the
output is identical to that of the original run:
$ smt repeat haggling
The new record exactly matches the original.
Although it is better not to delete simulation records (so as to preserve a full record of the project, false starts and all), it is possible:
$ smt delete 20121017-123706
It is also possible to delete all simulations with a given tag:
$ smt delete --tag foobar
Most of the commands described here have further options that we have not
described. A full description of the options for each command is given in the
command reference. The full list of commands is
available by running smt
by itself:
$ smt
Usage: smt <subcommand> [options] [args]
Simulation/analysis management tool version 0.4.0.dev
Available subcommands:
init
configure
info
run
list
delete
comment
tag
repeat
diff
export
upgrade
sync
and help on a given command is available by running the command with the --help
option, e.g.:
$ smt comment --help
Usage: smt comment [options] [LABEL] [COMMENT]
This command is used to describe the outcome of the simulation/analysis. If
LABEL is omitted, the comment will be added to the most recent experiment (any
existing comment will be overwritten). If the '-f/--file' option is set,
COMMENT should be the name of a file containing the comment, otherwise it
should be a string of text.
Options:
-h, --help show this help message and exit
-r, --replace if this flag is set, any existing comment will be
overwritten, otherwise, the new comment will be appended to
the end, starting on a new line
-f, --file interpret COMMENT as the path to a file containing the
comment
or smt help CMD
, where CMD
is the name of the command.
This tutorial has covered using smt
for serial simulations/analyses. A further tutorial
covers using smt for parallel computations (using MPI).
Also see smtweb, which provides a more graphical interface to viewing lists
of records than smt list
.