pymor.parameters package

Submodules

base module

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

A Parameter in pyMOR is basically a dict of NumPy arrays. Each item of the dict is called a parameter component. The ParameterType of a Parameter is the dict of the shapes of the parameter components, i.e.

mu.parameter_type['component'] == mu['component'].shape

Classes which represent mathematical objects depending on parameters, e.g. Functions, Operators, Models derive from the Parametric mixin. Each Parametric object has a parameter_type attribute holding the ParameterType of the Parameters the object’s evaluate, apply, solve, etc. methods expect. Note that the ParameterType of the given Parameter is allowed to be a superset of the object’s ParameterType.

The ParameterType of a Parametric object is determined in its __init__ method by calling build_parameter_type which computes the ParameterType as the union of the ParameterTypes of the objects given to the method. This way, e.g., an Operator can inherit the ParameterTypes of the data functions it depends upon.

A Parametric object can have a ParameterSpace assigned to it by setting the parameter_space attribute (the ParameterType of the space has to agree with the ParameterType of the object). The parse_parameter method parses a user input according to the object’s ParameterType to make it a Parameter (e.g. if the ParameterType consists of a single one-dimensional component, the user can simply supply a list of numbers of the right length). Moreover, when given a Parameter, parse_parameter ensures the Parameter has an appropriate ParameterType.

---

class pymor.parameters.base.Parameter(v)

Bases: dict

Class representing a parameter.

A Parameter is simply a dict where each key is a string and each value is a NumPy array. We call an item of the dictionary a parameter component.

A Parameter differs from an ordinary dict in the following ways:

• It is ensured that each value is a NumPy array.

• We overwrite copy to ensure that not only the dict but also the NumPy arrays are copied.

• The allclose method allows to compare Parameters for equality in a mathematically meaningful way.

• Each Parameter has a sid property providing a unique state id.

• We override __str__ to ensure alphanumerical ordering of the keys and pretty printing of the values.

• The parameter_type property can be used to obtain the ParameterType of the parameter.

• Use from_parameter_type to construct a Parameter from a ParameterType and user supplied input.

Parameters

v

Anything that dict accepts for the construction of a dictionary.

Methods

Parameter	allclose, clear, copy, from_parameter_type, fromkeys, pop, popitem, update
dict	get, items, keys, setdefault, values, __contains__, __getitem__, __new__, __sizeof__

Attributes

Parameter

parameter_type, sid

parameter_type

The ParameterType of the Parameter.

sid

The state id of the Parameter.

__delitem__(key)

Delete self[key].

__eq__(mu)

Return self==value.

__setitem__(key, value)

Set self[key] to value.

__str__()

Return str(self).

allclose(mu)

Compare two Parameters using float_cmp_all.

Parameters

mu

The Parameter with which to compare.

Returns

True if both Parameters have the same ParameterType and all parameter components are almost equal, else False.

clear() → None. Remove all items from D.

copy() → a shallow copy of D

classmethod from_parameter_type(mu, parameter_type=None)

Takes a user input mu and interprets it as a Parameter according to the given ParameterType.

Depending on the ParameterType, mu can be given as a Parameter, dict, tuple, list, array or scalar.

Parameters

mu

The user input which shall be interpreted as a Parameter.

parameter_type

The ParameterType w.r.t. which mu is to be interpreted.

Returns

The resulting Parameter.

Raises

ValueError

Is raised if mu cannot be interpreted as a Parameter of ParameterType parameter_type.

fromkeys(S, v=None)

Create a new dictionary with keys from iterable and values set to value.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

update([E, ]**F) → None. Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

---

class pymor.parameters.base.ParameterType(t)

Bases: collections.OrderedDict

Class representing a parameter type.

A parameter type is simply a dictionary with strings as keys and tuples of natural numbers as values. The keys are the names of the parameter components and the tuples their expected shape (compare Parameter).

Apart from checking the correct format of its values, the only difference between a ParameterType and an ordinary dict is, that ParameterType orders its keys alphabetically.

Parameters

t

If t is an object with a parameter_type attribute, a copy of this ParameterType is created. Otherwise, t can be anything from which a dict can be constructed.

Methods

ParameterType	copy, fromkeys
OrderedDict	clear, items, keys, move_to_end, pop, popitem, setdefault, update, values, __reversed__
dict	get, __contains__, __getitem__, __new__

Attributes

ParameterType

sid

__hash__()

Return hash(self).

__reduce__()

Return state information for pickling

__repr__()

Return repr(self).

__str__()

Return str(self).

copy() → a shallow copy of od

fromkeys(S, v=None)

Create a new ordered dictionary with keys from iterable and values set to value.

---

class pymor.parameters.base.Parametric

Bases: object

Mixin class for objects representing mathematical entities depending on a Parameter.

Each such object has a ParameterType stored in the parameter_type attribute, which should be set by the implementor during __init__ using the build_parameter_type method. Methods expecting the Parameter (typically evaluate, apply, solve, etc. ..) should accept an optional argument mu defaulting to None. This argument mu should then be fed into parse_parameter to obtain a Parameter of correct ParameterType from the (user supplied) input mu.

Methods

Parametric

build_parameter_type, parse_parameter, strip_parameter

Attributes

Parametric

parameter_space, parameter_type, parametric

parameter_type

The ParameterType of the Parameters the object expects.

parameter_space

ParameterSpace the parameters are expected to lie in or None.

parametric

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

build_parameter_type(*args, provides=None, **kwargs)

Builds the ParameterType of the object. Should be called by __init__.

The ParameterType of a Parametric object is determined by the parameter components the object itself requires for evaluation, and by the parameter components required by the objects the object depends upon for evaluation.

All parameter components (directly specified or inherited by the ParameterType of a given Parametric object) with the same name are treated as identical and are thus required to have the same shapes. The object’s ParameterType is then made up by the shapes of all parameter components appearing.

Additionally components of the resulting ParameterType can be removed by specifying them via the provides parameter. The idea is that the object itself may provide parameter components to the inherited objects which thus should not become part of the object’s own parameter type. (A typical application would be InstationaryModel, which provides a time parameter component to its (time-dependent) operators during time-stepping.)

Parameters

args

Each positional argument must either be a dict of parameter components and shapes or a Parametric object whose parameter_type is added.

kwargs

Each keyword argument is interpreted as parameter component with corresponding shape.

provides

Dict of parameter component names and shapes which are provided by the object itself. The parameter components listed here will not become part of the object’s ParameterType.

parse_parameter(mu)

Interpret a user supplied parameter mu as a Parameter.

If mu is not already a Parameter, Parameter.from_parameter_type is used, to make mu a parameter of the correct ParameterType. If mu is already a Parameter, it is checked if its ParameterType matches our own. (It is actually allowed that the ParameterType of mu is a superset of our own ParameterType in the obvious sense.)

Parameters

mu

The input to parse as a Parameter.

strip_parameter(mu)

Remove all components of the Parameter mu which are not part of the object’s ParameterType.

Otherwise strip_parameter behaves like parse_parameter.

This method is mainly useful for caching where the key should only contain the relevant parameter components.

functionals module

---

class pymor.parameters.functionals.ConjugateParameterFunctional(functional, name=None)

Bases: pymor.parameters.interfaces.ParameterFunctionalInterface

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	d_mu, evaluate
ImmutableInterface	generate_sid, with_, __setattr__
BasicInterface	disable_logging, enable_logging, has_interface_name, implementor_names, implementors
Parametric	build_parameter_type, parse_parameter, strip_parameter

Attributes

ImmutableInterface	sid, sid_ignore
BasicInterface	logger, logging_disabled, name, uid
Parametric	parameter_space, parameter_type, parametric

d_mu(component, index=())

Return the functionals’s derivative with respect to an index of a parameter component.

Parameters

component

Parameter component

index

index in the parameter component

Returns

New Parameter functional representing the partial derivative.

evaluate(mu=None)

Evaluate the functional for the given Parameter mu.

---

class pymor.parameters.functionals.ConstantParameterFunctional(constant_value, name=None)

Bases: pymor.parameters.interfaces.ParameterFunctionalInterface

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
ImmutableInterface	generate_sid, with_, __setattr__
BasicInterface	disable_logging, enable_logging, has_interface_name, implementor_names, implementors
Parametric	build_parameter_type, parse_parameter, strip_parameter

Attributes

ImmutableInterface	sid, sid_ignore
BasicInterface	logger, logging_disabled, name, uid
Parametric	parameter_space, parameter_type, parametric

d_mu(component, index=())

Return the functionals’s derivative with respect to an index of a parameter component.

Parameters

component

Parameter component

index

index in the parameter component

Returns

New Parameter functional representing the partial derivative.

evaluate(mu=None)

Evaluate the functional for the given Parameter mu.

---

class pymor.parameters.functionals.ExpressionParameterFunctional(expression, parameter_type, name=None, derivative_expressions=None)

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

parameter_type

The ParameterType of the Parameters the functional expects.

name

The name of the functional.

derivative_expressions

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

Methods

GenericParameterFunctional	d_mu, evaluate
ImmutableInterface	generate_sid, with_, __setattr__
BasicInterface	disable_logging, enable_logging, has_interface_name, implementor_names, implementors
Parametric	build_parameter_type, parse_parameter, strip_parameter

Attributes

ExpressionParameterFunctional	functions
ImmutableInterface	sid, sid_ignore
BasicInterface	logger, logging_disabled, name, uid
Parametric	parameter_space, parameter_type, parametric

__reduce__()

Helper for pickle.

---

class pymor.parameters.functionals.GenericParameterFunctional(mapping, parameter_type, name=None, derivative_mappings=None)

Bases: pymor.parameters.interfaces.ParameterFunctionalInterface

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

parameter_type

The ParameterType of the Parameters the functional expects.

name

The name of the functional.

derivative_mappings

A dict containing all partial derivatives of each component and index in the ParameterType with the signature derivative_mappings[component][index](mu)

Methods

GenericParameterFunctional	d_mu, evaluate
ImmutableInterface	generate_sid, with_, __setattr__
BasicInterface	disable_logging, enable_logging, has_interface_name, implementor_names, implementors
Parametric	build_parameter_type, parse_parameter, strip_parameter

Attributes

ImmutableInterface	sid, sid_ignore
BasicInterface	logger, logging_disabled, name, uid
Parametric	parameter_space, parameter_type, parametric

d_mu(component, index=())

Return the functionals’s derivative with respect to an index of a parameter component.

Parameters

component

Parameter component

index

index in the parameter component

Returns

New Parameter functional representing the partial derivative.

evaluate(mu=None)

Evaluate the functional for the given Parameter mu.

---

class pymor.parameters.functionals.ProductParameterFunctional(factors, name=None)

Bases: pymor.parameters.interfaces.ParameterFunctionalInterface

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
ImmutableInterface	generate_sid, with_, __setattr__
BasicInterface	disable_logging, enable_logging, has_interface_name, implementor_names, implementors
Parametric	build_parameter_type, parse_parameter, strip_parameter

Attributes

ImmutableInterface	sid, sid_ignore
BasicInterface	logger, logging_disabled, name, uid
Parametric	parameter_space, parameter_type, parametric

d_mu(component, index=())

Return the functionals’s derivative with respect to an index of a parameter component.

Parameters

component

Parameter component

index

index in the parameter component

Returns

New Parameter functional representing the partial derivative.

evaluate(mu=None)

Evaluate the functional for the given Parameter mu.

---

class pymor.parameters.functionals.ProjectionParameterFunctional(component_name, component_shape, index=(), name=None)

Bases: pymor.parameters.interfaces.ParameterFunctionalInterface

ParameterFunctional returning a component of the given parameter.

For given parameter mu, this functional evaluates to

mu[component_name][index]

Parameters

component_name

The name of the parameter component to return.

component_shape

The shape of the parameter component.

index

See above.

name

Name of the functional.

Methods

ProjectionParameterFunctional	d_mu, evaluate
ImmutableInterface	generate_sid, with_, __setattr__
BasicInterface	disable_logging, enable_logging, has_interface_name, implementor_names, implementors
Parametric	build_parameter_type, parse_parameter, strip_parameter

Attributes

ImmutableInterface	sid, sid_ignore
BasicInterface	logger, logging_disabled, name, uid
Parametric	parameter_space, parameter_type, parametric

d_mu(component, index=())

Return the functionals’s derivative with respect to an index of a parameter component.

Parameters

component

Parameter component

index

index in the parameter component

Returns

New Parameter functional representing the partial derivative.

evaluate(mu=None)

Evaluate the functional for the given Parameter mu.

interfaces module

---

class pymor.parameters.interfaces.ParameterFunctionalInterface

Bases: pymor.core.interfaces.ImmutableInterface, pymor.parameters.base.Parametric

Interface for Parameter functionals.

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

Methods

ParameterFunctionalInterface	d_mu, evaluate
ImmutableInterface	generate_sid, with_, __setattr__
BasicInterface	disable_logging, enable_logging, has_interface_name, implementor_names, implementors
Parametric	build_parameter_type, parse_parameter, strip_parameter

Attributes

ImmutableInterface	sid, sid_ignore
BasicInterface	logger, logging_disabled, name, uid
Parametric	parameter_space, parameter_type, parametric

__call__(mu=None)

Call self as a function.

abstract d_mu(component, index=())

Return the functionals’s derivative with respect to an index of a parameter component.

Parameters

component

Parameter component

index

index in the parameter component

Returns

New Parameter functional representing the partial derivative.

abstract evaluate(mu=None)

Evaluate the functional for the given Parameter mu.

---

class pymor.parameters.interfaces.ParameterSpaceInterface

Bases: pymor.core.interfaces.ImmutableInterface

Interface for Parameter spaces.

Methods

ParameterSpaceInterface	contains
ImmutableInterface	generate_sid, with_, __setattr__
BasicInterface	disable_logging, enable_logging, has_interface_name, implementor_names, implementors

Attributes

ParameterSpaceInterface	parameter_type
ImmutableInterface	sid, sid_ignore
BasicInterface	logger, logging_disabled, name, uid

parameter_type

ParameterType of the space.

abstract contains(mu)

True if mu is contained in the space.

spaces module

---

class pymor.parameters.spaces.CubicParameterSpace(parameter_type, minimum=None, maximum=None, ranges=None)

Bases: pymor.parameters.interfaces.ParameterSpaceInterface

Simple ParameterSpace where each summand is an n-cube.

Parameters

parameter_type

The ParameterType of the space.

minimum

The minimum for each matrix entry of each Parameter component. Must be None if ranges is specified.

maximum

The maximum for each matrix entry of each Parameter component. Must be None if ranges is specified.

ranges

dict whose keys agree with parameter_type and whose values are tuples (min, max) specifying the minimum and maximum of each matrix entry of corresponding Parameter component. Must be None if minimum and maximum are specified.

Methods

CubicParameterSpace	contains, parse_parameter, sample_randomly, sample_uniformly
ImmutableInterface	generate_sid, with_, __setattr__
BasicInterface	disable_logging, enable_logging, has_interface_name, implementor_names, implementors

Attributes

ParameterSpaceInterface	parameter_type
ImmutableInterface	sid, sid_ignore
BasicInterface	logger, logging_disabled, name, uid

__str__()

Return str(self).

contains(mu)

True if mu is contained in the space.

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

Randomly sample Parameters from the space.

Parameters

count

None or number of random parameters (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 radom state with this seed is used.

Returns

If count is None, an inexhaustible iterator returning random Parameters. Otherwise a list of count random Parameters.

sample_uniformly(counts)

Uniformly sample Parameters from the space.