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 18 package org.apache.commons.math.ode.sampling; 19 20 import org.apache.commons.math.ode.ContinuousOutputModel; 21 import org.apache.commons.math.ode.DerivativeException; 22 import org.apache.commons.math.ode.FirstOrderIntegrator; 23 import org.apache.commons.math.ode.SecondOrderIntegrator; 24 25 /** 26 * This interface represents a handler that should be called after 27 * each successful step. 28 * 29 * <p>The ODE integrators compute the evolution of the state vector at 30 * some grid points that depend on their own internal algorithm. Once 31 * they have found a new grid point (possibly after having computed 32 * several evaluation of the derivative at intermediate points), they 33 * provide it to objects implementing this interface. These objects 34 * typically either ignore the intermediate steps and wait for the 35 * last one, store the points in an ephemeris, or forward them to 36 * specialized processing or output methods.</p> 37 * 38 * @see FirstOrderIntegrator 39 * @see SecondOrderIntegrator 40 * @see StepInterpolator 41 * @version $Revision: 786881 $ $Date: 2009-06-20 14:53:08 -0400 (Sat, 20 Jun 2009) $ 42 * @since 1.2 43 */ 44 45 public interface StepHandler { 46 47 /** Determines whether this handler needs dense output. 48 * <p>This method allows the integrator to avoid performing extra 49 * computation if the handler does not need dense output. If this 50 * method returns false, the integrator will call the {@link 51 * #handleStep} method with a {@link DummyStepInterpolator} rather 52 * than a custom interpolator.</p> 53 * @return true if the handler needs dense output 54 */ 55 public boolean requiresDenseOutput(); 56 57 /** Reset the step handler. 58 * Initialize the internal data as required before the first step is 59 * handled. 60 */ 61 public void reset(); 62 63 /** 64 * Handle the last accepted step 65 * @param interpolator interpolator for the last accepted step. For 66 * efficiency purposes, the various integrators reuse the same 67 * object on each call, so if the instance wants to keep it across 68 * all calls (for example to provide at the end of the integration a 69 * continuous model valid throughout the integration range, as the 70 * {@link ContinuousOutputModel ContinuousOutputModel} class does), 71 * it should build a local copy using the clone method of the 72 * interpolator and store this copy. Keeping only a reference to the 73 * interpolator and reusing it will result in unpredictable 74 * behaviour (potentially crashing the application). 75 * @param isLast true if the step is the last one 76 * @throws DerivativeException this exception is propagated to the 77 * caller if the underlying user function triggers one 78 */ 79 public void handleStep(StepInterpolator interpolator, boolean isLast) 80 throws DerivativeException; 81 82 }