paramspace package

This page includes an extract of the API reference of the paramspace package, which is used throughout utopya, the Utopia frontend. In its own description, the package does the following:

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.

In everyday usage within Utopia, the paramspace objects are most easily defined directly inside the configuration files by using the specified YAML tags.

Refer to paramspace’s own documentation for more detailed information.

---

The ParamSpace class

Available YAML tags: !pspace

class paramspace.paramspace.ParamSpace(d: dict)

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.

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.

yaml_tag = '!pspace'

__init__(d: dict)

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.

property default: dict

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

If an object is Masked, it will resolve it.

property current_point: dict

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: Dict[str, paramspace.paramdim.ParamDim]

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: Dict[Tuple[str], paramspace.paramdim.ParamDim]

Returns the ParamDim objects of this ParamSpace, keys being the paths to the objects in the dictionary.

property coupled_dims: Dict[str, paramspace.paramdim.CoupledParamDim]

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: Dict[Tuple[str], paramspace.paramdim.CoupledParamDim]

Returns the CoupledParamDim objects found in this ParamSpace, keys being the paths to the objects in the dictionary.

property coords: Dict[str, tuple]

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: Dict[str, tuple]

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: collections.OrderedDict

Returns the current coordinates of all parameter dimensions.

This is a shortcut for the get_dim_values method without arguments.

property num_dims: int

Returns the number of parameter space dimensions. Coupled dimensions are not counted here!

property num_coupled_dims: int

Returns the number of coupled parameter space dimensions.

property volume: int

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

property full_volume: int

Returns the full volume, i.e. ignoring whether parameter dimensions are masked.

property shape: Tuple[int]

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: Tuple[int]

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: Tuple[int]

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: int

Returns the highest possible state number

property state_vector: Tuple[int]

Returns a tuple of all current parameter dimension states

property state_no: Optional[int]

Returns the current state number by visiting the active parameter dimensions and querying their state numbers.

__eq__(other) → bool

Tests the equality of two ParamSpace objects.

__str__() → str

Returns a parsed, human-readable information string

__repr__() → str

Returns the raw string representation of the ParamSpace.

get_info_dict() → dict

Returns a dict with information about this ParamSpace object.

The returned dict contains similar information as get_info_str(). Furthermore, it uses only native data types (scalars, sequences, and mappings) such that it is easily serializable and usable in scenarios where the paramspace package is not available.

Note

This information is not meant to fully recreate the ParamSpace object, but merely to provide essential metadata like the volume or shape of the parameter space and the coordinates of each of its dimensions.

Raises

NotImplementedError – If any of the parameter dimensions is masked.

get_info_str() → str

Returns a string that gives information about shape and size of this ParamSpace.

classmethod to_yaml(representer, node)

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)

The default constructor for a ParamSpace object

get(key, default=None)

Returns a _copy_ of the item in the underlying dict

pop(key, default=None)

Pops an item from the underlying dict, if it is not a ParamDim

__iter__() → dict

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: Optional[Union[str, Tuple[str]]] = None, omit_pt: bool = False) → Generator[dict, None, None]

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

Resets the paramter space and all of its dimensions to the initial state, i.e. where all states are None.

property state_map: xr.DataArray

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: xr.DataArray

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]

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: Optional[int] = None, state_vector: Optional[Tuple[int]] = None) → collections.OrderedDict

Returns the current parameter dimension values or those of a certain state number or state vector.

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

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.

__dict__ = mappingproxy({'__module__': 'paramspace.paramspace', '__doc__': 'The ParamSpace class holds dict-like data in which some entries are\n    ParamDim objects. These objects each define one parameter dimension.\n\n    The ParamSpace class then allows to iterate over the space that is created\n    by the parameter dimensions: at each point of the space (created by the\n    cartesian product of all dimensions), one manifestation of the underlying\n    dict-like data is returned.\n    ', 'yaml_tag': '!pspace', '__init__': <function ParamSpace.__init__>, '_gather_paramdims': <function ParamSpace._gather_paramdims>, '_unique_dim_names': <staticmethod object>, '_get_dim': <function ParamSpace._get_dim>, 'default': <property object>, 'current_point': <property object>, 'dims': <property object>, 'dims_by_loc': <property object>, 'coupled_dims': <property object>, 'coupled_dims_by_loc': <property object>, 'coords': <property object>, 'pure_coords': <property object>, 'current_coords': <property object>, 'num_dims': <property object>, 'num_coupled_dims': <property object>, 'volume': <property object>, 'full_volume': <property object>, 'shape': <property object>, 'full_shape': <property object>, 'states_shape': <property object>, 'max_state_no': <property object>, 'state_vector': <property object>, 'state_no': <property object>, '__eq__': <function ParamSpace.__eq__>, '__str__': <function ParamSpace.__str__>, '__repr__': <function ParamSpace.__repr__>, 'get_info_dict': <function ParamSpace.get_info_dict>, 'get_info_str': <function ParamSpace.get_info_str>, '_parse_dims': <function ParamSpace._parse_dims>, 'to_yaml': <classmethod object>, 'from_yaml': <classmethod object>, 'get': <function ParamSpace.get>, 'pop': <function ParamSpace.pop>, '__iter__': <function ParamSpace.__iter__>, 'iterator': <function ParamSpace.iterator>, 'reset': <function ParamSpace.reset>, '_next_state': <function ParamSpace._next_state>, '_gen_iter_rv': <function ParamSpace._gen_iter_rv>, 'state_map': <property object>, 'active_state_map': <property object>, 'get_state_vector': <function ParamSpace.get_state_vector>, 'get_dim_values': <function ParamSpace.get_dim_values>, '_calc_state_no': <function ParamSpace._calc_state_no>, 'set_mask': <function ParamSpace.set_mask>, 'set_masks': <function ParamSpace.set_masks>, 'activate_subspace': <function ParamSpace.activate_subspace>, '__dict__': <attribute '__dict__' of 'ParamSpace' objects>, '__weakref__': <attribute '__weakref__' of 'ParamSpace' objects>, '__hash__': None, '__annotations__': {}})

__hash__ = None

__module__ = 'paramspace.paramspace'

__weakref__

list of weak references to the object (if defined)

set_masks(*mask_specs) → None

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

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 – If totally masking a parameter dimension

Parameter Dimensions

The following classes are used to defined parameter dimensions inside the parameter space.

The ParamDimBase: A common base class

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

Bases: object

The ParamDim base class.

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__(*, default, values: Optional[Iterable] = None, order: Optional[float] = None, name: Optional[str] = None, as_type: Optional[str] = None, assert_unique: bool = True, **kwargs) → None

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

property name

The name value.

property order

The order value.

property default

The default value.

property values: tuple

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: tuple

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: tuple

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: int

The number of values available.

Returns

The number of available values

Return type

int

property num_states: int

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

Returns

The number of possible states

Return type

int

property state: int

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

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

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

Returns

Returns the string representation of the ParamDimBase-derived

object

Return type

str

__repr__() → str

Returns

Returns the string representation of the ParamDimBase-derived

object

Return type

str

__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)

abstract enter_iteration() → None

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

Iterates the state of the parameter dimension.

Returns

None

Raises

StopIteration – Upon end of iteration

abstract reset() → None

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

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

classmethod from_yaml(constructor, node)

The default constructor for ParamDim-derived objects

__abstractmethods__ = frozenset({'__len__', 'enter_iteration', 'iterate_state', 'reset'})

__dict__ = mappingproxy({'__module__': 'paramspace.paramdim', '__doc__': 'The ParamDim base class.', '_OMIT_ATTR_IN_EQ': (), '_REPR_ATTRS': (), '_VKWARGS': ('values', 'range', 'linspace', 'logspace'), '__init__': <function ParamDimBase.__init__>, '_init_vals': <function ParamDimBase._init_vals>, 'name': <property object>, 'order': <property object>, 'default': <property object>, 'values': <property object>, 'coords': <property object>, 'pure_coords': <property object>, 'num_values': <property object>, 'num_states': <property object>, 'state': <property object>, 'current_value': <property object>, '__eq__': <function ParamDimBase.__eq__>, '__len__': <function ParamDimBase.__len__>, '__str__': <function ParamDimBase.__str__>, '__repr__': <function ParamDimBase.__repr__>, '_parse_repr_attrs': <function ParamDimBase._parse_repr_attrs>, '__iter__': <function ParamDimBase.__iter__>, '__next__': <function ParamDimBase.__next__>, 'enter_iteration': <function ParamDimBase.enter_iteration>, 'iterate_state': <function ParamDimBase.iterate_state>, 'reset': <function ParamDimBase.reset>, '_parse_value': <function ParamDimBase._parse_value>, '_set_values': <function ParamDimBase._set_values>, '_rec_tuple_conv': <function ParamDimBase._rec_tuple_conv>, '_YAML_UPDATE': {}, '_YAML_REMOVE_IF': {'name': (None,), 'order': (None,)}, 'to_yaml': <classmethod object>, 'from_yaml': <classmethod object>, '__dict__': <attribute '__dict__' of 'ParamDimBase' objects>, '__weakref__': <attribute '__weakref__' of 'ParamDimBase' objects>, '__hash__': None, '__abstractmethods__': frozenset({'reset', '__len__', 'iterate_state', 'enter_iteration'}), '_abc_impl': <_abc_data object>, '__annotations__': {}})

__hash__ = None

__module__ = 'paramspace.paramdim'

__weakref__

list of weak references to the object (if defined)

The ParamDim: A proper parameter dimension

Available YAML tags: !pdim and !sweep

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

Bases: paramspace.paramdim.ParamDimBase

The ParamDim class.

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.

yaml_tag = '!pdim'

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

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: int

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: Tuple[bool]

Returns a tuple representation of the current mask

property mask: Union[bool, Tuple[bool]]

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

property num_masked: int

Returns the number of unmasked values

__len__() → int

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

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

Iterates the state of the parameter dimension.

Raises

StopIteration – Upon end of iteration

reset() → None

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

__abstractmethods__ = frozenset({})

__module__ = 'paramspace.paramdim'

The CoupledParamDim: attached to another dimension

Available YAML tags: !coupled-pdim and !coupled-sweep

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

Bases: paramspace.paramdim.ParamDimBase

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

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

yaml_tag = '!coupled-pdim'

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

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

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

Does nothing, as state has no effect for CoupledParamDim

iterate_state() → None

Does nothing, as state has no effect for CoupledParamDim

reset() → None

Does nothing, as state has no effect for CoupledParamDim

property target_name: Union[str, Sequence[str]]

The ParamDim object this CoupledParamDim couples to.

__abstractmethods__ = frozenset({})

__module__ = 'paramspace.paramdim'

property target_pdim: paramspace.paramdim.ParamDim

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: tuple

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: int

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: Union[bool, Tuple[bool]]

Return the coupled object’s mask value

The 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.

The paramspace.tools module

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

paramspace.tools.log

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

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.

__dict__ = mappingproxy({'__module__': 'paramspace.tools', '__doc__': 'A Skip object can be used to indiciate that no action should be taken.\n\n    It is used in the ``recursive_**`` functions like\n    :py:func:`paramspace.tools.recursive_update` to indicate that a value is\n    to be skipped.\n    ', '__dict__': <attribute '__dict__' of 'Skip' objects>, '__weakref__': <attribute '__weakref__' of 'Skip' objects>, '__annotations__': {}})

__module__ = 'paramspace.tools'

__weakref__

list of weak references to the object (if defined)

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

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

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)

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: typing.Union[typing.Mapping, typing.List], upd: typing.Union[typing.Mapping, typing.List], *, try_list_conversion: bool = False, no_convert: typing.Sequence[type] = (<class 'str'>,)) → Union[Mapping, List]

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)

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: Optional[Sequence] = None, info_func: Optional[Callable] = None, stop_recursion_types: Optional[Sequence[type]] = None, _parent_keys: Optional[tuple] = None) → list

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: Optional[Sequence[type]] = None) → Union[Mapping, Sequence]

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

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

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