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, Discretizations 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)[source]

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:

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.

allclose(mu)[source]

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.

classmethod from_parameter_type(mu, parameter_type=None)[source]

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.
class pymor.parameters.base.ParameterType(t)[source]

Bases: dict

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 clear, copy, fromkeys, pop, popitem, update
dict get, items, keys, setdefault, values, __contains__, __getitem__, __new__, __sizeof__

Attributes

ParameterType sid
class pymor.parameters.base.Parametric[source]

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)[source]

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 InstationaryDiscretization, which provides a time parameter component to its (time-dependent) operators during time-stepping.)

Parameters

args
Each positional argument must eihter 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)[source]

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)[source]

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.ExpressionParameterFunctional(expression, parameter_type, name=None)[source]

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.

Methods

GenericParameterFunctional 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 add_with_arguments, sid, sid_ignore, with_arguments
BasicInterface logger, logging_disabled, name, uid
Parametric parameter_space, parameter_type, parametric
class pymor.parameters.functionals.GenericParameterFunctional(mapping, parameter_type, name=None)[source]

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

parameter_type
The ParameterType of the Parameters the functional expects.
mapping
The function to wrap. The function has signature mapping(mu).
name
The name of the functional.

Methods

GenericParameterFunctional 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 add_with_arguments, sid, sid_ignore, with_arguments
BasicInterface logger, logging_disabled, name, uid
Parametric parameter_space, parameter_type, parametric
class pymor.parameters.functionals.ProductParameterFunctional(factors, name=None)[source]

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 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 add_with_arguments, sid, sid_ignore, with_arguments
BasicInterface logger, logging_disabled, name, uid
Parametric parameter_space, parameter_type, parametric
class pymor.parameters.functionals.ProjectionParameterFunctional(component_name, component_shape, coordinates=(), name=None)[source]

Bases: pymor.parameters.interfaces.ParameterFunctionalInterface

ParameterFunctional returning a component of the given parameter.

For given parameter mu, this functional evaluates to

mu[component_name][coordinates]

Parameters

component_name
The name of the parameter component to return.
component_shape
The shape of the parameter component.
coordinates
See above.
name
Name of the functional.

Methods

ProjectionParameterFunctional 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 add_with_arguments, sid, sid_ignore, with_arguments
BasicInterface logger, logging_disabled, name, uid
Parametric parameter_space, parameter_type, parametric

spaces module

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

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 add_with_arguments, sid, sid_ignore, with_arguments
BasicInterface logger, logging_disabled, name, uid
sample_randomly(count=None, random_state=None, seed=None)[source]

Randomly sample Parameters from the space.

Warning

When neither random_state nor seed are specified, repeated calls to this method will return the same sequence of parameters!

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.
seed
Random seed to use. If None, the default random seed is used.

Returns

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

sample_uniformly(counts)[source]

Uniformly sample Parameters from the space.