paramspace.paramdim module

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: 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, without tag

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: Optional[Iterable] = None, order: Optional[Union[int, float]] = 0, name: Optional[str] = None, as_type: Optional[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: Optional[Iterable] = None, order: Optional[Union[int, float]] = 0, name: Optional[str] = None, as_type: Optional[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. Dimensions with lowest order will then be iterated over more frequently. Default is 0.
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. See also: numpy.linspace(), numpy.logspace().

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: Union[Any, Masked]#: The default value, which may be masked.

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[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: Optional[str] = None)[source]#: Parses a single value and ensures it is of correct type.

_set_values(values: Iterable, *, assert_unique: bool, as_type: Optional[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,)}#

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(loader, node)[source]#: The default loader for ParamDim-derived objects

_abc_impl = <_abc._abc_data object>#

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

Bases: ParamDimBase

The ParamDim class.

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

_REPR_ATTRS = ('mask',)#

yaml_tag = '!sweep'#

_YAML_UPDATE = {'mask': 'mask'}#

_YAML_REMOVE_IF = {'mask': (None, False), 'name': (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, 0 will be used. See iterator() for more information on iteration order.
- 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[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._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: Optional[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: Optional[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: 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 current_value#: If in an iteration, returns the value according to the current state. Otherwise, returns the default value.

property default: Union[Any, Masked]#: The default value, which may be masked.

classmethod from_yaml(loader, node)#: The default loader for ParamDim-derived objects

property name#: The name value.

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

The number of values available.

Returns:: The number of available values
Return type:: int

property order#: The order value.

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

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

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

Bases: 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-sweep'#

_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,), 'values': (None, [None])}#

__init__(*, default=None, target_pdim: Optional[ParamDim] = None, target_name: Optional[Union[str, Sequence[str]]] = 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.
**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: Union[str, Sequence[str]]#: The ParamDim object this CoupledParamDim couples to.

property _target_name_as_list: Union[str, List[str]]#

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._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: Optional[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: Optional[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: 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

classmethod from_yaml(loader, node)#: The default loader for ParamDim-derived objects

property name#: The name value.

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

The number of values available.

Returns:: The number of available values
Return type:: int

property order#: The order value.

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

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: ParamDim#: The ParamDim object this CoupledParamDim couples to.

property default: Union[Any, Masked]#

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

paramspace.paramdim module

Contents

paramspace.paramdim module#