Preconditioner

All Known Implementing Classes:: IdentityPreconditioner, JacobiPreconditioner, SSORPreconditioner

public interface Preconditioner

Pluggable preconditioner for iterative linear system solvers.

Contract:

Call prepare(List, int) once per system before iterations to (re)initialise internal state.
apply(Access1D, PhysicalStore) should approximate M^{-1} applied to a vector. Solvers that use left-preconditioning will apply this to residuals or intermediate vectors.
applyTranspose(Access1D, PhysicalStore) should approximate (M^T)^{-1}. By default it delegates to apply(Access1D, PhysicalStore); override if the preconditioner is not symmetric.

Preconditioning modes (solver perspective):

Left preconditioning: solver forms M^{-1} A x = M^{-1} b and calls apply(Access1D, PhysicalStore) on vectors.
Right preconditioning: solver forms A M^{-1} y = b, then recovers x = M^{-1} y; may require both apply(Access1D, PhysicalStore) and applyTranspose(Access1D, PhysicalStore).
Symmetric preconditioners (M = M^T): implementations can usually provide only apply(Access1D, PhysicalStore) and rely on the default transpose behaviour.

Compatibility guidelines:

Methods requiring symmetric positive-definite preconditioning (e.g., for SPD systems) expect M to be symmetric positive-definite.
Methods for general nonsymmetric systems that use right-preconditioning may require a meaningful transpose action; override applyTranspose(Access1D, PhysicalStore) when M is not symmetric.
Some stationary (fixed-point) methods ignore preconditioners entirely and instead use a relaxation factor.

Field Summary

Fields

Modifier and Type

Field

Description

static final Preconditioner

IDENTITY

A no-op preconditioner.
Method Summary

Modifier and Type

Method

Description

void

apply(Access1D<Double> src, PhysicalStore<Double> dst)

Apply M^{-1} to a vector.

default void

applyTranspose(Access1D<Double> src, PhysicalStore<Double> dst)

Apply (M^T)^{-1} to a vector.

static Supplier<Preconditioner>

getSSOR(double omega)

Returns a factory method for a Symmetric Successive Over-Relaxation (SSOR) preconditioner with the specified relaxation factor.

static Preconditioner

newIdentity()

An identity (no-op) preconditioner.

static Preconditioner

newJacobi()

A Jacobi (diagonal) preconditioner.

static Preconditioner

newSSOR(double omega)

A Symmetric Successive Over-Relaxation (SSOR) preconditioner with a specified relaxation factor

static Preconditioner

newSymmetricGaussSeidel()

A symmetric Gauss-Seidel preconditioner (SSOR with omega=1).

void

prepare(List<Equation> equations, int dimension)

Prepare internal structures for a specific system.

Field Details
- IDENTITY
  
  static final Preconditioner IDENTITY
  
  A no-op preconditioner.
Method Details
- getSSOR
  
  static Supplier<Preconditioner> getSSOR(double omega)
  
  Returns a factory method for a Symmetric Successive Over-Relaxation (SSOR) preconditioner with the specified relaxation factor.
- newIdentity
  
  static Preconditioner newIdentity()
  
  An identity (no-op) preconditioner.
- newJacobi
  
  static Preconditioner newJacobi()
  
  A Jacobi (diagonal) preconditioner.
- newSSOR
  
  static Preconditioner newSSOR(double omega)
  
  A Symmetric Successive Over-Relaxation (SSOR) preconditioner with a specified relaxation factor
- newSymmetricGaussSeidel
  
  static Preconditioner newSymmetricGaussSeidel()
  
  A symmetric Gauss-Seidel preconditioner (SSOR with omega=1).
- apply
  
  void apply(Access1D<Double> src, PhysicalStore<Double> dst)
  
  Apply M^{-1} to a vector. src and dst may alias.
- applyTranspose
  
  default void applyTranspose(Access1D<Double> src, PhysicalStore<Double> dst)
  
  Apply (M^T)^{-1} to a vector. Defaults to apply(Access1D, PhysicalStore).
- prepare
  
  void prepare(List<Equation> equations, int dimension)
  
  Prepare internal structures for a specific system. Implementations may analyse sparsity or extract diagonals/factors here.
  
  Parameters:
  
  equations - The active set of rows constituting the system body.
  
  dimension - The vector dimension (number of variables / size of solution vector).