=============
About Sumatra
=============

Sumatra is a tool for managing and tracking projects based on numerical
simulation, with the aim of supporting reproducible research. It can be thought
of as an automated electronic lab notebook for simulation projects.

It consists of:

 * a command-line interface, smt, for launching simulations with automatic
   recording of information about the simulation, annotating these records,
   linking to data files, etc.
 * a web interface with a built-in web-server, smtweb, for browsing and
   annotating simulation results.
 * a Python API, on which smt and smtweb are based, that can be used in your own
   scripts in place of using smt, or could be integrated into a GUI-based
   application.

Sumatra is currently alpha code, and should be used with caution and frequent
backups of your simulation records.

For documentation, see http://neuralensemble.org/trac/sumatra/

    
Intended functionality (not all implemented yet):
    * launch simulations, and record various pieces of information about the
      simulation, including:
        - the executable (identity, version)
        - the script (identity, version)
        - the parameters
        - the duration (execution time)
        - console output
        - links to all data (whether in files, in a database, etc.) produced by
          the simulation
        - the reason for doing the simulation
        - the outcome of the simulation
    * allow browsing/searching/visualising the results of previous simulations
    * allow the re-running of previous simulations with automatic verification
      that the results are unchanged
    * launch single or batch simulations, serial or parallel
    

============
Requirements
============

Sumatra requires Python versions 2.5 or 2.6. The web interface requires Django
(>= 1.1). Sumatra requires that you keep your own code in a version control
system (currently Subversion and Mercurial are supported. Git and Bazaar support
is planned). If you are already using Mercurial there is nothing else to
install. If you are using Subversion you will need to install the pysvn package.


============
Installation
============

These instructions are for Unix, Mac OS X. They may work on Windows as well, but
it hasn't been tested.

If you have downloaded the source package, sumatra-0.1.tar.gz,

$ tar xzf Sumatra-0.1.tar.gz
$ cd Sumatra-0.1
# python setup.py install

The last step may have to be done as root.


Alternatively, you can install directly from the Python Package Index.

$ pip sumatra

or

$ easy_install sumatra

