paramspace.paramspace module

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, 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]]) → 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: 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, 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], ParamDim]#: Returns the ParamDim objects of this ParamSpace, keys being the paths to the objects in the dictionary.

property coupled_dims: Dict[str, 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], 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: 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[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_dict() → dict[source]#

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[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(loader, 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: Optional[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.

Iteration order depends on the order parameter, where smaller values of a parameter dimension will lead to more frequent iterations.

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 for each iteration point.

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 of them, add them to a tuple.
omit_pt (bool, optional) – If true, the current value is omitted and only the information tuple 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: 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][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: Optional[int] = None, state_vector: Optional[Tuple[int]] = None) → 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 – If totally masking a parameter dimension

paramspace.paramspace module

Contents

paramspace.paramspace module#