porepy.numerics.mixed_dim.dof_manager module

Implementation of a degree of freedom manager.

class DofManager(mdg)[source]

Bases: object

Class to keep track of degrees of freedom in a mixed-dimensional grid with several variables.

This class should be used for setting the state of variables, and to get indices of the degrees of freedom for grids and variables.

Parameters

mdg (pp.MixedDimensionalGrid) –

block_dof

Is a dictionary with keys that are either Tuple[pp.Grid, variable_name: str] for nodes in the MixedDimensionalGrid, or Tuple[pp.MortarGrid, str] for edges in the MixedDimensionalGrid. The values in block_dof are integers 0, 1, …, that identify the block index of this specific grid (or edge) - variable combination.

full_dof

Is a np.ndarray of int that stores the number of degrees of freedom per key-item pair in block_dof. Thus

len(full_dof) == len(block_dof).

The total size of the global system is self.num_dofs() = full_dof.sum().

assemble_variable(grids=None, variables=None, from_iterate=False)[source]

Assemble a vector from the variable state stored in nodes and edges in the MixedDimensionalGrid.

Parameters

  • grids (list of grids or grid tuples (interfaces), optional) – Names of the grids (both subdomains and interfaces) to be assembled from. If not provided, all variables found in self.block_dof will be considered.

  • variables (list of str, optional) – Names of the variables to be assembled. If not provided, all variables found in self.block_dof will be cosidered.

  • from_iterate (bool, optional) – If True, assemble from iterates, and not the state itself. Set this to True inside a non-linear scheme (Newton), False at the end of a time step.

Returns

Vector, size equal to self.num_dofs(). Values taken from the

state for those indices corresponding to an active grid-variable combination. Other values are set to zero.

Return type

np.ndarray

distribute_variable(values, grids=None, variables=None, additive=False, to_iterate=False)[source]

Distribute a vector to the nodes and edges in the MixedDimensionalGrid.

The intended use is to split a multi-physics solution vector into its component parts.

Parameters

  • values (np.array) – Vector to be split. It is assumed that the ordering in values coresponds to that implied in self._block_dof and self._full_dof. Should have size self.num_dofs(), thus projections from subsets of variables must be done before calling this function.

  • grids (list of pp.Grid or pp.MortarGrid, optional) – The subdomains and interfaces to be considered. If not provided, all grids and edges found in self.block_dof will be considered.

  • variables (list of str, optional) – Names of the variables to be distributed. If not provided, all variables found in self.block_dof will be considered.

  • additive (bool, optional) – If True, the variables are added to the current state or iterate, instead of overwrite the existing value.

  • to_iterate (bool, optional) – If True, distribute to iterates, and not the state itself. Set to True inside a non-linear scheme (Newton), False at the end of a time step.

Return type

None

dof_to_grid_and_variable(ind)[source]

Find the grid (or grid pair) and variable name for a degree of freedom, specified by its index in the global ordering.

Parameters

ind (int) – Index of degree of freedom.

Returns

Grid on subdomain, or pair of grids which

define an interface.

str: Name of variable.

Return type

pp.Grid or pp.MortarGrid

Raises

ValueError – If the given index is negative or larger than the system size.

dof_var(var, return_projection=False, matrix_format=sps.csr_matrix)[source]

Get the indices in the global system of variables given as input on all nodes and edges (in the MixedDimensionalGrid sense).

This method is primarily intended used when equations are assembled with an Assembler object. If you use the newer Ad framework (recommended), the Ad machinery, and in particular the EquationManager, can deliver subsystems in a better way.

Parameters

  • var (str or list of str) – Name or names of the variable. Should be an active variable.

  • return_projection (bool, optional) – Return the projection matrix from for selecting only the requested variables. Default to False.

  • matrix_format (csc_or_csr_matrix, optional) – Format of the projection matrix. Default to sps.csr_matrix.

Return type

Union[ndarray, Tuple[ndarray, Union[csc_matrix, csr_matrix]]]

dofs_of(variables)[source]

Get the indices in the global vector of unknowns belonging to the variables.

Method mirrors that of equation_system to allow for a smooth transition as this class is phased out.

Parameters

variables (list[porepy.numerics.ad.operators.Variable]) – VariableType input for which the indices are requested.

Returns

an order-preserving array of indices of DOFs belonging to the VariableType input.

Raises

ValueError – if unknown VariableType arguments are passed.

Return type

ndarray

get_variable_values(variables=None, from_iterate=False)[source]

Assembles an array containing values for the passed variable-like argument.

The global order is preserved and independent of the order of the argument.

The method mimics that of EquationSystem to ensure compatibility in Operation evaluation during the transition period until this class is removed.

Notes

The resulting array is of any size between 0 and num_dofs.

Parameters

  • variables (optional) – VariableType input for which the values are requested. If None (default), the global vector of unknowns is returned.

  • from_iterate (optional) – flag to return values stored as ITERATE, instead of STATE (default).

Returns

the respective (sub) vector in numerical format.

Raises

  • KeyError – if no values are stored for the VariableType input.

  • ValueError – if unknown VariableType arguments are passed.

Return type

ndarray

grid_and_variable_block_range(grids=None, variables=None, sort_by='', return_str=False)[source]

Get the range of indices in the global system of variables associated with combinations of nodes / edges (in the MixedDimensionalGrid sense) and variables.

This function is intended mainly for inquiries into the ordering of blocks in systems with multiple variables and/or grids. The results can be returned as variables or a string. Both options come with options for sorting of the output.

Parameters

  • grids (pp.Grid or pp.MixedDimensionalGrid edge) – List of grids, edges (in the MixedDimensionalGrid) or combinations of the two. If not provided, all

  • considered. (grids and edges that are assigned variables will be) –

  • variables (str) – Name of variables. If not provided, all variables assigned to at least one grid or variable will be considered).

  • sort_by (str) –

    Should take one of the values ‘grids’, ‘variables’ or an empty str (default). If either grids or variables is specified, the return

    argument will be sorted according to the corresponding type.

  • return_str (bool) – If True, information will be returned as a string instead of as variables.

Returns

Information on the range for grid-variable combinations. The format will depend on the value of sort_by: If set to grids, a dictionary with grids as keys will be returned, correspondingly for variables. If not specified, unsorted grid-variable combinations are returned.

If return_str is True, the information will instead be returned as a string, with formatting determined on the value of sort_by.

Return type

Dict | str

grid_and_variable_to_dofs(grid, variable)[source]

Get the indices in the global system of variables associated with a given node / edge (in the MixedDimensionalGrid sense) and a given variable.

Parameters

  • g – Either a grid or an edge in the MixedDimensionalGrid.

  • grid (Union[Grid, MortarGrid]) –

  • variable (str) –

Returns

Index of degrees of freedom for this variable.

Return type

np.array (int)

num_dofs()[source]

Get the number of degrees of freedom in this DofManager.

Returns

Size of subsystem.

Return type

np.int_