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 java.lang.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
`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
`(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||