You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ce...@apache.org on 2011/10/25 09:37:08 UTC
svn commit: r1188549 - in /commons/proper/math/trunk: pom.xml
src/main/java/org/apache/commons/math/linear/SymmLQ.java
Author: celestin
Date: Tue Oct 25 07:37:08 2011
New Revision: 1188549
URL: http://svn.apache.org/viewvc?rev=1188549&view=rev
Log:
1. Minor changes to Javadoc of SYMMLQ implementation, following Pr. M. A. Saunders review.
2. Added Michael Saunders as a contributor in the POM.
Modified:
commons/proper/math/trunk/pom.xml
commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/SymmLQ.java
Modified: commons/proper/math/trunk/pom.xml
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/pom.xml?rev=1188549&r1=1188548&r2=1188549&view=diff
==============================================================================
--- commons/proper/math/trunk/pom.xml (original)
+++ commons/proper/math/trunk/pom.xml Tue Oct 25 07:37:08 2011
@@ -228,6 +228,9 @@
<name>Joni Salonen</name>
</contributor>
<contributor>
+ <name>Michael Saunders</name>
+ </contributor>
+ <contributor>
<name>Christopher Schuck</name>
</contributor>
<contributor>
Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/SymmLQ.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/SymmLQ.java?rev=1188549&r1=1188548&r2=1188549&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/SymmLQ.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/SymmLQ.java Tue Oct 25 07:37:08 2011
@@ -48,11 +48,11 @@ import org.apache.commons.math.util.Math
* definite (but <em>must</em> be self-adjoint). The work per iteration is very
* slightly less if shift = 0.
* </p>
- * <h3>Peconditioning</h3>
+ * <h3>Preconditioning</h3>
* <p>
- * Preconditioning may reduce the number of iterations required. The solver is
+ * Preconditioning may reduce the number of iterations required. The solver may be
* provided with a positive definite preconditioner M = C · C<sup>T</sup>
- * that is known to approximate (A - shift · I) in some sense, while
+ * that is known to approximate (A - shift · I) in some sense, where
* systems of the form M · y = x can be solved efficiently. Then SYMMLQ
* will implicitly solve the system of equations P · (A - shift ·
* I) · P<sup>T</sup> · xhat = P · b, i.e. Ahat ·
@@ -74,16 +74,31 @@ import org.apache.commons.math.util.Math
* In the present context, an iteration should be understood as one evaluation
* of the matrix-vector product A · x. The initialization phase therefore
* counts as one iteration. If the user requires checks on the symmetry of A,
- * this entails one further matrix-vector product by iteration. This further
- * product is <em>not</em> accounted for in the iteration count. In other words,
- * the number of iterations required to reach convergence will be identical,
- * whether checks have been required or not.
+ * this entails one further matrix-vector product in the initial phase. This
+ * further product is <em>not</em> accounted for in the iteration count. In
+ * other words, the number of iterations required to reach convergence will be
+ * identical, whether checks have been required or not.
* </p>
* <p>
* The present definition of the iteration count differs from that adopted in
* the original FOTRAN code, where the initialization phase was <em>not</em>
* taken into account.
* </p>
+ * <h3><a id="initguess">Initial guess of the solution</a></h3>
+ * <p>
+ * The {@code x} parameter in
+ * <ul>
+ * <li>{@link #solve(RealLinearOperator, RealVector, RealVector)},</li>
+ * <li>{@link #solve(RealLinearOperator, InvertibleRealLinearOperator, RealVector, RealVector)}},</li>
+ * <li>{@link #solveInPlace(RealLinearOperator, RealVector, RealVector)},</li>
+ * <li>{@link #solveInPlace(RealLinearOperator, InvertibleRealLinearOperator, RealVector, RealVector)},</li>
+ * <li>{@link #solveInPlace(RealLinearOperator, InvertibleRealLinearOperator, RealVector, RealVector, boolean, double)},</li>
+ * </ul>
+ * should not be considered as an initial guess, as it is set to zero in the
+ * initial phase. If x<sub>0</sub> is known to be a good approximation to x, one
+ * should compute r<sub>0</sub> = b - A · x, solve A · dx = r0,
+ * and set x = x<sub>0</sub> + dx.
+ * </p>
* <h3><a id="context">Exception context</a></h3>
* <p>
* Besides standard {@link DimensionMismatchException}, this class might throw
@@ -136,8 +151,8 @@ public class SymmLQ
* 1. Preconditioning
* ---------------
* The Lanczos iterations associated with Ahat and bhat read
- * beta[1] = |P . b|
- * v[1] = P.b / beta[1]
+ * beta[1] = ||P * b||
+ * v[1] = P * b / beta[1]
* beta[k+1] * v[k+1] = Ahat * v[k] - alpha[k] * v[k] - beta[k] * v[k-1]
* = P * (A - shift * I) * P' * v[k] - alpha[k] * v[k]
* - beta[k] * v[k-1]
@@ -164,11 +179,11 @@ public class SymmLQ
* 3. Accounting for the goodb flag
* -----------------------------
* When goodb is set to true, the component of xL along b is computed
- * separately. From Page and Saunders (1975), equation (5.9), we have
+ * separately. From Paige and Saunders (1975), equation (5.9), we have
* wbar[k+1] = s[k] * wbar[k] - c[k] * v[k+1],
* wbar[1] = v[1].
* Introducing wbar2[k] = wbar[k] - s[1] * ... * s[k-1] * v[1], it can
- * easily be verified by induction that what follows the same recursive
+ * easily be verified by induction that wbar2 follows the same recursive
* relation
* wbar2[k+1] = s[k] * wbar2[k] - c[k] * v[k+1],
* wbar2[1] = 0,
@@ -317,8 +332,7 @@ public class SymmLQ
* @param m Preconditioner (can be {@code null}).
* @param b Right-hand side vector.
* @param x Vector to be updated with the solution. {@code x} should not
- * be considered as an initial guess, as it is set to 0 in the
- * initialization phase.
+ * be considered as an initial guess (<a href="#initguess">more</a>).
* @param goodb Usually {@code false}, except if {@code x} is expected
* to contain a large multiple of {@code b}.
* @param shift The amount to be subtracted to all diagonal elements of
@@ -676,7 +690,7 @@ public class SymmLQ
* @param delta δ parameter for the default stopping criterion.
* @param check {@code true} if self-adjointedness of both matrix and
* preconditioner should be checked. This entails an extra matrix-vector
- * product at each iteration.
+ * product in the initial phase.
*/
public SymmLQ(final int maxIterations, final double delta,
final boolean check) {
@@ -693,7 +707,7 @@ public class SymmLQ
* @param delta δ parameter for the default stopping criterion.
* @param check {@code true} if self-adjointedness of both matrix and
* preconditioner should be checked. This entails an extra matrix-vector
- * product at each iteration.
+ * product in the initial phase.
*/
public SymmLQ(final IterationManager manager, final double delta,
final boolean check) {
@@ -902,7 +916,7 @@ public class SymmLQ
* @param m Preconditioner (can be {@code null}).
* @param b Right-hand side vector.
* @param x Not meaningful in this implementation. Should not be considered
- * as an initial guess.
+ * as an initial guess (<a href="#initguess">more</a>).
* @return A new vector containing the solution.
* @throws NullArgumentException if one of the parameters is {@code null}.
* @throws NonSquareOperatorException if {@code a} or {@code m} is not
@@ -1010,7 +1024,7 @@ public class SymmLQ
* @param a Linear operator A of the system.
* @param b Right-hand side vector.
* @param x Not meaningful in this implementation. Should not be considered
- * as an initial guess.
+ * as an initial guess (<a href="#initguess">more</a>).
* @return A new vector containing the solution.
* @throws NullArgumentException if one of the parameters is {@code null}.
* @throws NonSquareOperatorException if {@code a} is not square.
@@ -1041,8 +1055,7 @@ public class SymmLQ
* @param m Preconditioner (can be {@code null}).
* @param b Right-hand side vector.
* @param x Vector to be updated with the solution. {@code x} should not be
- * considered as an initial guess, as it is set to 0 in the initialization
- * phase.
+ * considered as an initial guess (<a href="#initguess">more</a>).
* @return A reference to {@code x} (shallow copy) updated with the
* solution.
* @throws NullArgumentException if one of the parameters is {@code null}.
@@ -1093,8 +1106,7 @@ public class SymmLQ
* @param m Preconditioner (can be {@code null}).
* @param b Right-hand side vector.
* @param x Vector to be updated with the solution. {@code x} should not be
- * considered as an initial guess, as it is set to 0 in the initialization
- * phase.
+ * considered as an initial guess (<a href="#initguess">more</a>).
* @param goodb Usually {@code false}, except if {@code x} is expected to
* contain a large multiple of {@code b}.
* @param shift The amount to be subtracted to all diagonal elements of A.
@@ -1166,8 +1178,7 @@ public class SymmLQ
* @param a Linear operator A of the system.
* @param b Right-hand side vector.
* @param x Vector to be updated with the solution. {@code x} should not be
- * considered as an initial guess, as it is set to 0 in the initialization
- * phase.
+ * considered as an initial guess (<a href="#initguess">more</a>).
* @return A reference to {@code x} (shallow copy) updated with the
* solution.
* @throws NullArgumentException if one of the parameters is {@code null}.