Friday, February 22, 2013

Sumatra 0.5 released

We would like to announce the release of version 0.5.0 of Sumatra, a tool for automated tracking of simulations and computational analyses so as to be able to easily replicate them at a later date.

Interfaces to documentation systems

The big addition to Sumatra in this version is a set of tools to include figures and other results generated by Sumatra-tracked computations in documents, with links to full provenance information: i.e. the full details of the code, input data and computational environment used to generate the figure/result.

The following tools are available:

  • for reStructuredText/Sphinx: an “smtlink” role and “smtimage” directive.
  • for LaTeX, a “sumatra” package, which provides the “\smtincludegraphics” command.

see Reproducible publications: including and linking to provenance information in documents for more details.

Other changes

Sumatra 0.5 development has mostly been devoted to polishing. There were a bunch of small improvements, with contributions from several new contributors. The Bitbucket pull request workflow seemed to work well for this. The main changes are:

  • working directory now captured (as a parameter of LaunchMode);
  • data differences are now based on content, not name, i.e. henceforth two files with identical content but different names (e.g. because the name contains a timestamp) will evaluate as being the same;
  • improved error messages when a required version control wrapper is not installed;
  • dependencies now capture the source from which the version was obtained (e.g. repository url);
  • YAML-format parameter files are now supported (thanks to Tristan Webb);
  • added "upstream" attribute to the Repository class, which may contain the URL of the repository from which your local repository was cloned;
  • added MirroredFileSystemDataStore, which supports the case where files exist both on the local filesystem and on some web server (e.g. DropBox);
  • the name/e-mail of the user who launched the computation is now captured (first trying ~/.smtrc, then the version control system);
  • there is now a choice of methods for auto-generating labels when they are not supplied by the user: timestamp-based (the default and previously the only option) and uuid-based. Use the "-g" option to smt configure;
  • you can also specify the timestamp format to use (thanks to Yoav Ram);
  • improved API reference documentation.

Bug fixes

A handful of bugs have been fixed.

Download, support and documentation

The easiest way to get the latest version of Sumatra is

  $ pip install sumatra

Alternatively, Sumatra 0.5.0 may be downloaded from PyPI or from the INCF Software Center. Support is available from the sumatra-users Google Group. Full documentation is available on