=====================
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.

    optional arguments:
      -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.

    optional arguments:
      -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,distributed,slurm-mpi}, --launch_mode {serial,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.
      -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 Postgres
                            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

    optional arguments:
      -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

    optional arguments:
      -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.

    optional arguments:
      -h, --help  show this help message and exit

help
----
::

    usage: smt help CMD

    Get help on an smt command.

    positional arguments:
      cmd

    optional arguments:
      -h, --help  show this help message and exit

info
----
::

    usage: smt info

    Print information about the current project.

    optional arguments:
      -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.

    optional arguments:
      -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 Postgres
                            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
      -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

    optional arguments:
      -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 NAME, --main_file NAME     filter list of records by main file
      -P, --parameter_view          list records with parameter values

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.

    optional arguments:
      -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

    optional arguments:
      -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).

    optional arguments:
      -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

    optional arguments:
      -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.

    positional arguments:
      TAG           tag to add
      LIST          a space-separated list of records to be tagged

    optional arguments:
      -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.

    optional arguments:
      -h, --help  show this help message and exit

version
-------
::

    usage: smt version

    Print the Sumatra version.

    optional arguments:
      -h, --help  show this help message and exit
