porepy.numerics.ad.operator_functions module

This module contains callable operators representing functions to be called with other operators as input arguments. Contains also a decorator class for callables, which transforms them automatically in the specified operator function type.

class ADmethod(func=None, ad_function_type=Function, operator_kwargs={})

Bases: object

(Decorator) Class for methods representing e.g., physical properties. The decorated function is expected to take scalars/vectors and return a scalar/vector.

The return value will be an AD operator of a type passed to the decorator.

Examples

import porepy as pp

# decorating class methods
class IdealGas:

    @ADmethod(ad_operator=pp.ad.DiagonalJacobianFunction,
            operators_args={"multipliers"=[1,1]})
    def density(self, p: float, T: float) -> float:
        return p/T

# decorating function
@ADmethod(ad_operator=pp.ad.Function)
def dummy_rel_perm(s):
    return s**2

With above code, the density of an instance of IdealGas can be called using MergedVariable representing pressure and temperature. Analogously, dummy_rel_perm can be called with one representing the saturation.

Note

If used as decorator WITHOUT explicit instantiation, the instantiation will be done implicitly with above default arguments (that’s how Python decorators work).

Parameters

• func (Optional[Callable]) – decorated function object

• ad_function_type (Type[AbstractFunction]) – type reference to an AD operator function to be instantiated. When instantiated, that instance will effectively replace func.

• operator_kwargs (dict) – keyword arguments to be passed when instantiating an operator of type ad_function_type.

ad_wrapper(*args, **kwargs)

Actual wrapper function. Constructs the necessary AD-Operator class wrapping the decorated callable and performs the evaluation/call.

Parameters

• *args – arguments for the call to the wrapping AD operator function

• **kwargs – keyword argument for the call to the wrapping Ad operator function

Return type

Operator

class ConstantFunction(name, values)

Bases: AbstractFunction

Function representing constant, scalar values with no dependencies and ergo a zero Jacobian.

It still has to be called though since it fulfills the notion of a ‘function’.

Parameters

• values (np.ndarray) – constant values per cell.

• name (str) –

get_jacobian(*args)

Note

The return value is not a sparse matrix as imposed by the parent method signature, but a zero. Numerical operations with a zero always works with any numeric formats in numpy, scipy and PorePy’s AD framework. Since the constant function (most likely) gets no arguments passed, we have no way of knowing the necessary shape for a zero matrix. Hence scalar.

Returns: the trivial derivative of a constant.

Parameters

args (Ad_array) –

Return type

spmatrix

get_values(*args)

Returns

The values passed at instantiation.

Parameters

args (Ad_array) –

Return type

ndarray

interfaces: list[pp.MortarGrid]

List of interfaces on which the operator is defined, passed at instantiation.

Will be empty for operators not associated with specific interfaces.

subdomains: list[pp.Grid]

List of subdomains on which the operator is defined, passed at instantiation.

Will be empty for operators not associated with specific subdomains.

class DiagonalJacobianFunction(func, name, multipliers, array_compatible=False)

Bases: AbstractJacobianFunction

Approximates the Jacobian of the function using identities and scalar multipliers per dependency.

Parameters

• multipliers (float | list[float]) – scalar multipliers for the identity blocks in the Jacobian, per dependency of func. The order in multipliers is expected to match the order of AD operators passed to the call of this function.

• func (Callable) –

• name (str) –

• array_compatible (bool) –

get_jacobian(*args)

The approximate Jacobian consists of identity blocks times scalar multiplier per every function dependency.

Parameters

args (Ad_array) –

Return type

spmatrix

interfaces: list[pp.MortarGrid]

List of interfaces on which the operator is defined, passed at instantiation.

Will be empty for operators not associated with specific interfaces.

subdomains: list[pp.Grid]

List of subdomains on which the operator is defined, passed at instantiation.

Will be empty for operators not associated with specific subdomains.

class Function(func, name, array_compatible=True)

Bases: AbstractFunction

Ad representation of an analytically given function, where it is expected that passing Ad_arrays directly to func will return the proper result.

Here the values and the Jacobian are obtained exactly by the AD framework.

The intended use is as a wrapper for operations on pp.ad.Ad_array objects, in forms which are not directly or easily expressed by the rest of the Ad framework.

Note

This is a special case where the abstract methods for getting values and the Jacobian are formally implemented but never used by the AD framework. A separate operation called evaluate is implemented instead, which simply feeds the AD arrays to func.

Parameters

• func (Callable) –

• name (str) –

• array_compatible (bool) –

get_jacobian(*args)

Parameters

args (Ad_array) –

Return type

ndarray

get_values(*args)

Parameters

args (Ad_array) –

Return type

ndarray

interfaces: list[pp.MortarGrid]

List of interfaces on which the operator is defined, passed at instantiation.

Will be empty for operators not associated with specific interfaces.

subdomains: list[pp.Grid]

List of subdomains on which the operator is defined, passed at instantiation.

Will be empty for operators not associated with specific subdomains.

class InterpolatedFunction(func, name, min_val, max_val, npt, order=1, preval=False, array_compatible=False)

Bases: AbstractFunction

Represents the passed function as an interpolation of chosen order on a cartesian, uniform grid.

The image of the function is expected to be of dimension 1, while the domain can be multidimensional.

Note

All vector-valued ndarray arguments are assumed to be column vectors. Each row-entry represents a value for an argument of func in respective order.

Parameters

• min_val (np.ndarray) – lower bounds for the domain of func.

• max_val (np.ndarray) – upper bound for the domain.

• npt (np.ndarray) – number of interpolation points per dimension of the domain.

• order (int) – Order of interpolation. Supports currently only linear order.

• preval (optional) – If True, pre-evaluates the values of the function at the points of interpolation and stores them. If False, evaluates them if necessary. Influences the runtime. Defaults to False.

• func (Callable) –

• name (str) –

• array_compatible (bool) –

get_jacobian(*args)

Parameters

args (Ad_array) –

Return type

spmatrix

get_values(*args)

Parameters

args (Ad_array) –

Return type

ndarray

interfaces: list[pp.MortarGrid]

List of interfaces on which the operator is defined, passed at instantiation.

Will be empty for operators not associated with specific interfaces.

subdomains: list[pp.Grid]

List of subdomains on which the operator is defined, passed at instantiation.

Will be empty for operators not associated with specific subdomains.