pymor.parameters.base

This module contains the implementation of pyMOR’s parameter handling facilities.

Use the ParametricObject base class to define immutable (mathematical) objects that depend on some Parameters. Each Parameter in pyMOR has a name and a fixed dimension (number of scalar components of the parameter vector). In particular, scalar parameters are treated as parameter vectors of dimension 1. Mappings of Parameters to parameter values are stored in pyMOR using dedicated Mu objects. To sample parameter values within a given range, ParameterSpace objects can be used.

Module Contents

class pymor.parameters.base.Mu(*args, **kwargs)

Bases: pymor.core.base.ImmutableObject

Immutable mapping of Parameter names to parameter values.

This class represents an immutable mapping (dict) from parameter names to corresponding values given as one-dimensional NumPy arrays. In addition, time-dependent parameter values may be stored in the time_dependent_values attribute, which is an immutable mapping from parameter names to Functions of time.

Note

Time-dependent parameter values are invisible when using the class’s mapping protocol methods (__contains__, __getitem__, keys, items, etc.). Code wanting to handle time-dependent values needs to use at_time or explicitly lookup values in time_dependent_values.

Parameters

Anything that dict accepts for the construction of a dictionary. Values are automatically converted to one-dimensional NumPy arrays, except for Functions, which are interpreted as time-dependent parameter values. Unless the Python interpreter runs with the -O flag, the arrays are made immutable.

time_dependent_values

Immutable mapping from parameter names to Functions of time.

Methods

at_time	Return a new Mu instance with values for given time.
get
items
keys
to_numpy
values
with_	Returns a copy with changed attributes.

at_time(t)

Return a new Mu instance with values for given time.

This method evaluates all time_dependent_values for the given evaluation time t and returns a new Mu containing these values along with the other non-time-dependent values.

Parameters

t

Evaluation time for the time-dependent parameter values.

get(key, value=None)

items()

keys()

to_numpy()

values()

with_(new_type=None, **kwargs)

Returns a copy with changed attributes.

A a new class instance is created with the given keyword arguments as arguments for __init__. Missing arguments are obtained form instance attributes with the same name.

Parameters

new_type

If not None, return an instance of this class (instead of type(self)).

**kwargs

Names of attributes to change with their new values. Each attribute name has to be an argument to __init__.

Returns

Copy of self with changed attributes.

class pymor.parameters.base.ParameterSpace(parameters, *ranges, constraints=None)

Bases: ParametricObject

A set of Parameters with allowed ranges for their values.

ParameterSpaces are mostly used to create sample set of parameter values for given Parameters within a specified range.

parameters

The Parameters which are part of the space.

ranges

Allowed ranges for the parameter values. Either:

• two numbers specifying the lower and upper bound for all parameter value components,

• a list/tuple of two numbers specifying these bounds,

• or a dict of those tuples, specifying upper and lower bounds individually for each parameter of the space.

constraints

If not None, a function constraints(mu) -> bool defining additional (inequality) constraints on the space. For each given parameter values that lies within the given ranges, constraints is called to check if the constraints are satisfied.

Methods

clip	Clip (limit) parameter values to the space's parameter ranges.
contains
sample_logarithmic_randomly	Logarithmically scaled random sample parameter values from the space.
sample_logarithmic_uniformly	Logarithmically uniform sample parameter values from the space.
sample_randomly	Randomly sample parameter values from the space.
sample_uniformly	Uniformly sample parameter values from the space.

clip(mu, keep_additional=False)

Clip (limit) parameter values to the space’s parameter ranges.

Parameters

mu

Parameter value to clip.

keep_additional

If True, keep additional values in the Mu instance which are not contained in the parameters, e.g. time parameters.

Returns

The clipped parameter values.

contains(mu)

sample_logarithmic_randomly(count=None)

Logarithmically scaled random sample parameter values from the space.

Parameters

count

If None, a single dict mu of parameter values is returned. Otherwise, the number of logarithmically random samples to generate and return as a list of parameter values dicts.

Returns

The sampled parameter values.

sample_logarithmic_uniformly(counts)

Logarithmically uniform sample parameter values from the space.

In the case of additional constraints, the samples are generated w.r.t. the box constraints specified by ranges, but only those parameter values are returned, which satisfy the additional constraints.

Parameters

counts

Number of samples to take per parameter and component of the parameter. Either a dict of counts per Parameter or a single count that is taken for each parameter in Parameters.

Returns

List of parameter value dicts.

sample_randomly(count=None)

Randomly sample parameter values from the space.

Parameters

count

If None, a single dict mu of parameter values is returned. Otherwise, the number of random samples to generate and return as a list of parameter values dicts.

Returns

The sampled parameter values.

sample_uniformly(counts)

Uniformly sample parameter values from the space.

In the case of additional constraints, the samples are generated w.r.t. the box constraints specified by ranges, but only those parameter values are returned, which satisfy the additional constraints.

Parameters

counts

Number of samples to take per parameter and component of the parameter. Either a dict of counts per Parameter or a single count that is taken for each parameter in Parameters.

Returns

List of parameter value dicts.

class pymor.parameters.base.Parameters(*args, **kwargs)

Bases: pymor.tools.frozendict.SortedFrozenDict

Immutable dict mapping parameter names to parameter dimensions.

Each key of a Parameters dict is a string specifying the name of a parameter. The corresponding value is a non-negative int specifying the dimension (number of scalar components) of the parameter.

Methods

assert_compatible	Assert that parameter values are compatible with the given Parameters.
is_compatible	Check if parameter values are compatible with the given Parameters.
of	Computes the total set of Parameters a collection of objects depends on.
parse	Interpret mu as a set of parameter values according to the given Parameters.
space	Create a ParameterSpace with given ranges.
why_incompatible

assert_compatible(mu, allow_time_dependent=False)

Assert that parameter values are compatible with the given Parameters.

Each of the parameter must be contained in mu and the dimensions have to match, i.e.

mu[parameter].size == self[parameter]

Otherwise, an AssertionError will be raised.

Parameters

allow_time_dependent

If True, also the time-dependent parameter values stored in mu are taken into account. As these values are only usable when an evaluation time 't' is specified, code handling these values must be ‘time-aware’. Therefore, the default for this parameter is False, which means that time-dependent values are treated as non-existent.

is_compatible(mu, allow_time_dependent=False)

Check if parameter values are compatible with the given Parameters.

Each of the parameter must be contained in mu and the dimensions have to match, i.e.

mu[parameter].size == self[parameter]

Parameters

allow_time_dependent

If True, also the time-dependent parameter values stored in mu are taken into account. As these values are only usable when an evaluation time 't' is specified, code handling these values must be ‘time-aware’. Therefore, the default for this parameter is False, which means that time-dependent values are treated as non-existent.

classmethod of(*args)

Computes the total set of Parameters a collection of objects depends on.

If two objects depend on a parameter with the same name, both parameters must have the same dimension.

Parameters

args

Each positional argument must either be None, a ParametricObject or lists, tuples, dicts or NumPy arrays of such objects. The latter will be traversed recursively.

parse(mu)

Interpret mu as a set of parameter values according to the given Parameters.

Depending on the Parameters, mu can be given as a dict, list, tuple, NumPy array or scalar. In the latter cases, multiple parameters will be concatenated by alphabetical ordering. E.g.:

Parameters(b=2, a=1).parse([1,2,3])

will assign to parameter a the value [1] and to parameter b the values [2, 3]. Further, each parameter value can be given as a vector-valued Function with dim_domain == 1 to specify time-dependent values. A str is converted to an appropriate ExpressionFunction.

Parameters

mu

The user input which shall be interpreted as parameter values.

Returns

The resulting object of parameter values.

Raises

ValueError

Is raised if mu cannot be interpreted as parameter values for the given Parameters.

space(*ranges, constraints=None)

Create a ParameterSpace with given ranges.

This is a shorthand for

ParameterSpace(self, *range, constraints=constraints)

See ParameterSpace for allowed range and constraints arguments.

why_incompatible(mu, allow_time_dependent=False)

class pymor.parameters.base.ParametricObject

Bases: pymor.core.base.ImmutableObject

Base class for immutable mathematical entities depending on some Parameters.

Each ParametricObject lists the Parameters it depends on in the parameters attribute. Usually, these Parameters are automatically derived as the union of all Parameters of the object’s __init__ arguments.

Additional Parameters introduced by the object itself can be specified by setting the parameters_own attribute in __init__. In case the object fixes some Parameters it’s child objects depend on to concrete values, those Parameters can be removed from the parameters attribute by setting parameters_internal.

Alternatively, parameters can be initialized manually in __init__.

parameters

The Parameters the object depends on.

parameters_own

The Parameters the object depends on which are not inherited from a child object the object depends on. Each item of parameters_own is also an item of parameters.

parameters_inherited

The Parameters the object depends on because some child object depends on them. Each item of parameters_inherited is also an item of parameters.

parameters_internal

The Parameters some of the object’s child objects may depend on, but which are fixed to a concrete value by this object. All items of parameters_internal are removed from parameters and parameters_inherited. When initializing parameters_own and parameters_internal, it has to be ensured that both dicts are disjoint.

parametric

True if the object really depends on a parameter, i.e. parameters is not empty.