AbstractFieldStepInterpolator.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.sampling;

  18. import org.apache.commons.math4.legacy.core.RealFieldElement;
  19. import org.apache.commons.math4.legacy.exception.MaxCountExceededException;
  20. import org.apache.commons.math4.legacy.ode.FieldEquationsMapper;
  21. import org.apache.commons.math4.legacy.ode.FieldODEStateAndDerivative;

  22. /** This abstract class represents an interpolator over the last step
  23.  * during an ODE integration.
  24.  *
  25.  * <p>The various ODE integrators provide objects extending this class
  26.  * to the step handlers. The handlers can use these objects to
  27.  * retrieve the state vector at intermediate times between the
  28.  * previous and the current grid points (dense output).</p>
  29.  *
  30.  * @see org.apache.commons.math4.legacy.ode.FirstOrderFieldIntegrator
  31.  * @see StepHandler
  32.  *
  33.  * @param <T> the type of the field elements
  34.  * @since 3.6
  35.  */

  36. public abstract class AbstractFieldStepInterpolator<T extends RealFieldElement<T>>
  37.     implements FieldStepInterpolator<T> {

  38.     /** Global previous state. */
  39.     private final FieldODEStateAndDerivative<T> globalPreviousState;

  40.     /** Global current state. */
  41.     private final FieldODEStateAndDerivative<T> globalCurrentState;

  42.     /** Soft previous state. */
  43.     private final FieldODEStateAndDerivative<T> softPreviousState;

  44.     /** Soft current state. */
  45.     private final FieldODEStateAndDerivative<T> softCurrentState;

  46.     /** integration direction. */
  47.     private final boolean forward;

  48.     /** Mapper for ODE equations primary and secondary components. */
  49.     private FieldEquationsMapper<T> mapper;

  50.     /** Simple constructor.
  51.      * @param isForward integration direction indicator
  52.      * @param globalPreviousState start of the global step
  53.      * @param globalCurrentState end of the global step
  54.      * @param softPreviousState start of the restricted step
  55.      * @param softCurrentState end of the restricted step
  56.      * @param equationsMapper mapper for ODE equations primary and secondary components
  57.      */
  58.     protected AbstractFieldStepInterpolator(final boolean isForward,
  59.                                             final FieldODEStateAndDerivative<T> globalPreviousState,
  60.                                             final FieldODEStateAndDerivative<T> globalCurrentState,
  61.                                             final FieldODEStateAndDerivative<T> softPreviousState,
  62.                                             final FieldODEStateAndDerivative<T> softCurrentState,
  63.                                             final FieldEquationsMapper<T> equationsMapper) {
  64.         this.forward             = isForward;
  65.         this.globalPreviousState = globalPreviousState;
  66.         this.globalCurrentState  = globalCurrentState;
  67.         this.softPreviousState   = softPreviousState;
  68.         this.softCurrentState    = softCurrentState;
  69.         this.mapper              = equationsMapper;
  70.     }

  71.     /** Create a new restricted version of the instance.
  72.      * <p>
  73.      * The instance is not changed at all.
  74.      * </p>
  75.      * @param previousState start of the restricted step
  76.      * @param currentState end of the restricted step
  77.      * @return restricted version of the instance
  78.      * @see #getPreviousState()
  79.      * @see #getCurrentState()
  80.      */
  81.     public AbstractFieldStepInterpolator<T> restrictStep(final FieldODEStateAndDerivative<T> previousState,
  82.                                                          final FieldODEStateAndDerivative<T> currentState) {
  83.         return create(forward, globalPreviousState, globalCurrentState, previousState, currentState, mapper);
  84.     }

  85.     /** Create a new instance.
  86.      * @param newForward integration direction indicator
  87.      * @param newGlobalPreviousState start of the global step
  88.      * @param newGlobalCurrentState end of the global step
  89.      * @param newSoftPreviousState start of the restricted step
  90.      * @param newSoftCurrentState end of the restricted step
  91.      * @param newMapper equations mapper for the all equations
  92.      * @return a new instance
  93.      */
  94.     protected abstract AbstractFieldStepInterpolator<T> create(boolean newForward,
  95.                                                                FieldODEStateAndDerivative<T> newGlobalPreviousState,
  96.                                                                FieldODEStateAndDerivative<T> newGlobalCurrentState,
  97.                                                                FieldODEStateAndDerivative<T> newSoftPreviousState,
  98.                                                                FieldODEStateAndDerivative<T> newSoftCurrentState,
  99.                                                                FieldEquationsMapper<T> newMapper);

  100.     /**
  101.      * Get the previous global grid point state.
  102.      * @return previous global grid point state
  103.      */
  104.     public FieldODEStateAndDerivative<T> getGlobalPreviousState() {
  105.         return globalPreviousState;
  106.     }

  107.     /**
  108.      * Get the current global grid point state.
  109.      * @return current global grid point state
  110.      */
  111.     public FieldODEStateAndDerivative<T> getGlobalCurrentState() {
  112.         return globalCurrentState;
  113.     }

  114.     /** {@inheritDoc} */
  115.     @Override
  116.     public FieldODEStateAndDerivative<T> getPreviousState() {
  117.         return softPreviousState;
  118.     }

  119.     /** {@inheritDoc} */
  120.     @Override
  121.     public FieldODEStateAndDerivative<T> getCurrentState() {
  122.         return softCurrentState;
  123.     }

  124.     /** {@inheritDoc} */
  125.     @Override
  126.     public FieldODEStateAndDerivative<T> getInterpolatedState(final T time) {
  127.         final T thetaH         = time.subtract(globalPreviousState.getTime());
  128.         final T oneMinusThetaH = globalCurrentState.getTime().subtract(time);
  129.         final T theta          = thetaH.divide(globalCurrentState.getTime().subtract(globalPreviousState.getTime()));
  130.         return computeInterpolatedStateAndDerivatives(mapper, time, theta, thetaH, oneMinusThetaH);
  131.     }

  132.     /** {@inheritDoc} */
  133.     @Override
  134.     public boolean isForward() {
  135.         return forward;
  136.     }

  137.     /** Compute the state and derivatives at the interpolated time.
  138.      * This is the main processing method that should be implemented by
  139.      * the derived classes to perform the interpolation.
  140.      * @param equationsMapper mapper for ODE equations primary and secondary components
  141.      * @param time interpolation time
  142.      * @param theta normalized interpolation abscissa within the step
  143.      * (theta is zero at the previous time step and one at the current time step)
  144.      * @param thetaH time gap between the previous time and the interpolated time
  145.      * @param oneMinusThetaH time gap between the interpolated time and
  146.      * the current time
  147.      * @return interpolated state and derivatives
  148.      * @exception MaxCountExceededException if the number of functions evaluations is exceeded
  149.      */
  150.     protected abstract FieldODEStateAndDerivative<T> computeInterpolatedStateAndDerivatives(FieldEquationsMapper<T> equationsMapper,
  151.                                                                                             T time, T theta,
  152.                                                                                             T thetaH, T oneMinusThetaH)
  153.         throws MaxCountExceededException;
  154. }