Author: luc
Date: Fri Mar 1 17:36:46 2013
New Revision: 1451658
URL: http://svn.apache.org/r1451658
Log:
Improved javadoc to explain how switching functions should behave across
events in ODE events detection.
JIRA: MATH-937
Modified:
commons/proper/math/trunk/src/changes/changes.xml
commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ode/events/EventHandler.java
Modified: commons/proper/math/trunk/src/changes/changes.xml
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/changes/changes.xml?rev=1451658&r1=1451657&r2=1451658&view=diff
==============================================================================
--- commons/proper/math/trunk/src/changes/changes.xml (original)
+++ commons/proper/math/trunk/src/changes/changes.xml Fri Mar 1 17:36:46 2013
@@ -55,6 +55,10 @@ This is a minor release: It combines bug
Changes to existing features were made in a backwards-compatible
way such as to allow drop-in replacement of the v3.1[.1] JAR file.
">
+ <action dev="luc" type="fix" issue="MATH-937" >
+ Improved javadoc to explain how switching functions should
+ behave across events in ODE events detection.
+ </action>
<action dev="luc" type="add" >
Added Hermite interpolator for ExtendFieldElement instances.
</action>
Modified:
commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ode/events/EventHandler.java
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ode/events/EventHandler.java?rev=1451658&r1=1451657&r2=1451658&view=diff
==============================================================================
---
commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ode/events/EventHandler.java
(original)
+++
commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ode/events/EventHandler.java
Fri Mar 1 17:36:46 2013
@@ -17,6 +17,7 @@
package org.apache.commons.math3.ode.events;
+
/** This interface represents a handler for discrete events triggered
* during ODE integration.
*
@@ -107,6 +108,28 @@ public interface EventHandler {
* The switching function must be continuous in its roots neighborhood
* (but not necessarily smooth), as the integrator will need to find its
* roots to locate precisely the events.</p>
+ * <p>Also note that the integrator expect that once an event has occurred,
+ * the sign of the switching function at the start of the next step (i.e.
+ * just after the event) is the opposite of the sign just before the event.
+ * This consistency between the steps <string>must</strong> be preserved,
+ * otherwise {@link org.apache.commons.math3.exception.NoBracketingException
+ * exceptions} related to root not being bracketed will occur.</p>
+ * <p>This need for consistency is sometimes tricky to achieve. A typical
+ * example is using an event to model a ball bouncing on the floor. The first
+ * idea to represent this would be to have {@code g(t) = h(t)} where h is the
+ * height above the floor at time {@code t}. When {@code g(t)} reaches 0, the
+ * ball is on the floor, so it should bounce and the typical way to do this
is
+ * to reverse its vertical velocity. However, this would mean that before the
+ * event {@code g(t)} was decreasing from positive values to 0, and after the
+ * event {@code g(t)} would be increasing from 0 to positive values again.
+ * Consistency is broken here! The solution here is to have {@code g(t) =
sign
+ * * h(t)}, where sign is a variable with initial value set to {@code +1}.
Each
+ * time {@link #eventOccurred(double, double[], boolean) eventOccurred} is
called,
+ * {@code sign} is reset to {@code -sign}. This allows the {@code g(t)}
+ * function to remain continuous (and even smooth) even across events,
despite
+ * {@code h(t)} is not. Basically, the event is used to <em>fold</em> {@code
h(t)}
+ * at bounce points, and {@code sign} is used to <em>unfold</em> it back, so
the
+ * solvers sees a {@code g(t)} function which behaves smoothly even across
events.</p>
* @param t current value of the independent <i>time</i> variable
* @param y array containing the current value of the state vector
