porepy.grids.grid module

Module containing the parent class for all grids.

See documentation of class Grid for further details.

Acknowledgements The data structure for the grid is inspired by that used in the Matlab Reservoir Simulation Toolbox (MRST) developed by SINTEF ICT. Some of the methods, in particular compute_geometry() and its subfunctions is to a large degree translations of the corresponding functions in MRST as they were defined around 2016.

class Grid(*args, **kwargs)

Bases: object

Parent class for all grids.

The grid stores topological information, as well as geometric information. Geometric information requires calling compute_geometry() to be initialized.

Note

As of yet, there is no structure for tags (face or cell) in the grid. This may be introduced later.

Parameters

• dim – Grid dimension.

• nodes –

  shape=(ambient_dimension, num_nodes)

  Node coordinates, where ambient_dimension is the dimension of the grid.

• face_nodes –

  shape=(num_nodes, num_faces)

  A map from faces to respective nodes spanning the face.

• cell_faces –

  shape=(num_faces, num_cells)

  A map from cells to faces bordering the respective cell.

• name – Name of grid.

• history –

  default=None

  Information on the formation of the grid.

• external_tags –

  default=None

  External tags for nodes and grids. Will be added to tags.

Return type

Grid

cell_connection_map()

Get a matrix representation of cell-cell connections, as defined by two cells sharing a face.

Returns

A sparse matrix with (shape=(num_cells, num_cells), dtype=bool).

Element (i,j) is True if cells i and j share a face. The matrix is thus symmetric.

Return type

csr_matrix

cell_diameters(cn=None)

Computes the cell diameters.

Parameters

cn (Optional[spmatrix]) – default=None Cell-to-nodes map, already computed previously. If None, a call to cell_nodes() is provided.

Returns

Values of the cell diameter for each cell, (shape=(num_cells)).

If the dimension of the grid is zero, returns 0.

Return type

ndarray

cell_face_as_dense()

Obtain the cell-face relation in the form of two rows, rather than a sparse matrix.

This alternative format can be useful in some cases.

Each column in the array corresponds to a face, and the elements in that column refers to cell indices. The value -1 signifies a boundary. The normal vector of the face points from the first to the second row.

Returns

Array representation of face-cell relations with shape=(2, num_faces).

Return type

ndarray

cell_nodes()

Obtain mapping between cells and nodes.

Returns

An array with shape=(num_nodes, num_cells) representing the mapping from cells to nodes spanning respective cell.

The value 1 indicates a connection between a cell and node column-wise.

Return type

csc_matrix

closest_cell(p, return_distance=False)

For a set of points, find closest cell by cell center.

If several centers have the same distance, one of them will be returned.

For dim < 3, no checks are made if the point is in the plane / line of the grid.

Parameters

• p (ndarray) –

  shape=(3, n)

  Coordinates of n points. If p.shape[0] < 3, additional points will be treated as zeros.

• return_distance (bool) – A flag indicating whether the distances should be returned as well.

Returns

An array with (shape=(n,), dtype=int) containing for each point the index of the cell with center closest to the point.

If return_distance is True, returns a 2-tuple, where the second array contains the distances to respective centers for each point.

Return type

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

compute_geometry()

Compute geometric quantities for the grid.

The method could have been called from the constructor, however, in cases where the grid is modified after the initial construction ( say, grid refinement), this may lead to costly, unnecessary computations.

Computes the face areas, face centers, face normals and cell volumes.

Return type

None

copy()

Create a new instance with some attributes deep-copied from the grid.

Returns

A deep copy of self. Some predefined attributes are also copied.

Return type

Grid

get_all_boundary_faces()

Returns

An array with shape=(num_boundary_faces,) containing the indices of all faces tagged as either fractures, domain boundary or tip.

Return type

ndarray

get_all_boundary_nodes()

Returns

An array with Indices of all boundary nodes shape=(num_boundary_nodes,) containing the indices of all faces tagged as either fractures, domain boundary or tip.

Return type

ndarray

get_boundary_faces()

Returns

An array with shape=(n,) containing the indices of all faces tagged as domain boundary.

Return type

ndarray

get_boundary_nodes()

Returns

An array with shape=(n,) containing indices of all domain boundary nodes.

Return type

ndarray

get_internal_faces()

Returns

An array with shape=(num_internal_faces,) containing indices of internal faces.

Return type

ndarray

get_internal_nodes()

Returns

An array with shape=(num_internal_nodes,) containing the indices of internal nodes.

Return type

ndarray

initiate_face_tags()

Create zero arrays for the standard face tags and update tags.

Return type

None

initiate_node_tags()

Create zero arrays for the standard node tags and update tags.

Return type

None

num_cell_nodes()

Returns

An array with shape=(num_cells,) containing the number of nodes per cell.

Return type

ndarray

set_periodic_map(periodic_face_map)

Sets the index map between periodic boundary faces.

The mapping assumes a one to one mapping between the periodic boundary faces (i.e., matching faces).

Note

This method changes the attribute self.tags["domain_boundary_faces"]. The domain boundary tags are set to False for all faces in periodic_face_map.

Parameters

periodic_face_map (ndarray) –

shape=(2, num_periodic_faces), dtype=int

Defines the periodic faces. Face index periodic_face_map[0, i] is periodic with face index periodic_face_map[1, i]. The given map is stored to the attribute periodic_face_map.

Raises

ValueError – If periodic_face_map is of wrong shape or contains negative values.

Return type

None

signs_and_cells_of_boundary_faces(faces)

Get the direction of the normal vector (inward or outwards from a cell) and the cell neighbor of boundary faces.

Parameters

faces (ndarray) –

shape=(n,)

Indices of n faces that you want to know the sign for. The faces must be boundary faces.

Raises

ValueError – If a target face is internal.

Returns

A 2-tuple containing

ndarray:

shape=(n,)

The sign of the faces. Will be +1 if the face normal vector points out of the cell, -1 if the normal vector is pointing inwards.

ndarray:

shape=(n,)

For each face, index of the cell next to the boundary.

Return type

tuple[numpy.ndarray, numpy.ndarray]

update_boundary_face_tag()

Tags faces on the boundary of the grid with boundary tag.

Return type

None

update_boundary_node_tag()

Tags nodes on the boundary of the grid with boundary tag.

Return type

None

cell_centers: ndarray

An array containing column-wise the centers of all cells with shape=(ambient_dimension, num_cells).

Available after calling compute_geometry().

cell_faces: csc_matrix

An array with shape=(num_faces, num_cells) representing the map from cells to faces bordering respective cell.

Matrix elements have value +-1, where + corresponds to the face normal vector being outwards.

cell_volumes: ndarray

An array containing column-wise the volumes per cell with shape=(num_cells,).

Available after calling compute_geometry().

dim: int

Grid dimension. Should be in {0, 1, 2, 3}.

face_areas: ndarray

Areas of all faces (shape=(num_cells,)). Available after calling compute_geometry().

face_centers: ndarray

Centers of all faces. (shape=(ambient_dimension, num_faces)). Available after calling compute_geometry().

face_nodes: csc_matrix

An array with shape=(num_nodes, num_faces) representing the map from faces to nodes spanning respective face.

Assumes the nodes of each face are ordered according to the right-hand rule.

Note

To use compute_geometry() later, the field face_nodes.indices should store the nodes of each face sorted. face_nodes.indices[face_nodes.indptr[i]:face_nodes.indptr[i+1]] are the nodes of face i, which should be ordered counter-clockwise.

By counter-clockwise we mean as seen from cell cell_faces[i,:] == -1.

Equivalently the nodes will be clockwise as seen from cell cell_faces[i,:] == 1.

Note that operations on the face_nodes matrix (such as converting it to a csr-matrix) may change the ordering of the nodes (face_nodes.indices), which will break compute_geometry().

face_normals: ndarray

An array containing column-wise normal vectors of all faces with shape=(ambient_dimenaion, num_faces).

See also cell_faces.

Available after calling compute_geometry().

frac_num: int

Index of the fracture the grid corresponds to. Take value (0, 1, ...) if the grid corresponds to a fracture, -1 if not.

frac_pairs: ndarray

Indices of faces that are geometrically coinciding, but lay on different side of a lower-dimensional grid.

global_point_ind: ndarray

An array with shape=(num_nodes,) containing indices of each point, assigned during processing of mixed-dimensional grids created by gmsh.

Used to identify points that are geometrically equal, though on different grids.

Could potentially be used to identify such geometrically equal points at a later stage, but there is no guarantee that this will work.

history: list[str]

Information on the formation of the grid, such as the constructor, computations of geometry etc.

property id: int

Grid ID.

The returned attribute must not be changed. This may severely compromise other parts of the code, such as sorting in md grids.

The attribute is set in __new__(). This avoids calls to super().__init__ in child classes.

name: str

Name assigned to this grid.

nodes: ndarray

An array with shape=(ambient_dimension, num_nodes) containing node coordinates column-wise.

num_cells: int

Number of cells in the grid.

num_faces: int

Number of faces in the grid.

num_nodes: int

Number of nodes in the grid.

parent_cell_ind: ndarray

Index of parent the cell in the parent grid for grids that have refined sub-grids or are sub-grids of larger grids.

Defaults to a mapping to its own index with shape=(num_cells,).

periodic_face_map: ndarray

Index of periodic boundary faces, (shape=(2, num_periodic_faces), dtype=int).

Face index periodic_face_map[0, i] is periodic with face index periodic_face_map[1, i]. This attribute is set with set_periodic_map().

tags: dict[str, numpy.ndarray]

Tags allow to mark subdomains of interest.

The default tags are used to mark fractures, tips and domain boundaries. Tags are used for nodes, as well as faces. User tags can be provided in the constructor.

well_num: int

Index of the well associated to the grid. Takes a value in (0, 1, ..) if the grid corresponds to a well, -1 if not.