Affects Version/s: 2.1
Fix Version/s: 2.2
All ODE solvers support multiple events detection since a long time. Events are specified by users by implementing the EventHandler interface. Events occur when the g(t, y) function evaluates to 0. When an event occurs, the solver step is shortened to make sure the event is located at the end of the step, and the event is triggered by calling the eventOccurred method in the user defined implementation class. Depending on the return value of this method, integration can continue, it can be stopped, or the state vector can be reset.
Some ODE solvers are adaptive step size solvers. They can modify step size to match an integration error setting, increasing step size when error is low (thus reducing computing costs) or reducing step size when error is high (thus fulfilling accuracy requirements).
The step adaptations due to events on one side and due to adaptive step size solvers are quite intricate by now, due to numerous fixes (
MATH-161, MATH-213, MATH-322, MATH-358, MATH-421 and also during standard maintenance - see for example r781157). The code is very difficult to maintain. It seems each bug fix introduces new bugs (r781157/ MATH-322) or tighten the link between adaptive step size and event detection ( MATH-388/r927202).
A new bug discovered recently on an external library using a slightly modified version of this code could not be retroffitted into commons-math, despite the same problem is present. At the beginning of EventState.evaluateStep, the initial step may be exactly 0 thus preventing root solving, but preventing this size to drop to 0 would reopen
MATH-388. I could not fix both bugs at the same time.
So it is now time to untangle events detection and adaptive step size, simplify code, and remove some inefficiency (event root solving is always done twice, once before step truncation and another time after truncation, of course with slightly different results, events shortened steps induce high computation load until the integrator recovers its optimal pace again, steps are rejected even when the event does not requires it ...).