alvinalexander.com | career | drupal | java | mac | mysql | perl | scala | uml | unix  

Commons Math example source code file (AdamsMoultonIntegrator.java)

This example Commons Math source code file (AdamsMoultonIntegrator.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" TM.

Java - Commons Math tags/keywords

adams-moulton, adamsmoultonintegrator, adamsmoultonintegrator, corrector, corrector, derivativeexception, illegalargumentexception, integratorexception, nordsieckstepinterpolator, nordsieckstepinterpolator, override, realmatrixpreservingvisitor, stephandler, stephandler, util

The Commons Math AdamsMoultonIntegrator.java source code

/*
 * 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.
 */

package org.apache.commons.math.ode.nonstiff;

import java.util.Arrays;

import org.apache.commons.math.linear.Array2DRowRealMatrix;
import org.apache.commons.math.linear.MatrixVisitorException;
import org.apache.commons.math.linear.RealMatrixPreservingVisitor;
import org.apache.commons.math.ode.DerivativeException;
import org.apache.commons.math.ode.FirstOrderDifferentialEquations;
import org.apache.commons.math.ode.IntegratorException;
import org.apache.commons.math.ode.events.CombinedEventsManager;
import org.apache.commons.math.ode.sampling.NordsieckStepInterpolator;
import org.apache.commons.math.ode.sampling.StepHandler;


/**
 * This class implements implicit Adams-Moulton integrators for Ordinary
 * Differential Equations.
 *
 * <p>Adams-Moulton methods (in fact due to Adams alone) are implicit
 * multistep ODE solvers. This implementation is a variation of the classical
 * one: it uses adaptive stepsize to implement error control, whereas
 * classical implementations are fixed step size. The value of state vector
 * at step n+1 is a simple combination of the value at step n and of the
 * derivatives at steps n+1, n, n-1 ... Since y'<sub>n+1 is needed to
 * compute y<sub>n+1,another method must be used to compute a first
 * estimate of y<sub>n+1, then compute y'n+1, then compute
 * a final estimate of y<sub>n+1 using the following formulas. Depending
 * on the number k of previous steps one wants to use for computing the next
 * value, different formulas are available for the final estimate:</p>
 * <ul>
 *   <li>k = 1: yn+1 = yn + h y'n+1
 *   <li>k = 2: yn+1 = yn + h (y'n+1+y'n)/2
 *   <li>k = 3: yn+1 = yn + h (5y'n+1+8y'n-y'n-1)/12
 *   <li>k = 4: yn+1 = yn + h (9y'n+1+19y'n-5y'n-1+y'n-2)/24
 *   <li>...
 * </ul>
 *
 * <p>A k-steps Adams-Moulton method is of order k+1.

* * <h3>Implementation details * * <p>We define scaled derivatives si(n) at step n as: * <pre> * s<sub>1(n) = h y'n for first derivative * s<sub>2(n) = h2/2 y''n for second derivative * s<sub>3(n) = h3/6 y'''n for third derivative * ... * s<sub>k(n) = hk/k! y(k)n for kth derivative * </pre>

* * <p>The definitions above use the classical representation with several previous first * derivatives. Lets define * <pre> * q<sub>n = [ s1(n-1) s1(n-2) ... s1(n-(k-1)) ]T * </pre> * (we omit the k index in the notation for clarity). With these definitions, * Adams-Moulton methods can be written: * <ul> * <li>k = 1: yn+1 = yn + s1(n+1) * <li>k = 2: yn+1 = yn + 1/2 s1(n+1) + [ 1/2 ] qn+1 * <li>k = 3: yn+1 = yn + 5/12 s1(n+1) + [ 8/12 -1/12 ] qn+1 * <li>k = 4: yn+1 = yn + 9/24 s1(n+1) + [ 19/24 -5/24 1/24 ] qn+1 * <li>... * </ul>

* * <p>Instead of using the classical representation with first derivatives only (yn, * s<sub>1(n+1) and qn+1), our implementation uses the Nordsieck vector with * higher degrees scaled derivatives all taken at the same step (y<sub>n, s1(n) * and r<sub>n) where rn is defined as: * <pre> * r<sub>n = [ s2(n), s3(n) ... sk(n) ]T * </pre> * (here again we omit the k index in the notation for clarity) * </p> * * <p>Taylor series formulas show that for any index offset i, s1(n-i) can be * computed from s<sub>1(n), s2(n) ... sk(n), the formula being exact * for degree k polynomials. * <pre> * s<sub>1(n-i) = s1(n) + ∑j j (-i)j-1 sj(n) * </pre> * The previous formula can be used with several values for i to compute the transform between * classical representation and Nordsieck vector. The transform between r<sub>n * and q<sub>n resulting from the Taylor series formulas above is: * <pre> * q<sub>n = s1(n) u + P rn * </pre> * where u is the [ 1 1 ... 1 ]<sup>T vector and P is the (k-1)×(k-1) matrix built * with the j (-i)<sup>j-1 terms: * <pre> * [ -2 3 -4 5 ... ] * [ -4 12 -32 80 ... ] * P = [ -6 27 -108 405 ... ] * [ -8 48 -256 1280 ... ] * [ ... ] * </pre>

* * <p>Using the Nordsieck vector has several advantages: * <ul> * <li>it greatly simplifies step interpolation as the interpolator mainly applies * Taylor series formulas,</li> * <li>it simplifies step changes that occur when discrete events that truncate * the step are triggered,</li> * <li>it allows to extend the methods in order to support adaptive stepsize. * </ul>

* * <p>The predicted Nordsieck vector at step n+1 is computed from the Nordsieck vector at step * n as follows: * <ul> * <li>Yn+1 = yn + s1(n) + uT rn * <li>S1(n+1) = h f(tn+1, Yn+1) * <li>Rn+1 = (s1(n) - S1(n+1)) P-1 u + P-1 A P rn * </ul> * where A is a rows shifting matrix (the lower left part is an identity matrix): * <pre> * [ 0 0 ... 0 0 | 0 ] * [ ---------------+---] * [ 1 0 ... 0 0 | 0 ] * A = [ 0 1 ... 0 0 | 0 ] * [ ... | 0 ] * [ 0 0 ... 1 0 | 0 ] * [ 0 0 ... 0 1 | 0 ] * </pre> * From this predicted vector, the corrected vector is computed as follows: * <ul> * <li>yn+1 = yn + S1(n+1) + [ -1 +1 -1 +1 ... ±1 ] rn+1 * <li>s1(n+1) = h f(tn+1, yn+1) * <li>rn+1 = Rn+1 + (s1(n+1) - S1(n+1)) P-1 u * </ul> * where the upper case Y<sub>n+1, S1(n+1) and Rn+1 represent the * predicted states whereas the lower case y<sub>n+1, sn+1 and rn+1 * represent the corrected states.</p> * * <p>The P-1u vector and the P-1 A P matrix do not depend on the state, * they only depend on k and therefore are precomputed once for all.</p> * * @version $Revision: 927202 $ $Date: 2010-03-24 18:11:51 -0400 (Wed, 24 Mar 2010) $ * @since 2.0 */ public class AdamsMoultonIntegrator extends AdamsIntegrator { /** * Build an Adams-Moulton integrator with the given order and error control parameters. * @param nSteps number of steps of the method excluding the one being computed * @param minStep minimal step (must be positive even for backward * integration), the last step can be smaller than this * @param maxStep maximal step (must be positive even for backward * integration) * @param scalAbsoluteTolerance allowed absolute error * @param scalRelativeTolerance allowed relative error * @exception IllegalArgumentException if order is 1 or less */ public AdamsMoultonIntegrator(final int nSteps, final double minStep, final double maxStep, final double scalAbsoluteTolerance, final double scalRelativeTolerance) throws IllegalArgumentException { super("Adams-Moulton", nSteps, nSteps + 1, minStep, maxStep, scalAbsoluteTolerance, scalRelativeTolerance); } /** * Build an Adams-Moulton integrator with the given order and error control parameters. * @param nSteps number of steps of the method excluding the one being computed * @param minStep minimal step (must be positive even for backward * integration), the last step can be smaller than this * @param maxStep maximal step (must be positive even for backward * integration) * @param vecAbsoluteTolerance allowed absolute error * @param vecRelativeTolerance allowed relative error * @exception IllegalArgumentException if order is 1 or less */ public AdamsMoultonIntegrator(final int nSteps, final double minStep, final double maxStep, final double[] vecAbsoluteTolerance, final double[] vecRelativeTolerance) throws IllegalArgumentException { super("Adams-Moulton", nSteps, nSteps + 1, minStep, maxStep, vecAbsoluteTolerance, vecRelativeTolerance); } /** {@inheritDoc} */ @Override public double integrate(final FirstOrderDifferentialEquations equations, final double t0, final double[] y0, final double t, final double[] y) throws DerivativeException, IntegratorException { final int n = y0.length; sanityChecks(equations, t0, y0, t, y); setEquations(equations); resetEvaluations(); final boolean forward = t > t0; // initialize working arrays if (y != y0) { System.arraycopy(y0, 0, y, 0, n); } final double[] yDot = new double[y0.length]; final double[] yTmp = new double[y0.length]; // set up two interpolators sharing the integrator arrays final NordsieckStepInterpolator interpolator = new NordsieckStepInterpolator(); interpolator.reinitialize(y, forward); final NordsieckStepInterpolator interpolatorTmp = new NordsieckStepInterpolator(); interpolatorTmp.reinitialize(yTmp, forward); // set up integration control objects for (StepHandler handler : stepHandlers) { handler.reset(); } CombinedEventsManager manager = addEndTimeChecker(t0, t, eventsHandlersManager); // compute the initial Nordsieck vector using the configured starter integrator start(t0, y, t); interpolator.reinitialize(stepStart, stepSize, scaled, nordsieck); interpolator.storeTime(stepStart); double hNew = stepSize; interpolator.rescale(hNew); boolean lastStep = false; while (!lastStep) { // shift all data interpolator.shift(); double error = 0; for (boolean loop = true; loop;) { stepSize = hNew; // predict a first estimate of the state at step end (P in the PECE sequence) final double stepEnd = stepStart + stepSize; interpolator.setInterpolatedTime(stepEnd); System.arraycopy(interpolator.getInterpolatedState(), 0, yTmp, 0, y0.length); // evaluate a first estimate of the derivative (first E in the PECE sequence) computeDerivatives(stepEnd, yTmp, yDot); // update Nordsieck vector final double[] predictedScaled = new double[y0.length]; for (int j = 0; j < y0.length; ++j) { predictedScaled[j] = stepSize * yDot[j]; } final Array2DRowRealMatrix nordsieckTmp = updateHighOrderDerivativesPhase1(nordsieck); updateHighOrderDerivativesPhase2(scaled, predictedScaled, nordsieckTmp); // apply correction (C in the PECE sequence) error = nordsieckTmp.walkInOptimizedOrder(new Corrector(y, predictedScaled, yTmp)); if (error <= 1.0) { // evaluate a final estimate of the derivative (second E in the PECE sequence) computeDerivatives(stepEnd, yTmp, yDot); // update Nordsieck vector final double[] correctedScaled = new double[y0.length]; for (int j = 0; j < y0.length; ++j) { correctedScaled[j] = stepSize * yDot[j]; } updateHighOrderDerivativesPhase2(predictedScaled, correctedScaled, nordsieckTmp); // discrete events handling interpolatorTmp.reinitialize(stepEnd, stepSize, correctedScaled, nordsieckTmp); interpolatorTmp.storeTime(stepStart); interpolatorTmp.shift(); interpolatorTmp.storeTime(stepEnd); if (manager.evaluateStep(interpolatorTmp)) { final double dt = manager.getEventTime() - stepStart; if (Math.abs(dt) <= Math.ulp(stepStart)) { // we cannot simply truncate the step, reject the current computation // and let the loop compute another state with the truncated step. // it is so small (much probably exactly 0 due to limited accuracy) // that the code above would fail handling it. // So we set up an artificial 0 size step by copying states interpolator.storeTime(stepStart); System.arraycopy(y, 0, yTmp, 0, y0.length); hNew = 0; stepSize = 0; loop = false; } else { // reject the step to match exactly the next switch time hNew = dt; interpolator.rescale(hNew); } } else { // accept the step scaled = correctedScaled; nordsieck = nordsieckTmp; interpolator.reinitialize(stepEnd, stepSize, scaled, nordsieck); loop = false; } } else { // reject the step and attempt to reduce error by stepsize control final double factor = computeStepGrowShrinkFactor(error); hNew = filterStep(stepSize * factor, forward, false); interpolator.rescale(hNew); } } // the step has been accepted (may have been truncated) final double nextStep = stepStart + stepSize; System.arraycopy(yTmp, 0, y, 0, n); interpolator.storeTime(nextStep); manager.stepAccepted(nextStep, y); lastStep = manager.stop(); // provide the step data to the step handler for (StepHandler handler : stepHandlers) { interpolator.setInterpolatedTime(nextStep); handler.handleStep(interpolator, lastStep); } stepStart = nextStep; if (!lastStep && manager.reset(stepStart, y)) { // some events handler has triggered changes that // invalidate the derivatives, we need to restart from scratch start(stepStart, y, t); interpolator.reinitialize(stepStart, stepSize, scaled, nordsieck); } if (! lastStep) { // in some rare cases we may get here with stepSize = 0, for example // when an event occurs at integration start, reducing the first step // to zero; we have to reset the step to some safe non zero value stepSize = filterStep(stepSize, forward, true); // stepsize control for next step final double factor = computeStepGrowShrinkFactor(error); final double scaledH = stepSize * factor; final double nextT = stepStart + scaledH; final boolean nextIsLast = forward ? (nextT >= t) : (nextT <= t); hNew = filterStep(scaledH, forward, nextIsLast); interpolator.rescale(hNew); } } final double stopTime = stepStart; stepStart = Double.NaN; stepSize = Double.NaN; return stopTime; } /** Corrector for current state in Adams-Moulton method. * <p> * This visitor implements the Taylor series formula: * <pre> * Y<sub>n+1 = yn + s1(n+1) + [ -1 +1 -1 +1 ... ±1 ] rn+1 * </pre> * </p> */ private class Corrector implements RealMatrixPreservingVisitor { /** Previous state. */ private final double[] previous; /** Current scaled first derivative. */ private final double[] scaled; /** Current state before correction. */ private final double[] before; /** Current state after correction. */ private final double[] after; /** Simple constructor. * @param previous previous state * @param scaled current scaled first derivative * @param state state to correct (will be overwritten after visit) */ public Corrector(final double[] previous, final double[] scaled, final double[] state) { this.previous = previous; this.scaled = scaled; this.after = state; this.before = state.clone(); } /** {@inheritDoc} */ public void start(int rows, int columns, int startRow, int endRow, int startColumn, int endColumn) { Arrays.fill(after, 0.0); } /** {@inheritDoc} */ public void visit(int row, int column, double value) throws MatrixVisitorException { if ((row & 0x1) == 0) { after[column] -= value; } else { after[column] += value; } } /** * End visiting te Nordsieck vector. * <p>The correction is used to control stepsize. So its amplitude is * considered to be an error, which must be normalized according to * error control settings. If the normalized value is greater than 1, * the correction was too large and the step must be rejected.</p> * @return the normalized correction, if greater than 1, the step * must be rejected */ public double end() { double error = 0; for (int i = 0; i < after.length; ++i) { after[i] += previous[i] + scaled[i]; final double yScale = Math.max(Math.abs(previous[i]), Math.abs(after[i])); final double tol = (vecAbsoluteTolerance == null) ? (scalAbsoluteTolerance + scalRelativeTolerance * yScale) : (vecAbsoluteTolerance[i] + vecRelativeTolerance[i] * yScale); final double ratio = (after[i] - before[i]) / tol; error += ratio * ratio; } return Math.sqrt(error / after.length); } } }

Other Commons Math examples (source code examples)

Here is a short list of links related to this Commons Math AdamsMoultonIntegrator.java source code file:

... this post is sponsored by my books ...

#1 New Release!

FP Best Seller

 

new blog posts

 

Copyright 1998-2021 Alvin Alexander, alvinalexander.com
All Rights Reserved.

A percentage of advertising revenue from
pages under the /java/jwarehouse URI on this website is
paid back to open source projects.