From 380892dbd095f453e57a2a9f81b4722466f160f4 Mon Sep 17 00:00:00 2001 From: Sebastien Brisard Date: Tue, 27 Mar 2012 06:02:15 +0000 Subject: [PATCH] Changed o.a.c.m3.linear.PreconditionedIterativeLinearSolver according to MATH-771. git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1305738 13f79535-47bb-0310-9956-ffa450edef68 --- .../PreconditionedIterativeLinearSolver.java | 72 ++++++++++--------- 1 file changed, 38 insertions(+), 34 deletions(-) diff --git a/src/main/java/org/apache/commons/math3/linear/PreconditionedIterativeLinearSolver.java b/src/main/java/org/apache/commons/math3/linear/PreconditionedIterativeLinearSolver.java index a7c145181..c5e17d3b8 100644 --- a/src/main/java/org/apache/commons/math3/linear/PreconditionedIterativeLinearSolver.java +++ b/src/main/java/org/apache/commons/math3/linear/PreconditionedIterativeLinearSolver.java @@ -26,15 +26,23 @@ import org.apache.commons.math3.util.MathUtils; *

* This abstract class defines preconditioned iterative solvers. When A is * ill-conditioned, instead of solving system A · x = b directly, it is - * preferable to solve M-1 · A · x = M-1 - * · b, where M approximates in some way A, while remaining comparatively - * easier to invert. M (not M-1!) is called the + * preferable to solve either + *

+ * (M · A) · x = M · b + *
+ * (left preconditioning), or + *
+ * (A · M) · y = b,     followed by + * M · y = x + *
+ * (right preconditioning), where M approximates in some way A-1, + * while matrix-vector products of the type M · y remain comparatively + * easy to compute. In this library, M (not M-1!) is called the * preconditionner. *

*

- * Concrete implementations of this abstract class must be provided with - * M-1, the inverse of the preconditioner, as a - * {@link RealLinearOperator}. + * Concrete implementations of this abstract class must be provided with the + * preconditioner M, as a {@link RealLinearOperator}. *

* * @version $Id$ @@ -68,15 +76,14 @@ public abstract class PreconditionedIterativeLinearSolver * b. * * @param a the linear operator A of the system - * @param minv the inverse of the preconditioner, M-1 - * (can be {@code null}) + * @param m the preconditioner, M (can be {@code null}) * @param b the right-hand side vector * @param x0 the initial guess of the solution * @return a new vector containing the solution * @throws NullArgumentException if one of the parameters is {@code null} - * @throws NonSquareOperatorException if {@code a} or {@code minv} is not + * @throws NonSquareOperatorException if {@code a} or {@code m} is not * square - * @throws DimensionMismatchException if {@code minv}, {@code b} or + * @throws DimensionMismatchException if {@code m}, {@code b} or * {@code x0} have dimensions inconsistent with {@code a} * @throws MaxCountExceededException at exhaustion of the iteration count, * unless a custom @@ -84,11 +91,11 @@ public abstract class PreconditionedIterativeLinearSolver * has been set at construction */ public RealVector solve(final RealLinearOperator a, - final RealLinearOperator minv, final RealVector b, final RealVector x0) + final RealLinearOperator m, final RealVector b, final RealVector x0) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException { MathUtils.checkNotNull(x0); - return solveInPlace(a, minv, b, x0.copy()); + return solveInPlace(a, m, b, x0.copy()); } /** {@inheritDoc} */ @@ -120,28 +127,27 @@ public abstract class PreconditionedIterativeLinearSolver * and throws an exception if one of the checks fails. * * @param a the linear operator A of the system - * @param minv the inverse of the preconditioner, M-1 - * (can be {@code null}) + * @param m the preconditioner, M (can be {@code null}) * @param b the right-hand side vector * @param x0 the initial guess of the solution * @throws NullArgumentException if one of the parameters is {@code null} - * @throws NonSquareOperatorException if {@code a} or {@code minv} is not + * @throws NonSquareOperatorException if {@code a} or {@code m} is not * square - * @throws DimensionMismatchException if {@code minv}, {@code b} or + * @throws DimensionMismatchException if {@code m}, {@code b} or * {@code x0} have dimensions inconsistent with {@code a} */ protected static void checkParameters(final RealLinearOperator a, - final RealLinearOperator minv, final RealVector b, final RealVector x0) + final RealLinearOperator m, final RealVector b, final RealVector x0) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException { checkParameters(a, b, x0); - if (minv != null) { - if (minv.getColumnDimension() != minv.getRowDimension()) { - throw new NonSquareOperatorException(minv.getColumnDimension(), - minv.getRowDimension()); + if (m != null) { + if (m.getColumnDimension() != m.getRowDimension()) { + throw new NonSquareOperatorException(m.getColumnDimension(), + m.getRowDimension()); } - if (minv.getRowDimension() != a.getRowDimension()) { - throw new DimensionMismatchException(minv.getRowDimension(), + if (m.getRowDimension() != a.getRowDimension()) { + throw new DimensionMismatchException(m.getRowDimension(), a.getRowDimension()); } } @@ -152,26 +158,25 @@ public abstract class PreconditionedIterativeLinearSolver * b. * * @param a the linear operator A of the system - * @param minv the inverse of the preconditioner, M-1 - * (can be {@code null}) + * @param m the preconditioner, M (can be {@code null}) * @param b the right-hand side vector * @return a new vector containing the solution * @throws NullArgumentException if one of the parameters is {@code null} - * @throws NonSquareOperatorException if {@code a} or {@code minv} is not + * @throws NonSquareOperatorException if {@code a} or {@code m} is not * square - * @throws DimensionMismatchException if {@code minv} or {@code b} have + * @throws DimensionMismatchException if {@code m} or {@code b} have * dimensions inconsistent with {@code a} * @throws MaxCountExceededException at exhaustion of the iteration count, * unless a custom * {@link org.apache.commons.math3.util.Incrementor.MaxCountExceededCallback callback} * has been set at construction */ - public RealVector solve(RealLinearOperator a, RealLinearOperator minv, + public RealVector solve(RealLinearOperator a, RealLinearOperator m, RealVector b) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException { MathUtils.checkNotNull(a); final RealVector x = new ArrayRealVector(a.getColumnDimension()); - return solveInPlace(a, minv, b, x); + return solveInPlace(a, m, b, x); } /** @@ -179,16 +184,15 @@ public abstract class PreconditionedIterativeLinearSolver * b. The solution is computed in-place (initial guess is modified). * * @param a the linear operator A of the system - * @param minv the inverse of the preconditioner, M-1 - * (can be {@code null}) + * @param m the preconditioner, M (can be {@code null}) * @param b the right-hand side vector * @param x0 the initial guess of the solution * @return a reference to {@code x0} (shallow copy) updated with the * solution * @throws NullArgumentException if one of the parameters is {@code null} - * @throws NonSquareOperatorException if {@code a} or {@code minv} is not + * @throws NonSquareOperatorException if {@code a} or {@code m} is not * square - * @throws DimensionMismatchException if {@code minv}, {@code b} or + * @throws DimensionMismatchException if {@code m}, {@code b} or * {@code x0} have dimensions inconsistent with {@code a} * @throws MaxCountExceededException at exhaustion of the iteration count, * unless a custom @@ -196,7 +200,7 @@ public abstract class PreconditionedIterativeLinearSolver * has been set at construction. */ public abstract RealVector solveInPlace(RealLinearOperator a, - RealLinearOperator minv, RealVector b, RealVector x0) throws + RealLinearOperator m, RealVector b, RealVector x0) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException;