Assembly module (assembly.h)

Functions

PetscErrorCode assembleCsemRHS(const petgemParams params, const CsemSourceSet sources, const DM dm, const Grid grid, const PetscScalar constFactor, Mat *B)

Assembles the CSEM right-hand side matrix.

Produces B with one column per transmitter, with Dirichlet boundary DOFs eliminated, ready for solveCsemSystem.

Assembles the CSEM right-hand side matrix.

Constructs the RHS vectors for every transmitter in the simulation; each column of B corresponds to one source. Performs finite-element assembly using H(curl) Nédélec elements, taking the source dipole orientation, rotation, and position into account.

For each source the function (a) locates it in the mesh via locatePoint, (b) extracts cell coordinates and computes the Jacobian, (c) maps the source position to reference coordinates (ξ, η, ζ), (d) evaluates the Nédélec basis and its curls there, (e) writes the local contributions into a per-source RHS Vec, and (f) copies the assembled Vec into the corresponding column of B. A final complex scaling by iωμ is applied.

Note

The caller is responsible for destroying the returned matrix B.

Parameters:

  • params – [in] Forward-modeling parameters (order, MPI tasks).

  • sources – [in] Transmitter set (one column of B per source).

  • dm – [in] DMPlex mesh and H(curl) discretization.

  • grid – [in] Finite-element grid descriptor.

  • constFactor – [in] Fused-mode factor iωμ; ignored when Ms != NULL.

  • B – [out] Assembled right-hand side matrix.

  • params – [in] Forward-modeling parameters (order, MPI tasks).

  • sources – [in] Transmitter set (one column of B per source).

  • dm – [in] DMPlex mesh and H(curl) discretization.

  • grid – [in] Finite-element grid descriptor.

  • constFactor – [in] Fused-mode factor iωμ; ignored when Ms != NULL.

  • B – [out] Assembled RHS matrix, created and populated by this call.

Returns:

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

Returns:

PetscErrorCode PETSC_SUCCESS on successful assembly, or a PETSc error code on failure of vector/matrix creation, FEM basis evaluation, or point location.

PetscErrorCode assembleCsemMMSRHS(const petgemParams params, const CsemSourceSet sources, const DM dm, const Grid grid, const Vec conductivity, const PetscBool useForcing, Mat *B)

Assembles the volumetric manufactured-source RHS for MMS verification.

Replaces the point-dipole RHS (assembleCsemRHS) when running in MMS mode (-mms). Instead of a Dirac source in one cell, it integrates the manufactured forcing f* (include/mms.h) against the Nedelec basis over EVERY cell: 

b_j = sum_cells sum_q  w_q * detJ_cell * ( N_j(x_q) . f*(x_q) )
where x_q is the physical image of reference quadrature point q, f* is complex, and the same (weights, detJ) measure as computeElementalMatrices is used so b is consistent with the operator A = K - i omega mu Ms. The single manufactured RHS is written to a one-column dense matrix B. Boundary DOFs are eliminated via VEC_IGNORE_NEGATIVE_INDICES (E* already satisfies n x E* = 0). No final iωμ scaling is applied - f* already carries it.

With useForcing = PETSC_TRUE the integrand is the manufactured forcing f* (the ordinary MMS solve RHS). With useForcing = PETSC_FALSE it is the exact field E* itself, i.e. b_j = sum ∫ E*·N_j - the L2 moments used by the E3 projection/interpolation baseline (no iωμ, no sigma).

MMS counterpart of assembleCsemRHS: instead of a Dirac dipole located in a single cell, it integrates the manufactured forcing f* (include/mms.h) over every local cell, 

b_j = sum_cells sum_q  w_q * detJ_cell * ( N_j(x_q) . f*(x_q) ),
reusing the SAME quadrature rule and (weights, detJ) measure as computeElementalMatrices, so the RHS is consistent with the operator A = K - i omega mu Ms that assembleCsemKandM builds. Contributions from cells sharing an edge/face DOF accumulate (ADD_VALUES); boundary DOFs are skipped (negative closure indices + VEC_IGNORE_NEGATIVE_INDICES), which is exact since n x E* = 0. The single manufactured RHS is written into a one-column dense B.

Note

The caller is responsible for destroying the returned matrix B.

Parameters:

  • params – [in] Forward-modeling parameters (order, MPI tasks).

  • sources – [in] Transmitter set; only sources.freq (-> omega) is used.

  • dm – [in] DMPlex mesh and H(curl) discretization.

  • grid – [in] Finite-element grid descriptor.

  • conductivity – [in] Per-cell conductivity Vec (diagonal sigma in f*).

  • useForcing – [in] PETSC_TRUE: integrate f*; PETSC_FALSE: integrate E*.

  • B – [out] One-column dense RHS matrix (created by this call).

  • params – [in] Forward-modeling parameters (order, MPI tasks).

  • sources – [in] Transmitter set; only sources.freq (-> omega) is used.

  • dm – [in] DMPlex mesh and H(curl) discretization.

  • grid – [in] Finite-element grid descriptor.

  • conductivity – [in] Per-cell conductivity Vec (diagonal sigma in f*).

  • B – [out] One-column dense RHS matrix, created by this call.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code.

PetscErrorCode assembleCsemKandM(const petgemParams params, const DM dm, const Grid grid, const Vec conductivity, const PetscScalar constFactor, Mat *KorA, Mat *Ms, Mat *G_BDDC)

Assembles the CSEM left-hand side operator (unified K/Ms or fused).

Two output modes, selected by the Ms pointer:

Ms != NULL (K/Ms mode, used by the inverse kernel): *KorA receives the curl-curl stiffness K, *Ms receives the mass-σ matrix Ms. The frequency-dependent operator A_f = K − iωμ·Ms is formed by the caller per frequency via MatDuplicate + MatAXPY. constFactor is ignored in this mode.

Ms == NULL (fused mode, used by the forward kernel): *KorA receives the frequency-dependent operator A = K − constFactor·Ms directly, formed by per-cell element-level fusion A_e = K_e − constFactor·M_e, so Ms is never built as a global matrix. Saves one full complex matrix from the assembly-phase peak memory, one MatDuplicate, and one global MatAXPY. The caller passes constFactor = iωμ.

Matrices:

  • K : curl-curl stiffness, ∫_K (μ⁻¹ curl Ni)·curl Nj.

  • Ms : mass × σ, ∫_K (ε_r ⊙ Ni)·Nj.

  • G_BDDC : high-order discrete gradient (buildDiscreteGradientMatrix) consumed by PCBDDCSetDiscreteGradient. Each H(curl) DOF’s gradient is resolved against the full P_order H1 closure, so grad(phi_k) = sum_i G_ik N_i exactly (K·G = 0). Built against grid.H1dm_P_order; one solver code path serves every order.

Assembles the CSEM left-hand side operator (unified K/Ms or fused).

Single-pass element loop that assembles the frequency-INDEPENDENT pieces of the CSEM operator and the discrete-gradient hint matrices:

K - stiffness (curl–curl) matrix, ∫ (μ⁻¹ curl N_i)·curl N_j. Ms - mass × σ matrix, ∫ (ε_r ⊙ N_i)·N_j where ε_r encodes σ. G - high-order discrete gradient (buildDiscreteGradientMatrix) Consumed by PCBDDCSetDiscreteGradient.

The caller forms A_f = K − iωμ·Ms per frequency via MatDuplicate(K, MAT_COPY_VALUES, &A); MatAXPY(A, -iωμ, Ms, SAME_NONZERO_PATTERN);

  • the forward kernel does this once for the source frequency, the inverse kernel does it inside a frequency loop.

G may be passed as NULL to skip its construction (e.g. callers that don’t go through PCBDDC).

Parameters:

  • params – [in] Forward-modeling parameters (order, MPI tasks).

  • dm – [in] DMPlex mesh and H(curl) discretization.

  • grid – [in] Finite-element grid descriptor.

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

  • constFactor – [in] Fused-mode factor iωμ; ignored when Ms != NULL.

  • KorA – [out] Stiffness K (K/Ms mode) or fused operator A.

  • Ms – [out] Mass-σ matrix in K/Ms mode; pass NULL for fused mode.

  • G – [out] High-order discrete gradient; pass NULL to skip.

  • params – [in] Forward-modeling parameters (order, MPI tasks).

  • dm – [in] DMPlex mesh and H(curl) discretization.

  • grid – [in] Finite-element grid descriptor.

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

  • constFactor – [in] Fused-mode factor iωμ; ignored when Ms != NULL.

  • KorA – [out] Stiffness K (K/Ms mode) or fused operator A.

  • Ms – [out] Mass-σ matrix in K/Ms mode; pass NULL for fused mode.

  • G – [out] High-order discrete gradient; pass NULL to skip.

Returns:

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

Returns:

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

PetscErrorCode assembleCsemMsRefill(const petgemParams params, const DM dm, const Grid grid, const Vec conductivity, const Quadrature3D *quadrature_3d, PetscReal **Me, PetscReal **Ke, Mat Ms)

Refills an existing Ms matrix for the current conductivity field.

Used by the inverse kernel inside the L-BFGS loop: K and G_BDDC are σ-independent and built once at setup via assembleCsemKandM, while Ms must be re-computed every iteration when σ changes. fm.csem does NOT use this - its fused single-pass call to assembleCsemKandM is unchanged.

Preconditions:

  • Ms is already allocated with the same sparsity pattern as the K produced by assembleCsemKandM for the same mesh / order (typically MatDuplicate(K, MAT_DO_NOT_COPY_VALUES, &Ms)).

  • quadrature_3d, Me, Ke are caller-owned workspace buffers of the same shape used inside assembleCsemKandM (numDofInCell² for Me / Ke), passed in so a single allocation can serve all iterations.

On return Ms holds the σ-dependent mass-matrix entries with its sparsity preserved. Ke is computed by computeElementalMatrices but is unused here (kept in the signature so the caller can share the gradient-pass scratch).

Inverse-kernel companion to assembleCsemKandM: walks the local cells, computes only the mass-matrix entries for the current sigma, and writes them into the supplied Ms matrix. K and G are NOT touched - those are sigma-independent, built once at setup, and reused for every L-BFGS iteration.

The per-cell setup is shared with assembleCsemKandM via prepareCellForAssembly (single source of truth for cell geometry, conductivity slice, closure, and orientation). Ke is computed by computeElementalMatrices (it shares basis evaluations with Me) but is discarded - the small extra work is offset by not having to duplicate the basis-evaluation code.

Parameters:

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

  • dm – [in] DMPlex mesh and H(curl) discretization.

  • grid – [in] Finite-element grid descriptor.

  • conductivity – [in] Current per-cell conductivity Vec.

  • quadrature_3d – [in] Caller-owned 3D quadrature workspace.

  • Me – [inout] Scratch elemental mass buffer (numDofInCell²).

  • Ke – [inout] Scratch elemental stiffness buffer (unused output).

  • Ms – [inout] Pre-allocated matrix refilled with mass-σ entries.

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

  • dm – [in] DMPlex mesh and H(curl) discretization.

  • grid – [in] Finite-element grid descriptor.

  • conductivity – [in] Current per-cell conductivity Vec.

  • quadrature_3d – [in] Caller-owned 3D quadrature workspace.

  • Me – [inout] Scratch elemental mass buffer (numDofInCell²).

  • Ke – [inout] Scratch elemental stiffness buffer (unused output).

  • Ms – [inout] Pre-allocated matrix refilled with mass-σ entries.

Returns:

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

Returns:

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