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¶
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 Extending Sumatra with plug-ins. 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 Developers’ guide).