Class SymmLQ.State

java.lang.Object
org.apache.commons.math3.linear.SymmLQ.State
Enclosing class:
SymmLQ

private static class SymmLQ.State extends Object

A simple container holding the non-final variables used in the iterations. Making the current state of the solver visible from the outside is necessary, because during the iterations, x does not exactly hold the current estimate of the solution. Indeed, x needs in general to be moved from the LQ point to the CG point. Besides, additional upudates must be carried out in case goodb is set to true.

In all subsequent comments, the description of the state variables refer to their value after a call to update(). In these comments, k is the current number of evaluations of matrix-vector products.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final RealLinearOperator
    Reference to the linear operator.
    private final RealVector
    Reference to the right-hand side vector.
    private double
    The value of beta[k+1].
    private double
    The value of beta[1].
    private boolean
    The value of b == 0 (exact floating-point equality).
    private double
    The value of bstep[k-1].
    (package private) static final double
    The cubic root of MACH_PREC.
    private double
    The estimate of the norm of P * rC[k].
    private final boolean
    true if symmetry of matrix and conditioner must be checked.
    private double
    The value of dbar[k+1] = -beta[k+1] * c[k-1].
    private final double
    The value of the custom tolerance δ for the default stopping criterion.
    private double
    The value of gamma[k] * zeta[k].
    private double
    The value of gbar[k].
    private double
    The value of max(|alpha[1]|, gamma[1], ..., gamma[k-1]).
    private double
    The value of min(|alpha[1]|, gamma[1], ..., gamma[k-1]).
    private final boolean
    Copy of the goodb parameter.
    private boolean
    true if the default convergence criterion is verified.
    private double
    The estimate of the norm of P * rL[k-1].
    private final RealLinearOperator
    Reference to the preconditioner, M.
    (package private) static final double
    The machine precision.
    private final RealVector
    The value of M * b.
    private double
    The value of (-eps[k+1] * zeta[k-1]).
    private double
    The value of beta[k].
    private RealVector
    The value of beta[k] * M^(-1) * P' * v[k].
    private RealVector
    The value of beta[k+1] * M^(-1) * P' * v[k+1].
    private double
    The value of the updated, preconditioned residual P * r.
    private final double
    Copy of the shift parameter.
    private double
    The value of s[1] * ...
    private double
    An estimate of the square of the norm of A * V[k], based on Paige and Saunders (1975), equation (3.3).
    private RealVector
    The value of P' * wbar[k] or P' * (wbar[k] - s[1] * ...
    private final RealVector
    A reference to the vector to be updated with the solution.
    private RealVector
    The value of beta[k+1] * P' * v[k+1].
    private double
    The value of zeta[1]^2 + ...
  • Constructor Summary

    Constructors
    Constructor
    Description
    State(RealLinearOperator a, RealLinearOperator m, RealVector b, boolean goodb, double shift, double delta, boolean check)
    Creates and inits to k = 1 a new instance of this class.
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) boolean
    Returns true if the right-hand side vector is zero exactly.
    (package private) boolean
    Returns true if beta is essentially zero.
    private static void
    Performs a symmetry check on the specified linear operator, and throws an exception in case this check fails.
    private static void
    daxpbypz(double a, RealVector x, double b, RealVector y, RealVector z)
    A BLAS-like function, for the operation z ← a · x + b · y + z.
    private static void
    daxpy(double a, RealVector x, RealVector y)
    A clone of the BLAS DAXPY function, which carries out the operation y ← a · x + y.
    (package private) double
    Returns the norm of the updated, preconditioned residual.
    (package private) boolean
    Returns true if the default stopping criterion is fulfilled.
    (package private) void
    Performs the initial phase of the SYMMLQ algorithm.
    (package private) void
    Move to the CG point if it seems better.
    private static void
    Throws a new NonPositiveDefiniteOperatorException with appropriate context.
    (package private) void
    Performs the next iteration of the algorithm.
    private void
    Computes the norms of the residuals, and checks for convergence.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • CBRT_MACH_PREC

      static final double CBRT_MACH_PREC
      The cubic root of MACH_PREC.
    • MACH_PREC

      static final double MACH_PREC
      The machine precision.
    • a

      private final RealLinearOperator a
      Reference to the linear operator.
    • b

      private final RealVector b
      Reference to the right-hand side vector.
    • check

      private final boolean check
      true if symmetry of matrix and conditioner must be checked.
    • delta

      private final double delta
      The value of the custom tolerance δ for the default stopping criterion.
    • beta

      private double beta
      The value of beta[k+1].
    • beta1

      private double beta1
      The value of beta[1].
    • bstep

      private double bstep
      The value of bstep[k-1].
    • cgnorm

      private double cgnorm
      The estimate of the norm of P * rC[k].
    • dbar

      private double dbar
      The value of dbar[k+1] = -beta[k+1] * c[k-1].
    • gammaZeta

      private double gammaZeta
      The value of gamma[k] * zeta[k]. Was called rhs1 in the initial code.
    • gbar

      private double gbar
      The value of gbar[k].
    • gmax

      private double gmax
      The value of max(|alpha[1]|, gamma[1], ..., gamma[k-1]).
    • gmin

      private double gmin
      The value of min(|alpha[1]|, gamma[1], ..., gamma[k-1]).
    • goodb

      private final boolean goodb
      Copy of the goodb parameter.
    • hasConverged

      private boolean hasConverged
      true if the default convergence criterion is verified.
    • lqnorm

      private double lqnorm
      The estimate of the norm of P * rL[k-1].
    • m

      private final RealLinearOperator m
      Reference to the preconditioner, M.
    • minusEpsZeta

      private double minusEpsZeta
      The value of (-eps[k+1] * zeta[k-1]). Was called rhs2 in the initial code.
    • mb

      private final RealVector mb
      The value of M * b.
    • oldb

      private double oldb
      The value of beta[k].
    • r1

      private RealVector r1
      The value of beta[k] * M^(-1) * P' * v[k].
    • r2

      private RealVector r2
      The value of beta[k+1] * M^(-1) * P' * v[k+1].
    • rnorm

      private double rnorm
      The value of the updated, preconditioned residual P * r. This value is given by min(cgnorm, lqnorm).
    • shift

      private final double shift
      Copy of the shift parameter.
    • snprod

      private double snprod
      The value of s[1] * ... * s[k-1].
    • tnorm

      private double tnorm
      An estimate of the square of the norm of A * V[k], based on Paige and Saunders (1975), equation (3.3).
    • wbar

      private RealVector wbar
      The value of P' * wbar[k] or P' * (wbar[k] - s[1] * ... * s[k-1] * v[1]) if goodb is true. Was called w in the initial code.
    • xL

      private final RealVector xL
      A reference to the vector to be updated with the solution. Contains the value of xL[k-1] if goodb is false, (xL[k-1] - bstep[k-1] * v[1]) otherwise.
    • y

      private RealVector y
      The value of beta[k+1] * P' * v[k+1].
    • ynorm2

      private double ynorm2
      The value of zeta[1]^2 + ... + zeta[k-1]^2.
    • bIsNull

      private boolean bIsNull
      The value of b == 0 (exact floating-point equality).
  • Constructor Details

    • State

      State(RealLinearOperator a, RealLinearOperator m, RealVector b, boolean goodb, double shift, double delta, boolean check)
      Creates and inits to k = 1 a new instance of this class.
      Parameters:
      a - the linear operator A of the system
      m - the preconditioner, M (can be null)
      b - the right-hand side vector
      goodb - usually false, except if x is expected to contain a large multiple of b
      shift - the amount to be subtracted to all diagonal elements of A
      delta - the δ parameter for the default stopping criterion
      check - true if self-adjointedness of both matrix and preconditioner should be checked
  • Method Details

    • checkSymmetry

      private static void checkSymmetry(RealLinearOperator l, RealVector x, RealVector y, RealVector z) throws NonSelfAdjointOperatorException
      Performs a symmetry check on the specified linear operator, and throws an exception in case this check fails. Given a linear operator L, and a vector x, this method checks that x' · L · y = y' · L · x (within a given accuracy), where y = L · x.
      Parameters:
      l - the linear operator L
      x - the candidate vector x
      y - the candidate vector y = L · x
      z - the vector z = L · y
      Throws:
      NonSelfAdjointOperatorException - when the test fails
    • throwNPDLOException

      private static void throwNPDLOException(RealLinearOperator l, RealVector v) throws NonPositiveDefiniteOperatorException
      Throws a new NonPositiveDefiniteOperatorException with appropriate context.
      Parameters:
      l - the offending linear operator
      v - the offending vector
      Throws:
      NonPositiveDefiniteOperatorException - in any circumstances
    • daxpy

      private static void daxpy(double a, RealVector x, RealVector y)
      A clone of the BLAS DAXPY function, which carries out the operation y ← a · x + y. This is for internal use only: no dimension checks are provided.
      Parameters:
      a - the scalar by which x is to be multiplied
      x - the vector to be added to y
      y - the vector to be incremented
    • daxpbypz

      private static void daxpbypz(double a, RealVector x, double b, RealVector y, RealVector z)
      A BLAS-like function, for the operation z ← a · x + b · y + z. This is for internal use only: no dimension checks are provided.
      Parameters:
      a - the scalar by which x is to be multiplied
      x - the first vector to be added to z
      b - the scalar by which y is to be multiplied
      y - the second vector to be added to z
      z - the vector to be incremented
    • refineSolution

      void refineSolution(RealVector x)

      Move to the CG point if it seems better. In this version of SYMMLQ, the convergence tests involve only cgnorm, so we're unlikely to stop at an LQ point, except if the iteration limit interferes.

      Additional upudates are also carried out in case goodb is set to true.

      Parameters:
      x - the vector to be updated with the refined value of xL
    • init

      void init()
      Performs the initial phase of the SYMMLQ algorithm. On return, the value of the state variables of this object correspond to k = 1.
    • update

      void update()
      Performs the next iteration of the algorithm. The iteration count should be incremented prior to calling this method. On return, the value of the state variables of this object correspond to the current iteration count k.
    • updateNorms

      private void updateNorms()
      Computes the norms of the residuals, and checks for convergence. Updates lqnorm and cgnorm.
    • hasConverged

      boolean hasConverged()
      Returns true if the default stopping criterion is fulfilled.
      Returns:
      true if convergence of the iterations has occurred
    • bEqualsNullVector

      boolean bEqualsNullVector()
      Returns true if the right-hand side vector is zero exactly.
      Returns:
      the boolean value of b == 0
    • betaEqualsZero

      boolean betaEqualsZero()
      Returns true if beta is essentially zero. This method is used to check for early stop of the iterations.
      Returns:
      true if beta < MACH_PREC
    • getNormOfResidual

      double getNormOfResidual()
      Returns the norm of the updated, preconditioned residual.
      Returns:
      the norm of the residual, ||P * r||