added a section for the ODE package in the user guide
git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/math/trunk@517840 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Luc Maisonobe
parent
9bcae682df
commit
642cf40deb
|
|
@ -0,0 +1,161 @@
|
|||
<?xml version="1.0"?>
|
||||
|
||||
<!--
|
||||
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.
|
||||
-->
|
||||
|
||||
<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
|
||||
<!-- $Revision: 480435 $ $Date: 2006-11-29 08:06:35 +0100 (mer., 29 nov. 2006) $ -->
|
||||
<document url="ode.html">
|
||||
|
||||
<properties>
|
||||
<title>The Commons Math User Guide - Ordinary Differential Equations Integration</title>
|
||||
</properties>
|
||||
|
||||
<body>
|
||||
<section name="14 Ordinary Differential Equations Integration">
|
||||
<subsection name="14.1 Overview" href="overview">
|
||||
<p>
|
||||
The ode package provides classes to solve Ordinary Differential Equations problems.
|
||||
</p>
|
||||
<p>
|
||||
This package solves Initial Value Problems of the form y'=f(t,y) with t<sub>0</sub>
|
||||
and y(t<sub>0</sub>)=y<sub>0</sub> known. The provided integrators compute an estimate
|
||||
of y(t) from t=t<sub>0</sub> to t=t<sub>1</sub>.
|
||||
</p>
|
||||
<p>
|
||||
All integrators provide dense output. This means that besides computing the state vector
|
||||
at discrete times, they also provide a cheap mean to get the state between the time steps.
|
||||
They do so through classes extending the
|
||||
<a href="../apidocs/org/apache/commons/math/ode/StepInterpolator.html">StepInterpolator</a>
|
||||
abstract class, which are made available to the user at the end of each step.
|
||||
</p>
|
||||
<p>
|
||||
All integrators handle multiple switching functions. This means that the integrator can be
|
||||
driven by discrete events (occurring when the signs of user-supplied
|
||||
<a href="../apidocs/org/apache/commons/math/ode/SwitchingFunction.html">switching functions</a>
|
||||
change). The steps are shortened as needed to ensure the events occur at step boundaries (even
|
||||
if the integrator is a fixed-step integrator). When the events are triggered, integration can
|
||||
be stopped (this is called a G-stop facility), the state vector can be changed, or integration
|
||||
can simply go on. The latter case is useful to handle discontinuities in the differential
|
||||
equations gracefully and get accurate dense output even close to the discontinuity. The events
|
||||
are detected when the functions signs are different at the beginning and end of the current step,
|
||||
or at several equidistant points inside the step if its length becomes larger than the maximal
|
||||
checking interval specified for the given switching function. This time interval should be set
|
||||
appropriately to avoid missing some switching function sign changes (it is possible to set it
|
||||
to <code>Double.POSITIVE_INFINITY</code> if the sign changes cannot be missed).
|
||||
</p>
|
||||
<p>
|
||||
The user should describe his problem in his own classes which should implement the
|
||||
<a href="../apidocs/org/apache/commons/math/ode/FirstOrderDifferentialEquations.html">FirstOrderDifferentialEquations</a>
|
||||
interface. Then he should pass it to the integrator he prefers among all the classes that implement
|
||||
the <a href="../apidocs/org/apache/commons/math/ode/FirstOrderIntegrator.html">FirstOrderIntegrator</a>
|
||||
interface.
|
||||
</p>
|
||||
<p>
|
||||
The solution of the integration problem is provided by two means. The first one is aimed towards
|
||||
simple use: the state vector at the end of the integration process is copied in the y array of the
|
||||
<code>FirstOrderIntegrator.integrate</code> method. The second one should be used when more in-depth
|
||||
information is needed throughout the integration process. The user can register an object implementing
|
||||
the <a href="../apidocs/org/apache/commons/math/ode/StepHandler.html">StepHandler</a> interface or a
|
||||
<a href="../apidocs/org/apache/commons/math/ode/StepNormalizer.html">StepNormalizer</a> object wrapping
|
||||
a user-specified object implementing the
|
||||
<a href="../apidocs/org/apache/commons/math/ode/FixedStepHandler.html">FixedStepHandler</a> interface
|
||||
into the integrator before calling the <code>FirstOrderIntegrator.integrate</code> method. The user object
|
||||
will be called appropriately during the integration process, allowing the user to process intermediate
|
||||
results. The default step handler does nothing.
|
||||
</p>
|
||||
<p>
|
||||
<a href="../apidocs/org/apache/commons/math/ode/ContinuousOutputModel.html">ContinuousOutputModel</a>
|
||||
is a special-purpose step handler that is able to store all steps and to provide transparent access to
|
||||
any intermediate result once the integration is over. An important feature of this class is that it
|
||||
implements the <code>Serializable</code> interface. This means that a complete continuous model of the
|
||||
integrated function througout the integration range can be serialized and reused later (if stored into
|
||||
a persistent medium like a filesystem or a database) or elsewhere (if sent to another application).
|
||||
Only the result of the integration is stored, there is no reference to the integrated problem by itself.
|
||||
</p>
|
||||
<p>
|
||||
Other default implementations of the <a href="../apidocs/org/apache/commons/math/ode/StepHandler.html">StepHandler</a>
|
||||
interface are available for general needs
|
||||
(<a href="../apidocs/org/apache/commons/math/ode/DummyStepHandler.html">DummyStepHandler</a>,
|
||||
<a href="../apidocs/org/apache/commons/math/ode/StepNormalizer.html">StepNormalizer</a>) and custom
|
||||
implementations can be developped for specific needs. As an example, if an application is to be
|
||||
completely driven by the integration process, then most of the application code will be run inside a
|
||||
step handler specific to this application.
|
||||
</p>
|
||||
<p>
|
||||
Some integrators (the simple ones) use fixed steps that are set at creation time. The more efficient
|
||||
integrators use variable steps that are handled internally in order to control the integration error
|
||||
with respect to a specified accuracy (these integrators extend the
|
||||
<a href="../apidocs/org/apache/commons/math/ode/AdaptiveStepsizeIntegrator.html">AdaptiveStepsizeIntegrator</a>
|
||||
abstract class). In this case, the step handler which is called after each successful step shows up
|
||||
the variable stepsize. The <a href="../apidocs/org/apache/commons/math/ode/StepNormalizer.html">StepNormalizer</a>
|
||||
class can be used to convert the variable stepsize into a fixed stepsize that can be handled by classes
|
||||
implementing the <a href="../apidocs/org/apache/commons/math/ode/FixedStepHandler.html">FixedStepHandler</a>
|
||||
interface. Adaptive stepsize integrators can automatically compute the initial stepsize by themselves,
|
||||
however the user can specify it if he prefers to retain full control over the integration or if the
|
||||
automatic guess is wrong.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="14.2 ODE Problems" href="problems">
|
||||
<p>
|
||||
First order ODE problems are defined by implementing the
|
||||
<a href="../apidocs/org/apache/commons/math/ode/FirstOrderDifferentialEquations.html">FirstOrderDifferentialEquations</a>
|
||||
interface before they can be handled by the integrators <code>FirstOrderIntegrator.integrate</code>
|
||||
method.
|
||||
</p>
|
||||
<p>
|
||||
A first order differential equations problem, as seen by an integrator is the time
|
||||
derivative <code>dY/dt</code> of a state vector <code>Y</code>, both being one
|
||||
dimensional arrays. From the integrator point of view, this derivative depends
|
||||
only on the current time <code>t</code> and on the state vector <code>Y</code>.
|
||||
</p>
|
||||
<p>
|
||||
For real world problems, the derivative depends also on parameters that do not
|
||||
belong to the state vector (dynamical model constants for example). These
|
||||
constants are completely outside of the scope of this interface, the classes
|
||||
that implement it are allowed to handle them as they want.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="14.3 Integrators" href="integrators">
|
||||
<p>
|
||||
The tables below show the various integrators available.
|
||||
</p>
|
||||
<p>
|
||||
<table border="1" align="center">
|
||||
<tr BGCOLOR="#CCCCFF"><td colspan=2><font size="+2">Fixed Step Integrators</font></td></tr>
|
||||
<tr BGCOLOR="#EEEEFF"><font size="+1"><td>Name</td><td>Order</td></font></tr>
|
||||
<tr><td><a href="../apidocs/org/apache/commons/math/ode/EulerIntegrator.html">Euler</a></td><td>1</td></tr>
|
||||
<tr><td><a href="../apidocs/org/apache/commons/math/ode/MidpointIntegrator.html">Midpoint</a></td><td>2</td></tr>
|
||||
<tr><td><a href="../apidocs/org/apache/commons/math/ode/ClassicalRungeKuttaIntegrator.html">Classical Runge-Kutta</a></td><td>4</td></tr>
|
||||
<tr><td><a href="../apidocs/org/apache/commons/math/ode/GillIntegrator.html">Gill</a></td><td>4</td></tr>
|
||||
<tr><td><a href="../apidocs/org/apache/commons/math/ode/ThreeEighthesIntegrator.html">3/8</a></td><td>4</td></tr>
|
||||
</table>
|
||||
</p>
|
||||
<p>
|
||||
<table border="1" align="center">
|
||||
<tr BGCOLOR="#CCCCFF"><td colspan=3><font size="+2">Adaptive Stepsize Integrators</font></td></tr>
|
||||
<tr BGCOLOR="#EEEEFF"><font size="+1"><td>Name</td><td>Integration Order</td><td>Error Estimation Order</td></font></tr>
|
||||
<tr><td><a href="../apidocs/org/apache/commons/math/ode/HighamHall54Integrator.html">Higham and Hall</a></td><td>5</td><td>4</td></tr>
|
||||
<tr><td><a href="../apidocs/org/apache/commons/math/ode/DormandPrince54Integrator.html">Dormand-Prince 5(4)</a></td><td>5</td><td>4</td></tr>
|
||||
<tr><td><a href="../apidocs/org/apache/commons/math/ode/DormandPrince853Integrator.html">Dormand-Prince 8(5,3)</a></td><td>8</td><td>5 and 3</td></tr>
|
||||
<tr><td><a href="../apidocs/org/apache/commons/math/ode/GraggBulirschStoerIntegrator.html">Gragg-Bulirsch-Stoer</a> variable (up to 18 by default)</td><td>variable</td></tr>
|
||||
</table>
|
||||
</p>
|
||||
</subsection>
|
||||
</section>
|
||||
</body>
|
||||
</document>
|
||||
Loading…
Reference in New Issue