Author: luc
Date: Tue Mar 13 13:03:40 2007
New Revision: 517840
URL: http://svn.apache.org/viewvc?view=rev&rev=517840
Log:
added a section for the ODE package in the user guide
Added:
jakarta/commons/proper/math/trunk/xdocs/userguide/ode.xml (with props)
Added: jakarta/commons/proper/math/trunk/xdocs/userguide/ode.xml
URL:
http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/xdocs/userguide/ode.xml?view=auto&rev=517840
==============================================================================
--- jakarta/commons/proper/math/trunk/xdocs/userguide/ode.xml (added)
+++ jakarta/commons/proper/math/trunk/xdocs/userguide/ode.xml Tue Mar 13
13:03:40 2007
@@ -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>
Propchange: jakarta/commons/proper/math/trunk/xdocs/userguide/ode.xml
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
