View Javadoc

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 }