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