porepy.grids.coarsening module

This module contains methods to coarsen grids.

The main function is coarsen() (see there for more information).

coarsen(g, method, **method_kwargs)

Create a coarse grid from a given grid.

If a md-grid is passed, the procedure is applied to the grid of highest dimension.

Notes

• The passed grid is modified.

• Do not call compute_geometry() afterwards.

Parameters

• g (Union[Grid, MixedDimensionalGrid]) – The grid or mixed-dimensional grid to be coarsened.

• method (str) –

  A string defining the coarsening method.

  The available options are:

  • 'by_volume': The coarsening is based on the cell volume.

  • 'by_tpfa': Uses the AMG method’s coarse/fine-splittings based on direct couplings

• method_kwargs –

  Arguments for each method.

  For the 'by_volume'- method, see create_aggregations() for an overview on admissible keyword arguments.

  For the 'by_tpfa'- method, see create_partition(). Additionally, a keyword argument if_seeds of boolean type is supported. If True, generate_seeds() is called to create seeds.

Raises

ValueError – If method is not among the supported options.

Return type

None

create_aggregations(grid, **kwargs)

Creates a cell partition based on their volumes.

Parameters

• grid (Union[Grid, MixedDimensionalGrid]) – A single grid or mixed-dimensional grid.

• **kwargs –

  Following keyword arguments are supported:

  • 'weight': A float serving as weight for the mean of the cell volumes. Defaults to 1.

Returns

A dictionary containing a partition per grid.

Return type

dict[porepy.grids.grid.Grid, tuple[porepy.grids.grid.Grid, numpy.ndarray]]

create_partition(A, g, seeds=None, **kwargs)

Create the partition based on an input matrix using the AMG method’s coarse/fine-splittings based on direct couplings.

The standard values for cdepth and epsilon are taken from the reference below.

Example

>>> part = create_partition(tpfa_matrix(g))
>>> g = generate_coarse_grid(g, part)

References

U. Trottenberg, C. W. Oosterlee, and A. Schuller (200): Multigrid, Academic press.

Parameters

• A (spmatrix) – A sparse matrix used for the agglomeration.

• g (Union[Grid, MixedDimensionalGrid]) – A single grid or mixed-dimensional grid.

• seeds (Optional[ndarray]) –

  default=None

  A-priory defined cells of the coarser grid.

• **kwargs –

  The following keyword arguments are supported:

  • 'cdepth': A number to define the strength of the aggregation, i.e. a a greater number results in lesser cells. Defaults to 2.

  • 'epsilon': A float representing the weight for the off-diagonal entries to define the strong negative coupling. Defaults to 0.25.

Returns

A dictionary containing the a 2-tuple per grid. The 2-tuple contains the grid with the highest dimension and the map from finer to coarser grid containing as an array of agglomeration indices.

If g is a single grid, the grid of highest dimension is g itself.

Return type

dict[porepy.grids.grid.Grid, tuple[porepy.grids.grid.Grid, numpy.ndarray]]

generate_coarse_grid(g, subdiv)

Generates a coarse grid by clustering the cells according to the flags given by subdiv.

subdiv must be as long as the number of cells in the original grid, it contains integers (possibly not continuous) which represent the cell IDs in the final, coarser mesh. I.e. it is a cell map from finer to coarser.

If g is a mixed-dimensional grid, the coarsening is applied to the higher dimensional grid.

Warning

This method effectively overwrites every grid property computed by compute_geometry(). Do not call that method after calling this one.

Note

There is no check for disconnected cells in the final grid.

Example

>>> g = ...  # some grid with 12 cells
>>> subdiv = np.array([0,0,1,1,2,2,3,3,4,4,5,5])  # coarser grid with 6 cells
>>> generate_coarse_grid(g, subdiv)

Parameters

• g (Union[Grid, MixedDimensionalGrid]) – A grid or mixed-dimensional grid.

• subdiv (Union[ndarray, dict[porepy.grids.grid.Grid, tuple[Any, numpy.ndarray]]]) –

  If g is a single grid, a single array-like object as in above example suffices.

  If g is a mixed-dimensional grid, a dictionary containing per grid (key) a 2-tuple, where the second entry is the partition map as seen above. This special structure is passed by coarsen().

Return type

None

generate_seeds(mdg)

Generates a priory seeds (cells) for coarsening a mixed-dimensional grid based on topological information about the highest-dimensional grid.

Parameters

mdg (Union[Grid, MixedDimensionalGrid]) – A grid or mixed-dimensional grid.

Returns

If mdg is a single grid, this function returns an empty array.

If mdg is a mixed-dimensional grid, this function returns an initial seed for the coarsening based on the mortar projections between the grid of highest dimension and grids of co-dimension 1.

Return type

ndarray

reorder_partition(subdiv)

Re-order the partition IDs in order to obtain contiguous numbers.

Parameters

subdiv (Union[ndarray, dict[Any, tuple[Any, numpy.ndarray]]]) – A subdivision/partition as an array containing an ID for each cell, or a dictionary containing the previous in a 2-tuple for any key.

Returns

The subdivision stored in a contiguous way.

Return type

Union[ndarray, dict[Any, tuple[Any, numpy.ndarray]]]