Java tutorial
/* * 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(); } }