DormandPrince54FieldIntegrator.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.core.Field;
  19. import org.apache.commons.math4.legacy.core.RealFieldElement;
  20. import org.apache.commons.math4.legacy.ode.FieldEquationsMapper;
  21. import org.apache.commons.math4.legacy.ode.FieldODEStateAndDerivative;
  22. import org.apache.commons.math4.legacy.core.MathArrays;


  23. /**
  24.  * This class implements the 5(4) Dormand-Prince integrator for Ordinary
  25.  * Differential Equations.

  26.  * <p>This integrator is an embedded Runge-Kutta integrator
  27.  * of order 5(4) used in local extrapolation mode (i.e. the solution
  28.  * is computed using the high order formula) with stepsize control
  29.  * (and automatic step initialization) and continuous output. This
  30.  * method uses 7 functions evaluations per step. However, since this
  31.  * is an <i>fsal</i>, the last evaluation of one step is the same as
  32.  * the first evaluation of the next step and hence can be avoided. So
  33.  * the cost is really 6 functions evaluations per step.</p>
  34.  *
  35.  * <p>This method has been published (whithout the continuous output
  36.  * that was added by Shampine in 1986) in the following article :
  37.  * <pre>
  38.  *  A family of embedded Runge-Kutta formulae
  39.  *  J. R. Dormand and P. J. Prince
  40.  *  Journal of Computational and Applied Mathematics
  41.  *  volume 6, no 1, 1980, pp. 19-26
  42.  * </pre>
  43.  *
  44.  * @param <T> the type of the field elements
  45.  * @since 3.6
  46.  */

  47. public class DormandPrince54FieldIntegrator<T extends RealFieldElement<T>>
  48.     extends EmbeddedRungeKuttaFieldIntegrator<T> {

  49.     /** Integrator method name. */
  50.     private static final String METHOD_NAME = "Dormand-Prince 5(4)";

  51.     /** Error array, element 1. */
  52.     private final T e1;

  53.     // element 2 is zero, so it is neither stored nor used

  54.     /** Error array, element 3. */
  55.     private final T e3;

  56.     /** Error array, element 4. */
  57.     private final T e4;

  58.     /** Error array, element 5. */
  59.     private final T e5;

  60.     /** Error array, element 6. */
  61.     private final T e6;

  62.     /** Error array, element 7. */
  63.     private final T e7;

  64.     /** Simple constructor.
  65.      * Build a fifth order Dormand-Prince integrator with the given step bounds
  66.      * @param field field to which the time and state vector elements belong
  67.      * @param minStep minimal step (sign is irrelevant, regardless of
  68.      * integration direction, forward or backward), the last step can
  69.      * be smaller than this
  70.      * @param maxStep maximal step (sign is irrelevant, regardless of
  71.      * integration direction, forward or backward), the last step can
  72.      * be smaller than this
  73.      * @param scalAbsoluteTolerance allowed absolute error
  74.      * @param scalRelativeTolerance allowed relative error
  75.      */
  76.     public DormandPrince54FieldIntegrator(final Field<T> field,
  77.                                           final double minStep, final double maxStep,
  78.                                           final double scalAbsoluteTolerance,
  79.                                           final double scalRelativeTolerance) {
  80.         super(field, METHOD_NAME, 6,
  81.               minStep, maxStep, scalAbsoluteTolerance, scalRelativeTolerance);
  82.         e1 = fraction(    71,  57600);
  83.         e3 = fraction(   -71,  16695);
  84.         e4 = fraction(    71,   1920);
  85.         e5 = fraction(-17253, 339200);
  86.         e6 = fraction(    22,    525);
  87.         e7 = fraction(    -1,     40);
  88.     }

  89.     /** Simple constructor.
  90.      * Build a fifth order Dormand-Prince integrator with the given step bounds
  91.      * @param field field to which the time and state vector elements belong
  92.      * @param minStep minimal step (sign is irrelevant, regardless of
  93.      * integration direction, forward or backward), the last step can
  94.      * be smaller than this
  95.      * @param maxStep maximal step (sign is irrelevant, regardless of
  96.      * integration direction, forward or backward), the last step can
  97.      * be smaller than this
  98.      * @param vecAbsoluteTolerance allowed absolute error
  99.      * @param vecRelativeTolerance allowed relative error
  100.      */
  101.     public DormandPrince54FieldIntegrator(final Field<T> field,
  102.                                           final double minStep, final double maxStep,
  103.                                           final double[] vecAbsoluteTolerance,
  104.                                           final double[] vecRelativeTolerance) {
  105.         super(field, METHOD_NAME, 6,
  106.               minStep, maxStep, vecAbsoluteTolerance, vecRelativeTolerance);
  107.         e1 = fraction(    71,  57600);
  108.         e3 = fraction(   -71,  16695);
  109.         e4 = fraction(    71,   1920);
  110.         e5 = fraction(-17253, 339200);
  111.         e6 = fraction(    22,    525);
  112.         e7 = fraction(    -1,     40);
  113.     }

  114.     /** {@inheritDoc} */
  115.     @Override
  116.     public T[] getC() {
  117.         final T[] c = MathArrays.buildArray(getField(), 6);
  118.         c[0] = fraction(1,  5);
  119.         c[1] = fraction(3, 10);
  120.         c[2] = fraction(4,  5);
  121.         c[3] = fraction(8,  9);
  122.         c[4] = getField().getOne();
  123.         c[5] = getField().getOne();
  124.         return c;
  125.     }

  126.     /** {@inheritDoc} */
  127.     @Override
  128.     public T[][] getA() {
  129.         final T[][] a = MathArrays.buildArray(getField(), 6, -1);
  130.         for (int i = 0; i < a.length; ++i) {
  131.             a[i] = MathArrays.buildArray(getField(), i + 1);
  132.         }
  133.         a[0][0] = fraction(     1,     5);
  134.         a[1][0] = fraction(     3,    40);
  135.         a[1][1] = fraction(     9,    40);
  136.         a[2][0] = fraction(    44,    45);
  137.         a[2][1] = fraction(   -56,    15);
  138.         a[2][2] = fraction(    32,     9);
  139.         a[3][0] = fraction( 19372,  6561);
  140.         a[3][1] = fraction(-25360,  2187);
  141.         a[3][2] = fraction( 64448,  6561);
  142.         a[3][3] = fraction(  -212,   729);
  143.         a[4][0] = fraction(  9017,  3168);
  144.         a[4][1] = fraction(  -355,    33);
  145.         a[4][2] = fraction( 46732,  5247);
  146.         a[4][3] = fraction(    49,   176);
  147.         a[4][4] = fraction( -5103, 18656);
  148.         a[5][0] = fraction(    35,   384);
  149.         a[5][1] = getField().getZero();
  150.         a[5][2] = fraction(   500,  1113);
  151.         a[5][3] = fraction(   125,   192);
  152.         a[5][4] = fraction( -2187,  6784);
  153.         a[5][5] = fraction(    11,    84);
  154.         return a;
  155.     }

  156.     /** {@inheritDoc} */
  157.     @Override
  158.     public T[] getB() {
  159.         final T[] b = MathArrays.buildArray(getField(), 7);
  160.         b[0] = fraction(   35,   384);
  161.         b[1] = getField().getZero();
  162.         b[2] = fraction(  500, 1113);
  163.         b[3] = fraction(  125,  192);
  164.         b[4] = fraction(-2187, 6784);
  165.         b[5] = fraction(   11,   84);
  166.         b[6] = getField().getZero();
  167.         return b;
  168.     }

  169.     /** {@inheritDoc} */
  170.     @Override
  171.     protected DormandPrince54FieldStepInterpolator<T>
  172.         createInterpolator(final boolean forward, T[][] yDotK,
  173.                            final FieldODEStateAndDerivative<T> globalPreviousState,
  174.                            final FieldODEStateAndDerivative<T> globalCurrentState, final FieldEquationsMapper<T> mapper) {
  175.         return new DormandPrince54FieldStepInterpolator<>(getField(), forward, yDotK,
  176.                                                            globalPreviousState, globalCurrentState,
  177.                                                            globalPreviousState, globalCurrentState,
  178.                                                            mapper);
  179.     }

  180.     /** {@inheritDoc} */
  181.     @Override
  182.     public int getOrder() {
  183.         return 5;
  184.     }

  185.     /** {@inheritDoc} */
  186.     @Override
  187.     protected T estimateError(final T[][] yDotK, final T[] y0, final T[] y1, final T h) {

  188.         T error = getField().getZero();

  189.         for (int j = 0; j < mainSetDimension; ++j) {
  190.             final T errSum =     yDotK[0][j].multiply(e1).
  191.                              add(yDotK[2][j].multiply(e3)).
  192.                              add(yDotK[3][j].multiply(e4)).
  193.                              add(yDotK[4][j].multiply(e5)).
  194.                              add(yDotK[5][j].multiply(e6)).
  195.                              add(yDotK[6][j].multiply(e7));

  196.             final T yScale = RealFieldElement.max(y0[j].abs(), y1[j].abs());
  197.             final T tol    = (vecAbsoluteTolerance == null) ?
  198.                              yScale.multiply(scalRelativeTolerance).add(scalAbsoluteTolerance) :
  199.                              yScale.multiply(vecRelativeTolerance[j]).add(vecAbsoluteTolerance[j]);
  200.             final T ratio  = h.multiply(errSum).divide(tol);
  201.             error = error.add(ratio.multiply(ratio));
  202.         }

  203.         return error.divide(mainSetDimension).sqrt();
  204.     }
  205. }