Solver module (solver.h)

Functions

PetscErrorCode solveCsemSystem(const DM dm, const Mat A, const Mat B, const Mat G, const PetscInt order, 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 = order to capture the curl kernel for H(curl) problems. G is the high-order discrete gradient G: Nédélec_order -> P_order H1 from assembleCsemKandM.

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 exact order-p discrete gradient 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.

  • order – [in] Nédélec basis order (registered with the gradient in PCBDDC).

  • 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] High-order discrete-gradient hint for PCBDDC; may be NULL when A is not of type MATIS.

  • order – [in] Nedelec basis order (registered with the gradient in PCBDDC).

  • 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 (the high-order discrete gradient) 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 G is non-NULL, the preconditioner is set to PCBDDC and G is registered via PCBDDCSetDiscreteGradient(pc, G, 1, 0, PETSC_TRUE, PETSC_TRUE). When those conditions are not met the call is a no-op, so the caller’s default PC stays.

G is the high-order discrete gradient G : Nédélec_order –> P_order H1 produced by assembleCsemKandM (buildDiscreteGradientMatrix: 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 and K·G = 0). PCBDDC reads its sparsity (GᵀG) to build the curl-kernel coarse space.

The discrete gradient is the high-order operator G : Nedelec_order -> P_order H1, so it is registered at order = order (matching the column space of G); the coarse-space collapse is driven by G’s sparsity/values together with that order argument.

Parameters:

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

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

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

  • order – [in] Nédélec basis order registered with the gradient.

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

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

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

  • order – [in] Nedelec basis order registered with the gradient.

Returns:

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

Returns:

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