1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.math4.legacy.fitting.leastsquares;
18
19 import org.apache.commons.math4.legacy.linear.RealMatrix;
20 import org.apache.commons.math4.legacy.linear.RealVector;
21 import org.apache.commons.math4.legacy.optim.OptimizationProblem;
22
23 /**
24 * The data necessary to define a non-linear least squares problem.
25 * <p>
26 * Includes the observed values, computed model function, and
27 * convergence/divergence criteria. Weights are implicit in {@link
28 * Evaluation#getResiduals()} and {@link Evaluation#getJacobian()}.
29 * </p>
30 * <p>
31 * Instances are typically either created progressively using a {@link
32 * LeastSquaresBuilder builder} or created at once using a {@link LeastSquaresFactory
33 * factory}.
34 * </p>
35 * @see LeastSquaresBuilder
36 * @see LeastSquaresFactory
37 * @see LeastSquaresAdapter
38 *
39 * @since 3.3
40 */
41 public interface LeastSquaresProblem extends OptimizationProblem<LeastSquaresProblem.Evaluation> {
42
43 /**
44 * Gets the initial guess.
45 *
46 * @return the initial guess values.
47 */
48 RealVector getStart();
49
50 /**
51 * Get the number of observations (rows in the Jacobian) in this problem.
52 *
53 * @return the number of scalar observations
54 */
55 int getObservationSize();
56
57 /**
58 * Get the number of parameters (columns in the Jacobian) in this problem.
59 *
60 * @return the number of scalar parameters
61 */
62 int getParameterSize();
63
64 /**
65 * Evaluate the model at the specified point.
66 *
67 *
68 * @param point the parameter values.
69 * @return the model's value and derivative at the given point.
70 * @throws org.apache.commons.math4.legacy.exception.TooManyEvaluationsException
71 * if the maximal number of evaluations (of the model vector function) is
72 * exceeded.
73 */
74 Evaluation evaluate(RealVector point);
75
76 /**
77 * An evaluation of a {@link LeastSquaresProblem} at a particular point. This class
78 * also computes several quantities derived from the value and its Jacobian.
79 */
80 interface Evaluation {
81
82 /**
83 * Get the covariance matrix of the optimized parameters. <br> Note that this
84 * operation involves the inversion of the <code>J<sup>T</sup>J</code> matrix,
85 * where {@code J} is the Jacobian matrix. The {@code threshold} parameter is a
86 * way for the caller to specify that the result of this computation should be
87 * considered meaningless, and thus trigger an exception.
88 *
89 * @param threshold Singularity threshold.
90 * @return the covariance matrix.
91 * @throws org.apache.commons.math4.legacy.linear.SingularMatrixException
92 * if the covariance matrix cannot be computed (singular problem).
93 */
94 RealMatrix getCovariances(double threshold);
95
96 /**
97 * Get an estimate of the standard deviation of the parameters. The returned
98 * values are the square root of the diagonal coefficients of the covariance
99 * 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 }