Fem module (fem.h)

Functions

PetscErrorCode computeVectorRotation(const PetscReal azimuth, const PetscReal dip, PetscReal rotationVector[NUM_DIMENSIONS])

Computes a 3D unit vector from sequential azimuth/dip rotations.

This function builds the weights vector for source rotation in the xyz frame by composing the azimuth (x-y plane) and dip (x-z plane) rotation matrices and applying them to the base x-directed unit vector. Angles are given in degrees.

Parameters:

azimuth – [in] Azimuth angle (degrees).
dip – [in] Dip angle (degrees).
rotationVector – [out] Resulting unit direction vector.
azimuth – [in] Azimuth angle in degrees (x-y plane rotation).
dip – [in] Dip angle in degrees (x-z plane rotation).
rotationVector – [out] Resulting rotated unit direction vector.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

PetscErrorCode tetrahedronXYZToReference(const PetscReal coordinates[NUM_VERTICES_PER_CELL * NUM_DIMENSIONS], const PetscReal point[NUM_DIMENSIONS], PetscReal XiEtaZeta[NUM_DIMENSIONS])

Maps global Cartesian coordinates to reference-tetrahedron coordinates.

Produces the reference point in the same frame the Nedelec/H1 reference bases are defined on, so the result feeds evaluateNedelecBasis directly.

Maps global Cartesian coordinates to reference-tetrahedron coordinates.

This function applies the reference-consistent affine inverse of the cell’s geometric map, returning the (xi, eta, zeta) coordinates of a global point on the reference tetrahedron whose vertex labelling matches the Nedelec / H1 reference bases. The four cell vertices are given row-major (4x3).

Parameters:

coordinates – [in] Cell vertex coordinates (4 vertices x 3 dims).
point – [in] Global point to map.
XiEtaZeta – [out] Reference coordinates of the point.
coordinates – [in] Cell vertex coordinates (4x3, row-major).
point – [in] Global point to map.
XiEtaZeta – [out] Reference-cell coordinates of the point.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

PetscErrorCode computeCellJacobian(Cell *cell)

Computes a cell’s geometric Jacobian, its inverse, and determinant.

Geometry helper used for point location / degeneracy checks. The FE routines compute their own reference-consistent Jacobian internally from the cell vertex coordinates, so callers do not need to feed this back into them.

Computes a cell’s geometric Jacobian, its inverse, and determinant.

This function fills the cell’s jacobian (rows (v1-v0), (v2-v0), (v3-v0)), its inverse (from the adjugate) and its determinant. It is used for point location and degeneracy checks; the FE routines build their own reference-consistent Jacobian internally.

Parameters:

cell – [inout] Cell whose jacobian/invJacobian/detJacobian are filled.
cell – [inout] Cell whose jacobian/invJacobian/detJacobian are filled.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

PetscErrorCode computeNum3DQuadraturePoints(const PetscInt order, Quadrature3D *quadrature)

Sets the number of 3D quadrature points for a tetrahedron.

One quadrature path for every order: a Stroud conical rule with (order+1) points per axis, exact to degree 2*order+1 (covers the degree-2*order mass-matrix integrand on an affine tetrahedron). Total (order+1)^3 points.

This function selects the single quadrature path used for every order: a Stroud conical rule with order+1 points per axis, exact to degree 2*order+1, which covers the degree-2*order mass-matrix integrand on an affine tetrahedron. It stores the total point count (order+1)^3 in the rule.

Parameters:

order – [in] Basis order driving the quadrature degree.
quadrature – [out] Rule whose numPoints is set.
order – [in] Basis order driving the quadrature degree.
quadrature – [out] Rule whose numPoints is set.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

PetscErrorCode compute3DQuadraturePoints(Quadrature3D *quadrature)

Populates 3D Gauss quadrature points and weights for a tetrahedron.

The point/weight convention matches the reference element bases: points on the unit reference tetrahedron, weights summing to its volume 1/6.

Populates 3D Gauss quadrature points and weights for a tetrahedron.

This function recovers the per-axis point count m = order+1 from the stored numPoints (a perfect cube) and fills the rule’s points and weights via the Stroud conical construction on the unit reference tetrahedron.

Parameters:

quadrature – [inout] Rule (numPoints set) whose points/weights fill.
quadrature – [inout] Rule (numPoints set) whose points/weights are filled.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

PetscErrorCode computeElementalMatrices(const FEMSpace *fem, const Cell *cell, const Quadrature3D *quadrature, PetscReal **Me, PetscReal **Ke)

Computes the elemental mass and stiffness matrices for a cell.

Me_jk = INT (sigma * N_j) . N_k (mass weighted by the cell conductivity) Ke_jk = INT curl N_j . curl N_k (stiffness, mu_r = identity)

Orientation and the value/curl Piola pullbacks are applied internally, so the returned blocks are physical and ready to insert in DMPlex closure order.

This function builds the cell Jacobian and delegates to the reference core to accumulate the conductivity-weighted mass Me and the stiffness Ke over the given quadrature rule. Orientation and the Piola pullbacks are applied internally, so the returned blocks are physical and in DMPlex closure order.

Parameters:

fem – [in] Finite-element space descriptor (order, DOF counts).
cell – [in] Cell geometry and conductivity.
quadrature – [in] 3D quadrature rule.
Me – [out] Elemental mass matrix (numDofInCell x numDofInCell).
Ke – [out] Elemental stiffness matrix (numDofInCell x numDofInCell).
fem – [in] Finite-element space descriptor (order, DOF counts).
cell – [in] Cell geometry and conductivity.
quadrature – [in] 3D quadrature rule.
Me – [out] Elemental mass matrix (numDofInCell x numDofInCell).
Ke – [out] Elemental stiffness matrix (numDofInCell x numDofInCell).

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

PetscErrorCode buildDiscreteGradientMatrix(const FEMSpace *fem, const Cell *cell, PetscReal **gradientMatrix)

Builds the high-order discrete gradient block G_e for one cell (the curl-kernel operator consumed by PCBDDCSetDiscreteGradient).

grad(phi_k) = sum_i G_ik N_i, with rows = Nedelec DOFs and columns = P_order H1 DOFs, both in DMPlex closure order; sparse after thresholding, so K.G = 0.

Builds the high-order discrete gradient block G_e for one cell (the curl-kernel operator consumed by PCBDDCSetDiscreteGradient).

This function delegates to the reference core to build the per-cell discrete gradient block G_e (rows = Nedelec DOFs, columns = P_order H1 DOFs, both in DMPlex closure order), the curl-kernel operator consumed by PCBDDCSetDiscreteGradient.

Parameters:

fem – [in] FE space descriptor.
cell – [in] Cell geometry.
gradientMatrix – [out] Block sized numDofInCell x numH1DofInCell.
fem – [in] FE space descriptor.
cell – [in] Cell geometry.
gradientMatrix – [out] Block sized numDofInCell x numH1DofInCell_Porder.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

PetscErrorCode evaluateNedelecBasis(const FEMSpace *fem, const Cell *cell, const PetscReal point[NUM_DIMENSIONS], PetscReal **Ni, PetscReal **NiCurl)

Evaluates the Nedelec basis (and optionally curls) at a reference point.

The returned values/curls are physical and oriented. Pass NiCurl = NULL to skip the curl evaluation (e.g. RHS source integrals).

This function builds the cell Jacobian and evaluates the physical, oriented Nedelec basis values (and curls) at the given reference point. Passing NiCurl = NULL skips returning the curls (a scratch buffer is used internally, since the reference evaluator always produces them).

Parameters:

fem – [in] Finite-element space descriptor.
cell – [in] Cell geometry.
point – [in] Reference-cell evaluation point.
Ni – [out] Basis-function values: Ni[d][dof], d in [0,3).
NiCurl – [out] Basis-curl values: NiCurl[d][dof] (NULL to skip).
fem – [in] Finite-element space descriptor.
cell – [in] Cell geometry.
point – [in] Reference-cell evaluation point (3).
Ni – [out] Basis-function values: Ni[d][dof], d in [0,3).
NiCurl – [out] Basis-curl values: NiCurl[d][dof] (NULL to skip).

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

struct Quadrature3D

#include <fem.h>

3D (tetrahedron) Gauss quadrature rule (points and weights).

Public Members

PetscInt numPoints: Number of quadrature points.

PetscReal **points: Quadrature point coordinates (per point, 3 reals).

PetscReal *weights: Quadrature weights.