org.apache.commons.math3.fitting.leastsquares.LeastSquaresProblem Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-math3 Show documentation
Show all versions of commons-math3 Show documentation
The Apache Commons Math project is a library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems not immediately available in the Java programming language or commons-lang.
/*
* 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 {@link
* Evaluation#getResiduals()} and {@link Evaluation#getJacobian()}.
*
*
* Instances are typically either created progressively using a {@link
* LeastSquaresBuilder builder} or created at once using a {@link LeastSquaresFactory
* factory}.
*
* @see LeastSquaresBuilder
* @see LeastSquaresFactory
* @see LeastSquaresAdapter
*
* @since 3.3
*/
public interface LeastSquaresProblem extends OptimizationProblem {
/**
* Gets the initial guess.
*
* @return the initial guess values.
*/
RealVector getStart();
/**
* 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.
*
* @return the number of scalar parameters
*/
int getParameterSize();
/**
* 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 {@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 {@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, {@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.
*
* @return the cost.
*/
double getRMS();
/**
* Get the weighted Jacobian matrix.
*
* @return the weighted Jacobian: W1/2 J.
* @throws org.apache.commons.math3.exception.DimensionMismatchException
* if the Jacobian dimension does not match problem dimension.
*/
RealMatrix getJacobian();
/**
* 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.
*
* @return the weighted residuals: W1/2 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.
*
* @return the point provided to {@link #evaluate(RealVector)}.
*/
RealVector getPoint();
}
}