← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/commons-math/oneiric

« back to all changes in this revision

Viewing changes to src/main/java/org/apache/commons/math/ode/events/package.html

  • Committer: Bazaar Package Importer
  • Author(s): Damien Raude-Morvan
  • Date: 2009-08-22 01:13:25 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20090822011325-hi4peq1ua5weguwn
Tags: 2.0-1
* New upstream release.
* Set Maintainer field to Debian Java Team
* Add myself as Uploaders
* Switch to Quilt patch system:
  - Refresh all patchs
  - Remove B-D on dpatch, Add B-D on quilt
  - Include patchsys-quilt.mk in debian/rules
* Bump Standards-Version to 3.8.3:
  - Add a README.source to describe patch system
* Maven POMs:
  - Add a Build-Depends-Indep dependency on maven-repo-helper
  - Use mh_installpom and mh_installjar to install the POM and the jar to the
    Maven repository
* Use default-jdk/jre:
  - Depends on java5-runtime-headless
  - Build-Depends on default-jdk
  - Use /usr/lib/jvm/default-java as JAVA_HOME
* Move api documentation to /usr/share/doc/libcommons-math-java/api
* Build-Depends on junit4 instead of junit

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/main/java/org/apache/commons/math/ode/events/package.html
 
1
<html>
 
2
<!--
 
3
   Licensed to the Apache Software Foundation (ASF) under one or more
 
4
  contributor license agreements.  See the NOTICE file distributed with
 
5
  this work for additional information regarding copyright ownership.
 
6
  The ASF licenses this file to You under the Apache License, Version 2.0
 
7
  (the "License"); you may not use this file except in compliance with
 
8
  the License.  You may obtain a copy of the License at
 
9
 
 
10
       http://www.apache.org/licenses/LICENSE-2.0
 
11
 
 
12
   Unless required by applicable law or agreed to in writing, software
 
13
   distributed under the License is distributed on an "AS IS" BASIS,
 
14
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 
15
   See the License for the specific language governing permissions and
 
16
   limitations under the License.
 
17
  -->
 
18
    <!-- $Revision: 613620 $ -->
 
19
<body>
 
20
<p>
 
21
This package provides classes to handle discrete events occurring during
 
22
Ordinary Differential Equations integration.
 
23
</p>
 
24
 
 
25
<p>
 
26
Discrete events detection is based on switching functions. The user provides
 
27
a simple {@link org.apache.commons.math.ode.events.EventHandler#g g(t, y)}
 
28
function depending on the current time and state. The integrator will monitor
 
29
the value of the function throughout integration range and will trigger the
 
30
event when its sign changes. The magnitude of the value is almost irrelevant,
 
31
it should however be continuous (but not necessarily smooth) for the sake of
 
32
root finding. The steps are shortened as needed to ensure the events occur
 
33
at step boundaries (even if the integrator is a fixed-step integrator).
 
34
</p>
 
35
 
 
36
<p>
 
37
When an event is triggered, several different options are available:
 
38
</p>
 
39
<ul>
 
40
  <li>integration can be stopped (this is called a G-stop facility),</li>
 
41
  <li>the state vector or the derivatives can be changed,</li>
 
42
  <li>or integration can simply go on.</li>
 
43
</ul>
 
44
 
 
45
<p>
 
46
The first case, G-stop, is the most common one. A typical use case is when an
 
47
ODE must be solved up to some target state is reached, with a known value of
 
48
the state but an unknown occurrence time. As an example, if we want to monitor
 
49
a chemical reaction up to some predefined concentration for the first substance,
 
50
we can use the following switching function setting:
 
51
<pre>
 
52
  public double g(double t, double[] y) {
 
53
    return y[0] - targetConcentration;
 
54
  }
 
55
 
 
56
  public int eventOccurred(double t, double[] y) {
 
57
    return STOP;
 
58
  }
 
59
</pre>
 
60
</p>
 
61
 
 
62
<p>
 
63
The second case, change state vector or derivatives is encountered when dealing
 
64
with discontinuous dynamical models. A typical case would be the motion of a
 
65
spacecraft when thrusters are fired for orbital maneuvers. The acceleration is
 
66
smooth as long as no maneuver are performed, depending only on gravity, drag,
 
67
third body attraction, radiation pressure. Firing a thruster introduces a
 
68
discontinuity that must be handled appropriately by the integrator. In such a case,
 
69
we would use a switching function setting similar to this:
 
70
<pre>
 
71
  public double g(double t, double[] y) {
 
72
    return (t - tManeuverStart) * (t - tManeuverStop);
 
73
  }
 
74
 
 
75
  public int eventOccurred(double t, double[] y) {
 
76
    return RESET_DERIVATIVES;
 
77
  }
 
78
</pre>
 
79
</p>
 
80
 
 
81
<p>
 
82
The third case is useful mainly for monitoring purposes, a simple example is:
 
83
<pre>
 
84
  public double g(double t, double[] y) {
 
85
    return y[0] - y[1];
 
86
  }
 
87
 
 
88
  public int eventOccurred(double t, double[] y) {
 
89
    logger.log("y0(t) and y1(t) curves cross at t = " + t);
 
90
    return CONTINUE;
 
91
  }
 
92
</pre>
 
93
</p>
 
94
 
 
95
</body>
 
96
</html>