svn commit: r1569347 - /commons/proper/math/trunk/src/main/java/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.java

[lu...@apache.org]

Author: luc
Date: Tue Feb 18 14:32:11 2014
New Revision: 1569347

URL: http://svn.apache.org/r1569347
Log:
Fixup javadoc in LeastSquaresProblem

Modified:
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.java

Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.java?rev=1569347&r1=1569346&r2=1569347&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.java Tue Feb 18 14:32:11 2014
@@ -6,9 +6,11 @@ import org.apache.commons.math3.optim.Po
 
 /**
  * The data necessary to define a non-linear least squares problem. Includes the observed
- * values, computed model function, weights, and convergence/divergence criteria.
+ * values, computed model function, and convergence/divergence criteria. Weights are
+ * implicit in {@link Evaluation#computeResiduals()} and {@link
+ * Evaluation#computeJacobian()}.
  *
- * @author Evan Ward
+ * @version $Id$
  */
 public interface LeastSquaresProblem extends OptimizationProblem<PointVectorValuePair> {
 
@@ -19,13 +21,15 @@ public interface LeastSquaresProblem ext
      */
     double[] getStart();
 
-    /** Get the number of observations (rows in the Jacobian) in this problem.
+    /**
+     * 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.
+    /**
+     * Get the number of parameters (columns in the Jacobian) in this problem.
      *
      * @return the number of scalar parameters
      */
@@ -36,9 +40,16 @@ public interface LeastSquaresProblem ext
      *
      * @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(double[] 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 {
 
         /**
@@ -62,8 +73,7 @@ public interface LeastSquaresProblem ext
          * value of the {@code i}-th parameter, and {@code C} is the covariance matrix.
          *
          * @param covarianceSingularityThreshold Singularity threshold (see {@link
-         *                                       #computeCovariances(double[], double)
-         *                                       computeCovariances}).
+         *                                       #computeCovariances(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.
@@ -82,9 +92,6 @@ public interface LeastSquaresProblem ext
          * Computes the objective (model) function value.
          *
          * @return the objective function value at the specified point.
-         * @throws org.apache.commons.math3.exception.TooManyEvaluationsException
-         *          if the maximal number of evaluations (of the model vector function) is
-         *          exceeded.
          */
         double[] computeValue();
 
@@ -101,7 +108,7 @@ public interface LeastSquaresProblem ext
          * Computes the cost.
          *
          * @return the cost.
-         * @see #computeResiduals(double[])
+         * @see #computeResiduals()
          */
         double computeCost();
 
@@ -112,7 +119,7 @@ public interface LeastSquaresProblem ext
          * then multiplied by the square root of the weight matrix.
          *
          * @return the weighted residuals: W<sup>1/2</sup> K.
-         * @throws DimensionMismatchException if {@code params} has a wrong length.
+         * @throws DimensionMismatchException if the residuals have the wrong length.
          */
         double[] computeResiduals();