Mercurial > hg > de.mpg.mpiwg.itgroup.digilib.plugin

comparison libs/commons-math-2.1/docs/apidocs/src-html/org/apache/commons/math/ode/events/EventHandler.html @ 13:cbf34dd4d7e6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
commons-math-2.1 added
author dwinter
date Tue, 04 Jan 2011 10:02:07 +0100
parents
children
comparison
equal deleted inserted replaced
12:970d26a94fb7 13:cbf34dd4d7e6
1 <HTML>
2 <BODY BGCOLOR="white">
3 <PRE>
4 <FONT color="green">001</FONT> /*<a name="line.1"></a>
5 <FONT color="green">002</FONT> * Licensed to the Apache Software Foundation (ASF) under one or more<a name="line.2"></a>
6 <FONT color="green">003</FONT> * contributor license agreements. See the NOTICE file distributed with<a name="line.3"></a>
7 <FONT color="green">004</FONT> * this work for additional information regarding copyright ownership.<a name="line.4"></a>
8 <FONT color="green">005</FONT> * The ASF licenses this file to You under the Apache License, Version 2.0<a name="line.5"></a>
9 <FONT color="green">006</FONT> * (the "License"); you may not use this file except in compliance with<a name="line.6"></a>
10 <FONT color="green">007</FONT> * the License. You may obtain a copy of the License at<a name="line.7"></a>
11 <FONT color="green">008</FONT> *<a name="line.8"></a>
12 <FONT color="green">009</FONT> * http://www.apache.org/licenses/LICENSE-2.0<a name="line.9"></a>
13 <FONT color="green">010</FONT> *<a name="line.10"></a>
14 <FONT color="green">011</FONT> * Unless required by applicable law or agreed to in writing, software<a name="line.11"></a>
15 <FONT color="green">012</FONT> * distributed under the License is distributed on an "AS IS" BASIS,<a name="line.12"></a>
16 <FONT color="green">013</FONT> * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.<a name="line.13"></a>
17 <FONT color="green">014</FONT> * See the License for the specific language governing permissions and<a name="line.14"></a>
18 <FONT color="green">015</FONT> * limitations under the License.<a name="line.15"></a>
19 <FONT color="green">016</FONT> */<a name="line.16"></a>
20 <FONT color="green">017</FONT> <a name="line.17"></a>
21 <FONT color="green">018</FONT> package org.apache.commons.math.ode.events;<a name="line.18"></a>
22 <FONT color="green">019</FONT> <a name="line.19"></a>
23 <FONT color="green">020</FONT> /** This interface represents a handler for discrete events triggered<a name="line.20"></a>
24 <FONT color="green">021</FONT> * during ODE integration.<a name="line.21"></a>
25 <FONT color="green">022</FONT> *<a name="line.22"></a>
26 <FONT color="green">023</FONT> * &lt;p&gt;Some events can be triggered at discrete times as an ODE problem<a name="line.23"></a>
27 <FONT color="green">024</FONT> * is solved. This occurs for example when the integration process<a name="line.24"></a>
28 <FONT color="green">025</FONT> * should be stopped as some state is reached (G-stop facility) when the<a name="line.25"></a>
29 <FONT color="green">026</FONT> * precise date is unknown a priori, or when the derivatives have<a name="line.26"></a>
30 <FONT color="green">027</FONT> * discontinuities, or simply when the user wants to monitor some<a name="line.27"></a>
31 <FONT color="green">028</FONT> * states boundaries crossings.<a name="line.28"></a>
32 <FONT color="green">029</FONT> * &lt;/p&gt;<a name="line.29"></a>
33 <FONT color="green">030</FONT> *<a name="line.30"></a>
34 <FONT color="green">031</FONT> * &lt;p&gt;These events are defined as occurring when a &lt;code&gt;g&lt;/code&gt;<a name="line.31"></a>
35 <FONT color="green">032</FONT> * switching function sign changes.&lt;/p&gt;<a name="line.32"></a>
36 <FONT color="green">033</FONT> *<a name="line.33"></a>
37 <FONT color="green">034</FONT> * &lt;p&gt;Since events are only problem-dependent and are triggered by the<a name="line.34"></a>
38 <FONT color="green">035</FONT> * independent &lt;i&gt;time&lt;/i&gt; variable and the state vector, they can<a name="line.35"></a>
39 <FONT color="green">036</FONT> * occur at virtually any time, unknown in advance. The integrators will<a name="line.36"></a>
40 <FONT color="green">037</FONT> * take care to avoid sign changes inside the steps, they will reduce<a name="line.37"></a>
41 <FONT color="green">038</FONT> * the step size when such an event is detected in order to put this<a name="line.38"></a>
42 <FONT color="green">039</FONT> * event exactly at the end of the current step. This guarantees that<a name="line.39"></a>
43 <FONT color="green">040</FONT> * step interpolation (which always has a one step scope) is relevant<a name="line.40"></a>
44 <FONT color="green">041</FONT> * even in presence of discontinuities. This is independent from the<a name="line.41"></a>
45 <FONT color="green">042</FONT> * stepsize control provided by integrators that monitor the local<a name="line.42"></a>
46 <FONT color="green">043</FONT> * error (this event handling feature is available for all integrators,<a name="line.43"></a>
47 <FONT color="green">044</FONT> * including fixed step ones).&lt;/p&gt;<a name="line.44"></a>
48 <FONT color="green">045</FONT> *<a name="line.45"></a>
49 <FONT color="green">046</FONT> * @version $Revision: 902214 $ $Date: 2010-01-22 13:40:28 -0500 (Fri, 22 Jan 2010) $<a name="line.46"></a>
50 <FONT color="green">047</FONT> * @since 1.2<a name="line.47"></a>
51 <FONT color="green">048</FONT> */<a name="line.48"></a>
52 <FONT color="green">049</FONT> <a name="line.49"></a>
53 <FONT color="green">050</FONT> public interface EventHandler {<a name="line.50"></a>
54 <FONT color="green">051</FONT> <a name="line.51"></a>
55 <FONT color="green">052</FONT> /** Stop indicator.<a name="line.52"></a>
56 <FONT color="green">053</FONT> * &lt;p&gt;This value should be used as the return value of the {@link<a name="line.53"></a>
57 <FONT color="green">054</FONT> * #eventOccurred eventOccurred} method when the integration should be<a name="line.54"></a>
58 <FONT color="green">055</FONT> * stopped after the event ending the current step.&lt;/p&gt;<a name="line.55"></a>
59 <FONT color="green">056</FONT> */<a name="line.56"></a>
60 <FONT color="green">057</FONT> int STOP = 0;<a name="line.57"></a>
61 <FONT color="green">058</FONT> <a name="line.58"></a>
62 <FONT color="green">059</FONT> /** Reset state indicator.<a name="line.59"></a>
63 <FONT color="green">060</FONT> * &lt;p&gt;This value should be used as the return value of the {@link<a name="line.60"></a>
64 <FONT color="green">061</FONT> * #eventOccurred eventOccurred} method when the integration should<a name="line.61"></a>
65 <FONT color="green">062</FONT> * go on after the event ending the current step, with a new state<a name="line.62"></a>
66 <FONT color="green">063</FONT> * vector (which will be retrieved thanks to the {@link #resetState<a name="line.63"></a>
67 <FONT color="green">064</FONT> * resetState} method).&lt;/p&gt;<a name="line.64"></a>
68 <FONT color="green">065</FONT> */<a name="line.65"></a>
69 <FONT color="green">066</FONT> int RESET_STATE = 1;<a name="line.66"></a>
70 <FONT color="green">067</FONT> <a name="line.67"></a>
71 <FONT color="green">068</FONT> /** Reset derivatives indicator.<a name="line.68"></a>
72 <FONT color="green">069</FONT> * &lt;p&gt;This value should be used as the return value of the {@link<a name="line.69"></a>
73 <FONT color="green">070</FONT> * #eventOccurred eventOccurred} method when the integration should<a name="line.70"></a>
74 <FONT color="green">071</FONT> * go on after the event ending the current step, with a new derivatives<a name="line.71"></a>
75 <FONT color="green">072</FONT> * vector (which will be retrieved thanks to the {@link<a name="line.72"></a>
76 <FONT color="green">073</FONT> * org.apache.commons.math.ode.FirstOrderDifferentialEquations#computeDerivatives}<a name="line.73"></a>
77 <FONT color="green">074</FONT> * method).&lt;/p&gt;<a name="line.74"></a>
78 <FONT color="green">075</FONT> */<a name="line.75"></a>
79 <FONT color="green">076</FONT> int RESET_DERIVATIVES = 2;<a name="line.76"></a>
80 <FONT color="green">077</FONT> <a name="line.77"></a>
81 <FONT color="green">078</FONT> /** Continue indicator.<a name="line.78"></a>
82 <FONT color="green">079</FONT> * &lt;p&gt;This value should be used as the return value of the {@link<a name="line.79"></a>
83 <FONT color="green">080</FONT> * #eventOccurred eventOccurred} method when the integration should go<a name="line.80"></a>
84 <FONT color="green">081</FONT> * on after the event ending the current step.&lt;/p&gt;<a name="line.81"></a>
85 <FONT color="green">082</FONT> */<a name="line.82"></a>
86 <FONT color="green">083</FONT> int CONTINUE = 3;<a name="line.83"></a>
87 <FONT color="green">084</FONT> <a name="line.84"></a>
88 <FONT color="green">085</FONT> /** Compute the value of the switching function.<a name="line.85"></a>
89 <FONT color="green">086</FONT> <a name="line.86"></a>
90 <FONT color="green">087</FONT> * &lt;p&gt;The discrete events are generated when the sign of this<a name="line.87"></a>
91 <FONT color="green">088</FONT> * switching function changes. The integrator will take care to change<a name="line.88"></a>
92 <FONT color="green">089</FONT> * the stepsize in such a way these events occur exactly at step boundaries.<a name="line.89"></a>
93 <FONT color="green">090</FONT> * The switching function must be continuous in its roots neighborhood<a name="line.90"></a>
94 <FONT color="green">091</FONT> * (but not necessarily smooth), as the integrator will need to find its<a name="line.91"></a>
95 <FONT color="green">092</FONT> * roots to locate precisely the events.&lt;/p&gt;<a name="line.92"></a>
96 <FONT color="green">093</FONT> <a name="line.93"></a>
97 <FONT color="green">094</FONT> * @param t current value of the independent &lt;i&gt;time&lt;/i&gt; variable<a name="line.94"></a>
98 <FONT color="green">095</FONT> * @param y array containing the current value of the state vector<a name="line.95"></a>
99 <FONT color="green">096</FONT> * @return value of the g switching function<a name="line.96"></a>
100 <FONT color="green">097</FONT> * @exception EventException if the switching function cannot be evaluated<a name="line.97"></a>
101 <FONT color="green">098</FONT> */<a name="line.98"></a>
102 <FONT color="green">099</FONT> double g(double t, double[] y) throws EventException;<a name="line.99"></a>
103 <FONT color="green">100</FONT> <a name="line.100"></a>
104 <FONT color="green">101</FONT> /** Handle an event and choose what to do next.<a name="line.101"></a>
105 <FONT color="green">102</FONT> <a name="line.102"></a>
106 <FONT color="green">103</FONT> * &lt;p&gt;This method is called when the integrator has accepted a step<a name="line.103"></a>
107 <FONT color="green">104</FONT> * ending exactly on a sign change of the function, just &lt;em&gt;before&lt;/em&gt;<a name="line.104"></a>
108 <FONT color="green">105</FONT> * the step handler itself is called (see below for scheduling). It<a name="line.105"></a>
109 <FONT color="green">106</FONT> * allows the user to update his internal data to acknowledge the fact<a name="line.106"></a>
110 <FONT color="green">107</FONT> * the event has been handled (for example setting a flag in the {@link<a name="line.107"></a>
111 <FONT color="green">108</FONT> * org.apache.commons.math.ode.FirstOrderDifferentialEquations<a name="line.108"></a>
112 <FONT color="green">109</FONT> * differential equations} to switch the derivatives computation in<a name="line.109"></a>
113 <FONT color="green">110</FONT> * case of discontinuity), or to direct the integrator to either stop<a name="line.110"></a>
114 <FONT color="green">111</FONT> * or continue integration, possibly with a reset state or derivatives.&lt;/p&gt;<a name="line.111"></a>
115 <FONT color="green">112</FONT> <a name="line.112"></a>
116 <FONT color="green">113</FONT> * &lt;ul&gt;<a name="line.113"></a>
117 <FONT color="green">114</FONT> * &lt;li&gt;if {@link #STOP} is returned, the step handler will be called<a name="line.114"></a>
118 <FONT color="green">115</FONT> * with the &lt;code&gt;isLast&lt;/code&gt; flag of the {@link<a name="line.115"></a>
119 <FONT color="green">116</FONT> * org.apache.commons.math.ode.sampling.StepHandler#handleStep handleStep}<a name="line.116"></a>
120 <FONT color="green">117</FONT> * method set to true and the integration will be stopped,&lt;/li&gt;<a name="line.117"></a>
121 <FONT color="green">118</FONT> * &lt;li&gt;if {@link #RESET_STATE} is returned, the {@link #resetState<a name="line.118"></a>
122 <FONT color="green">119</FONT> * resetState} method will be called once the step handler has<a name="line.119"></a>
123 <FONT color="green">120</FONT> * finished its task, and the integrator will also recompute the<a name="line.120"></a>
124 <FONT color="green">121</FONT> * derivatives,&lt;/li&gt;<a name="line.121"></a>
125 <FONT color="green">122</FONT> * &lt;li&gt;if {@link #RESET_DERIVATIVES} is returned, the integrator<a name="line.122"></a>
126 <FONT color="green">123</FONT> * will recompute the derivatives,<a name="line.123"></a>
127 <FONT color="green">124</FONT> * &lt;li&gt;if {@link #CONTINUE} is returned, no specific action will<a name="line.124"></a>
128 <FONT color="green">125</FONT> * be taken (apart from having called this method) and integration<a name="line.125"></a>
129 <FONT color="green">126</FONT> * will continue.&lt;/li&gt;<a name="line.126"></a>
130 <FONT color="green">127</FONT> * &lt;/ul&gt;<a name="line.127"></a>
131 <FONT color="green">128</FONT> <a name="line.128"></a>
132 <FONT color="green">129</FONT> * &lt;p&gt;The scheduling between this method and the {@link<a name="line.129"></a>
133 <FONT color="green">130</FONT> * org.apache.commons.math.ode.sampling.StepHandler StepHandler} method {@link<a name="line.130"></a>
134 <FONT color="green">131</FONT> * org.apache.commons.math.ode.sampling.StepHandler#handleStep(<a name="line.131"></a>
135 <FONT color="green">132</FONT> * org.apache.commons.math.ode.sampling.StepInterpolator, boolean)<a name="line.132"></a>
136 <FONT color="green">133</FONT> * handleStep(interpolator, isLast)} is to call this method first and<a name="line.133"></a>
137 <FONT color="green">134</FONT> * &lt;code&gt;handleStep&lt;/code&gt; afterwards. This scheduling allows the integrator to<a name="line.134"></a>
138 <FONT color="green">135</FONT> * pass &lt;code&gt;true&lt;/code&gt; as the &lt;code&gt;isLast&lt;/code&gt; parameter to the step<a name="line.135"></a>
139 <FONT color="green">136</FONT> * handler to make it aware the step will be the last one if this method<a name="line.136"></a>
140 <FONT color="green">137</FONT> * returns {@link #STOP}. As the interpolator may be used to navigate back<a name="line.137"></a>
141 <FONT color="green">138</FONT> * throughout the last step (as {@link<a name="line.138"></a>
142 <FONT color="green">139</FONT> * org.apache.commons.math.ode.sampling.StepNormalizer StepNormalizer}<a name="line.139"></a>
143 <FONT color="green">140</FONT> * does for example), user code called by this method and user<a name="line.140"></a>
144 <FONT color="green">141</FONT> * code called by step handlers may experience apparently out of order values<a name="line.141"></a>
145 <FONT color="green">142</FONT> * of the independent time variable. As an example, if the same user object<a name="line.142"></a>
146 <FONT color="green">143</FONT> * implements both this {@link EventHandler EventHandler} interface and the<a name="line.143"></a>
147 <FONT color="green">144</FONT> * {@link org.apache.commons.math.ode.sampling.FixedStepHandler FixedStepHandler}<a name="line.144"></a>
148 <FONT color="green">145</FONT> * interface, a &lt;em&gt;forward&lt;/em&gt; integration may call its<a name="line.145"></a>
149 <FONT color="green">146</FONT> * &lt;code&gt;eventOccurred&lt;/code&gt; method with t = 10 first and call its<a name="line.146"></a>
150 <FONT color="green">147</FONT> * &lt;code&gt;handleStep&lt;/code&gt; method with t = 9 afterwards. Such out of order<a name="line.147"></a>
151 <FONT color="green">148</FONT> * calls are limited to the size of the integration step for {@link<a name="line.148"></a>
152 <FONT color="green">149</FONT> * org.apache.commons.math.ode.sampling.StepHandler variable step handlers} and<a name="line.149"></a>
153 <FONT color="green">150</FONT> * to the size of the fixed step for {@link<a name="line.150"></a>
154 <FONT color="green">151</FONT> * org.apache.commons.math.ode.sampling.FixedStepHandler fixed step handlers}.&lt;/p&gt;<a name="line.151"></a>
155 <FONT color="green">152</FONT> <a name="line.152"></a>
156 <FONT color="green">153</FONT> * @param t current value of the independent &lt;i&gt;time&lt;/i&gt; variable<a name="line.153"></a>
157 <FONT color="green">154</FONT> * @param y array containing the current value of the state vector<a name="line.154"></a>
158 <FONT color="green">155</FONT> * @param increasing if true, the value of the switching function increases<a name="line.155"></a>
159 <FONT color="green">156</FONT> * when times increases around event (note that increase is measured with respect<a name="line.156"></a>
160 <FONT color="green">157</FONT> * to physical time, not with respect to integration which may go backward in time)<a name="line.157"></a>
161 <FONT color="green">158</FONT> * @return indication of what the integrator should do next, this<a name="line.158"></a>
162 <FONT color="green">159</FONT> * value must be one of {@link #STOP}, {@link #RESET_STATE},<a name="line.159"></a>
163 <FONT color="green">160</FONT> * {@link #RESET_DERIVATIVES} or {@link #CONTINUE}<a name="line.160"></a>
164 <FONT color="green">161</FONT> * @exception EventException if the event occurrence triggers an error<a name="line.161"></a>
165 <FONT color="green">162</FONT> */<a name="line.162"></a>
166 <FONT color="green">163</FONT> int eventOccurred(double t, double[] y, boolean increasing) throws EventException;<a name="line.163"></a>
167 <FONT color="green">164</FONT> <a name="line.164"></a>
168 <FONT color="green">165</FONT> /** Reset the state prior to continue the integration.<a name="line.165"></a>
169 <FONT color="green">166</FONT> <a name="line.166"></a>
170 <FONT color="green">167</FONT> * &lt;p&gt;This method is called after the step handler has returned and<a name="line.167"></a>
171 <FONT color="green">168</FONT> * before the next step is started, but only when {@link<a name="line.168"></a>
172 <FONT color="green">169</FONT> * #eventOccurred} has itself returned the {@link #RESET_STATE}<a name="line.169"></a>
173 <FONT color="green">170</FONT> * indicator. It allows the user to reset the state vector for the<a name="line.170"></a>
174 <FONT color="green">171</FONT> * next step, without perturbing the step handler of the finishing<a name="line.171"></a>
175 <FONT color="green">172</FONT> * step. If the {@link #eventOccurred} never returns the {@link<a name="line.172"></a>
176 <FONT color="green">173</FONT> * #RESET_STATE} indicator, this function will never be called, and it is<a name="line.173"></a>
177 <FONT color="green">174</FONT> * safe to leave its body empty.&lt;/p&gt;<a name="line.174"></a>
178 <FONT color="green">175</FONT> <a name="line.175"></a>
179 <FONT color="green">176</FONT> * @param t current value of the independent &lt;i&gt;time&lt;/i&gt; variable<a name="line.176"></a>
180 <FONT color="green">177</FONT> * @param y array containing the current value of the state vector<a name="line.177"></a>
181 <FONT color="green">178</FONT> * the new state should be put in the same array<a name="line.178"></a>
182 <FONT color="green">179</FONT> * @exception EventException if the state cannot be reseted<a name="line.179"></a>
183 <FONT color="green">180</FONT> */<a name="line.180"></a>
184 <FONT color="green">181</FONT> void resetState(double t, double[] y) throws EventException;<a name="line.181"></a>
185 <FONT color="green">182</FONT> <a name="line.182"></a>
186 <FONT color="green">183</FONT> }<a name="line.183"></a>
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247 </PRE>
248 </BODY>
249 </HTML>