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]