org.apache.commons.math3.linear

## 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 and Description
    --- | ---
    `private RealLinearOperator` | `a` Reference to the linear operator.
    `private RealVector` | `b` Reference to the right-hand side vector.
    `private double` | `beta` The value of beta[k+1].
    `private double` | `beta1` The value of beta[1].
    `private boolean` | `bIsNull` The value of `b == 0` (exact floating-point equality).
    `private double` | `bstep` The value of bstep[k-1].
    `(package private) static double` | `CBRT_MACH_PREC` The cubic root of `MACH_PREC`.
    `private double` | `cgnorm` The estimate of the norm of P * rC[k].
    `private boolean` | `check` `true` if symmetry of matrix and conditioner must be checked.
    `private double` | `dbar` The value of dbar[k+1] = -beta[k+1] * c[k-1].
    `private double` | `delta` The value of the custom tolerance δ for the default stopping criterion.
    `private double` | `gammaZeta` The value of gamma[k] * zeta[k].
    `private double` | `gbar` The value of gbar[k].
    `private double` | `gmax` The value of max(|alpha[1]|, gamma[1], ..., gamma[k-1]).
    `private double` | `gmin` The value of min(|alpha[1]|, gamma[1], ..., gamma[k-1]).
    `private boolean` | `goodb` Copy of the `goodb` parameter.
    `private boolean` | `hasConverged` `true` if the default convergence criterion is verified.
    `private double` | `lqnorm` The estimate of the norm of P * rL[k-1].
    `private RealLinearOperator` | `m` Reference to the preconditioner, M.
    `(package private) static double` | `MACH_PREC` The machine precision.
    `private RealVector` | `mb` The value of M * b.
    `private double` | `minusEpsZeta` The value of (-eps[k+1] * zeta[k-1]).
    `private double` | `oldb` The value of beta[k].
    `private RealVector` | `r1` The value of beta[k] * M^(-1) * P' * v[k].
    `private RealVector` | `r2` The value of beta[k+1] * M^(-1) * P' * v[k+1].
    `private double` | `rnorm` The value of the updated, preconditioned residual P * r.
    `private double` | `shift` Copy of the `shift` parameter.
    `private double` | `snprod` The value of s[1] * ...
    `private double` | `tnorm` An estimate of the square of the norm of A * V[k], based on Paige and Saunders (1975), equation (3.3).
    `private RealVector` | `wbar` The value of P' * wbar[k] or P' * (wbar[k] - s[1] * ...
    `private RealVector` | `xL` A reference to the vector to be updated with the solution.
    `private RealVector` | `y` The value of beta[k+1] * P' * v[k+1].
    `private double` | `ynorm2` The value of zeta[1]^2 + ...

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SymmLQ.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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) boolean` | `bEqualsNullVector()` Returns `true` if the right-hand side vector is zero exactly.
    `(package private) boolean` | `betaEqualsZero()` Returns `true` if `beta` is essentially zero.
    `private static void` | `checkSymmetry(RealLinearOperator l, RealVector x, RealVector y, RealVector z)` 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` | `getNormOfResidual()` Returns the norm of the updated, preconditioned residual.
    `(package private) boolean` | `hasConverged()` Returns `true` if the default stopping criterion is fulfilled.
    `(package private) void` | `init()` Performs the initial phase of the SYMMLQ algorithm.
    `(package private) void` | `refineSolution(RealVector x)` Move to the CG point if it seems better.
    `private static void` | `throwNPDLOException(RealLinearOperator l, RealVector v)` Throws a new `NonPositiveDefiniteOperatorException` with appropriate context.
    `(package private) void` | `update()` Performs the next iteration of the algorithm.
    `private void` | `updateNorms()` 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 Detail

    - #### 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 Detail

    - #### SymmLQ.State

          public SymmLQ.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 Detail

    - #### 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 occured

    - #### 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||

Copyright (c) 2003-2013 Apache Software Foundation