smt command reference¶
comment¶
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. 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. By default, comments will be appended to any existing comments. To overwrite existing comments, use the '-r/--replace flag.
positional arguments:
LABEL the record to which the comment will be added
comment a string of text, or the name of a file containing the comment.
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
configure¶
usage: smt configure [options]
Modify the settings for the current project.
options:
-h, --help show this help message and exit
-d PATH, --datapath PATH
set the path to the directory in which smt will search for datafiles generated by the simulation or analysis.
-i PATH, --input PATH
set the path to the directory in which smt will search for input datafiles.
-l OPTION, --addlabel OPTION
If this option is set, smt will append the record label either to the command line (option 'cmdline') or to the parameter file (option 'parameters'), and will add the label to the datapath
when searching for datafiles. It is up to the user to make use of this label inside their program to ensure files are created in the appropriate location.
-e PATH, --executable PATH
set the path to the executable.
-r REPOSITORY, --repository REPOSITORY
the URL of a Subversion or Mercurial repository containing the code. This will be checked out/cloned into the current directory.
-m MAIN, --main MAIN the name of the script that would be supplied on the command line if running the simulator normally, e.g. init.hoc.
-c {store-diff,error}, --on-changed {store-diff,error}
may be 'store-diff' or 'error': the action to take if the code in the repository or any of the dependencies has changed.
-g OPTION, --labelgenerator OPTION
specify which method Sumatra should use to generate labels (options: timestamp, uuid)
-t TIMESTAMP_FORMAT, --timestamp_format TIMESTAMP_FORMAT
the timestamp format given to strftime
-L {serial,serial-tqdm,distributed,slurm-mpi}, --launch_mode {serial,serial-tqdm,distributed,slurm-mpi}
how computations should be launched.
-o LAUNCH_MODE_OPTIONS, --launch_mode_options LAUNCH_MODE_OPTIONS
extra options for the given launch mode, to be given in quotes with a leading space, e.g. ' --foo=3'
-p, --plain pass arguments to the 'run' command straight through to the program. Otherwise arguments of the form name=value can be used to overwrite default parameter values.
--no-plain arguments to the 'run' command of the form name=value will overwrite default parameter values. This is the opposite of the --plain option.
--ignore-parameters do not attempt to parse any parameter files.
--parse-parameters parse parameter files if found. This is the default.
-s STORE, --store STORE
Change the record store to the specified path, URL or URI (must be specified). The argument can take the following forms: (1) `/path/to/sqlitedb` - DjangoRecordStore is used with the
specified Sqlite database, (2) `http[s]://location` - remote HTTPRecordStore is used with a remote Sumatra server, (3) `postgres://username:password@hostname/databasename` -
DjangoRecordStore is used with specified PostgreSQL database.(4) `mysql://username:password@hostname/databasename` - DjangoRecordStore is used with specified MySQL database.(5)
`mariadb://username:password@hostname/databasename` - DjangoRecordStore is used with specified MariaDB database.
-W URL, --webdav URL specify a webdav URL (with username@password: if needed) as the archiving location for data
-A PATH, --archive PATH
specify a directory in which to archive output datafiles. If not specified, or if 'false', datafiles are not archived.
-M URL, --mirror URL specify a URL at which your datafiles will be mirrored.
--add-plugin ADD_PLUGIN
name of a Python module containing one or more plug-ins.
--remove-plugin REMOVE_PLUGIN
name of a plug-in module to remove from the project.
delete¶
usage: smt delete [options] LIST
LIST should be a space-separated list of labels for individual records or of tags. If it contains tags, you must set the --tag/-t option (see below). The special value "last" allows you to delete the most recent
simulation/analysis. If you want to delete all records, just delete the .smt directory and use smt init to create a new, empty project.
positional arguments:
LIST a space-separated list of labels for individual records or of tags
options:
-h, --help show this help message and exit
-t, --tag interpret LIST as containing tags. Records with any of these tags will be deleted.
-d, --data also delete any data associated with the record(s).
diff¶
usage: smt diff [options] LABEL1 LABEL2
Show the differences, if any, between two records.
positional arguments:
label1
label2
options:
-h, --help show this help message and exit
-i IGNORE, --ignore IGNORE
a regular expression pattern for filenames to ignore when evaluating differences in output data. To supply multiple patterns, use the -i option multiple times.
-l, --long prints full information for each record
export¶
usage: smt export
Export a Sumatra project and its records to JSON. This is needed before running upgrade.
options:
-h, --help show this help message and exit
help¶
usage: smt help CMD
Get help on an smt command.
positional arguments:
cmd
options:
-h, --help show this help message and exit
info¶
usage: smt info
Print information about the current project.
options:
-h, --help show this help message and exit
init¶
usage: smt init [options] NAME
Create a new project called NAME in the current directory.
positional arguments:
NAME a short name for the project; should not contain spaces.
options:
-h, --help show this help message and exit
-d PATH, --datapath PATH
set the path to the directory in which smt will search for output datafiles generated by the simulation/analysis. Defaults to ./Data.
-i PATH, --input PATH
set the path to the directory relative to which input datafile paths will be given. Defaults to the filesystem root.
-l OPTION, --addlabel OPTION
If this option is set, smt will append the record label either to the command line (option 'cmdline') or to the parameter file (option 'parameters'), and will add the label to the datapath
when searching for datafiles. It is up to the user to make use of this label inside their program to ensure files are created in the appropriate location.
-e PATH, --executable PATH
set the path to the executable. If this is not set, smt will try to infer the executable from the value of the --main option, if supplied, and will try to find the executable from the PATH
environment variable, then by searching various likely locations on the filesystem.
-r REPOSITORY, --repository REPOSITORY
the URL of a Subversion or Mercurial repository containing the code. This will be checked out/cloned into the current directory.
-m MAIN, --main MAIN the name of the script that would be supplied on the command line if running the simulation or analysis normally, e.g. init.hoc.
-c ON_CHANGED, --on-changed ON_CHANGED
the action to take if the code in the repository or any of the depdendencies has changed. Defaults to error
-s STORE, --store STORE
Specify the path, URL or URI to the record store (must be specified). This can either be an existing record store or one to be created. The argument can take the following forms: (1)
`/path/to/sqlitedb` - DjangoRecordStore is used with the specified Sqlite database, (2) `http[s]://location` - remote HTTPRecordStore is used with a remote Sumatra server, (3)
`postgres://username:password@hostname/databasename` - DjangoRecordStore is used with specified PostgreSQL database.(4) `mysql://username:password@hostname/databasename` -
DjangoRecordStore is used with specified MySQL database.(5) `mariadb://username:password@hostname/databasename` - DjangoRecordStore is used with specified MariaDB database. Not using the
`--store` argument defaults to a DjangoRecordStore with Sqlite in `.smt/records`
-g OPTION, --labelgenerator OPTION
specify which method Sumatra should use to generate labels (options: timestamp, uuid)
-t TIMESTAMP_FORMAT, --timestamp_format TIMESTAMP_FORMAT
the timestamp format given to strftime for generating labels
-L {serial,distributed,slurm-mpi}, --launch_mode {serial,distributed,slurm-mpi}
how computations should be launched. Defaults to serial
-o LAUNCH_MODE_OPTIONS, --launch_mode_options LAUNCH_MODE_OPTIONS
extra options for the given launch mode
-W URL, --webdav URL specify a webdav URL (with username@password: if needed) as the archiving location for data
-A PATH, --archive PATH
specify a directory in which to archive output datafiles. If not specified, or if 'false', datafiles are not archived.
-M URL, --mirror URL specify a URL at which your datafiles will be mirrored.
list¶
usage: smt list [options] [TAGS]
If TAGS (optional) is specified, then only records tagged with all the tags in TAGS will be listed.
positional arguments:
TAGS
options:
-h, --help show this help message and exit
-l, --long prints full information for each record
-T, --table prints information in tab-separated columns
-f FMT, --format FMT FMT can be 'text' (default), 'html', 'json', 'latex' or 'shell'.
-r, --reverse list records in reverse order (default: newest first)
-m MAIN_FILE, --main_file MAIN_FILE
filter list of records by main file
-O, --output_table list output files from records.
-P, --parameter_table
list records with parameter values
-p parameters, --parameters parameters
filter records by parameter values, separated by comma
-d TIMESTAMP, --date TIMESTAMP
filter records by the date (today or YYYYMMDD)
migrate¶
usage: smt migrate [options]
If you have moved your data files to a new location, update the record store to reflect the new paths.
options:
-h, --help show this help message and exit
-d PATH, --datapath PATH
modify the path to the directory in which your results are stored.
-i PATH, --input PATH
modify the path to the directory in which your input data files are stored.
-A PATH, --archive PATH
modify the directory in which your results are archived.
-M URL, --mirror URL modify the URL at which your data files are mirrored.
repeat¶
usage: smt repeat LABEL
Re-run a previous simulation/analysis under (in theory) identical conditions, and check that the results are unchanged.
positional arguments:
LABEL label of record to be repeated
options:
-h, --help show this help message and exit
-l NEW_LABEL, --label NEW_LABEL
specify a label for the new experiment. If no label is specified, one will be generated automatically.
run¶
usage: smt run [options] [arg1, ...] [param=value, ...]
The list of arguments will be passed on to the simulation/analysis script. It should normally contain at least the name of a parameter file, but can also contain input files, flags, etc. If the parameter file
should be in a format that Sumatra understands (see documentation), then the parameters will be stored to allow future searching, comparison, etc. of records. For convenience, it is possible to specify a file
with default parameters and then specify those parameters that are different from the default values on the command line with any number of param=value pairs (note no space around the equals sign).
options:
-h, --help show this help message and exit
-v REV, --version REV
use version REV of the code (if this is not the same as the working copy, it will be checked out of the repository). If this option is not specified, the most recent version in the
repository will be used. If there are changes in the working copy, the user will be prompted to commit them first
-l LABEL, --label LABEL
specify a label for the experiment. If no label is specified, one will be generated automatically.
-r REASON, --reason REASON
explain the reason for running this simulation/analysis.
-e PATH, --executable PATH
Use this executable for this run. If not specified, the project's default executable will be used.
-m MAIN, --main MAIN the name of the script that would be supplied on the command line if running the simulation/analysis normally, e.g. init.hoc. If not specified, the project's default will be used.
-n N, --num_processes N
run a distributed computation on N processes using MPI. If this option is not used, or if N=0, a normal, serial simulation/analysis is run.
-t TAG, --tag TAG tag you want to add to the project
-D, --debug print debugging information.
-i STDIN, --stdin STDIN
specify the name of a file that should be connected to standard input.
-o STDOUT, --stdout STDOUT
specify the name of a file that should be connected to standard output.
sync¶
usage: smt sync PATH1 [PATH2]
Synchronize two record stores. If both PATH1 and PATH2 are given, the record stores at those locations will be synchronized. If only PATH1 is given, and the command is run in a directory containing a Sumatra
project, only that project's records be synchronized with the store at PATH1. Note that PATH1 and PATH2 may be either filesystem paths or URLs.
positional arguments:
path1
path2
options:
-h, --help show this help message and exit
tag¶
usage: smt tag [options] TAG [LIST]
If TAG contains spaces, it must be enclosed in quotes. LIST should be a space-separated list of labels for individual records. If it is omitted, only the most recent record will be tagged. If the '-r/--remove'
option is set, the tag will be removed from the records. TAG can be a status from the mutually exclusive list: _initialized_, _pre_run_, _running_, _finished_, _failed_, _killed_, _succeeded_, _crashed_.
positional arguments:
TAG tag to add
LIST a space-separated list of records to be tagged
options:
-h, --help show this help message and exit
-r, --remove remove the tag from the record(s), rather than adding it.
upgrade¶
usage: smt upgrade
Upgrade an existing Sumatra project. You must have previously run "smt export" or the standalone 'export.py' script.
options:
-h, --help show this help message and exit
version¶
usage: smt version
Print the Sumatra version.
options:
-h, --help show this help message and exit
view¶
usage: smt view [options] LABEL
View detail of a single record.
positional arguments:
label
options:
-h, --help show this help message and exit
-s, --script show script content.