pymor.parameters package

Submodules

base module

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.

---

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

Bases: pymor.tools.frozendict.SortedFrozenDict

Immutable mapping of Parameter names to parameter values.

Parameters

Anything that dict accepts for the construction of a dictionary. Values are automatically converted to immutable one-dimensional NumPy arrays, unless the Python interpreter runs with the -O flag.

Methods

Mu	allclose, copy, to_numpy, with_
dict	fromkeys, get, items, keys, values, __contains__, __getitem__, __sizeof__

Attributes

Mu	parameters
FrozenDict	clear, pop, popitem, setdefault, update

parameters

The Parameters to which the mapping assigns values.

__eq__(mu)

Return self==value.

static __new__(cls, *args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

__repr__()

Return repr(self).

__str__()

Return str(self).

allclose(mu)

Compare two 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() → a shallow copy of D

to_numpy()

All parameter values as a NumPy array, ordered alphabetically.

---

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

Bases: pymor.parameters.base.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

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.

Methods

ParameterSpace	contains, sample_randomly, sample_uniformly
ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

sample_randomly(count=None, random_state=None, seed=None)

Randomly sample parameter values from the space.

Parameters

count

None or number of random samples (see below).

random_state

RandomState to use for sampling. If None, a new random state is generated using seed as random seed, or the default random state is used.

seed

If not None, a new random state with this seed is used.

Returns

If count is None, an inexhaustible iterator returning random parameter value dicts. Otherwise a list of count random parameter value dicts.

sample_uniformly(counts)

Uniformly sample parameter values from the space.

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

Parameters	assert_compatible, is_compatible, of, parse, space, why_incompatible, __le__
dict	copy, fromkeys, get, items, keys, values, __contains__, __getitem__, __sizeof__

Attributes

Parameters	dim
FrozenDict	clear, pop, popitem, setdefault, update

__hash__()

Return hash(self).

__le__(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]

__repr__()

Return repr(self).

__str__()

Return str(self).

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.

property dim

The sum of the dimensions of all parameters.

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)

Takes a user input mu and interprets it as 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].

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)

Create a ParameterSpace with given ranges.

This is a shorthand for

ParameterSpace(self, *range)

See ParameterSpace for allowed range arguments.

---

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

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__.

Methods

ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

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_own 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.

functionals module

---

class pymor.parameters.functionals.BaseMaxThetaParameterFunctional(*args, **kwargs)

Bases: pymor.parameters.functionals.ParameterFunctional

ParameterFunctional implementing a generalization of the max-theta approach from [Haa17] (Exercise 5.12).

Let V denote a Hilbert space and let a: V x V -> K denote a continuous bilinear form or l: V -> K a continuous linear functional, either with affine decomposition

a(u, v, mu) = sum_{q = 1}^Q theta_q(mu) a_q(u, v)  or  l(v, mu) = sum_{q = 1}^Q theta_q(mu) l_q(v)

for Q coefficient ParameterFunctional theta_1, …, theta_Q and continuous bilinear forms a_1, …, a_Q: V x V -> K or continuous linear functionals l_q: V -> K. Let mu_bar be a parameter with respect to which the continuity constant of a(., ., mu_bar) or l(., mu_bar) is known, i.e. we known gamma_mu_bar > 0, s.t.

a(u, v, mu_bar) <= gamma_mu_bar |u|_V |v|_V  or  l(v, mu_bar) <= gamma_mu_bar |v|_V.

The max-theta approach (in its generalized form) from [Haa17] (Exercise 5.12) allows to obtain a computable bound for the continuity constant of another bilinear form a_prime(., ., mu) or linear form l_prime(., mu) with the same affine decomposition but different theta_prime_q for arbitrary parameters mu, since

a_prime(u, v, mu=mu) <= |max_{q = 1}^Q theta_prime_q(mu)/theta_q(mu_bar)|  |a(u, v, mu=mu_bar)|

or

l_prime(v, mu=mu) <= |max_{q = 1}^Q theta_prime_q(mu)/theta_q(mu_bar)| |l(v, mu=mu_bar)|,

if all theta_q(mu_bar) != 0.

Given a list of the thetas, the parameter values mu_bar and the constant gamma_mu_bar, this functional thus evaluates to

|gamma_mu_bar * max_{q = 1}^Q theta_prime_q(mu)/theta_q(mu_bar)|

Note that we also get an upper bound if theta_prime_q(mu) == 0 for any q. However, if theta_prime_q(mu) == 0 for at least one q, we need to use the absolute value in the denominator, i.e.

|gamma_mu_bar * max_{q = 1}^Q theta_prime_q(mu)/|theta_q(mu_bar)| |

Parameters

thetas

List or tuple of ParameterFunctional of the base bilinear form a which is used for estimation.

thetas_prime

List or tuple of ParameterFunctional of the bilinear form a_prime for the numerator of the MaxThetaParameterFunctional.

mu_bar

Parameter associated with gamma_mu_bar.

gamma_mu_bar

Known continuity constant of the base bilinear form a.

name

Name of the functional.

Methods

BaseMaxThetaParameterFunctional	d_mu, evaluate
ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

d_mu(component, index=())

Return the functionals’s derivative with respect to a given parameter.

Parameters

parameter

The Parameter w.r.t. which to return the derivative.

index

Index of the Parameter’s component w.r.t which to return the derivative.

Returns

New ParameterFunctional representing the partial derivative.

evaluate(mu=None)

Evaluate the functional for given parameter values mu.

---

class pymor.parameters.functionals.ConjugateParameterFunctional(*args, **kwargs)

Bases: pymor.parameters.functionals.ParameterFunctional

Conjugate of a given ParameterFunctional

Evaluates a given ParameterFunctional and returns the complex conjugate of the value.

Parameters

functional

The ParameterFunctional of which the complex conjuate is taken.

name

Name of the functional.

Methods

ConjugateParameterFunctional	evaluate
ParameterFunctional	d_mu
ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

evaluate(mu=None)

Evaluate the functional for given parameter values mu.

---

class pymor.parameters.functionals.ConstantParameterFunctional(*args, **kwargs)

Bases: pymor.parameters.functionals.ParameterFunctional

ParameterFunctional returning a constant value for each parameter.

Parameters

constant_value

value of the functional

name

Name of the functional.

Methods

ConstantParameterFunctional	d_mu, evaluate
ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

d_mu(parameter, index=0)

Return the functionals’s derivative with respect to a given parameter.

Parameters

parameter

The Parameter w.r.t. which to return the derivative.

index

Index of the Parameter’s component w.r.t which to return the derivative.

Returns

New ParameterFunctional representing the partial derivative.

evaluate(mu=None)

Evaluate the functional for given parameter values mu.

---

class pymor.parameters.functionals.ExpressionParameterFunctional(*args, **kwargs)

Bases: pymor.parameters.functionals.GenericParameterFunctional

Turns a Python expression given as a string into a ParameterFunctional.

Some NumPy arithmetic functions like sin, log, min are supported. For a full list see the functions class attribute.

Warning

eval is used to evaluate the given expression. Using this class with expression strings from untrusted sources will cause mayhem and destruction!

Parameters

expression

A Python expression in the parameter components of the given parameters.

parameters

The Parameters the functional depends on.

name

The name of the functional.

derivative_expressions

A dict containing a Python expression for the partial derivatives of each parameter component.

second_derivative_expressions

A dict containing a list of dicts of Python expressions for all second order partial derivatives of each parameter component i and j.

Methods

GenericParameterFunctional	d_mu, evaluate
ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

ExpressionParameterFunctional	functions
ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

__reduce__()

Helper for pickle.

---

class pymor.parameters.functionals.GenericParameterFunctional(*args, **kwargs)

Bases: pymor.parameters.functionals.ParameterFunctional

A wrapper making an arbitrary Python function a ParameterFunctional

Note that a GenericParameterFunctional can only be pickled if the function it is wrapping can be pickled. For this reason, it is usually preferable to use ExpressionParameterFunctional instead of GenericParameterFunctional.

Parameters

mapping

The function to wrap. The function has signature mapping(mu).

parameters

The Parameters the functional depends on.

name

The name of the functional.

derivative_mappings

A dict containing all partial derivatives of each Parameter and index with the signature derivative_mappings[parameter][index](mu)

second_derivative_mappings

A dict containing all second order partial derivatives of each Parameter and index with the signature second_derivative_mappings[parameter_i][index_i][parameter_j][index_j](mu)

Methods

GenericParameterFunctional	d_mu, evaluate
ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

d_mu(parameter, index=0)

Return the functionals’s derivative with respect to a given parameter.

Parameters

parameter

The Parameter w.r.t. which to return the derivative.

index

Index of the Parameter’s component w.r.t which to return the derivative.

Returns

New ParameterFunctional representing the partial derivative.

evaluate(mu=None)

Evaluate the functional for given parameter values mu.

---

class pymor.parameters.functionals.LincombParameterFunctional(*args, **kwargs)

Bases: pymor.parameters.functionals.ParameterFunctional

A ParameterFunctional representing a linear combination of ParameterFunctionals.

The coefficients must be provided as scalars.

Parameters

functionals

List of ParameterFunctionals whose linear combination is formed.

coefficients

A list of scalar coefficients.

name

Name of the functional.

Methods

LincombParameterFunctional	d_mu, evaluate
ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

LincombParameterFunctional	coefficients, functionals
ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

functionals

coefficients

d_mu(parameter, index=0)

Return the functionals’s derivative with respect to a given parameter.

Parameters

parameter

The Parameter w.r.t. which to return the derivative.

index

Index of the Parameter’s component w.r.t which to return the derivative.

Returns

New ParameterFunctional representing the partial derivative.

evaluate(mu=None)

Evaluate the functional for given parameter values mu.

---

class pymor.parameters.functionals.MaxThetaParameterFunctional(*args, **kwargs)

Bases: pymor.parameters.functionals.BaseMaxThetaParameterFunctional

ParameterFunctional implementing the max-theta approach from [Haa17] (Exercise 5.12).

This is a specialized version of BaseMaxThetaParameterFunctional which allows to obtain a computable bound for the continuity constant of the actual a(., ., mu) or l(., mu) for arbitrary parameters mu, since

a(u, v, mu=mu) <= |max_{q = 1}^Q theta_q(mu)/theta_q(mu_bar)|  |a(u, v, mu=mu_bar)|

or

l(v, mu=mu) <= |max_{q = 1}^Q theta_q(mu)/theta_q(mu_bar)| |l(v, mu=mu_bar)|,

if all theta_q(mu_bar) != 0.

Given a list of the thetas, the parameter values mu_bar and the constant gamma_mu_bar, this functional thus evaluates to

|gamma_mu_bar * max{q = 1}^Q theta_q(mu)/theta_q(mu_bar)|

Parameters

thetas

List or tuple of ParameterFunctional

mu_bar

Parameter associated with gamma_mu_bar.

gamma_mu_bar

Known continuity constant.

name

Name of the functional.

Methods

BaseMaxThetaParameterFunctional	d_mu, evaluate
ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

---

class pymor.parameters.functionals.MinThetaParameterFunctional(*args, **kwargs)

Bases: pymor.parameters.functionals.ParameterFunctional

ParameterFunctional implementing the min-theta approach from [Haa17] (Proposition 2.35).

Let V denote a Hilbert space and let a: V x V -> K denote a parametric coercive bilinear form with affine decomposition

a(u, v, mu) = sum_{q = 1}^Q theta_q(mu) a_q(u, v),

for Q positive coefficient ParameterFunctional theta_1, …, theta_Q and positive semi-definite component bilinear forms a_1, …, a_Q: V x V -> K. Let mu_bar be a parameter with respect to which the coercivity constant of a(., ., mu_bar) is known, i.e. we known alpha_mu_bar > 0, s.t.

alpha_mu_bar |u|_V^2 <= a(u, u, mu=mu_bar).

The min-theta approach from [Haa17] (Proposition 2.35) allows to obtain a computable bound for the coercivity constant of a(., ., mu) for arbitrary parameters mu, since

a(u, u, mu=mu) >= min_{q = 1}^Q theta_q(mu)/theta_q(mu_bar) a(u, u, mu=mu_bar).

Given a list of the thetas, the parameter values mu_bar and the constant alpha_mu_bar, this functional thus evaluates to

alpha_mu_bar * min_{q = 1}^Q theta_q(mu)/theta_q(mu_bar)

Parameters

thetas

List or tuple of ParameterFunctional

mu_bar

Parameter associated with alpha_mu_bar.

alpha_mu_bar

Known coercivity constant.

name

Name of the functional.

Methods

MinThetaParameterFunctional	evaluate
ParameterFunctional	d_mu
ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

evaluate(mu=None)

Evaluate the functional for given parameter values mu.

---

class pymor.parameters.functionals.ParameterFunctional(*args, **kwargs)

Bases: pymor.parameters.base.ParametricObject

Interface for Parameter functionals.

A parameter functional is simply a function mapping Parameters to a number.

Methods

ParameterFunctional	d_mu, evaluate
ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

__call__(mu=None)

Call self as a function.

d_mu(parameter, index=0)

Return the functionals’s derivative with respect to a given parameter.

Parameters

parameter

The Parameter w.r.t. which to return the derivative.

index

Index of the Parameter’s component w.r.t which to return the derivative.

Returns

New ParameterFunctional representing the partial derivative.

abstract evaluate(mu=None)

Evaluate the functional for given parameter values mu.

---

class pymor.parameters.functionals.ProductParameterFunctional(*args, **kwargs)

Bases: pymor.parameters.functionals.ParameterFunctional

Forms the product of a list of ParameterFunctionals or numbers.

Parameters

factors

A list of ParameterFunctionals or numbers.

name

Name of the functional.

Methods

ProductParameterFunctional	d_mu, evaluate
ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

d_mu(parameter, index=0)

Return the functionals’s derivative with respect to a given parameter.

Parameters

parameter

The Parameter w.r.t. which to return the derivative.

index

Index of the Parameter’s component w.r.t which to return the derivative.

Returns

New ParameterFunctional representing the partial derivative.

evaluate(mu=None)

Evaluate the functional for given parameter values mu.

---

class pymor.parameters.functionals.ProjectionParameterFunctional(*args, **kwargs)

Bases: pymor.parameters.functionals.ParameterFunctional

ParameterFunctional returning a component value of the given parameter.

For given parameter map mu, this functional evaluates to

mu[parameter][index]

Parameters

parameter

The name of the parameter to return.

size

The size of the parameter.

index

See above.

name

Name of the functional.

Methods

ProjectionParameterFunctional	d_mu, evaluate
ImmutableObject	with_, __setattr__
BasicObject	disable_logging, enable_logging

Attributes

ParametricObject	parameters, parameters_inherited, parameters_internal, parameters_own, parametric
BasicObject	logger, logging_disabled, name, uid

d_mu(parameter, index=0)

Return the functionals’s derivative with respect to a given parameter.

Parameters

parameter

The Parameter w.r.t. which to return the derivative.

index

Index of the Parameter’s component w.r.t which to return the derivative.

Returns

New ParameterFunctional representing the partial derivative.

evaluate(mu=None)

Evaluate the functional for given parameter values mu.