diff options
Diffstat (limited to 'src/main/java/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.java')
| -rw-r--r-- | src/main/java/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.java | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/src/main/java/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.java b/src/main/java/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.java new file mode 100644 index 0000000..097ff81 --- /dev/null +++ b/src/main/java/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.java @@ -0,0 +1,156 @@ +/* + * 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. + * <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. + * + * @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. <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, {@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: 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. + * + * @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: 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. + * + * @return the point provided to {@link #evaluate(RealVector)}. + */ + RealVector getPoint(); + } +} |