Welcome!¶

This is the documentation of the paramspace package.

It currently is very much Work in Progress; in its current state, it only contains an API reference.

In the meantime, refer to the README on the project page for installation instructions, example usage, and development information.

Note

If you find any errors in this documentation or would like to contribute to the project, a visit to the project page is appreciated.

Supported YAML Tags¶

YAML allows defining custom so-called tags which can be distinguished during loading and serialization of objects. paramspace makes heavy use of this possibility, as it greatly simplifies the definition and usage of configuration files.

Python builtins and basic operators¶

paramspace.yaml adds YAML constructors for a number of frequently used Python built-in functions and operators. Having these available while specifying configurations can make the definition of configurations files more versatile.

Warning

The YAML tags provided here are only meant to allow basic operations, i.e. summing two parameters to create a third. Don’t overdo it. Configuration files should remain easy to read.

The tags shown below call the equivalent Python builtin or the operators defined in the operator Python module. Example:

any:      !any        [false, 0, true]    # == True
all:      !all        [true, 5, 0]        # == False

abs:      !abs        -1          # +1
int:      !int        1.23        # 1
round:    !round      9.87        # 10
sum:      !sum        [1, 2, 3]   # 6
prod:     !prod       [2, 3, 4]   # 24

min:      !min        [1, 2, 3]   # 1
max:      !max        [1, 2, 3]   # 3

sorted:   !sorted     [2, 1, 3]   # [1, 2, 3]
isorted:  !isorted    [2, 1, 3]   # [3, 2, 1]

# Operators
add:      !add        [1, 2]      # 1 + 2
sub:      !sub        [2, 1]      # 2 - 1
mul:      !mul        [3, 4]      # 3 * 4
mod:      !mod        [3, 2]      # 3 % 2
pow:      !pow        [2, 4]      # 2 ** 4
truediv:  !truediv    [3, 2]      # 3 // 2
floordiv: !floordiv   [3, 2]      # 3 / 2
pow_mod:  !pow        [2, 4, 3]   # 2 ** 4 % 3

not:      !not        [true]
and:      !and        [true, false]
or:       !or         [true, false]
xor:      !xor        [true, true]

lt:       !lt         [1, 2]      # 1 <  2
le:       !le         [2, 2]      # 2 <= 2
eq:       !eq         [3, 3]      # 3 == 3
ne:       !ne         [3, 1]      # 3 != 1
ge:       !ge         [2, 2]      # 2 >= 2
gt:       !gt         [4, 3]      # 4 >  3

negate:   !negate     [1]             # -1
invert:   !invert     [true]          # ~true
contains: !contains   [[1,2,3], 4]    # 4 in [1,2,3] == False

concat:   !concat     [[1,2,3], [4,5], [6,7,8]]  # […]+[…]+[…]+…

format1:  !format     ["{} is not {}", foo, bar]
format2:  !format
  fstr: "{some_key:}: {some_value:}"
  some_key: fish
  some_value: spam
format3:  !format
  fstr: "results: {stats[mean]:.2f} ± {stats[std]:.2f}"
  stats:
    mean: 1.632
    std:  0.026

Recursively updating maps¶

While YAML already provides the << operator to update a mapping, this operator does not work recursively. The !rec-update YAML tag supplies exactly that functionality using the recursive_update() function.

some_map: &some_map
  foo: bar
  spam: fish
some_other_map: &some_other_map
  foo:
    bar: baz
    baz: bar
  fish: spam

# Create a new map by recursively updating the first map with
# the second one (uses deep copies to avoid side effects)
merged: !rec-update [<<: *some_map, <<: *some_other_map]
# NOTE: Need to use  ^^-- inheritance here, otherwise this will
#       result in empty mappings (for some reason)

Warning

Always include via <<: *my_ref!

If supplying references to mappings (as shown in the example), the references have to be included using <<: *my_ref!

Otherwise, if using the simple *my_ref as argument, the YAML parser does not properly resolve the reference to the anchor but only returns an empty mapping.

paramspace package¶

This package provides classes to conveniently define hierarchically structured parameter spaces and iterate over them.

To that end, any dict-like object can be populated with ParamDim objects to create a parameter dimension at that key. When creating a ParamSpace from this dict, it becomes possible to iterate over all points in the space created by the parameter dimensions, i.e. the parameter space.

Furthermore, the paramspace.yaml module provides possibilities to define the parameter space fully from YAML configuration files, using custom YAML tags.

Submodules¶

paramspace.paramdim module¶

The ParamDim classes define parameter dimensions along which discrete values can be assumed. While they provide iteration abilities on their own, they make sense mostly to use as objects in a dict that is converted to a ParamSpace.

class paramspace.paramdim.Masked(value)[source]¶

Bases: object

To indicate a masked value in a ParamDim

__init__(value)[source]¶

Initialize a Masked object that is a placeholder for the given value

Parameters: value – The value to mask

property value¶

classmethod to_yaml(representer, node: paramspace.paramdim.Masked)[source]¶

Parameters

representer (ruamel.yaml.representer) – The representer module
node (Masked) – The node, i.e. an instance of this class

Returns

the scalar value that this object masks

exception paramspace.paramdim.MaskedValueError[source]¶

Bases: ValueError

Raised when trying to set the state of a ParamDim to a masked value

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class paramspace.paramdim.ParamDimBase(*, default, values: Iterable = None, order: float = None, name: str = None, as_type: str = None, assert_unique: bool = True, **kwargs)[source]¶

Bases: object

The ParamDim base class.

_OMIT_ATTR_IN_EQ = ()¶

_REPR_ATTRS = ()¶

_VKWARGS = ('values', 'range', 'linspace', 'logspace')¶

__init__(*, default, values: Iterable = None, order: float = None, name: str = None, as_type: str = None, assert_unique: bool = True, **kwargs) → None[source]¶

Initialise a parameter dimension object.

Parameters

default – default value of this parameter dimension
values (Iterable, optional) – Which discrete values this parameter dimension can take. This argument takes precedence over any constructors given in the kwargs (like range, linspace, …).
order (float, optional) – If given, this allows to specify an order within a ParamSpace that includes this ParamDim object. If not, will use np.inf instead.
name (str, optional) – If given, this is an additional name of this ParamDim object, and can be used by the ParamSpace to access this object.
as_type (str, optional) – If given, casts the individual created values to a certain python type. The following string values are possible: str, int, bool, float
assert_unique (bool, optional) – Whether to assert uniqueness of the values among them.
**kwargs – Constructors for the values argument, valid keys are range, linspace, and logspace; corresponding values are expected to be iterables and are passed to range(*args), np.linspace(*args), or np.logspace(*args), respectively.

Raises

TypeError – For invalid arguments

_init_vals(*, as_type: str, assert_unique: bool, **kwargs)[source]¶: Parses the arguments and invokes _set_vals

property name¶: The name value.

property order¶: The order value.

property default¶: The default value.

property values¶

The values that are iterated over.

Returns

the values this parameter dimension can take. If None, the: values are not yet set.

Return type

tuple

property coords¶

Returns the coordinates of this parameter dimension, i.e., the combined default value and the sequence of iteration values.

Returns: coordinates associated with the indices of this dimension
Return type: tuple

property pure_coords¶

Returns the pure coordinates of this parameter dimension, i.e., the combined default value and the sequence of iteration values, but with masked values resolved.

Returns: coordinates associated with the indices of this dimension
Return type: tuple

property num_values¶

The number of values available.

Returns: The number of available values
Return type: int

property num_states¶

The number of possible states, i.e., including the default state

Returns: The number of possible states
Return type: int

property state¶

The current iterator state

Returns

The state of the iterator; if it is None, the: ParamDim is not inside an iteration.

Return type

Union[int, None]

property current_value¶: If in an iteration, returns the value according to the current state. Otherwise, returns the default value.

__eq__(other) → bool[source]¶

Check for equality between self and other

Parameters: other – the object to compare to
Returns: Whether the two objects are equivalent
Return type: bool

abstract __len__() → int[source]¶

Returns the effective length of the parameter dimension, i.e. the number of values that will be iterated over

Returns: The number of values to be iterated over
Return type: int

__str__() → str[source]¶

Returns

Returns the string representation of the ParamDimBase-derived: object

Return type

str

__repr__() → str[source]¶

Returns

Returns the string representation of the ParamDimBase-derived: object

Return type

str

_parse_repr_attrs() → dict[source]¶: For the __repr__ method, collects some attributes into a dict

__iter__()[source]¶: Iterate over available values

__next__()[source]¶

Move to the next valid state and return the corresponding parameter value.

Returns: The current value (inside an iteration)

abstract enter_iteration() → None[source]¶

Sets the state to the first possible one, symbolising that an iteration has started.

Returns: None
Raises: StopIteration – If no iteration is possible

abstract iterate_state() → None[source]¶

Iterates the state of the parameter dimension.

Returns: None
Raises: StopIteration – Upon end of iteration

abstract reset() → None[source]¶

Called after the end of an iteration and should reset the object to a state where it is possible to start another iteration over it.

Returns: None

_parse_value(val, *, as_type: str = None)[source]¶: Parses a single value and ensures it is of correct type.

_set_values(values: Iterable, *, assert_unique: bool, as_type: str = None)[source]¶

This function sets the values attribute; it is needed for the values setter function that is overwritten when changing the property in a derived class.

Parameters

values (Iterable) – The iterable to set the values with
assert_unique (bool) – Whether to assert uniqueness of the values
as_type (str, optional) – The following values are possible: str, int, bool, float. If not given, will leave the values as they are.

Raises

AttributeError – If the attribute is already set
ValueError – If the iterator is invalid

Deleted Parameters:

as_float (bool, optional): If given, makes sure that values are: of type float; this is needed for the numpy initializers

_rec_tuple_conv(obj: list)[source]¶: Recursively converts a list-like object into a tuple, replacing all occurences of lists with tuples.

_YAML_UPDATE = {}¶

_YAML_REMOVE_IF = {'name': (None,), 'order': (None,)}¶

classmethod to_yaml(representer, node)[source]¶

Parameters

representer (ruamel.yaml.representer) – The representer module
node (type(self)) – The node, i.e. an instance of this class

Returns

a yaml mapping that is able to recreate this object

classmethod from_yaml(constructor, node)[source]¶: The default constructor for ParamDim-derived objects

_abc_impl = <_abc_data object>¶

class paramspace.paramdim.ParamDim(*, mask: Union[bool, Tuple[bool]] = False, **kwargs)[source]¶

Bases: paramspace.paramdim.ParamDimBase

The ParamDim class.

_OMIT_ATTR_IN_EQ = ('_mask_cache', '_inside_iter', '_target_of')¶

_REPR_ATTRS = ('mask',)¶

yaml_tag = '!pdim'¶

_YAML_UPDATE = {'mask': 'mask'}¶

_YAML_REMOVE_IF = {'mask': (None, False), 'name': (None,), 'order': (None,)}¶

__init__(*, mask: Union[bool, Tuple[bool]] = False, **kwargs)[source]¶

Initialize a regular parameter dimension.

Parameters

mask (Union[bool, Tuple[bool]], optional) – Which values of the dimension to mask, i.e., skip in iteration. Note that masked values still count to the length of the parameter dimension!
**kwargs –
Passed to ParamDimBase.__init__. Possible arguments:
- default: default value of this parameter dimension
- values (Iterable, optional): Which discrete values this
  parameter dimension can take. This argument takes precedence over any constructors given in the kwargs (like range, linspace, …).
- order (float, optional): If given, this allows to specify an
  order within a ParamSpace that includes this ParamDim. If not given, np.inf will be used, i.e., dimension is last.
- name (str, optional): If given, this is an additional name
  of this ParamDim object, and can be used by the ParamSpace to access this object.
- **kwargs: Constructors for the values argument, valid
  keys are range, linspace, and logspace; corresponding values are expected to be iterables and are passed to range(*args), np.linspace(*args), or np.logspace(*args), respectively.

property target_of¶: Returns the list that holds all the CoupledParamDim objects that point to this instance of ParamDim.

property state¶

The current iterator state

Returns

The state of the iterator; if it is None, the: ParamDim is not inside an iteration.

Return type

Union[int, None]

property mask_tuple¶: Returns a tuple representation of the current mask

property mask¶: Returns False if no value is masked or a tuple of booleans that represents the mask

property num_masked¶: Returns the number of unmasked values

__len__() → int[source]¶

Returns the effective length of the parameter dimension, i.e. the number of values that will be iterated over.

Returns: The number of values to be iterated over
Return type: int

enter_iteration() → None[source]¶

Sets the state to the first possible one, symbolising that an iteration has started.

Raises: StopIteration – If no iteration is possible because all values are masked.

iterate_state() → None[source]¶

Iterates the state of the parameter dimension.

Raises: StopIteration – Upon end of iteration

reset() → None[source]¶

Called after the end of an iteration and should reset the object to a state where it is possible to start another iteration over it.

Returns: None

_VKWARGS = ('values', 'range', 'linspace', 'logspace')¶

__eq__(other) → bool¶

Check for equality between self and other

Parameters: other – the object to compare to
Returns: Whether the two objects are equivalent
Return type: bool

__iter__()¶: Iterate over available values

__next__()¶

Move to the next valid state and return the corresponding parameter value.

Returns: The current value (inside an iteration)

__repr__() → str¶

Returns

Returns the string representation of the ParamDimBase-derived: object

Return type

str

__str__() → str¶

Returns

Returns the string representation of the ParamDimBase-derived: object

Return type

str

_abc_impl = <_abc_data object>¶

_init_vals(*, as_type: str, assert_unique: bool, **kwargs)¶: Parses the arguments and invokes _set_vals

_parse_repr_attrs() → dict¶: For the __repr__ method, collects some attributes into a dict

_parse_value(val, *, as_type: str = None)¶: Parses a single value and ensures it is of correct type.

_rec_tuple_conv(obj: list)¶: Recursively converts a list-like object into a tuple, replacing all occurences of lists with tuples.

_set_values(values: Iterable, *, assert_unique: bool, as_type: str = None)¶

This function sets the values attribute; it is needed for the values setter function that is overwritten when changing the property in a derived class.

Parameters

values (Iterable) – The iterable to set the values with
assert_unique (bool) – Whether to assert uniqueness of the values
as_type (str, optional) – The following values are possible: str, int, bool, float. If not given, will leave the values as they are.

Raises

AttributeError – If the attribute is already set
ValueError – If the iterator is invalid

Deleted Parameters:

as_float (bool, optional): If given, makes sure that values are: of type float; this is needed for the numpy initializers

property coords¶

Returns the coordinates of this parameter dimension, i.e., the combined default value and the sequence of iteration values.

Returns: coordinates associated with the indices of this dimension
Return type: tuple

property current_value¶: If in an iteration, returns the value according to the current state. Otherwise, returns the default value.

property default¶: The default value.

classmethod from_yaml(constructor, node)¶: The default constructor for ParamDim-derived objects

property name¶: The name value.

property num_states¶

The number of possible states, i.e., including the default state

Returns: The number of possible states
Return type: int

property num_values¶

The number of values available.

Returns: The number of available values
Return type: int

property order¶: The order value.

property pure_coords¶

Returns the pure coordinates of this parameter dimension, i.e., the combined default value and the sequence of iteration values, but with masked values resolved.

Returns: coordinates associated with the indices of this dimension
Return type: tuple

classmethod to_yaml(representer, node)¶

Parameters

representer (ruamel.yaml.representer) – The representer module
node (type(self)) – The node, i.e. an instance of this class

Returns

a yaml mapping that is able to recreate this object

property values¶

The values that are iterated over.

Returns

the values this parameter dimension can take. If None, the: values are not yet set.

Return type

tuple

class paramspace.paramdim.CoupledParamDim(*, default=None, target_pdim: paramspace.paramdim.ParamDim = None, target_name: Union[str, Sequence[str]] = None, use_coupled_default: bool = None, use_coupled_values: bool = None, **kwargs)[source]¶

Bases: paramspace.paramdim.ParamDimBase

A CoupledParamDim object is recognized by the ParamSpace and its state moves alongside with another ParamDim’s state.

_OMIT_ATTR_IN_EQ = ()¶

_REPR_ATTRS = ('target_pdim', 'target_name', '_use_coupled_default', '_use_coupled_values')¶

yaml_tag = '!coupled-pdim'¶

_YAML_UPDATE = {'target_name': '_target_name_as_list'}¶

_YAML_REMOVE_IF = {'assert_unique': (True, False), 'default': (None,), 'name': (None,), 'order': (None,), 'target_name': (None,), 'target_pdim': (None,), 'use_coupled_default': (None,), 'use_coupled_values': (None,), 'values': (None, [None])}¶

__init__(*, default=None, target_pdim: paramspace.paramdim.ParamDim = None, target_name: Union[str, Sequence[str]] = None, use_coupled_default: bool = None, use_coupled_values: bool = None, **kwargs)[source]¶

Initialize a coupled parameter dimension.

If the default or any values-setting argument is set, those will be used. If that is not the case, the respective parts from the coupled dimension will be used.

Parameters

default (None, optional) – The default value. If not given, will use the one from the coupled object.
target_pdim (ParamDim, optional) – The ParamDim object to couple to
target_name (Union[str, Sequence[str]], optional) – The name of the ParamDim object to couple to; needs to be within the same ParamSpace and the ParamSpace needs to be able to resolve it using this name.
use_coupled_default (bool, optional) – DEPRECATED
use_coupled_values (bool, optional) – DEPRECATED
**kwargs – Passed to ParamDimBase.__init__

Raises

TypeError – If neither target_pdim nor target_name were given or or both were given

__len__() → int[source]¶

Returns the effective length of the parameter dimension, i.e. the number of values that will be iterated over; corresponds to that of the target ParamDim

Returns: The number of values to be iterated over
Return type: int

enter_iteration() → None[source]¶: Does nothing, as state has no effect for CoupledParamDim

iterate_state() → None[source]¶: Does nothing, as state has no effect for CoupledParamDim

reset() → None[source]¶: Does nothing, as state has no effect for CoupledParamDim

property target_name¶: The ParamDim object this CoupledParamDim couples to.

property _target_name_as_list¶

For the safe yaml representer, the target_name cannot be a tuple.

This property returns it as str or list of strings.

_VKWARGS = ('values', 'range', 'linspace', 'logspace')¶

__eq__(other) → bool¶

Check for equality between self and other

Parameters: other – the object to compare to
Returns: Whether the two objects are equivalent
Return type: bool

__iter__()¶: Iterate over available values

__next__()¶

Move to the next valid state and return the corresponding parameter value.

Returns: The current value (inside an iteration)

__repr__() → str¶

Returns

Returns the string representation of the ParamDimBase-derived: object

Return type

str

__str__() → str¶

Returns

Returns the string representation of the ParamDimBase-derived: object

Return type

str

_abc_impl = <_abc_data object>¶

_init_vals(*, as_type: str, assert_unique: bool, **kwargs)¶: Parses the arguments and invokes _set_vals

_parse_repr_attrs() → dict¶: For the __repr__ method, collects some attributes into a dict

_parse_value(val, *, as_type: str = None)¶: Parses a single value and ensures it is of correct type.

_rec_tuple_conv(obj: list)¶: Recursively converts a list-like object into a tuple, replacing all occurences of lists with tuples.

_set_values(values: Iterable, *, assert_unique: bool, as_type: str = None)¶

This function sets the values attribute; it is needed for the values setter function that is overwritten when changing the property in a derived class.

Parameters

values (Iterable) – The iterable to set the values with
assert_unique (bool) – Whether to assert uniqueness of the values
as_type (str, optional) – The following values are possible: str, int, bool, float. If not given, will leave the values as they are.

Raises

AttributeError – If the attribute is already set
ValueError – If the iterator is invalid

Deleted Parameters:

as_float (bool, optional): If given, makes sure that values are: of type float; this is needed for the numpy initializers

property coords¶

Returns the coordinates of this parameter dimension, i.e., the combined default value and the sequence of iteration values.

Returns: coordinates associated with the indices of this dimension
Return type: tuple

classmethod from_yaml(constructor, node)¶: The default constructor for ParamDim-derived objects

property name¶: The name value.

property num_states¶

The number of possible states, i.e., including the default state

Returns: The number of possible states
Return type: int

property num_values¶

The number of values available.

Returns: The number of available values
Return type: int

property order¶: The order value.

property pure_coords¶

Returns the pure coordinates of this parameter dimension, i.e., the combined default value and the sequence of iteration values, but with masked values resolved.

Returns: coordinates associated with the indices of this dimension
Return type: tuple

classmethod to_yaml(representer, node)¶

Parameters

representer (ruamel.yaml.representer) – The representer module
node (type(self)) – The node, i.e. an instance of this class

Returns

a yaml mapping that is able to recreate this object

property target_pdim¶: The ParamDim object this CoupledParamDim couples to.

property default¶

The default value.

Returns: the default value this parameter dimension can take.
Raises: RuntimeError – If no ParamDim was associated yet

property values¶

The values that are iterated over.

If self._use_coupled_values is set, will be those of the coupled pdim.

Returns: The values of this CoupledParamDim or the target ParamDim
Return type: tuple

property state¶

The current iterator state of the target ParamDim

Returns

The state of the iterator; if it is None, the: ParamDim is not inside an iteration.

Return type

Union[int, None]

property current_value¶: If in an iteration, returns the value according to the current state. Otherwise, returns the default value.

property mask¶: Return the coupled object’s mask value

paramspace.paramspace module¶

Implementation of the ParamSpace class

class paramspace.paramspace.ParamSpace(d: dict)[source]¶

Bases: object

The ParamSpace class holds dict-like data in which some entries are ParamDim objects. These objects each define one parameter dimension.

The ParamSpace class then allows to iterate over the space that is created by the parameter dimensions: at each point of the space (created by the cartesian product of all dimensions), one manifestation of the underlying dict-like data is returned.

yaml_tag = '!pspace'¶

__init__(d: dict)[source]¶

Initialize a ParamSpace object from a given mapping or sequence.

Parameters: d (Union[MutableMapping, MutableSequence]) – The mapping or sequence that will form the parameter space. It is crucial that this object is mutable.

_gather_paramdims()[source]¶: Gathers ParamDim objects by recursively going through the dict

static _unique_dim_names(kv_pairs: Sequence[Tuple]) → List[Tuple[str, paramspace.paramdim.ParamDim]][source]¶

Given a sequence of key-value pairs, tries to create a unique string representation of the entries, such that it can be used as a unique mapping from names to parameter dimension objects.

Parameters: kv_pairs (Sequence[Tuple]) – Pairs of (path, ParamDim), where the path is a Tuple of strings.
Returns: The now unique (name, ParamDim) pairs
Return type: List[Tuple[str, ParamDim]]
Raises: ValueError – For invalid names, i.e.: failure to find a unique representation.

_get_dim(name: Union[str, Tuple[str]]) → paramspace.paramdim.ParamDimBase [source]¶

Get the ParamDim object with the given name or location.

Note that coupled parameter dimensions cannot be accessed via this method.

Parameters

name (Union[str, Tuple[str]]) – If a string, will look it up by that name, which has to match completely. If it is a tuple of strings, the location is looked up instead.

Returns

the parameter dimension object

Return type

ParamDimBase

Raises

KeyError – If the ParamDim could not be found
ValueError – If the parameter dimension name was ambiguous

property default¶

Returns the dictionary with all parameter dimensions resolved to their default values.

If an object is Masked, it will resolve it.

property current_point¶

Returns the dictionary with all parameter dimensions resolved to the values, depending on the point in parameter space at which the iteration is.

Note that unlike .default, this does not resolve the value if it is Masked.

property dims¶: Returns the ParamDim objects of this ParamSpace. The keys of this dictionary are the unique names of the dimensions, created during initialization.

property dims_by_loc¶: Returns the ParamDim objects of this ParamSpace, keys being the paths to the objects in the dictionary.

property coupled_dims¶: Returns the CoupledParamDim objects of this ParamSpace. The keys of this dictionary are the unique names of the dimensions, created during initialization.

property coupled_dims_by_loc¶: Returns the CoupledParamDim objects found in this ParamSpace, keys being the paths to the objects in the dictionary.

property coords¶

Returns the coordinates of all parameter dimensions as dict. This does not include the coupled dimensions!

As the coordinates are merely collected from the parameter dimensions, they may include Masked objects.

Note that the coordinates are converted to lists to make interfacing with xarray.DataArray easier.

property pure_coords¶

Returns the pure coordinates of all parameter dimensions as dict. This does not include the coupled dimensions!

Unlike the .coords property, the pure coordinates are cleaned of any Masked values.

Note that the coordinates are converted to lists to make interfacing with xarray.DataArray easier.

property current_coords¶

Returns the current coordinates of all parameter dimensions.

This is a shortcut for the get_dim_values method without arguments.

property num_dims¶: Returns the number of parameter space dimensions. Coupled dimensions are not counted here!

property num_coupled_dims¶: Returns the number of coupled parameter space dimensions.

property volume¶: Returns the active volume of the parameter space, i.e. not counting coupled parameter dimensions or masked values

property full_volume¶: Returns the full volume, i.e. ignoring whether parameter dimensions are masked.

property shape¶

Returns the shape of the parameter space, not counting masked values of parameter dimensions. If a dimension is fully masked, it is still represented as of length 1, representing the default value being used.

Returns: The iterator shape
Return type: Tuple[int]

property full_shape¶

Returns the shape of the parameter space, ignoring masked values

Returns: The shape of the fully unmasked iterator
Return type: Tuple[int]

property states_shape¶

Returns the shape of the parameter space, including default states for each parameter dimension and ignoring masked ones.

Returns: The shape tuple
Return type: Tuple[int]

property max_state_no¶: Returns the highest possible state number

property state_vector¶: Returns a tuple of all current parameter dimension states

property state_no¶: Returns the current state number by visiting the active parameter dimensions and querying their state numbers.

__eq__(other) → bool[source]¶: Tests the equality of two ParamSpace objects.

__str__() → str[source]¶: Returns a parsed, human-readable information string

__repr__() → str[source]¶: Returns the raw string representation of the ParamSpace.

get_info_str() → str[source]¶: Returns a string that gives information about shape and size of this ParamSpace.

_parse_dims(*, mode: str = 'names', join_str: str = ' -> ', prefix: str = ' * ') → str[source]¶

Returns a multi-line string of dimension names or locations.

This function is intended mostly for internal representation, thus defaulting to the longer join strings.

classmethod to_yaml(representer, node)[source]¶

In order to dump a ParamSpace as yaml, basically only the _dict attribute needs to be saved. It can be plugged into a constructor without any issues. However, to make the string representation a bit simpler, the OrderedDict is resolved to an unordered one.

Parameters

representer (ruamel.yaml.representer) – The representer module
node (type(self)) – The node, i.e. an instance of this class

Returns

a yaml mapping that is able to recreate this object

classmethod from_yaml(constructor, node)[source]¶: The default constructor for a ParamSpace object

get(key, default=None)[source]¶: Returns a _copy_ of the item in the underlying dict

pop(key, default=None)[source]¶: Pops an item from the underlying dict, if it is not a ParamDim

__iter__() → dict[source]¶

Move to the next valid point in parameter space and return the corresponding dictionary.

Returns: The current value of the iteration
Raises: StopIteration – When the iteration has finished

iterator(*, with_info: Union[str, Tuple[str]] = None, omit_pt: bool = False) → Generator[dict, None, None][source]¶

Returns an iterator (more precisely: a generator) yielding all unmasked points of the parameter space.

To control which information is returned at each point, the with_info and omit_pt arguments can be used. By default, the generator will return a single dictionary.

Note that an iteration is also possible for zero-volume parameter spaces, i.e. where no parameter dimensions were defined.

Parameters

with_info (Union[str, Tuple[str]], optional) – Can pass strings here that are to be returned as the second value. Possible values are: ‘state_no’, ‘state_vector’, ‘state_no_str’, and ‘current_coords’. To get multiple, add them to a tuple.
omit_pt (bool, optional) – If true, the current value is omitted and only the information is returned.

Returns

yields point after point of the: ParamSpace and the corresponding information

Return type

Generator[dict, None, None]

reset() → None[source]¶: Resets the paramter space and all of its dimensions to the initial state, i.e. where all states are None.

_next_state() → bool[source]¶

Iterates the state of the parameter dimensions managed by this ParamSpace.

Important: this assumes that the parameter dimensions already have been prepared for an iteration and that self.state_no == 0.

Returns: Returns False when iteration finishes
Return type: bool

_gen_iter_rv(pt, *, with_info: Sequence[str]) → tuple[source]¶

Is used during iteration to generate the iteration return value, adding additional information if specified.

Note that pt can also be None if iterate is a dry_run

property state_map¶

Returns an inverse mapping, i.e. an n-dimensional array where the indices along the dimensions relate to the states of the parameter dimensions and the content of the array relates to the state numbers.

Returns

A mapping of indices and coordinates to the state: number. Note that it is not ensured that the coordinates are unique, so it _might_ not be possible to use location-based indexing.

Return type

xr.DataArray

Raises

RuntimeError – If – for an unknown reason – the iteration did not cover all of the state mapping. Should not occur.

property active_state_map¶

Returns a subset of the state map, where masked coordinates are removed and only the active coordinates are present.

Note that this array has to be re-calculated every time, as the mask status of the ParamDim objects is not controlled by the ParamSpace and can change without notice.

Also: the indices will no longer match the states of the dimensions! Values of the DataArray should only be accessed via the coordinates!

Returns

A reduced state map which only includes active, i.e.:: unmasked coordinates.

Return type

xr.DataArray

get_state_vector(*, state_no: int) → Tuple[int][source]¶

Returns the state vector that corresponds to a state number

Parameters: state_no (int) – The state number to look for in the inverse mapping
Returns: the state vector corresponding to the state number
Return type: Tuple[int]

get_dim_values(*, state_no: int = None, state_vector: Tuple[int] = None) → collections.OrderedDict[source]¶: Returns the current parameter dimension values or those of a certain state number or state vector.

_calc_state_no(state_vector: Tuple[int]) → int[source]¶

set_mask(name: Union[str, Tuple[str]], mask: Union[bool, Tuple[bool]], invert: bool = False) → None[source]¶

Set the mask value of the parameter dimension with the given name.

Parameters

name (Union[str, Tuple[str]]) – the name of the dim, which can be a tuple of strings or a string. If name is a string, it will be converted to a tuple, regarding the ‘/’ character as splitting string. The tuple is compared to the paths of the dimensions, starting from the back; thus, not the whole path needs to be given, it just needs to be enough to resolve the dimension names unambiguously. For names at the root level that could be ambiguous, a leading “/” in the string argument or an empty string in the tuple-form of the argument needs to be set to symbolise the dimension being at root level. Also, the ParamDim’s custom name attribute can be used to identify it.
mask (Union[bool, Tuple[bool]]) – The new mask values. Can also be a slice, the result of which defines the True values of the mask.
invert (bool, optional) – If set, the mask will be inverted _after_ application.

set_masks(*mask_specs) → None[source]¶

Sets multiple mask specifications after another. Note that the order is maintained and that sequential specifications can apply to the same parameter dimensions.

Parameters: *mask_specs – Can be tuples/lists or dicts which will be unpacked (in the given order) and passed to .set_mask

activate_subspace(*, allow_default: bool = False, reset_all_others: bool = True, **selector) → None[source]¶

Selects a subspace of the parameter space and makes only that part active for iteration.

This is a wrapper around set_mask, implementing more arguments and also checking if any dimension is reduced to a default value, which might cause problems elsewhere.

Parameters

allow_default (bool, optional) – If True, a ValueError is raised when any of the dimensions is completely masked or when the index 0 is used during selecting of a mask.
reset_all_others (bool, optional) – If True, resets all masks before activating the subspace. If False, the previously applied masks are untouched.
**selector –
A dict specifying the active states. A key of the key-value pairs should be the name of the dimension, the value should be a dict with one of the following keys:
- idx: to select by index
- loc: to select by coordinate values
- **tol_kwargs: passed on to np.isclose when
  comparing coordinate values.
Non-sequence values will be put into lists. Alternatively, slices can be specified, which are applied on the list of all available indices or coordinates, respectively. As a shorthand, not specifying a dict but directly a list or a slice defaults to loc-behaviour.

Raises

ValueError – Description

paramspace.tools module¶

This module provides general methods needed by the ParamSpan and ParamSpace classes.

paramspace.tools.log[source]¶: The local logger instance

paramspace.tools.SKIP¶: A global paramspace.tools.Skip object to signify a Skip operation in the recursive_* functions. Not supported everywhere.

class paramspace.tools.Skip[source]¶

Bases: object

A Skip object can be used to indiciate that no action should be taken.

It is used in the recursive_** functions like paramspace.tools.recursive_update() to indicate that a value is to be skipped.

paramspace.tools.create_indices(*, from_range: list = None, unique: bool = False, sort: bool = True, append: list = None, remove: list = None) → List[int][source]¶

Generates a list of integer elements.

Parameters

from_range (list, optional) – range arguments to use as the basis of the list
unique (bool, optional) – Whether to ascertain uniqueness of elements
sort (bool, optional) – Whether to sort the list before returning
append (list, optional) – Additional elements to append to the list
remove (list, optional) – Elements to remove all occurrences of

Returns

The generated list

Return type

List[int]

paramspace.tools.recursive_contains(obj: Union[Mapping, Sequence], *, keys: Sequence) → bool[source]¶

Checks whether the given keysequence is reachable in the obj.

Parameters

obj (Union[Mapping, Sequence]) – The object to check recursively
keys (Sequence) – The sequence of keys to check for

Returns

Whether the key sequence is reachable

Return type

bool

paramspace.tools.recursive_getitem(obj: Union[Mapping, Sequence], *, keys: Sequence)[source]¶

Go along the sequence of keys through obj and return the target item.

Parameters

obj (Union[Mapping, Sequence]) – The object to get the item from
keys (Sequence) – The sequence of keys to follow

Returns

The target item from obj, specified by keys

Raises

IndexError – If any index in the key sequence was not available
KeyError – If any key in the key sequence was not available

paramspace.tools.recursive_update(obj: Union[Mapping, List], upd: Union[Mapping, List], *, try_list_conversion: bool = False, no_convert: Sequence[type] = (<class 'str'>,)) → Union[Mapping, List][source]¶

Recursively update items in obj with the values from upd.

Be aware that objects are not copied from upd to obj, but only assigned. This means:

the given obj will be changed in place

changing mutable elements in obj will also change them in upd

After the update, obj holds all entries of upd plus those that it did not have in common with upd.

If recursion is possible is determined by type; it is only done for types mappings (dicts) or lists.

To indicate that a value in a list should not be updated, an instance of the tools.Skip class, e.g. the tools.SKIP object, can be passed instead.

Parameters

obj (Union[Mapping, List]) – The object to update.
upd (Union[Mapping, List]) – The object to use for updating.
try_list_conversion (bool, optional) – If true, it is tried to convert an entry in obj to a list if it is a list in upd
no_convert (Sequence[type], optional) – For these types, conversion is skipped and an empty list is generated instead.

Returns

The updated obj

Return type

Union[Mapping, List]

paramspace.tools.recursive_setitem(d: dict, *, keys: Tuple[str], val, create_key: bool = False)[source]¶

Recursively goes through dict-like d along the keys sequence in keys and sets the value to the child entry.

Parameters

d (dict) – The dict-like object to invoke setitem on
keys (tuple) – The key sequence pointing to the node to set the value of
val – The value to set at d[the][key][sequence]
create_key (bool, optional) – Whether to create the key if it does not already exist. Default: False.

Raises

KeyError – On missing entry at keys.

paramspace.tools.recursive_collect(obj: Union[Mapping, Sequence], *, select_func: Callable, prepend_info: Sequence = None, info_func: Callable = None, stop_recursion_types: Sequence[type] = None, _parent_keys: tuple = None) → list[source]¶

Go recursively through a mapping or sequence and collect selected elements.

The select_func is called on each value. If it returns True, that value will be collected to a list, which is returned at the end.

Additionally, some information can be gathered about these elements, controlled by prepend_info.

With prepend_info, information can be prepended to the return value. Then, not only the values but also these additional items can be gathered:

keys : prepends the key

info_func : prepends the return value of info_func(val)

The resulting return value is then a list of tuples (in that order).

Parameters

obj (Union[Mapping, Sequence]) – The object to recursively search
select_func (Callable) – Each element is passed to this function; if True is returned, the element is collected and search ends here.
prepend_info (Sequence, optional) –
If given, additional info about the selected elements can be gathered in two ways:
1. By passing keys, the sequence of keys to get to this element is appended;
2. by passing info_func, the info_func function is called on the argument and that value is added to the information tuple.
info_func (Callable, optional) – The function used to prepend info
stop_recursion_types (Sequence[type], optional) – Can specify types here that will not be further recursed through. NOTE that strings are never recursed through further.
_parent_keys (tuple, optional) – Used to track the keys; not public!

Returns

the collected elements, as selected by select_func(val) or – if prepend_info was set – tuples of (info, element), where the requested information is in the first entries of the tuple

Return type

list

Raises

ValueError – Raised if invalid prepend_info entries were set

paramspace.tools.recursive_replace(obj: Union[Mapping, Sequence], *, select_func: Callable, replace_func: Callable, stop_recursion_types: Sequence[type] = None) → Union[Mapping, Sequence][source]¶

Go recursively through a mapping or sequence and call a replace function on each element that the select function returned true on.

For passing arguments to any of the two, use lambda functions.

Parameters

cont (Union[Mapping, Sequence]) – The object to walk through recursively
select_func (Callable) – The function that each value is passed to. If it returns True, the element will be replaced using the replace_func.
replace_func (Callable) – Called if the select_func returned True. The return value replaces the existing object at the selected position inside obj.
stop_recursion_types (Sequence[type], optional) – Can specify types here that will not be further recursed through. NOTE that strings are never recursed through further.

Returns

The updated mapping where each element that was selected was replaced by the return value of the replacement function.

Return type

Union[Mapping, Sequence]

paramspace.tools.is_iterable(obj) → bool[source]¶

Whether the given object is iterable or not.

This is tested simply by invoking iter(obj) and returning False if this operation raises a TypeError.

Parameters: obj – The object to test
Returns: True if iterable, False else
Return type: bool

paramspace.tools.get_key_val_iter(obj: Union[Mapping, Sequence]) → Iterator[source]¶

Given an object – assumed dict- or sequence-like – returns a (key, value) iterator.

Parameters: obj (Union[Mapping, Sequence]) – The object to generate the key-value iterator from
Returns: An iterator that emits (key, value) tuples
Return type: Iterator

paramspace.yaml module¶

This module registers various YAML constructors and representers, notably those for ParamSpace and ParamDim.

Furthermore, it defines a shared ruamel.yaml.YAML object that can be imported and used for loading and storing YAML files using the representers and constructors.

paramspace.yaml_constructors module¶

Defines the yaml constructors for the generation of ParamSpace and ParamDim during loading of YAML files.

Note that they are not registered in this module but in the paramspace.yaml module.

paramspace.yaml_constructors.pspace(loader, node) → paramspace.paramspace.ParamSpace [source]¶

yaml constructor for creating a ParamSpace object from a mapping.

Suggested tag: !pspace

paramspace.yaml_constructors.pspace_unsorted(loader, node) → paramspace.paramspace.ParamSpace [source]¶

yaml constructor for creating a ParamSpace object from a mapping.

Unlike the regular constructor, this one does NOT sort the input before instantiating ParamSpace.

Suggested tag: !pspace-unsorted

paramspace.yaml_constructors.pdim(loader, node) → paramspace.paramdim.ParamDim [source]¶

constructor for creating a ParamDim object from a mapping

Suggested tag: !pdim

paramspace.yaml_constructors.pdim_default(loader, node) → paramspace.paramdim.ParamDim [source]¶

constructor for creating a ParamDim object from a mapping, but only return the default value.

Suggested tag: !pdim-default

paramspace.yaml_constructors.coupled_pdim(loader, node) → paramspace.paramdim.CoupledParamDim [source]¶

constructor for creating a CoupledParamDim object from a mapping

Suggested tag: !coupled-pdim

paramspace.yaml_constructors.coupled_pdim_default(loader, node) → paramspace.paramdim.CoupledParamDim [source]¶

constructor for creating a CoupledParamDim object from a mapping, but only return the default value.

Suggested tag: !coupled-pdim-default

paramspace.yaml_constructors._pspace_constructor(loader, node, sort_if_mapping: bool = True) → paramspace.paramspace.ParamSpace [source]¶: Constructor for instantiating ParamSpace from a mapping or a sequence

paramspace.yaml_constructors._pdim_constructor(loader, node) → paramspace.paramdim.ParamDim [source]¶

Constructor for creating a ParamDim object from a mapping

For it to be incorported into a ParamSpace, one parent (or higher) of this node needs to be tagged such that the pspace_constructor is invoked.

paramspace.yaml_constructors._coupled_pdim_constructor(loader, node) → paramspace.paramdim.ParamDim [source]¶

Constructor for creating a ParamDim object from a mapping

For it to be incorported into a ParamSpace, one parent (or higher) of this node needs to be tagged such that the pspace_constructor is invoked.

paramspace.yaml_constructors._slice_constructor(loader, node)[source]¶: Constructor for slices

paramspace.yaml_constructors._range_constructor(loader, node)[source]¶: Constructor for range

paramspace.yaml_constructors._list_constructor(loader, node)[source]¶: Constructor for lists, where node can be a mapping or sequence

paramspace.yaml_constructors._func_constructor(loader, node, *, func: Callable, unpack: bool = True)[source]¶

A constructor that constructs a scalar, mapping, or sequence from the given node and subsequently applies the given function on it.

Parameters

loader – The selected YAML loader
node – The node from which to construct a Python object
func (Callable) – The callable to invoke on the resulting
unpack (bool, optional) – Whether to unpack sequences or mappings into the func call

paramspace.yaml_constructors.recursively_sort_dict(d: dict) → collections.OrderedDict[source]¶

Recursively sorts a dictionary by its keys, transforming it to an OrderedDict in the process.

From: http://stackoverflow.com/a/22721724/1827608

Parameters: d (dict) – The dictionary to be sorted
Returns: the recursively sorted dict
Return type: OrderedDict

paramspace.yaml_representers module¶

This module implements custom YAML representer functions

paramspace.yaml_representers._slice_representer(representer, node: slice)[source]¶

Represents a Python slice object using the !slice YAML tag.

Parameters

representer (ruamel.yaml.representer) – The representer module
node (slice) – The node, i.e. a slice instance

Returns

a yaml sequence that is able to recreate a slice

paramspace.yaml_representers._range_representer(representer, node: range)[source]¶

Represents a Python range object using the !range YAML tag.

Parameters

representer (ruamel.yaml.representer) – The representer module
node (range) – The node, i.e. a range instance

Returns

a yaml sequence that is able to recreate a range

Welcome!¶

Supported YAML Tags¶

paramspace-related tags¶

Python builtins and basic operators¶

Recursively updating maps¶

paramspace package¶

Submodules¶

paramspace.paramdim module¶

paramspace.paramspace module¶

paramspace.tools module¶

paramspace.yaml module¶

paramspace.yaml_constructors module¶

paramspace.yaml_representers module¶

`paramspace`-related tags¶