| <html> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!-- $Revision: 613620 $ --> |
| <body> |
| <p> |
| This package provides classes to handle discrete events occurring during |
| Ordinary Differential Equations integration. |
| </p> |
| |
| <p> |
| Discrete events detection is based on switching functions. The user provides |
| a simple {@link org.apache.commons.math.ode.events.EventHandler#g g(t, y)} |
| function depending on the current time and state. The integrator will monitor |
| the value of the function throughout integration range and will trigger the |
| event when its sign changes. The magnitude of the value is almost irrelevant, |
| it should however be continuous (but not necessarily smooth) for the sake of |
| root finding. The steps are shortened as needed to ensure the events occur |
| at step boundaries (even if the integrator is a fixed-step integrator). |
| </p> |
| |
| <p> |
| When an event is triggered, several different options are available: |
| </p> |
| <ul> |
| <li>integration can be stopped (this is called a G-stop facility),</li> |
| <li>the state vector or the derivatives can be changed,</li> |
| <li>or integration can simply go on.</li> |
| </ul> |
| |
| <p> |
| The first case, G-stop, is the most common one. A typical use case is when an |
| ODE must be solved up to some target state is reached, with a known value of |
| the state but an unknown occurrence time. As an example, if we want to monitor |
| a chemical reaction up to some predefined concentration for the first substance, |
| we can use the following switching function setting: |
| <pre> |
| public double g(double t, double[] y) { |
| return y[0] - targetConcentration; |
| } |
| |
| public int eventOccurred(double t, double[] y) { |
| return STOP; |
| } |
| </pre> |
| </p> |
| |
| <p> |
| The second case, change state vector or derivatives is encountered when dealing |
| with discontinuous dynamical models. A typical case would be the motion of a |
| spacecraft when thrusters are fired for orbital maneuvers. The acceleration is |
| smooth as long as no maneuver are performed, depending only on gravity, drag, |
| third body attraction, radiation pressure. Firing a thruster introduces a |
| discontinuity that must be handled appropriately by the integrator. In such a case, |
| we would use a switching function setting similar to this: |
| <pre> |
| public double g(double t, double[] y) { |
| return (t - tManeuverStart) * (t - tManeuverStop); |
| } |
| |
| public int eventOccurred(double t, double[] y) { |
| return RESET_DERIVATIVES; |
| } |
| </pre> |
| </p> |
| |
| <p> |
| The third case is useful mainly for monitoring purposes, a simple example is: |
| <pre> |
| public double g(double t, double[] y) { |
| return y[0] - y[1]; |
| } |
| |
| public int eventOccurred(double t, double[] y) { |
| logger.log("y0(t) and y1(t) curves cross at t = " + t); |
| return CONTINUE; |
| } |
| </pre> |
| </p> |
| |
| </body> |
| </html> |