001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018 package org.apache.commons.math.ode.sampling; 019 020 import org.apache.commons.math.ode.ContinuousOutputModel; 021 import org.apache.commons.math.ode.DerivativeException; 022 import org.apache.commons.math.ode.FirstOrderIntegrator; 023 import org.apache.commons.math.ode.SecondOrderIntegrator; 024 025 /** 026 * This interface represents a handler that should be called after 027 * each successful step. 028 * 029 * <p>The ODE integrators compute the evolution of the state vector at 030 * some grid points that depend on their own internal algorithm. Once 031 * they have found a new grid point (possibly after having computed 032 * several evaluation of the derivative at intermediate points), they 033 * provide it to objects implementing this interface. These objects 034 * typically either ignore the intermediate steps and wait for the 035 * last one, store the points in an ephemeris, or forward them to 036 * specialized processing or output methods.</p> 037 * 038 * @see FirstOrderIntegrator 039 * @see SecondOrderIntegrator 040 * @see StepInterpolator 041 * @version $Revision: 786881 $ $Date: 2009-06-20 14:53:08 -0400 (Sat, 20 Jun 2009) $ 042 * @since 1.2 043 */ 044 045 public interface StepHandler { 046 047 /** Determines whether this handler needs dense output. 048 * <p>This method allows the integrator to avoid performing extra 049 * computation if the handler does not need dense output. If this 050 * method returns false, the integrator will call the {@link 051 * #handleStep} method with a {@link DummyStepInterpolator} rather 052 * than a custom interpolator.</p> 053 * @return true if the handler needs dense output 054 */ 055 public boolean requiresDenseOutput(); 056 057 /** Reset the step handler. 058 * Initialize the internal data as required before the first step is 059 * handled. 060 */ 061 public void reset(); 062 063 /** 064 * Handle the last accepted step 065 * @param interpolator interpolator for the last accepted step. For 066 * efficiency purposes, the various integrators reuse the same 067 * object on each call, so if the instance wants to keep it across 068 * all calls (for example to provide at the end of the integration a 069 * continuous model valid throughout the integration range, as the 070 * {@link ContinuousOutputModel ContinuousOutputModel} class does), 071 * it should build a local copy using the clone method of the 072 * interpolator and store this copy. Keeping only a reference to the 073 * interpolator and reusing it will result in unpredictable 074 * behaviour (potentially crashing the application). 075 * @param isLast true if the step is the last one 076 * @throws DerivativeException this exception is propagated to the 077 * caller if the underlying user function triggers one 078 */ 079 public void handleStep(StepInterpolator interpolator, boolean isLast) 080 throws DerivativeException; 081 082 }