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.
- 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:
- 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:
- 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 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 state_no: Optional[int]#
Returns the current state number by visiting the active parameter dimensions and querying their state numbers.
- 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
- __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
, andcurrent_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:
- _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
- 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.
- 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 tonp.isclose
whencomparing 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