001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.math4.legacy.fitting.leastsquares;
018
019import org.apache.commons.math4.legacy.linear.RealMatrix;
020import org.apache.commons.math4.legacy.linear.RealVector;
021import org.apache.commons.math4.legacy.optim.OptimizationProblem;
022
023/**
024 * The data necessary to define a non-linear least squares problem.
025 * <p>
026 * Includes the observed values, computed model function, and
027 * convergence/divergence criteria. Weights are implicit in {@link
028 * Evaluation#getResiduals()} and {@link Evaluation#getJacobian()}.
029 * </p>
030 * <p>
031 * Instances are typically either created progressively using a {@link
032 * LeastSquaresBuilder builder} or created at once using a {@link LeastSquaresFactory
033 * factory}.
034 * </p>
035 * @see LeastSquaresBuilder
036 * @see LeastSquaresFactory
037 * @see LeastSquaresAdapter
038 *
039 * @since 3.3
040 */
041public interface LeastSquaresProblem extends OptimizationProblem<LeastSquaresProblem.Evaluation> {
042
043    /**
044     * Gets the initial guess.
045     *
046     * @return the initial guess values.
047     */
048    RealVector getStart();
049
050    /**
051     * Get the number of observations (rows in the Jacobian) in this problem.
052     *
053     * @return the number of scalar observations
054     */
055    int getObservationSize();
056
057    /**
058     * Get the number of parameters (columns in the Jacobian) in this problem.
059     *
060     * @return the number of scalar parameters
061     */
062    int getParameterSize();
063
064    /**
065     * Evaluate the model at the specified point.
066     *
067     *
068     * @param point the parameter values.
069     * @return the model's value and derivative at the given point.
070     * @throws org.apache.commons.math4.legacy.exception.TooManyEvaluationsException
071     *          if the maximal number of evaluations (of the model vector function) is
072     *          exceeded.
073     */
074    Evaluation evaluate(RealVector point);
075
076    /**
077     * An evaluation of a {@link LeastSquaresProblem} at a particular point. This class
078     * also computes several quantities derived from the value and its Jacobian.
079     */
080    public interface Evaluation {
081
082        /**
083         * Get the covariance matrix of the optimized parameters. <br> Note that this
084         * operation involves the inversion of the <code>J<sup>T</sup>J</code> matrix,
085         * where {@code J} is the Jacobian matrix. The {@code threshold} parameter is a
086         * way for the caller to specify that the result of this computation should be
087         * considered meaningless, and thus trigger an exception.
088         *
089         * @param threshold Singularity threshold.
090         * @return the covariance matrix.
091         * @throws org.apache.commons.math4.legacy.linear.SingularMatrixException
092         *          if the covariance matrix cannot be computed (singular problem).
093         */
094        RealMatrix getCovariances(double threshold);
095
096        /**
097         * Get an estimate of the standard deviation of the parameters. The returned
098         * values are the square root of the diagonal coefficients of the covariance
099         * matrix, {@code sd(a[i]) ~= sqrt(C[i][i])}, where {@code a[i]} is the optimized
100         * value of the {@code i}-th parameter, and {@code C} is the covariance matrix.
101         *
102         * @param covarianceSingularityThreshold Singularity threshold (see {@link
103         *                                       #getCovariances(double) computeCovariances}).
104         * @return an estimate of the standard deviation of the optimized parameters
105         * @throws org.apache.commons.math4.legacy.linear.SingularMatrixException
106         *          if the covariance matrix cannot be computed.
107         */
108        RealVector getSigma(double covarianceSingularityThreshold);
109
110        /**
111         * Get the normalized cost. It is the square-root of the sum of squared of
112         * the residuals, divided by the number of measurements.
113         *
114         * @return the cost.
115         */
116        double getRMS();
117
118        /**
119         * Get the weighted Jacobian matrix.
120         *
121         * @return the weighted Jacobian: W<sup>1/2</sup> J.
122         * @throws org.apache.commons.math4.legacy.exception.DimensionMismatchException
123         * if the Jacobian dimension does not match problem dimension.
124         */
125        RealMatrix getJacobian();
126
127        /**
128         * Get the cost.
129         * It is the square-root of the {@link #getChiSquare() objective function}.
130         *
131         * @return the cost.
132         * @see #getResiduals()
133         * @see #getChiSquare()
134         */
135        double getCost();
136
137        /**
138         * Get the sum of the squares of the residuals.
139         *
140         * @return the cost.
141         * @see #getResiduals()
142         * @see #getCost()
143         */
144        double getChiSquare();
145
146        /**
147         * Get the reduced chi-square.
148         *
149         * @param n Number of fitted parameters.
150         * @return the sum of the squares of the residuals divided by the number
151         * of degrees of freedom.
152         */
153        double getReducedChiSquare(int n);
154
155        /**
156         * Get the weighted residuals. The residual is the difference between the
157         * observed (target) values and the model (objective function) value. There is one
158         * residual for each element of the vector-valued function. The raw residuals are
159         * then multiplied by the square root of the weight matrix.
160         *
161         * @return the weighted residuals: W<sup>1/2</sup> K.
162         * @throws org.apache.commons.math4.legacy.exception.DimensionMismatchException
163         * if the residuals have the wrong length.
164         */
165        RealVector getResiduals();
166
167        /**
168         * Get the abscissa (independent variables) of this evaluation.
169         *
170         * @return the point provided to {@link #evaluate(RealVector)}.
171         */
172        RealVector getPoint();
173    }
174}