Module ojalgo

Package org.ojalgo.matrix.task.iterative

Interface 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(org.ojalgo.structure.Access1D<java.lang.Double>, org.ojalgo.matrix.store.PhysicalStore<java.lang.Double>) on vectors.
• Right preconditioning: solver forms A M^{-1} y = b, then recovers x = M^{-1} y; may require both apply(org.ojalgo.structure.Access1D<java.lang.Double>, org.ojalgo.matrix.store.PhysicalStore<java.lang.Double>) and applyTranspose(org.ojalgo.structure.Access1D<java.lang.Double>, org.ojalgo.matrix.store.PhysicalStore<java.lang.Double>).
• 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 Preconditioner	IDENTITY	A no-op preconditioner.

Method Summary

Modifier and Type	Method	Description
void	apply(Access1D<java.lang.Double> src, PhysicalStore<java.lang.Double> dst)	Apply M^{-1} to a vector.
default void	applyTranspose(Access1D<java.lang.Double> src, PhysicalStore<java.lang.Double> dst)	Apply (M^T)^{-1} to a vector.
static java.util.function.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(java.util.List<Equation> equations, int dimension)	Prepare internal structures for a specific system.

Field Detail

IDENTITY

static final Preconditioner IDENTITY

A no-op preconditioner.

Method Detail

getSSOR

static java.util.function.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<java.lang.Double> src,
           PhysicalStore<java.lang.Double> dst)

Apply M^{-1} to a vector. src and dst may alias.

applyTranspose

default void applyTranspose(Access1D<java.lang.Double> src,
                            PhysicalStore<java.lang.Double> dst)

Apply (M^T)^{-1} to a vector. Defaults to apply(Access1D, PhysicalStore).

prepare

void prepare(java.util.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).