Solvers API Reference

Linear solver functionality in SafePETSc.

Type

SafePETSc.KSP — Type
KSP{T}

A PETSc KSP (Krylov Subspace) linear solver with element type T, managed by SafePETSc's reference counting system.

KSP{T} is actually a type alias for DRef{_KSP{T}}, meaning solvers are automatically tracked across MPI ranks and destroyed collectively when all ranks release their references.

KSP objects can be reused for multiple linear systems with the same matrix, avoiding the cost of repeated factorization or preconditioner setup.

Sparse Matrices Only

KSP solvers only work with sparse coefficient matrices (MPIAIJ). The KSP always uses the MPIAIJ prefix internally. For matrix right-hand sides (solving AX = B), the RHS matrix B must be dense (MPIDENSE).

Construction

See the KSP constructor for creating solver instances.

Usage

KSP solvers can be used implicitly via the backslash operator, or explicitly for reuse:

# Implicit (creates and destroys solver internally)
x = A \ b

# Explicit (reuse solver for multiple solves)
ksp = KSP(A)
x1 = similar(b)
x2 = similar(b)
LinearAlgebra.ldiv!(ksp, x1, b1)  # First solve
LinearAlgebra.ldiv!(ksp, x2, b2)  # Second solve with same matrix

See also: Mat, Vec, the KSP constructor

Initialization

SafePETSc.Init — Function
Init() -> nothing

MPI Collective

Ensure MPI and PETSc are initialized in the recommended order (MPI first, then PETSc). Safe to call multiple times. Does not register custom finalizers; rely on library defaults for shutdown (MPI.jl finalizes at exit; PETSc may remain initialized).

Sets up PETSc options for prefix types:

  • MPIDENSE: Dense matrices with -MPIDENSE_mat_type mpidense -MPIDENSE_vec_type mpi
  • MPIAIJ: Sparse matrices with -MPIAIJ_mat_type mpiaij

If STRUMPACK is available (detected via has_strumpack), it is automatically configured as the default direct solver for sparse matrices: -MPIAIJ_pc_type lu -MPIAIJ_pc_factor_mat_solver_type strumpack

See also: has_strumpack, build_petsc_strumpack

SafePETSc.Initialized — Function
Initialized() -> Bool

MPI Non-Collective

Return true if both MPI and PETSc are initialized. This is a simple conjunction of MPI.Initialized() and PETSc.initialized for the active PETSc library.

SafePETSc.petsc_options_insert_string — Function
petsc_options_insert_string(options_string::String)

MPI Collective

Insert command-line style options into PETSc's global options database.

Example: petsc_options_insert_string("-dense_mat_type mpidense")

This sets options that will be used by PETSc objects created with the corresponding prefix. PETSc must already be initialized by the caller.

SafePETSc.has_strumpack — Function
has_strumpack() -> Bool

MPI Non-Collective

Check if the currently loaded PETSc library has STRUMPACK support.

This function checks if JULIA_PETSC_LIBRARY points to a STRUMPACK-enabled build. It is used by Init() to automatically configure STRUMPACK as the default direct solver when available.

Example

if has_strumpack()
    println("STRUMPACK is available in the current PETSc library")
end

See also: Init

Linear Solves

Direct Solve

# Vector RHS
x = A \ b                              # Solve Ax = b
x = A' \ b                             # Solve A^T x = b

# Matrix RHS (must be dense)
X = A \ B                              # Solve AX = B
X = A' \ B                             # Solve A^T X = B

Reusable Solver with inv(A)

# Create reusable solver (factorization happens here)
Ainv = inv(A)                          # Returns KSP object

# Left multiplication (solve Ax = b)
x = Ainv * b                           # Solve Ax = b
X = Ainv * B                           # Solve AX = B

# Transpose solver
Aitinv = inv(A')                       # Returns Adjoint{KSP}
x = Aitinv * b                         # Solve A'x = b
X = Aitinv * B                         # Solve A'X = B

# Right multiplication (solve xA = b)
xt = b' * Ainv                         # Solve x'A = b' (returns adjoint)
X = B * Ainv                           # Solve XA = B
X = B' * Ainv                          # Solve XA = B'

In-Place Solve

# Vector RHS
LinearAlgebra.ldiv!(x, A, b)           # x = A \ b
LinearAlgebra.ldiv!(ksp, x, b)         # Using reusable solver

# Matrix RHS (must be dense)
LinearAlgebra.ldiv!(X, A, B)           # X = A \ B
LinearAlgebra.ldiv!(ksp, X, B)         # Using reusable solver

Right Division

# Vector
x_adj = b' / A                         # Solve x^T A = b^T

# Matrix (must be dense)
X = B / A                              # Solve XA = B
X = B / A'                             # Solve XA^T = B

Properties

m, n = size(ksp)                       # KSP matrix dimensions