/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.math3.fitting.leastsquares;

import org.apache.commons.math3.linear.RealMatrix;
import org.apache.commons.math3.linear.RealVector;
import org.apache.commons.math3.optim.OptimizationProblem;

The data necessary to define a non-linear least squares problem.
 Includes the observed values, computed model function, and convergence/divergence criteria. Weights are implicit in Evaluation.getResiduals() and Evaluation.getJacobian(). 
 Instances are typically either created progressively using a builder or created at once using a 
factory. 
See Also:
LeastSquaresBuilder
LeastSquaresFactory
LeastSquaresAdapter
Since:
3.3/**
 * The data necessary to define a non-linear least squares problem.
 * <p>
 * Includes the observed values, computed model function, and
 * convergence/divergence criteria. Weights are implicit in {@link
 * Evaluation#getResiduals()} and {@link Evaluation#getJacobian()}.
 * </p>
 * <p>
 * Instances are typically either created progressively using a {@link
 * LeastSquaresBuilder builder} or created at once using a {@link LeastSquaresFactory
 * factory}.
 * </p>
 * @see LeastSquaresBuilder
 * @see LeastSquaresFactory
 * @see LeastSquaresAdapter
 *
 * @since 3.3
 */
public interface LeastSquaresProblem extends OptimizationProblem<LeastSquaresProblem.Evaluation> {

    
Gets the initial guess.
Returns:
the initial guess values./**
     * Gets the initial guess.
     *
     * @return the initial guess values.
     */
    RealVector getStart();

    
Get the number of observations (rows in the Jacobian) in this problem.
Returns:
the number of scalar observations/**
     * Get the number of observations (rows in the Jacobian) in this problem.
     *
     * @return the number of scalar observations
     */
    int getObservationSize();

    
Get the number of parameters (columns in the Jacobian) in this problem.
Returns:
the number of scalar parameters/**
     * Get the number of parameters (columns in the Jacobian) in this problem.
     *
     * @return the number of scalar parameters
     */
    int getParameterSize();

    
Evaluate the model at the specified point.
Params:
point – the parameter values.
Throws:
TooManyEvaluationsException – 
         if the maximal number of evaluations (of the model vector function) is
         exceeded.
Returns:
the model's value and derivative at the given point./**
     * Evaluate the model at the specified point.
     *
     *
     * @param point the parameter values.
     * @return the model's value and derivative at the given point.
     * @throws org.apache.commons.math3.exception.TooManyEvaluationsException
     *          if the maximal number of evaluations (of the model vector function) is
     *          exceeded.
     */
    Evaluation evaluate(RealVector point);

    
An evaluation of a LeastSquaresProblem at a particular point. This class also computes several quantities derived from the value and its Jacobian. /**
     * An evaluation of a {@link LeastSquaresProblem} at a particular point. This class
     * also computes several quantities derived from the value and its Jacobian.
     */
    public interface Evaluation {

        
Get the covariance matrix of the optimized parameters. 
 Note that this
operation involves the inversion of the JTJ matrix, where J is the Jacobian matrix. The threshold parameter is a way for the caller to specify that the result of this computation should be considered meaningless, and thus trigger an exception. 
Params:
threshold – Singularity threshold.
Throws:
SingularMatrixException – 
         if the covariance matrix cannot be computed (singular problem).
Returns:
the covariance matrix./**
         * Get the covariance matrix of the optimized parameters. <br/> Note that this
         * operation involves the inversion of the <code>J<sup>T</sup>J</code> matrix,
         * where {@code J} is the Jacobian matrix. The {@code threshold} parameter is a
         * way for the caller to specify that the result of this computation should be
         * considered meaningless, and thus trigger an exception.
         *
         *
         * @param threshold Singularity threshold.
         * @return the covariance matrix.
         * @throws org.apache.commons.math3.linear.SingularMatrixException
         *          if the covariance matrix cannot be computed (singular problem).
         */
        RealMatrix getCovariances(double threshold);

        
Get an estimate of the standard deviation of the parameters. The returned values are the square root of the diagonal coefficients of the covariance matrix, sd(a[i]) ~= sqrt(C[i][i]), where a[i] is the optimized value of the i-th parameter, and C is the covariance matrix. 
Params:
covarianceSingularityThreshold – Singularity threshold (see computeCovariances).
Throws:
SingularMatrixException – 
         if the covariance matrix cannot be computed.
Returns:
an estimate of the standard deviation of the optimized parameters/**
         * Get an estimate of the standard deviation of the parameters. The returned
         * values are the square root of the diagonal coefficients of the covariance
         * matrix, {@code sd(a[i]) ~= sqrt(C[i][i])}, where {@code a[i]} is the optimized
         * value of the {@code i}-th parameter, and {@code C} is the covariance matrix.
         *
         *
         * @param covarianceSingularityThreshold Singularity threshold (see {@link
         *                                       #getCovariances(double) computeCovariances}).
         * @return an estimate of the standard deviation of the optimized parameters
         * @throws org.apache.commons.math3.linear.SingularMatrixException
         *          if the covariance matrix cannot be computed.
         */
        RealVector getSigma(double covarianceSingularityThreshold);

        
Get the normalized cost. It is the square-root of the sum of squared of
the residuals, divided by the number of measurements.
Returns:
the cost./**
         * Get the normalized cost. It is the square-root of the sum of squared of
         * the residuals, divided by the number of measurements.
         *
         * @return the cost.
         */
        double getRMS();

        
Get the weighted Jacobian matrix.
Throws:
DimensionMismatchException – 
if the Jacobian dimension does not match problem dimension.
Returns:
the weighted Jacobian: W1/2 J./**
         * Get the weighted Jacobian matrix.
         *
         * @return the weighted Jacobian: W<sup>1/2</sup> J.
         * @throws org.apache.commons.math3.exception.DimensionMismatchException
         * if the Jacobian dimension does not match problem dimension.
         */
        RealMatrix getJacobian();

        
Get the cost.
See Also:
getResiduals()
Returns:
the cost./**
         * Get the cost.
         *
         * @return the cost.
         * @see #getResiduals()
         */
        double getCost();

        
Get the weighted residuals. The residual is the difference between the
observed (target) values and the model (objective function) value. There is one
residual for each element of the vector-valued function. The raw residuals are
then multiplied by the square root of the weight matrix.
Throws:
DimensionMismatchException – 
if the residuals have the wrong length.
Returns:
the weighted residuals: W1/2 K./**
         * Get the weighted residuals. The residual is the difference between the
         * observed (target) values and the model (objective function) value. There is one
         * residual for each element of the vector-valued function. The raw residuals are
         * then multiplied by the square root of the weight matrix.
         *
         * @return the weighted residuals: W<sup>1/2</sup> K.
         * @throws org.apache.commons.math3.exception.DimensionMismatchException
         * if the residuals have the wrong length.
         */
        RealVector getResiduals();

        
Get the abscissa (independent variables) of this evaluation.
Returns:
the point provided to LeastSquaresProblem.evaluate(RealVector)./**
         * Get the abscissa (independent variables) of this evaluation.
         *
         * @return the point provided to {@link #evaluate(RealVector)}.
         */
        RealVector getPoint();
    }
}