Module for encapsulating model parameters.
Instances of the Parameters class represents a set of parameters, typically program input data.
The Parameters object can be used to represent the input parameters to your model. It works like a dict with attribute access, but has several additional features:
- stores metadata about itself and the parameters, like:
- the parameter object entity id
- a description this parameter object
- parameter types
- parameter units
- parameter descriptions
- parameter grouping
- parameter ordering
nesting - Parameters object values might themselves be Parameters objects interpreating dots in parameter names correctly
can be read from/written to file - support for new file formats can be added by subclassing ParametersFormat
has protection against overwriting existing values or setting invalid parameters through the mode argument
templating - by setting mode to “c”, a Parameters object will work as a template where values can be changed, but new parameters cannot be added/removed and existing types cannot be changed
automatic conversion between different template versions, through registration of the entityid and defining an EntityConverter
can be viewed and edited through an autogenerated ParEdit gui
For nesting and attribute access to work, parameter names should be valid Python identifiers not starting with underscore.
A basic example
An empty parameters object can be created with:
>>> from pario import parameters
>>> p = parameters.Parameters()
and later populated by hand by like:
>>> p._set('length', 4.0, 'm', doc='The length')
or from a file with the _update_fromstring() and_update_fromfile() methods, like:
>>> p._update_fromstring('5.0 m height # The height')
However, typically it will be created by reading a parameter file:
p = parameters.read('mydatafile')
The parameter values can later be accessed as attributes or indexing:
>>> p.length
4.0
>>> p['height']
5.0
If you e.g. want the length in cm you can do:
>>> p._get('length', 'cm')
400.0
Content
| pario.parameters.Parameters([entityid, ...]) | A dict-like class for encapsulating model parameters. |
| pario.parameters.read(fname[, fmt, ...]) | Returns a new Parameters object from file. |
| pario.parameters.fromstring(string[, fmt, ...]) | Returns a new Parameters object from string. |
| pario.parameters.getpar(fname, name[, fmt]) | Returns the value of a given parameter from a parameter file. |
| pario.parameters.setpar(filename, name, value) | Sets the value of a parameter in a parameter file. |
| pario.parameters.NotPermittedError | Raised when trying to add or change a parameter not permitted by |
A dict-like class for encapsulating model parameters.
All parameters are available either as attributes (only those that are Python identifiers) or through standard key indexing. In order to avoid name conflicts, all methods are prefixed with underscore.
| Parameters : | entityid : string | tuple
description : string
mode : string
options : keywords
|
||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Examples
>>> s = '''
... 2 - model model flag
... 1.52e10 m^-2 rho_i dislocation density
... # a comment
... 0.3e-6 m delta subgrain size
... '''
>>> p = fromstring(s, fmt='txt', entityid='mymodel-0.1')
>>> print(p)
2 - model model flag
15200000000.0 m^-2 rho_i dislocation density
3e-07 m delta subgrain size
>>> p._names
['model', 'rho_i', 'delta']
>>> [p[name] for name in p._names]
[2, 15200000000.0, 3e-07]
Attributes
| _entityid | (parameter entity id) |
| _description | (description of parameter entity) |
| _options | (dict of options, set from keyword arguments) |
| _names | (list of parameter names) |
| _values | (dict mapping parameter names to their value) |
| _units | (dict mapping parameter names to their unit) |
| _groups | (dict mapping parameter names to group name) |
| _doc | (dict mapping parameter names to documentation strings) |
| _mode | (default mode for adding and changing parameters) |
Methods
| _set_mode(mode) | Sets the current mode. |
| _get_mode() | Returns the current mode. |
| _set_option(self, key, value): | Sets option key to value. |
| _get_option(self, key, default=None) | Returns value of option key. If no such option exists, default is returned. |
| _has_option(self, key) | Returns whether an option with the given name exists. |
| _remove_option(self, key): | Deletes the given option. |
| _get_names(group=None) | Returns all parameter names for the given group. |
| _get_groups() | Returns all groups. |
| _copy(names=None) | Returns a copy of self. |
| _remove(name) | Removes a parameter. |
| _set(name, value, unit, doc=None, group=None, mode=’ac’) | Sets a parameter, adding it if it does not exists (and mode allows). |
| _get(name, unit=None) | Returns a parameter value in the given unit. |
| _get_quantity(name, unit=None) | Returns parameter name as a pint Qiantity in given unit. |
| _update(par, mode=None) | Update parameters from other Parameters object. |
| _update_fromstring(self, string, fmt=’text’, mode=None, options) | Update parameters from string. |
| _update_fromfile(self, fnaeme, fmt=None, mode=None, options) | Update parameters from file. |
| _tostring(fmt, names=None, linesep=None) | Returns a string representation of self in given format. |
| _write(fname, fmt=None, names=None, linesep=None) | Write parameters to file. |
| _edit(names=None, group=None, title=’Parameters’, callback=None) | Opens a graphical window for editing stored parameters. |
| _connect(callback, name, action) | Register callback to be called when a parameter is changed. |
| _disconnect(callback, name, action) | Unregister a callback. |
| _emit(name, action) | Calls all callbacks connected to name and action. |
Set current mode for allowing adding and changing parameters. It is a combination of ‘a’ (allow adding new parameters) and ‘c’ (allow changing existing parameters).
Returns a list of parameter names. If group is None, all parameter names are returned. Else, if group is the empty string, the name of all ungrouped parameters is returned. Otherwise only the names in the given group is returned.
Returns a copy of self. If names is provided, only the given parameters are included in the copy.
Add or set the value of a parameter.
| Parameters : | name: string
value: bool | int | float | string | array
unit: None | string
ptype : None | type | string
group: None | string
doc: None | string
mode : string
|
|---|
Returns the value of parameter name. If unit is provided, convert the returned value to the given unit.
Returns parameter name as a pint Quantity. If unit is provided, convert the returned quantity to the given unit.
Update parameters. par can be another Parameters object, a mapping or a sequence of (key, value) tuples. If mode is not None, it overwrites the default mode.
Updates parameters from string.
fmt is the data format mode, if not None, overwrites the default mode options is passed to the format parser
Updates parameters from file fname.
fmt is the data format mode, if not None, overwrites the default mode options is passed to the format parser
Returns a string representation of self in given format.
The default is to return all names, but if names is given, then only the given names are returned.
The keyword arguments are passed to the tostring() method of the actual ParametersFormat subclass.
Writes self to file fname using given format.
The default is to return all names, but if names is given, then only the given names are returned.
The keyword arguments are passed to the write() method of the actual ParametersFormat subclass.
Popup a graphical window for editing stored parameters.
See pario.paredit.paredit() for a description of the arguments and return value.
Returns a new Parameters object from file.
| Parameters : | fname : string | file_like
fmt : None | string
entityid : None | string | tuple
description : string
mode : string
options : keywords
|
|---|
Returns a new Parameters object from string.
See read() for a description of the parameters.
Returns the value of a given parameter from a parameter file.
| Parameters : | fname : string | file-like
name : string
fmt : None | string
|
|---|
Sets the value of a parameter in a parameter file.
| Parameters : | filename : string
name : string
value : correct type for this parameter
fmt : None | string
options : keywords
|
|---|
Raised when trying to add or change a parameter not permitted by the mode.
Since Parameters objects knows so much about themselves, it is possible to convert between different versions of your input file or make rules for generating input to another program based on some input files and the output from your program. This functionality is supported through the pario.parameters.EntityConverter class.
See the class documentation below for an example.
If the only changes between two versions of an input file is one of:
- reordering of the parameters
- change of units
- adding a new parameter with a default value
you can use the pario.parameters.simple_converter() to generate a converter. Other you have to subclass pario.parameters.EntityConverter .
Content
| pario.parameters.EntityConverter(ereg) | Class for converting between parameter entities. |
| pario.parameters.ConversionError | Error in convertion between parameter entities. |
| pario.parameters.simple_converter(name, ...) | A factory function that returns a new converter class that |
Class for converting between parameter entities.
| Parameters : | ereg : EntityRegistry intance
|
|---|
Notes
Examples
# Define some converters
>>> class A2fromA1Converter(EntityConverter):
... sources = [('A', '1'), ]
... target = ('A', '2')
... def converter(self, a1):
... self.check_arguments(a1)
... return self.updated_copy(self.target, a1)
>>> class B2fromB1_A2Converter(EntityConverter):
... sources = [('B', '1'), ('A', '2')]
... target = ('B', '2')
... def converter(self, b1, a2):
... self.check_arguments(b1, a2)
... b2 = self.updated_copy(self.target, b1)
... b2.area = a2.length * a2.height
... return b2
# Define some parameter templates
>>> a1 = Parameters('A-1')
>>> a1._set('length', 1.0, 'm')
>>> a1._set('height', 2.0, 'cm')
>>> a2 = Parameters('A-2')
>>> a2._set('length', 1.0, 'm')
>>> a2._set('height', 0.03, 'm')
>>> b1 = Parameters('B-1')
>>> b1._set('time', 5.0, 's')
>>> b2 = Parameters('B-2')
>>> b2._set('time', 4.0, 's')
>>> b2._set('area', 0.04, 'm^2')
# Register the templates
>>> ereg = EntityRegistry()
>>> ereg.register_parameters(a1, a2, b1, b2)
# Use the a1 and b1 templates as input to generate a new Parameters # instance of entity B-2. Note the implicit conversion of unis # when a1 is converted to entity A-2.
>>> econv = EntityConverter(ereg)
>>> b2_new = econv.convert(('B', '2'), a1, b1)
>>> print(b2_new)
5.0 s time None
0.02 m^2 area None
Checks that *sources confirms to the EntityConverter subclass sources attribute. Raises an exception on error.
Returns a Parameters instance of entity target using sources as input.
| Parameters : | target : string | tuple
*sources : Parameters instances
|
|---|---|
| Raises : | ConversionError if the conversion fails. |
Converter implemented by subclasses.
It should return an Parameters instance of the subclass target entity, using the *sources Parameters instances as input.
You can call check_sources() to check that *sources confirms in number and entity types to the subclass sources attribute.
Returns a copy of src with values updated from pars.
src is either a Parameters instance or an entity identifier. In the latter case a template Parameters object from the registry is used.
pars is either a Parameters instances or a sequence of zero or more instances. These will update src in the given order, which means that the later arguments will overwrite the firsts.
mode is a combination of ‘a’ (allow adding new parameters) and ‘c’ (allow changing existing parameters).
A factory function that returns a new converter class that converts Parameters objects of entity sources to target.
mode determines wheter parameters can be changed or added. Is a combination of ‘a’ (allow adding new parameters) and ‘c’ (allow changing existing parameters).
Examples
>>> A2fromA1Converter = simple_converter(
... 'A2fromA1Converter', sources=['A-1'], target='A-2')
>>> C1fromA1_B2Converter = simple_converter(
... 'C1fromA1_B2Converter', sources=['A-1', 'B-2'], target='C-1')
In order for the parameter entity conversions to work, the converter needs to know a definition of the parameter entities. This is simply done by creating an entity register
>>> ereg = EntityRegistry()
and registering a default input file as a Parameters objects
>>> ereg.register_file('my_default_inputfile.txt')
The ereg object is then be passed to the EntityConverter constructor.
Entity registry class.
Examples
>>> ereg = EntityRegistry()
>>> ereg.register_template_folder('templates')
Returns the entityid(s) of templates that matches names.
If require_unique is true and there is one match its entityid is returned, otherwise an exception is raised.
If require_unique if false, a list with entityid’s for all the matches is returned.
Adds template file fname to registry. See read() for a arguments.
New file formats can be added by subclassing ParametersFormat. Predefined includes:
- ‘text’ defined by pario.parameters.TextFormat
- ‘settings’ defined by pario.parameters.SettingsFormat
Content
| pario.parameters.ParametersFormat | Base class for parameter formats. |
| pario.parameters.TextFormat | Text format. |
| pario.parameters.SettingsFormat | A subclass of TextFormat where each input line has the |
| pario.parameters.InputError | Raised on error when reading input. |
Base class for parameter formats.
Subclasses should define the name and extension attributes as well as overriding the fromstring() and tostring() methods. If it is more natural to only support files, the read() and write() methods could be overridden instead.
Attributes
| name | (string) Name of the format. |
| extension | (string) Name of file name extension associated with this format. |
Returns a Parameters object read from string.
Should be implemented by the subclass.
Returns the subclass with given format name or extension.
Reads a fname and returns a Parameters object.
Text format.
Returns a Parameters object read from string.
| Parameters : | string : str
entityid : string | tuple
description : string
mode : string
converters : None | sequence_of_types | string
options : keywords
|
|---|
Returns parameters as a string.
| Parameters : | par : Parameters instance
names : None | sequence
linesep : string
show_heading : bool
show_group_comments : bool
kw : keywords
|
|---|
A subclass of TextFormat where each input line has the following syntax:
name = value # doc
Examples
>>> s = '''
... model = 2 # model flag
... rho_i = 1.52e10 # dislocation density, m^-2
...
... # subgrain size, m
... delta = 3e-7
... '''
>>> settings = fromstring(s, fmt='settings')
>>> print(settings._tostring(fmt='settings'))
model = 2 # model flag
rho_i = 15200000000.0 # dislocation density, m^-2
delta = 3e-07 # subgrain size, m
Returns entity as an (entityname, version) tuple. entity may be either the wanted tuple or a string of the form:
entityname-version[.ext]
where the extension .ext is optional.
Examples
>>> entity_to_tuple('myprogram-0.1')
('myprogram', '0')
>>> entity_to_tuple('myprogram-3.txt')
('myprogram', '3')
Returns entity as a string on the form entityname-version.
Examples
>>> entity_to_string(('myprogram', '0.1'))
'myprogram-0.1'
Returns all list with all subclasses of cls. If recurs is true, nested subclasses are also included.
Tries to convert value to another type using the converters in the sequence converters. converters may also be a comma-separated string of converter names (looked up in the local, global or builtin scopes).
The new value after the first successful convertsion is returned.
If value is a sequence, a list is returned with all elements converted using the first conversion that works for all of them.
If types is None, it defaults to (int, float, ast.literal_eval, string2bool, str).
Examples
>>> typeconvert('3.4')
3.4
>>> typeconvert('3.4a')
'3.4a'
>>> typeconvert('yes')
True
>>> typeconvert('yes', converters='int,float,string2bool')
True
>>> typeconvert(['3', '1', '2.2'])
[3.0, 1.0, 2.2]
>>> typeconvert([3, 1, 2.2]) # Note that 2.2 is truncated!
[3, 1, 2]
>>> typeconvert(['a', 1, 2.2])
['a', '1', '2.2']