porepy.numerics.ad.equation_manager module

Main content: EquationManager: representation of a set of equations on Ad form.

class EquationManager(mdg, dof_manager, equations=None, secondary_variables=None)

Bases: object

Representation of a set of equations specified on Ad form.

The equations are tied to a specific MixedDimensionalGrid, with variables fixed in a corresponding DofManager.

Parameters

• mdg (pp.MixedDimensionalGrid) –

• dof_manager (pp.DofManager) –

• equations (Optional[Dict[str, 'pp.ad.Operator']]) –

• secondary_variables (Optional[Sequence['pp.ad.Variable']]) –

mdg

Mixed-dimensional grid on which this EquationManager operates.

Type

pp.MixedDimensionalGrid

dof_manager

Degree of freedom manager used for this EquationManager.

Type

pp.DofManager

equations

Equations assigned to this EquationManager. can be expanded by direct addition to the list.

Type

List of Ad Operators

variables

Mapping from subdomains or grid tuples (interfaces) to Ad variables. These are set at initialization from the MixedDimensionalGrid, and should not be changed later.

Type

Dict

secondary_variables

List of variables that are secondary, that is, their derivatives will not be included in the Jacobian matrix. Variables will be represented on atomic form, that is, mixed-dimensional variables are unravelled. Secondary variables act as a filter during assembly, that is, they do not impact the ordering or treatment of variables.

Type

List of Ad Variables

row_block_indices_last_assembled

Row indices for the start of blocks corresponding to different equations in the last assembled system. The last item in the array is the total number of rows, so that row indices for block i can be recovered by np.arange(row_bl..[i], row_bl..[i+1]). The user must relate the indices to equations (either in self.equations or the equation list given to the relevant assembly method). This information is intended for diagnostic usage.

Type

np.ndarray

assemble(state=None)

Assemble Jacobian matrix and residual vector with respect to the current state represented in self.mdg.

Derivatives for secondary variables are not included in the Jacobian matrix.

Parameters

state (np.ndarray, optional) – State vector to assemble from. If not provided, the default behavior of pp.ad.Expression.to_ad() will be followed.

Returns

Jacobian matrix corresponding to the current variable state,

as found in self.mdg. The ordering of the equations is determined by the ordering in self.equations (for rows) and self.dof_manager (for columns).

np.ndarray: Residual vector corresponding to the current variable state,

as found in self.mdg. Scaled with -1 (moved to rhs).

Return type

sps.spmatrix

assemble_schur_complement_system(primary_equations, primary_variables, inverter)

Assemble Jacobian matrix and residual vector using a Schur complement elimination of the variables and equations not to be included.

The specified equations and variables will define a reordering of the linearized system into

[A_pp, A_ps [x_p = [b_p

A_sp, A_ss] x_s] b_s]

Where subscripts p and s define primary and secondary quantities. The Schur complement system is then given by

(A_pp - A_ps * inv(A_ss) * A_sp) * x_p = b_p - A_ps * inv(A_pp) * b_s.

The Schur complement is well-defined only if the inverse of A_ss exists, and the efficiency of the approach assumes that an efficient inverter for A_ss can be found. The user must ensure both requirements are fulfilled. The simplest option is a lambda function on the form:

inverter = lambda A: sps.csr_matrix(np.linalg.inv(A.A))

but depending on A (size and sparsity pattern), this can be costly in terms of computational time and memory.

The method can be used e.g. for splitting between primary and secondary variables, where the latter can be efficiently eliminated (for instance, they contain no spatial derivatives).

Parameters

• primary_equations (Sequence of str) – Equations to be assembled, specified as keys in self.equations. Should have length > 0.

• primary_variables (Sequence of Variables) – Variables to be assembled. Should have length > 0.

• inverter (Callable) – Method to compute the inverse of the matrix A_ss.

Returns

Jacobian matrix corresponding to the current variable state,

as found in self.mdg, for the specified equations and variables.

np.ndarray: Residual vector corresponding to the current variable state,

as found in self.mdg, for the specified equations and variables. Scaled with -1 (moved to rhs).

Return type

sps.spmatrix

assemble_subsystem(eq_names=None, variables=None)

Assemble Jacobian matrix and residual vector using a specified subset of equations and variables.

The method is intended for use in splitting algorithms. Matrix blocks not included will simply be ignored.

Parameters

• eq_names (Sequence of str, optional) – Equations to be assembled, specified as keys in self.equations. If not provided (None), all equations known to this EquationManager will be included.

• variables (Sequence of Variables, optional) – Variables to be assembled. If not provided (None), all variables known to this EquationManager will be included. If a secondary variable is specified, this will be included in the returned system.

Returns

Jacobian matrix corresponding to the current variable state,

as found in self.mdg, for the specified equations and variables.

np.ndarray: Residual vector corresponding to the current variable state,

as found in self.mdg, for the specified equations and variables. Scaled with -1 (moved to rhs).

NOTE: The ordering of columns in the system are defined by the order of the

variables specified in DofManager. For the rows, no corresponding global ordering of equations exists, and the rows will therefore be organized by the ordering in the parameter eq_names.

Return type

sps.spmatrix

discretize(mdg)

Loop over all discretizations in self.equations, find all unique discretizations and discretize.

This is more efficient than discretizing on the Operator level, since discretizations which occur more than once in a set of equations will be identified and only discretized once.

Parameters

mdg (pp.MixedDimensionalGrid) – Mixed-dimensional grid from which parameters etc. will be taken and where discretization matrices will be stored.

Return type

None

merge_variables(grid_var)

Concatenate a variable defined over several subdomains or interfaces.

The mixed-dimensional variable can be used to define mathematical operations on multiple subdomains simultaneously (provided it is combined with other operators defined on the same subdomains).

NOTE: mixed-dimensional variables are assigned unique ids (see documentation of Variable and MixedDimensionalVariable), thus two MixedDimensionalVariables will have different ids even if they represent the same combination of subdomains and variables. This does not impact the parsing of the variables into numerical values.

Parameters

grid_var (Sequence[Tuple[Union[Grid, MortarGrid], str]]) – Tuple containing first a (Mortar)grid representing the subdomain or interface and second the name of the variable.

Returns

Joint representation of the variable on the

specified subdomains.

Return type

pp.ad.MixedDimensionalVariable

name_and_assign_equations(equation_dictionary)

Convenience method for assigning and naming equations.

Parameters

equation_dictionary (Dict) – Dictionary containing name: equation pairs.

Return type

None

subsystem_equation_manager(eq_names, variables)

Extract an EquationManager for a subset of variables and equations. In effect, this produce a nonlinear subsystem.

Parameters

• eq_names (Sequence of str) – Equations assigned to the new EquationManager, specified as keys in self.equations.

• variables (Sequence of Variables) – Variables for which the new EquationManager is defined.

Returns

System of nonlinear equations. The ordering of the

equations in the subsystem will be the same as in the original EquationManager (i.e. self), disregarding equations not included in the subset. Variables that were excluded are added to the set of secondary_variables in the new EquationManager.

Return type

EquationManager

variable(grid_like, variable)

Get a variable for a specified grid or interface between grids, that is a mortar grid.

Subsequent calls of this method with the same grid and variable will return references to the same variable.

Returns

Ad representation of a variable.

Return type

pp.ad.Variable

Parameters

• grid_like (Union[Grid, MortarGrid]) –

• variable (str) –

variable_state(grid_var, state)

Parameters

• grid_var (List[Tuple[Grid, str]]) –

• state (ndarray) –

Return type

List[ndarray]