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. The local_parameter method is used to extract the local parameter components of the given Parameter and performs some name mapping (see the documentation of build_parameter_type for details).


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.
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, items, iteritems, iterkeys, itervalues, keys, pop, popitem, update, values
dict get, has_key, setdefault, viewitems, viewkeys, viewvalues, __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. The local parameter components (see build_parameter_type) can be extracted using local_type.

parameter_type

The ParameterType of the Parameters the object expects.

parameter_local_type

The ParameterType of the parameter components which are introduced by the object itself and are not inherited by other objects it depends on. (See build_parameter_type.)

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(local_type=None, global_names=None, local_global=False, inherits=None, provides=None)[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. We speak of local and inherited parameter components. The ParameterType of the local parameter components are provided via the local_type parameter, whereas the Parametric objects from which parameter components are inherited are provided as the inherits parameter.

Since the implementor does not necessarily know the future use of the object, a mapping between the names of the local parameter components and their intended global names (from the user perspective) can be provided via the global_names parameter. This mapping of names will be usually provided by the user when instantiating the class. (E.g. a Function evaluating x->x^a could depend on a local parameter component named ‘base’, whereas the user wishes to name the component ‘decay_rate’.) If such a mapping is not desired, the local_global parameter must be set to True. (To later extract the local parameter components with their local names from a given Parameter use the local_parameter method.)

After the name mapping, all parameter components (local or inherited by one of the objects provided via inherits) 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 dict. 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.)

Note

As parameter components of the ParameterTypes of different objects are treated as equal if they have the same name, renaming a local parameter component is not merely a convenience feature but can also have a semantic meaning by identifying local parameter components with inherited ones.

Parameters

local_type
ParameterType of the local parameter components.
global_names
A dict of the form {'localname': 'globalname', ...} defining a name mapping specifying global parameter component names for each key of local_type. If None and local_type is not None, local_global must be set to True.
local_global
If True, treat the names of the local parameter components as global names of these components. In this case, global_names must be None.
inherits
Iterable where each entry is a Parametric object whose ParameterType shall become part of the built ParameterType.
provides
Dict of parameter component names and their shapes which are provided by the object itself to the objects in the inherited list. The parameter components listed here will not become part of the object’s ParameterType.
local_parameter(mu)[source]

Extract the local parameter components with their local names from a given Parameter.

See build_parameter_type for details.

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

helper for pickle

__repr__() <==> repr(x)[source]

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.
evaluate(mu=None)[source]

Evaluate the functional for the given Parameter mu.


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.
evaluate(mu=None)[source]

Evaluate the functional for the given Parameter mu.


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.
evaluate(mu=None)[source]

Evaluate the functional for the given Parameter mu.

interfaces module


class pymor.parameters.interfaces.ParameterFunctionalInterface[source]

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.

__call__(...) <==> x(...)[source]
evaluate(mu=None)[source]

Evaluate the functional for the given Parameter mu.


class pymor.parameters.interfaces.ParameterSpaceInterface[source]

Bases: pymor.core.interfaces.ImmutableInterface

Interface for Parameter spaces.

parameter_type

ParameterType of the space.

contains(mu)[source]

True if mu is contained in the space.

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.
__repr__() <==> repr(x)[source]
__str__() <==> str(x)[source]
contains(mu)[source]

True if mu is contained in the space.

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.