MATH-799

Deprecated default values for thresholds, and constructors that use
them. Scheduled for removal in CM 4.0.


git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1345803 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/math3/optimization/AbstractConvergenceChecker.java

@@ -31,10 +31,14 @@ public abstract class AbstractConvergenceChecker<PAIR>
     implements ConvergenceChecker<PAIR> {
     /**
      * Default relative threshold.
+     * @deprecated in 3.1 (to be removed in 4.0) because this value is too small
+     * to be useful as a default (cf. MATH-798).
      */
     private static final double DEFAULT_RELATIVE_THRESHOLD = 100 * Precision.EPSILON;
     /**
      * Default absolute threshold.
+     * @deprecated in 3.1 (to be removed in 4.0) because this value is too small
+     * to be useful as a default (cf. MATH-798).
      */
     private static final double DEFAULT_ABSOLUTE_THRESHOLD = 100 * Precision.SAFE_MIN;
     /**
@@ -48,7 +52,13 @@ public abstract class AbstractConvergenceChecker<PAIR>
 
     /**
      * Build an instance with default thresholds.
+     * @deprecated in 3.1 (to be removed in 4.0). Convergence thresholds are
+     * problem-dependent. As this class is intended for users who want to set
+     * their own convergence criterion instead of relying on an algorithm's
+     * default procedure, they should also set the thresholds appropriately
+     * (cf. MATH-798).
      */
+    @Deprecated
     public AbstractConvergenceChecker() {
         this.relativeThreshold = DEFAULT_RELATIVE_THRESHOLD;
         this.absoluteThreshold = DEFAULT_ABSOLUTE_THRESHOLD;

src/main/java/org/apache/commons/math3/optimization/SimplePointChecker.java

@@ -39,7 +39,9 @@ public class SimplePointChecker<PAIR extends Pair<double[], ? extends Object>>
     extends AbstractConvergenceChecker<PAIR> {
     /**
      * Build an instance with default threshold.
+     * @deprecated See {@link AbstractConvergenceChecker#AbstractConvergenceChecker()}
      */
+    @Deprecated
     public SimplePointChecker() {}
 
     /**

src/main/java/org/apache/commons/math3/optimization/SimpleValueChecker.java

@@ -35,7 +35,9 @@ public class SimpleValueChecker
     extends AbstractConvergenceChecker<PointValuePair> {
     /**
      * Build an instance with default thresholds.
+     * @deprecated See {@link AbstractConvergenceChecker#AbstractConvergenceChecker()}
      */
+    @Deprecated
     public SimpleValueChecker() {}
 
     /** Build an instance with specified thresholds.

src/main/java/org/apache/commons/math3/optimization/SimpleVectorValueChecker.java

@@ -35,7 +35,9 @@ public class SimpleVectorValueChecker
     extends AbstractConvergenceChecker<PointVectorValuePair> {
     /**
      * Build an instance with default thresholds.
+     * @deprecated See {@link AbstractConvergenceChecker#AbstractConvergenceChecker()}
      */
+    @Deprecated
     public SimpleVectorValueChecker() {}
 
     /**

src/main/java/org/apache/commons/math3/optimization/direct/BOBYQAOptimizer.java

@@ -225,6 +225,7 @@ public class BOBYQAOptimizer
     public BOBYQAOptimizer(int numberOfInterpolationPoints,
                            double initialTrustRegionRadius,
                            double stoppingTrustRegionRadius) {
+        super(null); // No custom convergence criterion.
         this.numberOfInterpolationPoints = numberOfInterpolationPoints;
         this.initialTrustRegionRadius = initialTrustRegionRadius;
         this.stoppingTrustRegionRadius = stoppingTrustRegionRadius;

src/main/java/org/apache/commons/math3/optimization/direct/BaseAbstractMultivariateOptimizer.java

@@ -53,9 +53,10 @@ public abstract class BaseAbstractMultivariateOptimizer<FUNC extends Multivariat
 
     /**
      * Simple constructor with default settings.
-     * The convergence check is set to a {@link SimpleValueChecker} and
-     * the allowed number of evaluations is set to {@link Integer#MAX_VALUE}.
+     * The convergence check is set to a {@link SimpleValueChecker}.
+     * @deprecated See {@link SimpleValueChecker#SimpleValueChecker()}
      */
+    @Deprecated
     protected BaseAbstractMultivariateOptimizer() {
         this(new SimpleValueChecker());
     }

src/main/java/org/apache/commons/math3/optimization/direct/BaseAbstractMultivariateSimpleBoundsOptimizer.java

@@ -51,11 +51,12 @@ public abstract class BaseAbstractMultivariateSimpleBoundsOptimizer<FUNC extends
     /**
      * Simple constructor with default settings.
      * The convergence checker is set to a
-     * {@link org.apache.commons.math3.optimization.SimpleValueChecker} and
-     * the allowed number of evaluations is set to {@link Integer#MAX_VALUE}.
+     * {@link org.apache.commons.math3.optimization.SimpleValueChecker}.
      *
      * @see BaseAbstractMultivariateOptimizer#BaseAbstractMultivariateOptimizer()
+     * @deprecated See {@link org.apache.commons.math3.optimization.SimpleValueChecker#SimpleValueChecker()}
      */
+    @Deprecated
     protected BaseAbstractMultivariateSimpleBoundsOptimizer() {}
 
     /**

src/main/java/org/apache/commons/math3/optimization/direct/BaseAbstractMultivariateVectorOptimizer.java

@@ -55,9 +55,10 @@ public abstract class BaseAbstractMultivariateVectorOptimizer<FUNC extends Multi
 
     /**
      * Simple constructor with default settings.
-     * The convergence check is set to a {@link SimpleVectorValueChecker} and
-     * the allowed number of evaluations is set to {@link Integer#MAX_VALUE}.
+     * The convergence check is set to a {@link SimpleVectorValueChecker}.
+     * @deprecated See {@link SimpleVectorValueChecker#SimpleVectorValueChecker()}
      */
+    @Deprecated
     protected BaseAbstractMultivariateVectorOptimizer() {
         this(new SimpleVectorValueChecker());
     }

src/main/java/org/apache/commons/math3/optimization/direct/CMAESOptimizer.java

@@ -270,7 +270,9 @@ public class CMAESOptimizer
      * generated in case they are out of bounds.
      * @param random Random generator.
      * @param generateStatistics Whether statistic data is collected.
+     * @deprecated See {@link SimpleValueChecker#SimpleValueChecker()}
      */
+    @Deprecated
     public CMAESOptimizer(int lambda, double[] inputSigma,
                           int maxIterations, double stopFitness,
                           boolean isActiveCMA, int diagonalOnly, int checkFeasableCount,

src/main/java/org/apache/commons/math3/optimization/direct/SimplexOptimizer.java

@@ -92,7 +92,9 @@ public class SimplexOptimizer
     /**
      * Constructor using a default {@link SimpleValueChecker convergence
      * checker}.
+     * @deprecated See {@link SimpleValueChecker#SimpleValueChecker()}
      */
+    @Deprecated
     public SimplexOptimizer() {
         this(new SimpleValueChecker());
     }

src/main/java/org/apache/commons/math3/optimization/general/AbstractLeastSquaresOptimizer.java

@@ -82,8 +82,11 @@ public abstract class AbstractLeastSquaresOptimizer
      * Simple constructor with default settings.
      * The convergence check is set to a {@link
      * org.apache.commons.math3.optimization.SimpleVectorValueChecker}.
+     * @deprecated See {@link org.apache.commons.math3.optimization.SimpleValueChecker#SimpleValueChecker()}
      */
+    @Deprecated
     protected AbstractLeastSquaresOptimizer() {}
+
     /**
      * @param checker Convergence checker.
      */

src/main/java/org/apache/commons/math3/optimization/general/AbstractScalarDifferentiableOptimizer.java

@@ -46,8 +46,11 @@ public abstract class AbstractScalarDifferentiableOptimizer
      * The convergence check is set to a
      * {@link org.apache.commons.math3.optimization.SimpleValueChecker
      * SimpleValueChecker}.
+     * @deprecated See {@link org.apache.commons.math3.optimization.SimpleValueChecker#SimpleValueChecker()}
      */
+    @Deprecated
     protected AbstractScalarDifferentiableOptimizer() {}
+
     /**
      * @param checker Convergence checker.
      */

src/main/java/org/apache/commons/math3/optimization/general/GaussNewtonOptimizer.java

@@ -53,7 +53,9 @@ public class GaussNewtonOptimizer extends AbstractLeastSquaresOptimizer {
      * The normal equations will be solved using LU decomposition and the
      * convergence check is set to a {@link SimpleVectorValueChecker}
      * with default tolerances.
+     * @deprecated See {@link SimpleVectorValueChecker#SimpleVectorValueChecker()}
      */
+    @Deprecated
     public GaussNewtonOptimizer() {
         this(true);
     }
@@ -76,7 +78,9 @@ public class GaussNewtonOptimizer extends AbstractLeastSquaresOptimizer {
      * @param useLU If {@code true}, the normal equations will be solved
      * using LU decomposition, otherwise they will be solved using QR
      * decomposition.
+     * @deprecated See {@link SimpleVectorValueChecker#SimpleVectorValueChecker()}
      */
+    @Deprecated
     public GaussNewtonOptimizer(final boolean useLU) {
         this(useLU, new SimpleVectorValueChecker());
     }

src/main/java/org/apache/commons/math3/optimization/general/LevenbergMarquardtOptimizer.java

@@ -260,6 +260,7 @@ public class LevenbergMarquardtOptimizer extends AbstractLeastSquaresOptimizer {
                                        double parRelativeTolerance,
                                        double orthoTolerance,
                                        double threshold) {
+        super(null); // No custom convergence criterion.
         this.initialStepBoundFactor = initialStepBoundFactor;
         this.costRelativeTolerance = costRelativeTolerance;
         this.parRelativeTolerance = parRelativeTolerance;

src/main/java/org/apache/commons/math3/optimization/general/NonLinearConjugateGradientOptimizer.java

@@ -61,7 +61,9 @@ public class NonLinearConjugateGradientOptimizer
      * @param updateFormula formula to use for updating the β parameter,
      * must be one of {@link ConjugateGradientFormula#FLETCHER_REEVES} or {@link
      * ConjugateGradientFormula#POLAK_RIBIERE}.
+     * @deprecated See {@link SimpleValueChecker#SimpleValueChecker()}
      */
+    @Deprecated
     public NonLinearConjugateGradientOptimizer(final ConjugateGradientFormula updateFormula) {
         this(updateFormula,
              new SimpleValueChecker());

src/main/java/org/apache/commons/math3/optimization/univariate/SimpleUnivariateValueChecker.java

@@ -37,7 +37,9 @@ public class SimpleUnivariateValueChecker
     extends AbstractConvergenceChecker<UnivariatePointValuePair> {
     /**
      * Build an instance with default thresholds.
+     * @deprecated See {@link AbstractConvergenceChecker#AbstractConvergenceChecker()}
      */
+    @Deprecated
     public SimpleUnivariateValueChecker() {}
 
     /** Build an instance with specified thresholds.

src/test/java/org/apache/commons/math3/optimization/direct/SimplexOptimizerMultiDirectionalTest.java

@@ -141,7 +141,7 @@ public class SimplexOptimizerMultiDirectionalTest {
     public void testMath283() {
         // fails because MultiDirectional.iterateSimplex is looping forever
         // the while(true) should be replaced with a convergence check
-        SimplexOptimizer optimizer = new SimplexOptimizer();
+        SimplexOptimizer optimizer = new SimplexOptimizer(1e-14, 1e-14);
         optimizer.setSimplex(new MultiDirectionalSimplex(2));
         final Gaussian2D function = new Gaussian2D(0, 0, 1);
         PointValuePair estimate = optimizer.optimize(1000, function,

src/test/java/org/apache/commons/math3/optimization/general/AbstractLeastSquaresOptimizerTest.java

@@ -25,7 +25,7 @@ import org.junit.Test;
 public class AbstractLeastSquaresOptimizerTest {
 
     public static AbstractLeastSquaresOptimizer createOptimizer() {
-        return new AbstractLeastSquaresOptimizer() {
+        return new AbstractLeastSquaresOptimizer(null) {
 
             @Override
             protected PointVectorValuePair doOptimize() {

src/test/java/org/apache/commons/math3/optimization/general/AbstractLeastSquaresOptimizerTestValidation.java

@@ -305,6 +305,10 @@ public class AbstractLeastSquaresOptimizerTestValidation {
  * Used for computing the covariance matrix.
  */
 class DummyOptimizer extends AbstractLeastSquaresOptimizer {
+    public DummyOptimizer() {
+        super(null);
+    }
+
     /**
      * This method does nothing and returns a dummy value.
      */