porepy.numerics.ad.operators module

Implementation of wrappers for Ad representations of several operators.

class Array(values, name=None)[source]

Bases: Operator

AD representation of a constant numpy array.

For sparse matrices, use Matrix instead. For time-dependent arrays see TimeDependentArray.

This is a shallow wrapper around the real array; it is needed to combine the array with other types of AD operators.

Parameters

values (np.ndarray) – Numpy array to be represented.
name (Optional[str]) –

parse(mdg)[source]

See Operator.parse().

Returns: The wrapped array.
Parameters: mdg (MixedDimensionalGrid) –
Return type: ndarray

interfaces: list[porepy.grids.mortar_grid.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[porepy.grids.grid.Grid]

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

Will be empty for operators not associated with specific subdomains.

class Matrix(mat, name=None)[source]

Bases: Operator

Ad representation of a sparse matrix.

For dense matrices, use Array instead.

This is a shallow wrapper around the real matrix; it is needed to combine the matrix with other types of Ad objects.

Parameters

mat (sps.spmatrix) – Sparse matrix to be wrapped as an AD operator.
name (Optional[str]) – Name of this operator

parse(mdg)[source]

See Operator.parse().

Returns: The wrapped matrix.
Parameters: mdg (MixedDimensionalGrid) –
Return type: spmatrix

transpose()[source]

Returns an AD operator representing the transposed matrix.

Return type: Matrix

property T: Matrix: Shorthand for transpose.

interfaces: list[porepy.grids.mortar_grid.MortarGrid]

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

Will be empty for operators not associated with specific interfaces.

shape: Shape of the wrapped matrix.

subdomains: list[porepy.grids.grid.Grid]

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

Will be empty for operators not associated with specific subdomains.

class MixedDimensionalVariable(variables)[source]

Bases: Variable

Ad representation of a collection of variables that individually live on separate subdomains or interfaces, but treated jointly in the mixed-dimensional sense.

Conversion of the variables into numerical value should be done with respect to the state of an array; see Operator.evaluate(). Therefore, the MergedVariable does not implement the method Operator.parse().

Parameters: variables (list[Variable]) – List of variables to be merged. Should all have the same name.

copy()[source]

Copy the mixed-dimensional variable.

Returns: A shallow copy should be sufficient here; the attributes are not expected to change.
Return type: MixedDimensionalVariable

copy_common_sub_tags()[source]

Copy any shared tags from the sub variables to this variable.

Only tags with identical values are copied. Thus, the md variable can “trust” that its tags are consistent with all sub variables.

Return type: None

previous_iteration()[source]

Return a representation of this mixed-dimensional variable on the previous iteration.

Returns: A representation of this merged variable on the previous iteration, with its prev_iter attribute set to True
Return type: MixedDimensionalVariable

previous_timestep()[source]

Return a representation of this mixed-dimensional variable on the previous time step.

If the md-variable is already defined on the previous time step, return itself.

Returns: A representation of this merged variable on the previous time iteration, with its prev_iter attribute set to True.
Return type: MixedDimensionalVariable

size()[source]

Returns the total size of the mixed-dimensional variable by summing the sizes of sub-variables.

Return type: int

property domain: list[Union[porepy.grids.grid.Grid, porepy.grids.mortar_grid.MortarGrid]]: A tuple of all domains on which the atomic sub-variables are defined.

id: int: ID counter. Used to identify variables during operator parsing.

interfaces: list[porepy.grids.mortar_grid.MortarGrid]

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

Will be empty for operators not associated with specific interfaces.

original_variable: MixedDimensionalVariable

The original variable, if this variable is a copy of another variable.

This attribute is used by the methods Variable.previous_timestep() and Variable.previous_iteration() to keep a link to the original variable.

prev_iter: bool: Flag indicating if the variable represents the state at the previous iteration.

prev_time: bool: Flag indicating if the variable represents the state at the previous time step.

sub_vars: List of sub-variables passed at instantiation, each defined on a separate domain.

subdomains: list[porepy.grids.grid.Grid]

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

Will be empty for operators not associated with specific subdomains.

class Operator(name=None, subdomains=None, interfaces=None, tree=None)[source]

Bases: object

Parent class for all AD operators.

Objects of this class are not meant to be initiated directly, rather the various subclasses should be used. Instances of this class will still be created when subclasses are combined by Operator.Operations.

Contains a tree structure of child operators for the recursive forward evaluation.

Provides overload functions for basic arithmetic operations.

Parameters

name (Optional[str]) – Name of this operator. Used for string representations
subdomains (optional) – List of subdomains on which the operator is defined. Will be empty for operators not associated with any subdomains. Defaults to None (converted to empty list).
interfaces (optional) – List of interfaces in the mixed-dimensional grid on which the operator is defined. Will be empty for operators not associated with any interface. Defaults to None (converted to empty list).
tree (Optional[Tree]) –

class Operations(value)

Bases: Enum

Object representing all supported operations by the operator class.

Used to construct the operator tree and identify Operator.Operations.

add

approximate

div

evaluate

mul

pow

sub

void

discretize(mdg)[source]

Perform discretization operation on all discretizations identified in the tree of this operator, using data from mdg.

IMPLEMENTATION NOTE: The discretizations was identified at initialization of Expression - it is now done here to accommodate updates (?) and

Parameters: mdg (MixedDimensionalGrid) –
Return type: None

evaluate(system_manager, state=None)[source]

Evaluate the residual and Jacobian matrix for a given state.

Parameters

system_manager (pp.ad.EquationSystem | pp.DofManager) – Used to represent the problem. Will be used to parse the sub-operators that combine to form this operator.
state (optional) – State vector for which the residual and its derivatives should be formed. If not provided, the state will be pulled from the previous iterate (if this exists), or alternatively from the state at the previous time step.

Returns

A representation of the residual and Jacobian in form of an AD Array. Note that the Jacobian matrix need not be invertible, or even square; this depends on the operator.

is_leaf()[source]

Check if this operator is a leaf in the tree-representation of an expression.

Note that this implies that the method parse() is expected to be implemented.

Returns: True if the operator has no children.
Return type: bool

parse(mdg)[source]

Translate the operator into a numerical expression.

Subclasses that represent atomic operators (leaves in a tree-representation of an operator) should override this method to return e.g. a number, an array or a matrix. This method should not be called on operators that are formed as combinations of atomic operators; such operators should be evaluated by the method evaluate().

Parameters: mdg (MixedDimensionalGrid) – Mixed-dimensional grid on which this operator is to be parsed.
Returns: A numerical format representing this operator;s values on given domain.
Return type: Any

previous_timestep()[source]

Return an operator that represents the value of this operator at the previous timestep.

The operator tree at the previous time step is created as a shallow copy, and will thus be identical to the original operator, except that all time dependent operators are evaluated at the previous time step.

Returns: A copy of self, with all time dependent operators evaluated at the previous time step.
Return type: Operator

set_name(name)[source]

Reset this object’s name originally passed at instantiation.

Parameters: name (str) – the new name to be assigned.
Return type: None

viz()[source]: Draws a visualization of the operator tree that has this operator as its root.

interfaces: list[porepy.grids.mortar_grid.MortarGrid]

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

Will be empty for operators not associated with specific interfaces.

property name: str: The name given to this variable.

subdomains: list[porepy.grids.grid.Grid]

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

Will be empty for operators not associated with specific subdomains.

class Scalar(value, name=None)[source]

Bases: Operator

Ad representation of a scalar.

This is a shallow wrapper around a real scalar. It may be useful to combine the scalar with other types of Ad objects.

NOTE: Since this is a wrapper around a Python immutable, copying a Scalar will effectively create a deep copy, i.e., changes in the value of one Scalar will not be reflected in the other. This is in contrast to the behavior of the other Ad objects.

Parameters

value (float) –
name (Optional[str]) –

parse(mdg)[source]

See Operator.parse().

Returns: The wrapped number.
Parameters: mdg (MixedDimensionalGrid) –
Return type: float

interfaces: list[porepy.grids.mortar_grid.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[porepy.grids.grid.Grid]

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

Will be empty for operators not associated with specific subdomains.

class TimeDependentArray(name, subdomains=None, interfaces=None, previous_timestep=False)[source]

Bases: Array

An Ad-wrapper around a time-dependent numpy array.

The array is tied to a MixedDimensionalGrid, and is distributed among the data dictionaries associated with subdomains and interfaces. The array values are stored in data[pp.STATE][pp.ITERATE][self._name] for the current time and data[pp.STATE][self._name] for the previous time.

The array can be differentiated in time using pp.ad.dt().

The intended use is to represent time-varying quantities in equations, e.g., source terms. Future use will also include numerical values of boundary conditions, however, this is pending an update to the model classes.

Parameters

name (str) – Name of the variable. Should correspond to items in data[pp.STATE].
subdomains (list[porepy.grids.grid.Grid]) – Subdomains on which the array is defined. Defaults to None.
interfaces (list[porepy.grids.mortar_grid.MortarGrid]) – Interfaces on which the array is defined. Defaults to None. Exactly one of subdomains and interfaces must be non-empty.
previous_timestep (bool) – Flag indicating if the array should be evaluated at the previous time step.

previous_timestep[source]

If True, the array will be evaluated using data[pp.STATE] (data being the data dictionaries for subdomains and interfaces), if False, data[pp.STATE][pp.ITERATE] is used.

Return type: TimeDependentArray

Raises

ValueError – If either none of, or both of, subdomains and interfaces are empty.

Parameters

name (str) –
subdomains (list[porepy.grids.grid.Grid]) –
interfaces (list[porepy.grids.mortar_grid.MortarGrid]) –
previous_timestep (bool) –

parse(mdg)[source]

Convert this array into numerical values.

The numerical values will be picked from the representation of the array in data[pp.STATE][pp.ITERATE] (where data is the data dictionary of the subdomains or interfaces of this Array), or, if self.prev_time = True, from data[pp.STATE].

Parameters: mdg (MixedDimensionalGrid) – Mixed-dimensional grid.
Returns: A numpy ndarray containing the numerical values of this array.
Return type: ndarray

previous_timestep()[source]

Returns: This array represented at the previous time step.
Return type: TimeDependentArray

interfaces: list[porepy.grids.mortar_grid.MortarGrid]

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

Will be empty for operators not associated with specific interfaces.

prev_time: bool

If True, the array will be evaluated using data[pp.STATE] (data being the data dictionaries for subdomains and interfaces).

If False, data[pp.STATE][pp.ITERATE] is used.

subdomains: list[porepy.grids.grid.Grid]

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

Will be empty for operators not associated with specific subdomains.

class Variable(name, ndof, domain, tags=None, previous_timestep=False, previous_iteration=False)[source]

Bases: Operator

AD operator representing a variable defined on a single grid or mortar grid.

For combinations of variables on different subdomains, see MergedVariable.

Conversion of the variable into numerical value should be done with respect to the state of an array; see Operator.evaluate(). Therefore, the variable does not implement the method Operator.parse().

A variable is associated with either a grid or an interface. Therefore it is assumed that either subdomains or interfaces is passed as an argument.

Parameters

name (str) – Variable name.
ndof (dict[Literal['cells', 'faces', 'nodes'], int]) – Number of dofs per grid element. Valid keys are cells, faces and nodes.
subdomains (length=1) – List containing a single grid.
interfaces (length=1) – List containing a single mortar grid.
num_cells – Number of cells in the grid. Only relevant if this is an interface variable.
domain (GridLike) –
tags (Optional[dict[str, Any]]) –
previous_timestep (bool) –
previous_iteration (bool) –

previous_iteration()[source]

Returns: A representation of this variable on the previous time iteration, with its prev_iter attribute set to True.
Return type: Variable

previous_timestep()[source]

Return a representation of this variable on the previous time step.

If the variable is already a representation of the previous time step, the method returns itself.

Returns: A representation of this variable at the previous time step, with its prev_time attribute set to True.
Return type: Variable

set_name(name)[source]

Raises: RuntimeError – Variables must not be re-named once defined, since the name is used as an identifier.
Parameters: name (str) –
Return type: None

size()[source]

Returns the total number of dofs this variable has.

Return type: int

property domain: Union[Grid, MortarGrid]: The grid or mortar grid on which this variable is defined.

id: int: ID counter. Used to identify variables during operator parsing.

interfaces: list[porepy.grids.mortar_grid.MortarGrid]

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

Will be empty for operators not associated with specific interfaces.

original_variable: Variable

The original variable, if this variable is a copy of another variable.

This attribute is used by the methods Variable.previous_timestep() and Variable.previous_iteration() to keep a link to the original variable.

prev_iter: bool: Flag indicating if the variable represents the state at the previous iteration.

prev_time: bool: Flag indicating if the variable represents the state at the previous time step.

subdomains: list[porepy.grids.grid.Grid]

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

Will be empty for operators not associated with specific subdomains.

property tags: dict[str, Any]: A dictionary of tags associated with this variable.