org.apache.commons.math3.optim.nonlinear.scalar

## Class LeastSquaresConverter

- java.lang.Object
- - org.apache.commons.math3.optim.nonlinear.scalar.LeastSquaresConverter

- All Implemented Interfaces:
    MultivariateFunction

      public class LeastSquaresConverter
      extends Object
      implements MultivariateFunction

  This class converts `vectorial objective functions` to `scalar objective functions` when the goal is to minimize them.
  This class is mostly used when the vectorial objective function represents a theoretical result computed from a point set applied to a model and the models point must be adjusted to fit the theoretical result to some reference observations. The observations may be obtained for example from physical measurements whether the model is built from theoretical considerations.
  This class computes a possibly weighted squared sum of the residuals, which is a scalar value. The residuals are the difference between the theoretical model (i.e. the output of the vectorial objective function) and the observations. The class implements the `MultivariateFunction` interface and can therefore be minimized by any optimizer supporting scalar objectives functions.This is one way to perform a least square estimation. There are other ways to do this without using this converter, as some optimization algorithms directly support vectorial objective functions.
  This class support combination of residuals with or without weights and correlations.
  Since:
    2.0
  Version:
    $Id: LeastSquaresConverter.java 1416643 2012-12-03 19:37:14Z tn $
  See Also:
    `MultivariateFunction`, `MultivariateVectorFunction`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private MultivariateVectorFunction` | `function` Underlying vectorial function.
    `private double[]` | `observations` Observations to be compared to objective function to compute residuals.
    `private RealMatrix` | `scale` Optional scaling matrix (weight and correlations) for the residuals.
    `private double[]` | `weights` Optional weights for the residuals.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LeastSquaresConverter(MultivariateVectorFunction function, double[] observations)` Builds a simple converter for uncorrelated residuals with identical weights.
    `LeastSquaresConverter(MultivariateVectorFunction function, double[] observations, double[] weights)` Builds a simple converter for uncorrelated residuals with the specified weights.
    `LeastSquaresConverter(MultivariateVectorFunction function, double[] observations, RealMatrix scale)` Builds a simple converter for correlated residuals with the specified weights.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `double` | `value(double[] point)` Compute the value for the function at the given point.

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

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

- - ### Field Detail

    - #### function

          private final MultivariateVectorFunction function

      Underlying vectorial function.

    - #### observations

          private final double[] observations

      Observations to be compared to objective function to compute residuals.

    - #### weights

          private final double[] weights

      Optional weights for the residuals.

    - #### scale

          private final RealMatrix scale

      Optional scaling matrix (weight and correlations) for the residuals.

  - ### Constructor Detail

    - #### LeastSquaresConverter

          public LeastSquaresConverter(MultivariateVectorFunction function,
                               double[] observations)

      Builds a simple converter for uncorrelated residuals with identical weights.
      Parameters:
        `function` - vectorial residuals function to wrap
        `observations` - observations to be compared to objective function to compute residuals

    - #### LeastSquaresConverter

          public LeastSquaresConverter(MultivariateVectorFunction function,
                               double[] observations,
                               double[] weights)

      Builds a simple converter for uncorrelated residuals with the specified weights.

      The scalar objective function value is computed as:

           objective = ∑weighti(observationi-objectivei)2

      Weights can be used for example to combine residuals with different standard deviations. As an example, consider a residuals array in which even elements are angular measurements in degrees with a 0.01° standard deviation and odd elements are distance measurements in meters with a 15m standard deviation. In this case, the weights array should be initialized with value 1.0/(0.012) in the even elements and 1.0/(15.02) in the odd elements (i.e. reciprocals of variances).

      The array computed by the objective function, the observations array and the weights array must have consistent sizes or a `DimensionMismatchException` will be triggered while computing the scalar objective.

      Parameters:
        `function` - vectorial residuals function to wrap
        `observations` - observations to be compared to objective function to compute residuals
        `weights` - weights to apply to the residuals
      Throws:
        `DimensionMismatchException` - if the observations vector and the weights vector dimensions do not match (objective function dimension is checked only when the `value(double[])` method is called)

    - #### LeastSquaresConverter

          public LeastSquaresConverter(MultivariateVectorFunction function,
                               double[] observations,
                               RealMatrix scale)

      Builds a simple converter for correlated residuals with the specified weights.

      The scalar objective function value is computed as:

           objective = yTy with y = scale×(observation-objective)

      The array computed by the objective function, the observations array and the the scaling matrix must have consistent sizes or a `DimensionMismatchException` will be triggered while computing the scalar objective.

      Parameters:
        `function` - vectorial residuals function to wrap
        `observations` - observations to be compared to objective function to compute residuals
        `scale` - scaling matrix
      Throws:
        `DimensionMismatchException` - if the observations vector and the scale matrix dimensions do not match (objective function dimension is checked only when the `value(double[])` method is called)

  - ### Method Detail

    - #### value

          public double value(double[] point)

      Compute the value for the function at the given point.
      Specified by:
        `value` in interface `MultivariateFunction`
      Parameters:
        `point` - Point at which the function must be evaluated.
      Returns:
        the function value for the given point.

Copyright (c) 2003-2013 Apache Software Foundation