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: 785473 $ $Date: 2009-06-17 00:02:35 -0400 (Wed, 17 Jun 2009) $ 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, 077 double maxCheckInterval, 078 double convergence, 079 int maxIterationCount); 080 081 /** Get all the event handlers that have been added to the integrator. 082 * @return an unmodifiable collection of the added events handlers 083 * @see #addEventHandler(EventHandler, double, double, int) 084 * @see #clearEventHandlers() 085 */ 086 Collection<EventHandler> getEventHandlers(); 087 088 /** Remove all the event handlers that have been added to the integrator. 089 * @see #addEventHandler(EventHandler, double, double, int) 090 * @see #getEventHandlers() 091 */ 092 void clearEventHandlers(); 093 094 /** Get the current value of the step start time t<sub>i</sub>. 095 * <p>This method can be called during integration (typically by 096 * the object implementing the {@link FirstOrderDifferentialEquations 097 * differential equations} problem) if the value of the current step that 098 * is attempted is needed.</p> 099 * <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 }