Grid module (grid.h)

Functions

PetscErrorCode setupCsemGrid(const fmParams params, DM *dm, Grid *grid)

Configures a DMPlex object with H(curl) and H1 sections for CSEM.

Configures a DMPlex object with H(curl) and H1 sections for CSEM.

This function sets up the primary DMPlex object for CSEM modeling using high-order edge (H(curl)) elements of order params.nord and a corresponding H1 conforming space. The following steps are performed:

  • Sets the number of fields in the DM to 1.

  • Creates a “Boundary” label and marks boundary faces with ID 100.

  • Computes degrees of freedom (DOFs) per vertex, edge, face, and volume according to the PETGEM basis order (params.nord).

  • Creates and attaches a PetscSection for H(curl) elements, applying boundary conditions on the marked faces.

  • Clones the DM to create the P_nord H1 DM (grid->H1dm_Pnord) used for the topological discrete-gradient (G_BDDC) column space.

  • Computes local and global counts of vertices, edges, faces, and cells.

  • Stores DOF counts, element start/end indices, and dimension in the grid struct.

  • Prints mesh and HEFEM statistics for verification.

Note

The function uses PETSc parallel reductions (MPI_Allreduce) to compute global mesh statistics and relies on PETSc DMPlex utilities to handle boundary labeling, section creation, and point numbering. Output is printed collectively using PETSc routines.

Parameters:

  • params – [in] Forward-modeling parameters (nord).

  • dm – [inout] DMPlex mesh configured with the FE sections.

  • grid – [out] Grid struct filled with mesh statistics and FEMSpace.

  • params – [in] Struct containing simulation parameters, especially the basis order params.nord and mesh filename.

  • dm – [inout] Pointer to the DMPlex object to configure with H(curl) and H1 sections.

  • grid – [out] Pointer to the Grid struct to be populated with mesh statistics, DOF counts, and the H1 DM.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PetscError code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

PetscErrorCode locatePoint(const DM dm, const PetscReal *position, PetscInt *pointInCell)

Locates the mesh cell containing a given point.

Locates the mesh cell containing a given point.

This function uses DMLocatePoints to determine which DMPlex cell owns the specified point coordinates. It performs a parallel check across all MPI ranks to ensure that the point is contained in at least one process. If the point is not found globally, the function raises a PETSc error.

Note

The search is performed collectively across all MPI processes using MPI_Allreduce with logical OR to ensure the point exists somewhere in the domain. Each process may return -1 if it does not own the point.

Note

A PETSc error is raised if the point is not located on any process.

Note

This function allocates a temporary Vec for point coordinates and a PetscSF for the search, both of which are destroyed before returning.

Parameters:

  • dm – [in] DMPlex mesh.

  • position – [in] Query point coordinates (x, y, z).

  • pointInCell – [out] Index of the containing cell (or a not-found marker).

  • dm – [in] DMPlex object representing the computational mesh.

  • position – [in] Array of size 3 containing the [x, y, z] coordinates of the point.

  • pointInCell – [out] Pointer to an integer where the index of the containing cell will be stored. Set to -1 if the point is not found locally.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PetscError code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code on failure.

PetscErrorCode extractCellCoordinates(const DM dm, const PetscInt cellID, Cell *cell)

Extracts the vertex coordinates of a given cell.

Extracts the vertex coordinates of a given cell.

This function retrieves the coordinates of all vertices of the specified cell from a DMPlex object and stores them in a user-provided Cell struct. It uses DMPlexGetCellCoordinates and DMPlexRestoreCellCoordinates to access the cell geometry safely.

Note

The function assumes that each cell has exactly NUM_VERTICES_PER_CELL vertices and each vertex has NUM_DIMENSIONS coordinates. If this is not satisfied, a PETSc error is raised.

Note

The coordinates are copied as PetscReal values into the cell->coordinates array.

Note

Temporary internal arrays returned by DMPlexGetCellCoordinates are restored before the function returns.

Parameters:

  • dm – [in] DMPlex mesh.

  • cellID – [in] Cell index.

  • cell – [inout] Cell whose coordinates field is filled.

  • dm – [in] DMPlex object representing the computational mesh.

  • cellID – [in] Global/local index of the cell to extract coordinates from.

  • cell – [out] Pointer to a Cell struct where the coordinates of the cell’s vertices will be stored. The struct is assumed to have sufficient space for NUM_VERTICES_PER_CELL * NUM_DIMENSIONS.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PetscError code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

PetscErrorCode extractCellConductivity(DM dmConductivity, Vec conductivity, PetscInt cellID, Cell *cell)

Extracts the conductivity components of a given cell.

This function retrieves the conductivity values associated with a specific cell from a PETSc Vec defined on a DMPlex object and stores them in a user-provided Cell struct. It uses DMPlexVecGetClosure and DMPlexVecRestoreClosure to access the local cell data safely.

Note

The function assumes each cell has exactly NUM_CONDUCTIVITY_COMPONENTS (3) conductivity values. If this is not satisfied, a PETSc error is raised.

Note

The conductivity values are copied as PetscReal into cell->conductivity.

Note

Temporary internal arrays returned by DMPlexVecGetClosure are restored before the function returns.

Parameters:

  • dmConductivity – [in] DM carrying the conductivity field.

  • conductivity – [in] Per-cell conductivity Vec.

  • cellID – [in] Cell index.

  • cell – [inout] Cell whose conductivity field is filled.

  • dmConductivity – [in] DMPlex object representing the conductivity field layout.

  • conductivity – [in] Vec containing the conductivity values defined on the mesh.

  • cellID – [in] Index of the cell to extract conductivity from.

  • cell – [out] Pointer to a Cell struct where the conductivity components for the cell will be stored. Assumes space for NUM_CONDUCTIVITY_COMPONENTS entries.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PetscError code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

PetscErrorCode extractCellMaterialID(DM dmMaterialsID, Vec materialsID, PetscInt cellID, Cell *cell)

Extracts the material id of a given cell.

Extracts the material id of a given cell.

This function retrieves the material identifier associated with a specific cell from a PETSc Vec defined on a DMPlex sub-DM (field 1 of the model section, 1 dof per cell) and stores it in a user-provided Cell struct. It uses DMPlexVecGetClosure and DMPlexVecRestoreClosure to access the local cell data safely.

The function works in parallel: each MPI rank operates on its local portion of the distributed mesh, and the materials_id Vec is the local vector obtained from the global-to-local scatter performed in loadCsemInputs.

Note

The function assumes each cell has exactly NUM_MATERIALS_ID_COMPONENTS (1) material ID value. A PETSc error is raised if this is not satisfied.

Note

The material ID is stored as a floating-point value in the PETSc Vec (since PETSc scalars are complex); PetscRealPart is used to extract the real part before casting to PetscInt.

Parameters:

  • dmMaterialsID – [in] DM carrying the material-id field.

  • materialsID – [in] Per-cell material-id Vec.

  • cellID – [in] Cell index.

  • cell – [inout] Cell whose material_id field is filled.

  • dmMaterialsID – [in] DMPlex sub-DM representing the materials_id field layout (1 dof per cell).

  • materialsID – [in] Local Vec containing the material IDs defined on the local mesh partition.

  • cellID – [in] Index of the cell to extract the material ID from.

  • cell – [out] Pointer to a Cell struct where the material ID will be stored in cell->material_id.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PetscError code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

PetscErrorCode extractCellClousure(const DM dm, const PetscInt cellID, Cell *cell)

Extracts the transitive closure of a given cell.

This function retrieves the transitive closure of a specified cell in a DMPlex mesh and stores it in a user-provided Cell struct. The closure contains all points (vertices, edges, faces, and the cell itself) that make up the cell, along with their orientation.

Note

The function uses DMPlexGetTransitiveClosure and DMPlexRestoreTransitiveClosure to access internal DMPlex data.

Note

Each entry in the closure array is a pair: (point, orientation).

Note

A PETSc error is raised if the closure size exceeds MAX_TRANSITIVE_CLOSURE_SIZE.

Parameters:

  • dm – [in] DMPlex mesh.

  • cellID – [in] Cell index.

  • cell – [inout] Cell whose closure/closureSize fields are filled.

  • dm – [in] DMPlex object representing the computational mesh.

  • cellID – [in] Index of the cell whose transitive closure is to be extracted.

  • cell – [out] Pointer to a Cell struct where the closure will be stored. Assumes space for MAX_TRANSITIVE_CLOSURE_SIZE * 2 integers. The field cell->closureSize will store the number of points in the closure.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PetscError code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

PetscErrorCode computeCellCentroid(Cell *cell)

Computes the geometric centroid (vertex barycenter) of a cell.

Computes the geometric centroid (vertex barycenter) of a cell.

Writes the result into cell->centroid (NUM_DIMENSIONS reals). The input cell->coordinates must already be populated by extractCellCoordinates. Used by the inversion smoother to weight neighbour graph edges by inverse cell-to-cell distance.

Parameters:

  • cell – [inout] Cell whose centroid field is filled.

  • cell – [inout] Cell struct; coordinates read, centroid written.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PetscError code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success.

PetscErrorCode printCellEntities(const DM dm, const PetscInt cell)

Prints connectivity and geometric information of a tetrahedral cell.

Prints connectivity and geometric information of a tetrahedral cell.

This function retrieves and prints the following information for a given cell:

  1. Transitive closure of the cell:

    • Includes all points (vertices, edges, faces) connected to the cell.

    • Prints the point index and its orientation.

  2. Face connectivity:

    • Indices of faces associated with the cell.

    • For each face:

      • Indices of edges forming the face.

      • Indices of vertices forming the face.

  3. Edge connectivity:

    • Indices of edges associated with the cell.

    • For each edge:

      • Indices of the two vertices defining the edge.

  4. Vertex coordinates:

    • Coordinates of each vertex in the cell in 3D space.

  5. Edge midpoints:

    • Computed as the average of the coordinates of the two vertices of the edge.

Note

  • Assumes tetrahedral cells with:

    • NUM_FACES_PER_CELL = 4

    • NUM_EDGES_PER_CELL = 6

    • NUM_VERTICES_PER_CELL = 4

    • NUM_VERTICES_PER_EDGE = 2

    • NUM_EDGES_PER_FACE = 3

    • NUM_VERTICES_PER_FACE = 3

  • Relies on DMPlex functions:

    • DMPlexGetTransitiveClosure for retrieving connected points

    • DMPlexGetCone for face-to-edge and edge-to-vertex connectivity

    • DMPlexGetCellCoordinates for vertex coordinates

Parameters:

  • dm – [in] DMPlex mesh.

  • cell – [in] Cell index.

  • dm – [in] The DMPlex object representing the unstructured mesh.

  • cell – [in] The index of the cell whose entities are to be printed.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PetscError code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success.

struct FEMSpace
#include <grid.h>

Finite-element space descriptor.

Bundles the fields needed by the hvfem routines (element matrices, gradient matrix, DOF signs) so those signatures do not need to carry nord + DOF counts separately.

DOF-class layout inside the per-cell H(curl) vector (length numDofInCell) matches PETSc DMPlex’s closure-traversal order (cell -> faces -> edges -> vertices), which is also what shape3DETet’s permutation table is built against: nord=1: edges only [edges 0..5] (6) nord=2: faces-then-edges [faces 0..7, edges 8..19] (20) nord=3: volume-faces-edges [volume 0..2, faces 3..26, edges 27..44] (45) nord=k (>=3) generally: [volume 0..nVol-1, faces nVol..nVol+nFace-1, edges nVol+nFace..numDofInCell-1]. The *Offset fields mark the first index of each class (== numDofInCell when the class is empty), so loops can iterate [offset, offset+count) without a per-order switch.

Public Members

PetscInt nord

Basis order (1, 2, 3, …).

PetscInt numDofInCell

Total H(curl) DOFs per cell.

PetscInt numH1DofInCell

P1 H1 DOFs per cell (= 4); vertex-column count for the topological G_BDDC builder.

PetscInt numH1DofInCell_Pnord

P_nord H1 DOFs per cell; column count of the topological G_BDDC discrete gradient.

PetscInt numDofPerEdge

H(curl) DOFs per edge.

PetscInt numDofPerFace

H(curl) DOFs per face.

PetscInt numDofPerVolume

H(curl) DOFs in the volume (interior).

PetscInt numEdgeDof

= NUM_EDGES_PER_CELL * numDofPerEdge.

PetscInt numFaceDof

= NUM_FACES_PER_CELL * numDofPerFace.

PetscInt numVolumeDof

= numDofPerVolume.

PetscInt faceDofOffset

First index of the face-DOF class.

PetscInt edgeDofOffset

First index of the edge-DOF class.

PetscInt volumeDofOffset

First index of the volume-DOF class.

const struct NedelecOps *ops

Per-order Nédélec dispatch (coefficients / basis / curls / gradient). Populated in setupCsemGrid; hot loops call through this table instead of a switch (nord).

struct CellOrientation
#include <grid.h>

Per-cell orientation data.

Built once in computeCellOrientation and consumed by the shape / basis / sign routines. A named struct replaces the earlier opaque orientation[10] layout so higher-order codes can extend it (e.g. per-face permutations for nord=3 face DOFs) without touching every accessor.

Public Members

PetscInt faces[NUM_FACES_PER_CELL]

Face-orientation code in {0..5}.

PetscInt edgeSigns[NUM_EDGES_PER_CELL]

±1 sign for each edge.

struct Grid
#include <grid.h>

Mesh statistics and DOF counts for a CSEM grid.

Public Members

PetscInt numCellsLocal

Number of local cells.

PetscInt numCellsGlobal

Number of global cells.

PetscInt numFacesLocal

Number of local faces.

PetscInt numFacesGlobal

Number of global faces.

PetscInt numEdgesLocal

Number of local edges.

PetscInt numEdgesGlobal

Number of global edges.

PetscInt numVerticesLocal

Number of local vertices.

PetscInt numVerticesGlobal

Number of global vertices.

PetscInt numDofInVertex

Number of DOFs per vertex.

PetscInt numDofInEdge

Number of DOFs per edge.

PetscInt numDofInFace

Number of DOFs per face.

PetscInt numDofInVolume

Number of DOFs per volume.

PetscInt numDofInCell

Number of DOFs per cell.

PetscInt cellStart

Index of global cell start.

PetscInt cellEnd

Index of global cell end.

PetscInt faceStart

Index of global face start.

PetscInt faceEnd

Index of global face end.

PetscInt edgeStart

Index of global edge start.

PetscInt edgeEnd

Index of global edge end.

PetscInt vertexStart

Index of global vertex start.

PetscInt vertexEnd

Index of global vertex end.

PetscInt dim

Number of spatial dimensions.

PetscInt numH1DofInCell

P1 H1 DOFs per cell (= 4 always); held by the topological gradient builder which writes ±1 vertex incidences into a 4-column scratch buffer before tail-padding into the P_nord H1 closure.

PetscInt numH1DofInCell_Pnord

P_nord H1 DOFs per cell (= (nord+1)(nord+2)(nord+3)/6); the column count of the G_BDDC discrete gradient produced by assembleCsemKandM.

DM H1dm_Pnord

P_nord H1 DM: column space of the topological G_BDDC discrete gradient. For nord = 1 it is the P1 vertex space; for nord >= 2 it adds edge/face/volume bubble DOFs per the De Rham complex.

FEMSpace fem

Finite-element space descriptor (mirrors nord + DOF counts).

struct Cell
#include <grid.h>

Per-cell geometry, material, and topology working data.

Public Members

PetscReal coordinates[NUM_VERTICES_PER_CELL * NUM_DIMENSIONS]

Vertex coords (4×3).

PetscReal conductivity[NUM_CONDUCTIVITY_COMPONENTS]

Cell conductivity (σx, σy, σz).

PetscInt material_id

Material id of the cell.

PetscInt closure[MAX_TRANSITIVE_CLOSURE_SIZE]

DMPlex transitive closure points.

PetscInt closureSize

Number of valid closure entries.

PetscReal jacobian[NUM_DIMENSIONS][NUM_DIMENSIONS]

Geometric Jacobian.

PetscReal invJacobian[NUM_DIMENSIONS][NUM_DIMENSIONS]

Inverse Jacobian.

PetscReal detJacobian

Jacobian determinant.

CellOrientation orientation

Face/edge orientation data.

PetscReal centroid[NUM_DIMENSIONS]

Cell centroid (vertex barycenter).