Detect start failures with multi-step ODE integrators.

JIRA: MATH-1297

src/changes/changes.xml

@@ -54,6 +54,9 @@ If the output is not quite correct, check for invisible trailing spaces!
     </release>
 
     <release version="4.0" date="XXXX-XX-XX" description="">
+      <action dev="luc" type="fix" issue="MATH-1297"> <!-- backported to 3.6 -->
+        Detect start failures with multi-step ODE integrators.
+      </action>
       <action dev="luc" type="add" issue="MATH-1302,MATH-1303"> <!-- backported to 3.6 -->
         Added a RotationConvention enumerate to allow specifying the semantics
         or axis/angle for rotations. This enumerate has two values:

src/main/java/org/apache/commons/math4/exception/util/LocalizedFormats.java

@@ -162,6 +162,7 @@ public enum LocalizedFormats implements Localizable {
     LOWER_BOUND_NOT_BELOW_UPPER_BOUND("lower bound ({0}) must be strictly less than upper bound ({1})"), /* keep */
     LOWER_ENDPOINT_ABOVE_UPPER_ENDPOINT("lower endpoint ({0}) must be less than or equal to upper endpoint ({1})"),
     MAP_MODIFIED_WHILE_ITERATING("map has been modified while iterating"),
+    MULTISTEP_STARTER_STOPPED_EARLY("multistep integrator starter stopped early, maybe too large step size"),
     EVALUATIONS("evaluations"), /* keep */
     MAX_COUNT_EXCEEDED("maximal count ({0}) exceeded"), /* keep */
     MAX_ITERATIONS_EXCEEDED("maximal number of iterations ({0}) exceeded"),

src/main/java/org/apache/commons/math4/ode/MultistepIntegrator.java

@@ -18,6 +18,7 @@
 package org.apache.commons.math4.ode;
 
 import org.apache.commons.math4.exception.DimensionMismatchException;
+import org.apache.commons.math4.exception.MathIllegalStateException;
 import org.apache.commons.math4.exception.MaxCountExceededException;
 import org.apache.commons.math4.exception.NoBracketingException;
 import org.apache.commons.math4.exception.NumberIsTooSmallException;
@@ -248,6 +249,9 @@ public abstract class MultistepIntegrator extends AdaptiveStepsizeIntegrator {
                 }, t0, y0, t, new double[y0.length]);
             }
 
+            // we should not reach this step
+            throw new MathIllegalStateException(LocalizedFormats.MULTISTEP_STARTER_STOPPED_EARLY);
+
         } catch (InitializationCompletedMarkerException icme) { // NOPMD
             // this is the expected nominal interruption of the start integrator
 

src/main/resources/assets/org/apache/commons/math4/exception/util/LocalizedFormats_fr.properties

@@ -141,6 +141,7 @@ MAX_ITERATIONS_EXCEEDED = nombre maximal d''it\u00e9rations ({0}) d\u00e9pass\u0
 MINIMAL_STEPSIZE_REACHED_DURING_INTEGRATION = pas minimal ({1,number,0.00E00}) atteint, l''int\u00e9gration n\u00e9cessite {0,number,0.00E00}
 MISMATCHED_LOESS_ABSCISSA_ORDINATE_ARRAYS = Loess a besoin de tableaux d''abscisses et d''ordonn\u00e9es de m\u00eame taille, mais il y a {0} points en abscisse et {1} en ordonn\u00e9e
 MUTATION_RATE = proportion de mutation ({0})
+MULTISTEP_STARTER_STOPPED_EARLY = arr\u00eat pr\u00e9matur\u00e9 du d\u00e9marrage de l''int\u00e9grateur multi-pas, taille de pas peut-\u00eatre trop grande"),
 NAN_ELEMENT_AT_INDEX = l''\u00e9l\u00e9ment {0} est un NaN
 NAN_VALUE_CONVERSION = les valeurs NaN ne peuvent \u00eatre converties
 NEGATIVE_BRIGHTNESS_EXPONENT = l''exposant de brillance devrait \u00eatre positif ou null, or e = {0}

src/test/java/org/apache/commons/math4/exception/util/LocalizedFormatsTest.java

@@ -29,7 +29,7 @@ public class LocalizedFormatsTest {
 
     @Test
     public void testMessageNumber() {
-        Assert.assertEquals(327, LocalizedFormats.values().length);
+        Assert.assertEquals(328, LocalizedFormats.values().length);
     }
 
     @Test

src/test/java/org/apache/commons/math4/ode/nonstiff/AdamsBashforthIntegratorTest.java

@@ -22,12 +22,14 @@ import java.io.ObjectInput;
 import java.io.ObjectOutput;
 
 import org.apache.commons.math4.exception.DimensionMismatchException;
+import org.apache.commons.math4.exception.MathIllegalStateException;
 import org.apache.commons.math4.exception.MaxCountExceededException;
 import org.apache.commons.math4.exception.NoBracketingException;
 import org.apache.commons.math4.exception.NumberIsTooSmallException;
 import org.apache.commons.math4.ode.AbstractIntegrator;
 import org.apache.commons.math4.ode.ExpandableStatefulODE;
 import org.apache.commons.math4.ode.FirstOrderIntegrator;
+import org.apache.commons.math4.ode.MultistepIntegrator;
 import org.apache.commons.math4.ode.TestProblem1;
 import org.apache.commons.math4.ode.TestProblem5;
 import org.apache.commons.math4.ode.TestProblem6;
@@ -163,6 +165,29 @@ public class AdamsBashforthIntegratorTest {
 
     }
 
+    @Test(expected=MathIllegalStateException.class)
+    public void testStartFailure() {
+        TestProblem1 pb = new TestProblem1();
+        double minStep = 0.0001 * (pb.getFinalTime() - pb.getInitialTime());
+        double maxStep = pb.getFinalTime() - pb.getInitialTime();
+        double scalAbsoluteTolerance = 1.0e-6;
+        double scalRelativeTolerance = 1.0e-7;
+
+        MultistepIntegrator integ =
+                        new AdamsBashforthIntegrator(6, minStep, maxStep,
+                                                     scalAbsoluteTolerance,
+                                                     scalRelativeTolerance);
+        integ.setStarterIntegrator(new DormandPrince853Integrator(0.5 * (pb.getFinalTime() - pb.getInitialTime()),
+                                                                  pb.getFinalTime() - pb.getInitialTime(),
+                                                                  0.1, 0.1));
+        TestProblemHandler handler = new TestProblemHandler(pb, integ);
+        integ.addStepHandler(handler);
+        integ.integrate(pb,
+                        pb.getInitialTime(), pb.getInitialState(),
+                        pb.getFinalTime(), new double[pb.getDimension()]);
+
+    }
+
     private static class PerfectStarter extends AbstractIntegrator {
 
         private final PerfectInterpolator interpolator;