===============
Parameter files
===============

There is no requirement to put parameters in a separate file to use Sumatra,
nor is it required to use a particular parameter file format. However, if you
do use one of the formats Sumatra supports then you will gain extra
functionality: currently, the ability to modify/add parameters on the command
line and to have Sumatra automatically add the record label to the parameter
file; in future versions, the ability to search and filter your records based
on parameters.

If the name of your parameter file ends in a recognized extension, such as
".json" or ".yaml", Sumatra will use the associated format, otherwise it
chooses the appropriate format based on file contents.


Enabling and disabling parameter file parsing
=============================================

By default, Sumatra will try to parse your parameter files.
You can turn this off with::

  $ smt configure --ignore-parameters

To re-enable parsing::

  $ smt configure --parse-parameters


Supported formats
=================

Simple
------

Each parameter on a separate line, in "name = value" format. Values may be
numbers, strings or lists (denoted with square brackets, comma-separated).
Comments are indicated by a leading "#". Example::

    # Example parameter file
    nx = 10   # } grid
    ny = 12   # } size
    inputs = [1e-3, 2e-3, 5e-3, 1e-2]
    label = "default"


Config/ini-style
----------------

Traditional config file format, as parsed by the standard Python configparser_
module. Note that this format does not distinguish numbers from string
representations of those numbers, so all parameter values are treated as
strings. This format allows one level of nesting: you can create sections within
which you can define parameters. Comments are indicated by a leading "#".
Example::

    [sectionA]
        a: 2
        b: 3

    [sectionB]
        c: hello
        d: world

See the configparser_ docs for more details.

JSON
----

See http://www.json.org/.


YAML
----

See http://www.yaml.org


Hierarchical parameter set format
---------------------------------

The parameters_ package provides a format based
on JSON, but with the addition of a ``url()`` function which allows
sub-parameter sets to be included from other files. Example::

    {
      "network": {
        "excitatory_cells": url("https://neuralensemble.org/svn/NeuroTools/trunk/doc/example.param")
        "inhibitory_cells": {
          "tau_m": 15.0,
          "cm": 0.75,
        },
      },
      "sim": {
        "tstop": 1000.0,
        "dt": 0.11,
      }
    }


Adding new formats
==================

If your parameter file format is not supported by Sumatra, there is no problem:
Sumatra will treat your parameter file as any other input data file and pass it
directly through to your simulation/analysis script.

However, it is fairly straightforward to add support for a new format. You will
need to write a Python class according to the following skeleton::

    from sumatra.core import component
    from sumatra.parameters import ParameterSet

    @component
    class MyParameterSet(ParameterSet):

        def __init__(self, initialiser):
            # initialiser could be either a filesystem path or a string containing
            # the contents of your parameter file, and should raise a SyntaxError
            # if it cannot make sense of the contents.

        def __getitem__(self, name):
            # return the parameter or sub-parameter set with the given name

        def __eq__(self, other):
            # must be implemented

        def __ne__(self, other):
            # must be implemented

        def as_dict(self):
            # return the parameter set as a Python dict containing only numerical
            # types, lists, or other dicts.

        def save(self, filename):
            # self-explanatory

        def pop(self, k, d=None):
            # same behaviour as Python dict

        def update(self, E, **F):
            # same behaviour as Python dict

        def pretty(self, expand_urls=False):
            # Return a string representation of the parameter set, suitable for
            # creating a new, identical parameter set.
            # expand_urls is present for compatibility with NTParameterSet, and need
            # not be used.


This code should be saved in a file that is somewhere on the Python module search path,
and then registered as a Sumatra plugin - see :doc:`plugins`.
If you think this format would be useful to other Sumatra users,
please send it to the developers to include in the Sumatra repository (see :doc:`developers_guide`).

.. _configparser: https://docs.python.org/3/library/configparser.html
.. _parameters: https://parameters.readthedocs.org/en/latest/