=====================
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.
    
    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]
    
     Commands provided by the smt tool.  Each command corresponds to a function in
    this module.
    
    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.
                            Defaults to ./Data
      -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 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 none

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

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.
    
    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/analysis.
                            Defaults to ./Data
      -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
      --plugins=MODULE      (advanced) specify the Python path of a module
                            containing plug-ins. These allow Sumatra's
                            functionality to be customized.
      -D, --debug           print debugging information.

list
----
::

    Usage: smt list [options] [TAGS]
    
    If TAGS (optional) is specified, then only records with a tag in TAGS will be
    listed.
    
    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) or 'html'.

repeat
------
::

    Usage: smt repeat LABEL
    
    Re-run a previous simulation/analysis under (in theory) identical conditions,
    and check that the results are unchanged.
    
    Options:
      -h, --help  show this help message and exit

run
---
::

    Usage: smt run [options] PARAMFILE [param=value, ...]
    
    PARAMFILE is the name of the parameter file to be used for this simulation or
    analysis. 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). The parameter file should also consist of
    param=value pairs, one per line, although here spaces are allowed around the
    equals sign. Comments may be included using #.
    
    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, the label will be based on PARAMFILE and
                            the timestamp.
      -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

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 '-d/--delete' option is set, the tag
    will be removed from the records.
    
    Options:
      -h, --help    show this help message and exit
      -r, --remove  remove the tag from the record(s), rather than adding it.

