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