AdamsIntegrator.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  17. package org.apache.commons.math4.legacy.ode.nonstiff;

  18. import org.apache.commons.math4.legacy.exception.DimensionMismatchException;
  19. import org.apache.commons.math4.legacy.exception.MaxCountExceededException;
  20. import org.apache.commons.math4.legacy.exception.NoBracketingException;
  21. import org.apache.commons.math4.legacy.exception.NumberIsTooSmallException;
  22. import org.apache.commons.math4.legacy.linear.Array2DRowRealMatrix;
  23. import org.apache.commons.math4.legacy.ode.ExpandableStatefulODE;
  24. import org.apache.commons.math4.legacy.ode.MultistepIntegrator;


  25. /** Base class for {@link AdamsBashforthIntegrator Adams-Bashforth} and
  26.  * {@link AdamsMoultonIntegrator Adams-Moulton} integrators.
  27.  * @since 2.0
  28.  */
  29. public abstract class AdamsIntegrator extends MultistepIntegrator {

  30.     /** Transformer. */
  31.     private final AdamsNordsieckTransformer transformer;

  32.     /**
  33.      * Build an Adams integrator with the given order and step control parameters.
  34.      * @param name name of the method
  35.      * @param nSteps number of steps of the method excluding the one being computed
  36.      * @param order order of the method
  37.      * @param minStep minimal step (sign is irrelevant, regardless of
  38.      * integration direction, forward or backward), the last step can
  39.      * be smaller than this
  40.      * @param maxStep maximal step (sign is irrelevant, regardless of
  41.      * integration direction, forward or backward), the last step can
  42.      * be smaller than this
  43.      * @param scalAbsoluteTolerance allowed absolute error
  44.      * @param scalRelativeTolerance allowed relative error
  45.      * @exception NumberIsTooSmallException if order is 1 or less
  46.      */
  47.     public AdamsIntegrator(final String name, final int nSteps, final int order,
  48.                            final double minStep, final double maxStep,
  49.                            final double scalAbsoluteTolerance,
  50.                            final double scalRelativeTolerance)
  51.         throws NumberIsTooSmallException {
  52.         super(name, nSteps, order, minStep, maxStep,
  53.               scalAbsoluteTolerance, scalRelativeTolerance);
  54.         transformer = AdamsNordsieckTransformer.getInstance(nSteps);
  55.     }

  56.     /**
  57.      * Build an Adams integrator with the given order and step control parameters.
  58.      * @param name name of the method
  59.      * @param nSteps number of steps of the method excluding the one being computed
  60.      * @param order order of the method
  61.      * @param minStep minimal step (sign is irrelevant, regardless of
  62.      * integration direction, forward or backward), the last step can
  63.      * be smaller than this
  64.      * @param maxStep maximal step (sign is irrelevant, regardless of
  65.      * integration direction, forward or backward), the last step can
  66.      * be smaller than this
  67.      * @param vecAbsoluteTolerance allowed absolute error
  68.      * @param vecRelativeTolerance allowed relative error
  69.      * @exception IllegalArgumentException if order is 1 or less
  70.      */
  71.     public AdamsIntegrator(final String name, final int nSteps, final int order,
  72.                            final double minStep, final double maxStep,
  73.                            final double[] vecAbsoluteTolerance,
  74.                            final double[] vecRelativeTolerance)
  75.         throws IllegalArgumentException {
  76.         super(name, nSteps, order, minStep, maxStep,
  77.               vecAbsoluteTolerance, vecRelativeTolerance);
  78.         transformer = AdamsNordsieckTransformer.getInstance(nSteps);
  79.     }

  80.     /** {@inheritDoc} */
  81.     @Override
  82.     public abstract void integrate(ExpandableStatefulODE equations, double t)
  83.         throws NumberIsTooSmallException, DimensionMismatchException,
  84.                MaxCountExceededException, NoBracketingException;

  85.     /** {@inheritDoc} */
  86.     @Override
  87.     protected Array2DRowRealMatrix initializeHighOrderDerivatives(final double h, final double[] t,
  88.                                                                   final double[][] y,
  89.                                                                   final double[][] yDot) {
  90.         return transformer.initializeHighOrderDerivatives(h, t, y, yDot);
  91.     }

  92.     /** Update the high order scaled derivatives for Adams integrators (phase 1).
  93.      * <p>The complete update of high order derivatives has a form similar to:
  94.      * <div style="white-space: pre"><code>
  95.      * r<sub>n+1</sub> = (s<sub>1</sub>(n) - s<sub>1</sub>(n+1)) P<sup>-1</sup> u + P<sup>-1</sup> A P r<sub>n</sub>
  96.      * </code></div>
  97.      * this method computes the P<sup>-1</sup> A P r<sub>n</sub> part.
  98.      * @param highOrder high order scaled derivatives
  99.      * (h<sup>2</sup>/2 y'', ... h<sup>k</sup>/k! y(k))
  100.      * @return updated high order derivatives
  101.      * @see #updateHighOrderDerivativesPhase2(double[], double[], Array2DRowRealMatrix)
  102.      */
  103.     public Array2DRowRealMatrix updateHighOrderDerivativesPhase1(final Array2DRowRealMatrix highOrder) {
  104.         return transformer.updateHighOrderDerivativesPhase1(highOrder);
  105.     }

  106.     /** Update the high order scaled derivatives Adams integrators (phase 2).
  107.      * <p>The complete update of high order derivatives has a form similar to:
  108.      * <div style="white-space: pre"><code>
  109.      * r<sub>n+1</sub> = (s<sub>1</sub>(n) - s<sub>1</sub>(n+1)) P<sup>-1</sup> u + P<sup>-1</sup> A P r<sub>n</sub>
  110.      * </code></div>
  111.      * this method computes the (s<sub>1</sub>(n) - s<sub>1</sub>(n+1)) P<sup>-1</sup> u part.
  112.      * <p>Phase 1 of the update must already have been performed.</p>
  113.      * @param start first order scaled derivatives at step start
  114.      * @param end first order scaled derivatives at step end
  115.      * @param highOrder high order scaled derivatives, will be modified
  116.      * (h<sup>2</sup>/2 y'', ... h<sup>k</sup>/k! y(k))
  117.      * @see #updateHighOrderDerivativesPhase1(Array2DRowRealMatrix)
  118.      */
  119.     public void updateHighOrderDerivativesPhase2(final double[] start,
  120.                                                  final double[] end,
  121.                                                  final Array2DRowRealMatrix highOrder) {
  122.         transformer.updateHighOrderDerivativesPhase2(start, end, highOrder);
  123.     }
  124. }