Rodin::PETSc module

PETSc storage, assembly and linear/nonlinear solver adapters.

PETSc-backed trial/test functions connect Rodin variational forms to PETSc matrices, vectors, Krylov solvers and nonlinear solvers. The mesh execution context determines whether those objects are local or distributed. Backends and supported configurations describes the relationship between context, assembly strategy and algebraic storage.

Object lifetime

Initialize PETSc before constructing its objects. Destroy Rodin objects owning PETSc matrices, vectors and solver contexts before finalization.

PetscErrorCode ierr = PetscInitialize(&argc, &argv, PETSC_NULLPTR, PETSC_NULLPTR);
assert(ierr == PETSC_SUCCESS);
{
  // Construct and use PETSc-backed spaces, fields, forms and solvers here.
}
ierr = PetscFinalize();
assert(ierr == PETSC_SUCCESS);

In distributed programs, the MPI environment and communicator must also outlive their borrowers. Collective operations require participation in the same order on all ranks. See Distributed computing with MPI for partitioning, ownership, ghost data and collective queries.

Variational storage and solvers

Construct PETSc trial and test functions on a compatible finite element space.

P1 space(mesh);
PETSc::Variational::TrialFunction u(space);
PETSc::Variational::TestFunction v(space);
Problem poisson(u, v);
poisson = Integral(Grad(u), Grad(v)) - Integral(f, v)
        + DirichletBC(u, Zero());
PETSc::Solver::KSP solver(poisson);
solver.solve();

This fragment assumes the mesh, right-hand side and required connectivity have already been prepared. It must execute within the initialized scope. Select KSP and preconditioner settings for the actual matrix properties and inspect convergence status. Parallel solvers and distributed linear algebra with PETSc contains a complete Poisson program and explicit command-line configuration.

Multiple trial/test pairs represent coupled systems, including velocity, pressure and pressure-mean constraints for Stokes flow. The field-split preconditioner must use the corresponding field index sets and block names. Its configuration depends on the formulation and block ordering; see the multivariable examples linked from Examples and tutorials and the field-split discussion in Parallel solvers and distributed linear algebra with PETSc.

SNES handles nonlinear residual and Jacobian callbacks. Their state updates, assembly and convergence criteria must be consistent with the nonlinear weak problem.

Submodules

ModuleRole
MathMatrix, vector and linear-system handles
VariationalPETSc-backed fields, forms and problems
AssemblySequential, OpenMP and distributed assembly specializations
SolverLinear and nonlinear solver adapters

Configure Rodin with RODIN_USE_PETSC=ON; distributed execution additionally requires its MPI configuration. Availability of a particular solver, factorization or preconditioner depends on the PETSc installation.

Namespaces

namespace Assembly
PETSc-specific assembly strategies.
namespace Math
PETSc-backed linear algebra adapters.
namespace Solver
PETSc-backed linear and nonlinear solver adapters.
namespace Variational
PETSc-backed variational form adapters.

Classes

template<class Handle>
class Object
RAII base class for wrappers around PETSc opaque handles.

Typedefs

using Scalar = PetscScalar
Scalar type used by PETSc vectors and matrices.
using Integer = PetscInt
Integer index type used by PETSc row/column indices.
using Real = PetscReal
Real-valued floating-point type (tolerances, norms, etc.).
using Complex = PetscComplex
Complex scalar type (available when PETSc is built with complex support).

Typedef documentation

using Scalar = PetscScalar

Defined in Rodin/PETSc/Types.h

Scalar type used by PETSc vectors and matrices.

using Integer = PetscInt

Defined in Rodin/PETSc/Types.h

Integer index type used by PETSc row/column indices.

using Real = PetscReal

Defined in Rodin/PETSc/Types.h

Real-valued floating-point type (tolerances, norms, etc.).

using Complex = PetscComplex

Defined in Rodin/PETSc/Types.h

Complex scalar type (available when PETSc is built with complex support).