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 import java.util.Collection; 21 22 import org.apache.commons.math.ode.events.EventHandler; 23 import org.apache.commons.math.ode.sampling.StepHandler; 24 25 /** 26 * This interface defines the common parts shared by integrators 27 * for first and second order differential equations. 28 * @see FirstOrderIntegrator 29 * @see SecondOrderIntegrator 30 * @version $Revision: 1061507 $ $Date: 2011-01-20 21:55:00 +0100 (jeu. 20 janv. 2011) $ 31 * @since 2.0 32 */ 33 public interface ODEIntegrator { 34 35 /** Get the name of the method. 36 * @return name of the method 37 */ getName()38 String getName(); 39 40 /** Add a step handler to this integrator. 41 * <p>The handler will be called by the integrator for each accepted 42 * step.</p> 43 * @param handler handler for the accepted steps 44 * @see #getStepHandlers() 45 * @see #clearStepHandlers() 46 * @since 2.0 47 */ addStepHandler(StepHandler handler)48 void addStepHandler(StepHandler handler); 49 50 /** Get all the step handlers that have been added to the integrator. 51 * @return an unmodifiable collection of the added events handlers 52 * @see #addStepHandler(StepHandler) 53 * @see #clearStepHandlers() 54 * @since 2.0 55 */ getStepHandlers()56 Collection<StepHandler> getStepHandlers(); 57 58 /** Remove all the step handlers that have been added to the integrator. 59 * @see #addStepHandler(StepHandler) 60 * @see #getStepHandlers() 61 * @since 2.0 62 */ clearStepHandlers()63 void clearStepHandlers(); 64 65 /** Add an event handler to the integrator. 66 * @param handler event handler 67 * @param maxCheckInterval maximal time interval between switching 68 * function checks (this interval prevents missing sign changes in 69 * case the integration steps becomes very large) 70 * @param convergence convergence threshold in the event time search 71 * @param maxIterationCount upper limit of the iteration count in 72 * the event time search 73 * @see #getEventHandlers() 74 * @see #clearEventHandlers() 75 */ addEventHandler(EventHandler handler, double maxCheckInterval, double convergence, int maxIterationCount)76 void addEventHandler(EventHandler handler, double maxCheckInterval, 77 double convergence, int maxIterationCount); 78 79 /** Get all the event handlers that have been added to the integrator. 80 * @return an unmodifiable collection of the added events handlers 81 * @see #addEventHandler(EventHandler, double, double, int) 82 * @see #clearEventHandlers() 83 */ getEventHandlers()84 Collection<EventHandler> getEventHandlers(); 85 86 /** Remove all the event handlers that have been added to the integrator. 87 * @see #addEventHandler(EventHandler, double, double, int) 88 * @see #getEventHandlers() 89 */ clearEventHandlers()90 void clearEventHandlers(); 91 92 /** Get the current value of the step start time t<sub>i</sub>. 93 * <p>This method can be called during integration (typically by 94 * the object implementing the {@link FirstOrderDifferentialEquations 95 * differential equations} problem) if the value of the current step that 96 * is attempted is needed.</p> 97 * <p>The result is undefined if the method is called outside of 98 * calls to <code>integrate</code>.</p> 99 * @return current value of the step start time t<sub>i</sub> 100 */ getCurrentStepStart()101 double getCurrentStepStart(); 102 103 /** Get the current signed value of the integration stepsize. 104 * <p>This method can be called during integration (typically by 105 * the object implementing the {@link FirstOrderDifferentialEquations 106 * differential equations} problem) if the signed value of the current stepsize 107 * that is tried is needed.</p> 108 * <p>The result is undefined if the method is called outside of 109 * calls to <code>integrate</code>.</p> 110 * @return current signed value of the stepsize 111 */ getCurrentSignedStepsize()112 double getCurrentSignedStepsize(); 113 114 /** Set the maximal number of differential equations function evaluations. 115 * <p>The purpose of this method is to avoid infinite loops which can occur 116 * for example when stringent error constraints are set or when lots of 117 * discrete events are triggered, thus leading to many rejected steps.</p> 118 * @param maxEvaluations maximal number of function evaluations (negative 119 * values are silently converted to maximal integer value, thus representing 120 * almost unlimited evaluations) 121 */ setMaxEvaluations(int maxEvaluations)122 void setMaxEvaluations(int maxEvaluations); 123 124 /** Get the maximal number of functions evaluations. 125 * @return maximal number of functions evaluations 126 */ getMaxEvaluations()127 int getMaxEvaluations(); 128 129 /** Get the number of evaluations of the differential equations function. 130 * <p> 131 * The number of evaluations corresponds to the last call to the 132 * <code>integrate</code> method. It is 0 if the method has not been called yet. 133 * </p> 134 * @return number of evaluations of the differential equations function 135 */ getEvaluations()136 int getEvaluations(); 137 138 } 139