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: 785473 $ $Date: 2009-06-17 00:02:35 -0400 (Wed, 17 Jun 2009) $ 31 * @since 2.0 32 */ 33 public interface ODEIntegrator { 34 35 /** Get the name of the method. 36 * @return name of the method 37 */ 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 */ 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 */ 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 */ 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 */ 76 void addEventHandler(EventHandler handler, 77 double maxCheckInterval, 78 double convergence, 79 int maxIterationCount); 80 81 /** Get all the event handlers that have been added to the integrator. 82 * @return an unmodifiable collection of the added events handlers 83 * @see #addEventHandler(EventHandler, double, double, int) 84 * @see #clearEventHandlers() 85 */ 86 Collection<EventHandler> getEventHandlers(); 87 88 /** Remove all the event handlers that have been added to the integrator. 89 * @see #addEventHandler(EventHandler, double, double, int) 90 * @see #getEventHandlers() 91 */ 92 void clearEventHandlers(); 93 94 /** Get the current value of the step start time t<sub>i</sub>. 95 * <p>This method can be called during integration (typically by 96 * the object implementing the {@link FirstOrderDifferentialEquations 97 * differential equations} problem) if the value of the current step that 98 * is attempted is needed.</p> 99 * <p>The result is undefined if the method is called outside of 100 * calls to <code>integrate</code>.</p> 101 * @return current value of the step start time t<sub>i</sub> 102 */ 103 double getCurrentStepStart(); 104 105 /** Get the current signed value of the integration stepsize. 106 * <p>This method can be called during integration (typically by 107 * the object implementing the {@link FirstOrderDifferentialEquations 108 * differential equations} problem) if the signed value of the current stepsize 109 * that is tried is needed.</p> 110 * <p>The result is undefined if the method is called outside of 111 * calls to <code>integrate</code>.</p> 112 * @return current signed value of the stepsize 113 */ 114 double getCurrentSignedStepsize(); 115 116 /** Set the maximal number of differential equations function evaluations. 117 * <p>The purpose of this method is to avoid infinite loops which can occur 118 * for example when stringent error constraints are set or when lots of 119 * discrete events are triggered, thus leading to many rejected steps.</p> 120 * @param maxEvaluations maximal number of function evaluations (negative 121 * values are silently converted to maximal integer value, thus representing 122 * almost unlimited evaluations) 123 */ 124 void setMaxEvaluations(int maxEvaluations); 125 126 /** Get the maximal number of functions evaluations. 127 * @return maximal number of functions evaluations 128 */ 129 int getMaxEvaluations(); 130 131 /** Get the number of evaluations of the differential equations function. 132 * <p> 133 * The number of evaluations corresponds to the last call to the 134 * <code>integrate</code> method. It is 0 if the method has not been called yet. 135 * </p> 136 * @return number of evaluations of the differential equations function 137 */ 138 int getEvaluations(); 139 140 }