/*
 * 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:
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:
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:
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:
Throws:
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:
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:
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:
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(); } }