Assembly module (assembly.h)

Functions

PetscErrorCode assembleCsemRHS(const fmParams 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 (nord, 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 (nord, 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 assembleCsemKandM(const fmParams 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 : lowest-Whitney topological gradient consumed by PCBDDCSetDiscreteGradient at order = 1. Each H(curl) edge DOF couples to its two endpoint vertex H1 DOFs (±1); higher-order rows and inter-bubble columns are zero. Built against grid.H1dm_Pnord so a single 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_BDDC - topological lowest-Whitney gradient against the P_nord H¹ DM (grid.H1dm_Pnord) with vertex incidence only. Inter-bubble columns never enter the sparsity pattern: G_BDDC is built with MAT_IGNORE_ZERO_ENTRIES and a 4-nnz/row preallocation, so no MatFilter pass is required. Consumed by PCBDDCSetDiscreteGradient at order = 1.

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_BDDC may be passed as NULL to skip its construction (e.g. callers that don’t go through PCBDDC).

Parameters:

  • params – [in] Forward-modeling parameters (nord, 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_BDDC – [out] Topological discrete gradient; pass NULL to skip.

Returns:

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

PetscErrorCode assembleCsemMsRefill(const fmParams 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 / nord (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_BDDC 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 (nord).

  • 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 (nord).

  • 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.