org.apache.commons.math3.ode.package-info Maven / Gradle / Ivy
Show all versions of commons-math3 Show documentation
/*
* 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.
*/
/**
*
*
* This package provides classes to solve Ordinary Differential Equations problems.
*
*
*
* This package solves Initial Value Problems of the form
* y'=f(t,y) with t0 and
* y(t0)=y0 known. The provided
* integrators compute an estimate of y(t) from
* t=t0 to t=t1.
* It is also possible to get thederivatives with respect to the initial state
* dy(t)/dy(t0) or the derivatives with
* respect to some ODE parameters dy(t)/dp.
*
*
*
* 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 {@link
* org.apache.commons.math3.ode.sampling.StepInterpolator StepInterpolator}
* abstract class, which are made available to the user at the end of
* each step.
*
*
*
* All integrators handle multiple discrete events detection based on switching
* functions. This means that the integrator can be driven by user specified
* discrete events. 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 user should describe his problem in his own classes
* (UserProblem in the diagram below) which should implement
* the {@link org.apache.commons.math3.ode.FirstOrderDifferentialEquations
* FirstOrderDifferentialEquations} interface. Then he should pass it to
* the integrator he prefers among all the classes that implement the
* {@link org.apache.commons.math3.ode.FirstOrderIntegrator
* FirstOrderIntegrator} interface.
*
*
*
* 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
* {@link org.apache.commons.math3.ode.FirstOrderIntegrator#integrate
* FirstOrderIntegrator.integrate} 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 {@link
* org.apache.commons.math3.ode.sampling.StepHandler StepHandler} interface or a
* {@link org.apache.commons.math3.ode.sampling.StepNormalizer StepNormalizer}
* object wrapping a user-specified object implementing the {@link
* org.apache.commons.math3.ode.sampling.FixedStepHandler FixedStepHandler}
* interface into the integrator before calling the {@link
* org.apache.commons.math3.ode.FirstOrderIntegrator#integrate
* FirstOrderIntegrator.integrate} 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.
*
*
*
* {@link org.apache.commons.math3.ode.ContinuousOutputModel
* ContinuousOutputModel} 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 Serializable
* interface. This means that a complete continuous model of the
* integrated function throughout 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.
*
*
*
* Other default implementations of the {@link
* org.apache.commons.math3.ode.sampling.StepHandler StepHandler} interface are
* available for general needs ({@link
* org.apache.commons.math3.ode.sampling.DummyStepHandler DummyStepHandler}, {@link
* org.apache.commons.math3.ode.sampling.StepNormalizer StepNormalizer}) and custom
* implementations can be developed 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.
*
*
*
* 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 {@link
* org.apache.commons.math3.ode.nonstiff.AdaptiveStepsizeIntegrator
* AdaptiveStepsizeIntegrator} abstract class). In this case, the step
* handler which is called after each successful step shows up the
* variable stepsize. The {@link
* org.apache.commons.math3.ode.sampling.StepNormalizer StepNormalizer} class can
* be used to convert the variable stepsize into a fixed stepsize that
* can be handled by classes implementing the {@link
* org.apache.commons.math3.ode.sampling.FixedStepHandler FixedStepHandler}
* 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.
*
*
*
*
* Fixed Step Integrators Name Order {@link org.apache.commons.math3.ode.nonstiff.EulerIntegrator Euler} 1 {@link org.apache.commons.math3.ode.nonstiff.MidpointIntegrator Midpoint} 2 {@link org.apache.commons.math3.ode.nonstiff.ClassicalRungeKuttaIntegrator Classical Runge-Kutta} 4 {@link org.apache.commons.math3.ode.nonstiff.GillIntegrator Gill} 4 {@link org.apache.commons.math3.ode.nonstiff.ThreeEighthesIntegrator 3/8} 4
*
*
*
* Adaptive Stepsize Integrators Name Integration Order Error Estimation Order {@link org.apache.commons.math3.ode.nonstiff.HighamHall54Integrator Higham and Hall} 5 4 {@link org.apache.commons.math3.ode.nonstiff.DormandPrince54Integrator Dormand-Prince 5(4)} 5 4 {@link org.apache.commons.math3.ode.nonstiff.DormandPrince853Integrator Dormand-Prince 8(5,3)} 8 5 and 3 {@link org.apache.commons.math3.ode.nonstiff.GraggBulirschStoerIntegrator Gragg-Bulirsch-Stoer} variable (up to 18 by default) variable {@link org.apache.commons.math3.ode.nonstiff.AdamsBashforthIntegrator Adams-Bashforth} variable variable {@link org.apache.commons.math3.ode.nonstiff.AdamsMoultonIntegrator Adams-Moulton} variable variable
*
*
*
* In the table above, the {@link org.apache.commons.math3.ode.nonstiff.AdamsBashforthIntegrator
* Adams-Bashforth} and {@link org.apache.commons.math3.ode.nonstiff.AdamsMoultonIntegrator
* Adams-Moulton} integrators appear as variable-step ones. This is an experimental extension
* to the classical algorithms using the Nordsieck vector representation.
*
*
*
*/
package org.apache.commons.math3.ode;