org.apache.commons.math.estimation

## Class GaussNewtonEstimator

- java.lang.Object
- - org.apache.commons.math.estimation.AbstractEstimator
  - - org.apache.commons.math.estimation.GaussNewtonEstimator

- All Implemented Interfaces:
    Serializable, Estimator

  Deprecated.
  as of 2.0, everything in package org.apache.commons.math.estimation has been deprecated and replaced by package org.apache.commons.math.optimization.general

      @Deprecated
      public class GaussNewtonEstimator
      extends AbstractEstimator
      implements Serializable

  This class implements a solver for estimation problems.

  This class solves estimation problems using a weighted least squares criterion on the measurement residuals. It uses a Gauss-Newton algorithm.

  Since:
    1.2
  Version:
    $Revision: 990655 $ $Date: 2010-08-29 23:49:40 +0200 (dim. 29 août 2010) $
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private double` | `convergence` Deprecated. Threshold for cost convergence.
    `private static double` | `DEFAULT_CONVERGENCE` Deprecated. Default threshold for cost convergence.
    `private static double` | `DEFAULT_STEADY_STATE_THRESHOLD` Deprecated. Default threshold for cost steady state detection.
    `private static long` | `serialVersionUID` Deprecated. Serializable version identifier
    `private double` | `steadyStateThreshold` Deprecated. Threshold for cost steady state detection.

    - ### Fields inherited from class org.apache.commons.math.estimation.AbstractEstimator

      `cols, cost, DEFAULT_MAX_COST_EVALUATIONS, jacobian, measurements, parameters, residuals, rows`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GaussNewtonEstimator()` Deprecated. Simple constructor with default settings.
    `GaussNewtonEstimator(int maxCostEval, double convergence, double steadyStateThreshold)` Deprecated. Simple constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `estimate(EstimationProblem problem)` Deprecated. Solve an estimation problem using a least squares criterion.
    `void` | `setConvergence(double convergence)` Deprecated. Set the convergence criterion threshold.
    `void` | `setSteadyStateThreshold(double steadyStateThreshold)` Deprecated. Set the steady state detection threshold.

    - ### Methods inherited from class org.apache.commons.math.estimation.AbstractEstimator

      `getChiSquare, getCostEvaluations, getCovariances, getJacobianEvaluations, getRMS, guessParametersErrors, incrementJacobianEvaluationsCounter, initializeEstimate, setMaxCostEval, updateJacobian, updateResidualsAndCost`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### serialVersionUID

          private static final long serialVersionUID

      Deprecated.
      Serializable version identifier
      See Also:
        Constant Field Values

    - #### DEFAULT_STEADY_STATE_THRESHOLD

          private static final double DEFAULT_STEADY_STATE_THRESHOLD

      Deprecated.
      Default threshold for cost steady state detection.
      See Also:
        Constant Field Values

    - #### DEFAULT_CONVERGENCE

          private static final double DEFAULT_CONVERGENCE

      Deprecated.
      Default threshold for cost convergence.
      See Also:
        Constant Field Values

    - #### steadyStateThreshold

          private double steadyStateThreshold

      Deprecated.
      Threshold for cost steady state detection.

    - #### convergence

          private double convergence

      Deprecated.
      Threshold for cost convergence.

  - ### Constructor Detail

    - #### GaussNewtonEstimator

          public GaussNewtonEstimator()

      Deprecated.
      Simple constructor with default settings.

      The estimator is built with default values for all settings.

      See Also:
        `DEFAULT_STEADY_STATE_THRESHOLD`, `DEFAULT_CONVERGENCE`, `AbstractEstimator.DEFAULT_MAX_COST_EVALUATIONS`

    - #### GaussNewtonEstimator

          public GaussNewtonEstimator(int maxCostEval,
                              double convergence,
                              double steadyStateThreshold)

      Deprecated.
      Simple constructor.

      This constructor builds an estimator and stores its convergence characteristics.

      An estimator is considered to have converged whenever either the criterion goes below a physical threshold under which improvements are considered useless or when the algorithm is unable to improve it (even if it is still high). The first condition that is met stops the iterations.

      The fact an estimator has converged does not mean that the model accurately fits the measurements. It only means no better solution can be found, it does not mean this one is good. Such an analysis is left to the caller.

      If neither conditions are fulfilled before a given number of iterations, the algorithm is considered to have failed and an `EstimationException` is thrown.

      Parameters:
        `maxCostEval` - maximal number of cost evaluations allowed
        `convergence` - criterion threshold below which we do not need to improve the criterion anymore
        `steadyStateThreshold` - steady state detection threshold, the problem has converged has reached a steady state if `FastMath.abs(Jn - Jn-1) < Jn × convergence`, where `Jn` and `Jn-1` are the current and preceding criterion values (square sum of the weighted residuals of considered measurements).

  - ### Method Detail

    - #### setConvergence

          public void setConvergence(double convergence)

      Deprecated.
      Set the convergence criterion threshold.
      Parameters:
        `convergence` - criterion threshold below which we do not need to improve the criterion anymore

    - #### setSteadyStateThreshold

          public void setSteadyStateThreshold(double steadyStateThreshold)

      Deprecated.
      Set the steady state detection threshold.

      The problem has converged has reached a steady state if `FastMath.abs(Jn - Jn-1) < Jn × convergence`, where `Jn` and `Jn-1` are the current and preceding criterion values (square sum of the weighted residuals of considered measurements).

      Parameters:
        `steadyStateThreshold` - steady state detection threshold

    - #### estimate

          public void estimate(EstimationProblem problem)
                        throws EstimationException

      Deprecated.
      Solve an estimation problem using a least squares criterion.

      This method set the unbound parameters of the given problem starting from their current values through several iterations. At each step, the unbound parameters are changed in order to minimize a weighted least square criterion based on the measurements of the problem.

      The iterations are stopped either when the criterion goes below a physical threshold under which improvement are considered useless or when the algorithm is unable to improve it (even if it is still high). The first condition that is met stops the iterations. If the convergence it not reached before the maximum number of iterations, an `EstimationException` is thrown.

      Specified by:
        `estimate` in interface `Estimator`
      Specified by:
        `estimate` in class `AbstractEstimator`
      Parameters:
        `problem` - estimation problem to solve
      Throws:
        `EstimationException` - if the problem cannot be solved
      See Also:
        `EstimationProblem`

Copyright (c) 2003-2013 Apache Software Foundation