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.tools.frozendict.FrozenDict

Immutable mapping of Parameter names to parameter 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.

parameters

The Parameters to which the mapping assigns values.

Methods

allclose	Compare dicts of parameter values using float_cmp_all.
copy	D.copy() -> a shallow copy of D
get_time_dependent_value	Return time-dependent Function for given parameter.
is_time_dependent	Check whether the values for a given parameter depend on time.
to_numpy	All parameter values as a NumPy array, ordered alphabetically.
with_

allclose(mu)

Compare dicts of parameter values using float_cmp_all.

Parameters

mu

The parameter values with which to compare.

Returns

True if both parameter value dicts contain values for the same Parameters and all components of the parameter values are almost equal, else False.

copy()

D.copy() -> a shallow copy of D

get_time_dependent_value(param)

Return time-dependent Function for given parameter.

Parameters

param

The parameter for which to return the time-dependent values.

Returns

If param depends on time, this corresponding Function (and not its evaluation at the current time) is returned. If param is not given by a Function, a ConstantFunction is returned.

is_time_dependent(param)

Check whether the values for a given parameter depend on time.

This is the case when the value for self[param] was given by a Function instead of a constant array.

to_numpy()

All parameter values as a NumPy array, ordered alphabetically.

with_(**kwargs)

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)

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.

is_compatible(mu)

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]

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)

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.