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