PETSc Shell Solvers#

This tutorial summarizes the PETSc shell-matrix demos:

  • tutorials/petsc_shell_poisson_demo.py

  • tutorials/petsc_shell_poisson_pmat_demo.py

They show how to wrap FluxFEM operators in PETSc shells for flexible preconditioning and matrix-free solves.

Prerequisites#

The demos require PETSc and petsc4py (the petsc extra). Install with:

poetry add fluxfem --extras "petsc"

Ensure PETSC_DIR (and optionally PETSC_ARCH) point to a valid PETSc build so petsc4py can import successfully. Once PETSc is configured, run:

Run the examples#

python tutorials/petsc_shell_poisson_demo.py
python tutorials/petsc_shell_poisson_pmat_demo.py

What the demos do#

  • Build a structured 2D Poisson residual and wrap its action in a PETSc shell matrix via ff.petsc_shell_solve.

  • Let PETSc control the Krylov method (ksp_type) and preconditioning via the options database.

  • Show both a pure shell solve with a diagonal preconditioner and a hybrid mode where pmat supplies an explicit matrix for PETSc preconditioners such as ILU or Jacobi.

Details per script#

  • tutorials/petsc_shell_poisson_demo.py keeps everything matrix-free and sets preconditioner="diag0" so PETSc only sees the shell operator.

  • tutorials/petsc_shell_poisson_pmat_demo.py still uses the shell for the mat-vec but passes pmat=A plus pc_type="jacobi" so PETSc can build an explicit preconditioner from the assembled stiffness while the shell retains flexibility for the operator action.

The pmat argument is handy whenever a preconditioner needs access to the numerical matrix or sparsity pattern even though the mat-vec is computed on the fly. These demos thus document both a fully matrix-free workflow and a hybrid matrix-preconditioner setup that keeps the best of both worlds.

Notes#

  • If PETSc is not installed, the scripts will raise during import.

  • The demos are a good starting point for matrix-free or hybrid preconditioning workflows inside FluxFEM.