Solver module (solver.h)

Functions

PetscErrorCode solveCsemSystem(const DM dm, const Mat A, const Mat B, const Mat G, Mat *X)

Solves the linear system A·X = B using PETSc KSP.

When A is a MATIS matrix and G is provided, the preconditioner is set to PCBDDC and G is registered via PCBDDCSetDiscreteGradient at order = 1 to capture the curl kernel for H(curl) problems. G is the topological lowest-Whitney gradient G_BDDC : Nédélec_k → P_nord H1 from assembleCsemKandM. (A denser, exact P_nord gradient was removed: its face/volume couplings violate PCBDDC’s coarse-edge model — every coarse edge must resolve to exactly two corner nodes — and abort PCBDDCNedelecSupport at nord ≥ 3. See solver.c.)

Solves the linear system A·X = B using PETSc KSP.

Drives a single KSP over every column of B via KSPMatSolve, which is how the forward kernel solves for all CSEM sources simultaneously. The preconditioner is set up through setupBDDCFromPetgemGradient: when A is of type MATIS and G is supplied, PCBDDC is configured with the topological discrete gradient at order 1 to capture the curl kernel of the H(curl) operator; otherwise PETSc’s default PC is used. The KSP type, tolerances and PC settings stay overridable through the PETSc options database (KSPSetFromOptions).

Steps:

  1. Create the KSP on dm's communicator and set A as both the operator and the preconditioner matrix.

  2. Configure PCBDDC from G (a no-op unless A is MATIS and G given).

  3. Read solver options with KSPSetFromOptions.

  4. Allocate the dense solution matrix X, matched to B's layout and A's vector type.

  5. Solve all right-hand sides with KSPMatSolve, reporting progress.

  6. Destroy the KSP.

Note

B must have a size and ordering consistent with A, and G (when used) must match the DOF ordering of A.

Parameters:

  • dm – [in] DMPlex mesh; its communicator drives the parallel solve.

  • A – [in] System matrix (H(curl) FEM operator).

  • B – [in] Right-hand side matrix, one column per source.

  • G – [in] Discrete-gradient hint for PCBDDC; may be NULL when A is not of type MATIS.

  • X – [out] Solution matrix, created internally (caller destroys).

  • dm – [in] DMPlex mesh; its communicator drives the parallel solve.

  • A – [in] System matrix (H(curl) FEM operator).

  • B – [in] Right-hand side matrix, one column per source.

  • G – [in] Topological discrete-gradient hint for PCBDDC; may be NULL when A is not of type MATIS.

  • X – [out] Solution matrix, created internally (the caller destroys it).

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 setupBDDCFromPetgemGradient(KSP ksp, Mat A, Mat Gbddc, PetscInt order)

Configures ksp’s PC as PCBDDC with the discrete-gradient hint, if the operator is MATIS and a gradient was supplied.

Shared helper that captures the single BDDC policy used by both the forward solver (solveCsemSystem) and the inverse solver (createInvKSP): when A is of type MATIS and Gbddc is non-NULL, set PC to PCBDDC and register Gbddc via PCBDDCSetDiscreteGradient(…, order, 0,

PETSC_TRUE, PETSC_TRUE). When the conditions are not met the function is a no-op so the caller’s existing default PC stays in place.

Configures ksp’s PC as PCBDDC with the discrete-gradient hint, if the operator is MATIS and a gradient was supplied.

Shared helper that captures the single PCBDDC + Nédélec discrete-gradient policy used by BOTH kernels: the forward solver (solveCsemSystem) and the inverse solver (createInvKSP). When A is of type MATIS and Gbddc is non-NULL, the preconditioner is set to PCBDDC and Gbddc is registered via PCBDDCSetDiscreteGradient(pc, Gbddc, order, 0, PETSC_TRUE, PETSC_TRUE). When those conditions are not met the call is a no-op, so the caller’s default PC stays in place.

Gbddc is the TOPOLOGICAL gradient G_BDDC : Nédélec_k → P_nord H1 produced by assembleCsemKandM (lowest-Whitney vertex incidence per mesh edge; the higher-order edge / face / volume rows are zero, so K·G_BDDC ≠ 0 by design). BDDC uses it only as a structural hint to identify the curl-kernel coarse space (∇P_1 ⊂ Nédélec_1 ⊂ Nédélec_k); the higher-order H(curl) DOFs are static-condensed internally. Because G_BDDC only ever fills the lowest Whitney slot per edge, order must be 1 regardless of the basis order fm.nord — both kernels pass order = 1.

A denser, mathematically exact canonical Π^Ned gradient against P_nord H1 was historically a separate assembleCsemKandM output for K·G analysis, but it was never passed to PCBDDC: its face / volume couplings violate the edge-cluster nnz budget BDDC checks in PCBDDCNedelecSupport (every coarse edge must resolve to exactly two corner nodes, else “SIZE OF EDGE > EXTCOL SECOND PASS” at nord ≥ 3), and has been removed as unused.

Parameters:

  • ksp – [inout] KSP whose preconditioner is configured.

  • A – [in] System matrix (probed for MATIS).

  • Gbddc – [in] Discrete-gradient hint (may be NULL).

  • order – [in] Polynomial order passed to PCBDDCSetDiscreteGradient.

  • ksp – [inout] KSP whose preconditioner is configured.

  • A – [in] System matrix (probed for the MATIS type).

  • Gbddc – [in] Discrete-gradient hint; may be NULL.

  • order – [in] Polynomial order forwarded to PCBDDCSetDiscreteGradient (always 1 here; see above).

Returns:

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

Returns:

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