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; 019 020 import java.util.Collection; 021 022 import org.apache.commons.math.ode.events.EventHandler; 023 import org.apache.commons.math.ode.sampling.StepHandler; 024 025 /** 026 * This interface defines the common parts shared by integrators 027 * for first and second order differential equations. 028 * @see FirstOrderIntegrator 029 * @see SecondOrderIntegrator 030 * @version $Revision: 1061507 $ $Date: 2011-01-20 21:55:00 +0100 (jeu. 20 janv. 2011) $ 031 * @since 2.0 032 */ 033 public interface ODEIntegrator { 034 035 /** Get the name of the method. 036 * @return name of the method 037 */ 038 String getName(); 039 040 /** Add a step handler to this integrator. 041 * <p>The handler will be called by the integrator for each accepted 042 * step.</p> 043 * @param handler handler for the accepted steps 044 * @see #getStepHandlers() 045 * @see #clearStepHandlers() 046 * @since 2.0 047 */ 048 void addStepHandler(StepHandler handler); 049 050 /** Get all the step handlers that have been added to the integrator. 051 * @return an unmodifiable collection of the added events handlers 052 * @see #addStepHandler(StepHandler) 053 * @see #clearStepHandlers() 054 * @since 2.0 055 */ 056 Collection<StepHandler> getStepHandlers(); 057 058 /** Remove all the step handlers that have been added to the integrator. 059 * @see #addStepHandler(StepHandler) 060 * @see #getStepHandlers() 061 * @since 2.0 062 */ 063 void clearStepHandlers(); 064 065 /** Add an event handler to the integrator. 066 * @param handler event handler 067 * @param maxCheckInterval maximal time interval between switching 068 * function checks (this interval prevents missing sign changes in 069 * case the integration steps becomes very large) 070 * @param convergence convergence threshold in the event time search 071 * @param maxIterationCount upper limit of the iteration count in 072 * the event time search 073 * @see #getEventHandlers() 074 * @see #clearEventHandlers() 075 */ 076 void addEventHandler(EventHandler handler, double maxCheckInterval, 077 double convergence, int maxIterationCount); 078 079 /** Get all the event handlers that have been added to the integrator. 080 * @return an unmodifiable collection of the added events handlers 081 * @see #addEventHandler(EventHandler, double, double, int) 082 * @see #clearEventHandlers() 083 */ 084 Collection<EventHandler> getEventHandlers(); 085 086 /** Remove all the event handlers that have been added to the integrator. 087 * @see #addEventHandler(EventHandler, double, double, int) 088 * @see #getEventHandlers() 089 */ 090 void clearEventHandlers(); 091 092 /** Get the current value of the step start time t<sub>i</sub>. 093 * <p>This method can be called during integration (typically by 094 * the object implementing the {@link FirstOrderDifferentialEquations 095 * differential equations} problem) if the value of the current step that 096 * is attempted is needed.</p> 097 * <p>The result is undefined if the method is called outside of 098 * calls to <code>integrate</code>.</p> 099 * @return current value of the step start time t<sub>i</sub> 100 */ 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 */ 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 */ 122 void setMaxEvaluations(int maxEvaluations); 123 124 /** Get the maximal number of functions evaluations. 125 * @return maximal number of functions evaluations 126 */ 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 */ 136 int getEvaluations(); 137 138 }