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)[source]¶
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 forFunctions
which are interpreted as time-dependent parameter values. Unless the Python interpreter runs with the-O
flag, the arrays are made immutable.- parameters[source]¶
The
Parameters
to which the mapping assigns values.
Methods
Compare dicts of
parameter values
usingfloat_cmp_all
.D.copy() -> a shallow copy of D
Return time-dependent
Function
for given parameter.Check whether the values for a given parameter depend on time.
All parameter values as a NumPy array, ordered alphabetically.
- allclose(mu)[source]¶
Compare dicts of
parameter values
usingfloat_cmp_all
.Parameters
- mu
The
parameter values
with which to compare.
Returns
True
if bothparameter value
dicts contain values for the sameParameters
and all components of the parameter values are almost equal, elseFalse
.
- get_time_dependent_value(param)[source]¶
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 correspondingFunction
(and not its evaluation at the current time) is returned. Ifparam
is not given by aFunction
, aConstantFunction
is returned.
- class pymor.parameters.base.ParameterSpace(parameters, *ranges)[source]¶
Bases:
ParametricObject
A set of
Parameters
with allowed ranges for their values.ParameterSpaces
are mostly used to create sample set ofparameter values
for givenParameters
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
Clip (limit)
parameter values
to the space's parameter ranges.Logarithmically scaled random sample
parameter values
from the space.Logarithmically uniform sample
parameter values
from the space.Randomly sample
parameter values
from the space.Uniformly sample
parameter values
from the space.- clip(mu, keep_additional=False)[source]¶
Clip (limit)
parameter values
to the space’s parameter ranges.Parameters
- mu
Parameter value
to clip.- keep_additional
If
True
, keep additional values in theMu
instance which are not contained in the parameters, e.g. time parameters.
Returns
The clipped
parameter values
.
- sample_logarithmic_randomly(count=None)[source]¶
Logarithmically scaled random sample
parameter values
from the space.Parameters
- count
If
None
, a single dictmu
ofparameter values
is returned. Otherwise, the number of logarithmically random samples to generate and return as a list ofparameter values
dicts.
Returns
The sampled
parameter values
.
- sample_logarithmic_uniformly(counts)[source]¶
Logarithmically uniform 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 each parameter inParameters
.
Returns
List of
parameter value
dicts.
- sample_randomly(count=None)[source]¶
Randomly sample
parameter values
from the space.Parameters
- count
If
None
, a single dictmu
ofparameter values
is returned. Otherwise, the number of random samples to generate and return as a list ofparameter values
dicts.
Returns
The sampled
parameter values
.
- sample_uniformly(counts)[source]¶
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 each parameter inParameters
.
Returns
List of
parameter value
dicts.
- class pymor.parameters.base.Parameters(*args, **kwargs)[source]¶
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-negativeint
specifying the dimension (number of scalar components) of the parameter.Methods
Assert that
parameter values
are compatible with the givenParameters
.Check if
parameter values
are compatible with the givenParameters
.Computes the total set of
Parameters
a collection of objects depends on.Interpret
mu
as a set ofparameter values
according to the givenParameters
.Create a
ParameterSpace
with given ranges.- assert_compatible(mu)[source]¶
Assert that
parameter values
are compatible with the givenParameters
.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)[source]¶
Check if
parameter values
are compatible with the givenParameters
.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)[source]¶
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
, aParametricObject
or lists, tuples, dicts orNumPy arrays
of such objects. The latter will be traversed recursively.
- parse(mu)[source]¶
Interpret
mu
as a set ofparameter values
according to the givenParameters
.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 parameterb
the values[2, 3]
. Further, each parameter value can be given as a vector-valuedFunction
withdim_domain == 1
to specify time-dependent values. Astr
is converted to an appropriateExpressionFunction
.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 asparameter values
for the givenParameters
.
- space(*ranges)[source]¶
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[source]¶
Bases:
pymor.core.base.ImmutableObject
Base class for immutable mathematical entities depending on some
Parameters
.Each
ParametricObject
lists theParameters
it depends on in theparameters
attribute. Usually, theseParameters
are automatically derived as the union of allParameters
of the object’s__init__
arguments.Additional
Parameters
introduced by the object itself can be specified by setting theparameters_own
attribute in__init__
. In case the object fixes someParameters
it’s child objects depend on to concrete values, thoseParameters
can be removed from theparameters
attribute by settingparameters_internal
.Alternatively,
parameters
can be initialized manually in__init__
.- parameters[source]¶
The
Parameters
the object depends on.
- parameters_own[source]¶
The
Parameters
the object depends on which are not inherited from a child object the object depends on. Each item ofparameters_own
is also an item ofparameters
.
- parameters_inherited[source]¶
The
Parameters
the object depends on because some child object depends on them. Each item ofparameters_own
is also an item ofparameters
.
- parameters_internal[source]¶
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 ofparameters_internal
are removed fromparameters
andparameters_inherited
. When initializingparameters_own
andparameters_internal
, it has to be ensured that both dicts are disjoint.
- parametric[source]¶
True
if the object really depends on a parameter, i.e.parameters
is not empty.