Class AbstractStepInterpolator

    • Field Detail

      • h

        protected double h
        current time step
      • currentState

        protected double[] currentState
        current state
      • interpolatedTime

        protected double interpolatedTime
        interpolated time
      • interpolatedState

        protected double[] interpolatedState
        interpolated state
      • interpolatedDerivatives

        protected double[] interpolatedDerivatives
        interpolated derivatives
      • interpolatedPrimaryState

        protected double[] interpolatedPrimaryState
        interpolated primary state
      • interpolatedPrimaryDerivatives

        protected double[] interpolatedPrimaryDerivatives
        interpolated primary derivatives
      • interpolatedSecondaryState

        protected double[][] interpolatedSecondaryState
        interpolated secondary state
      • interpolatedSecondaryDerivatives

        protected double[][] interpolatedSecondaryDerivatives
        interpolated secondary derivatives
      • globalPreviousTime

        private double globalPreviousTime
        global previous time
      • globalCurrentTime

        private double globalCurrentTime
        global current time
      • softPreviousTime

        private double softPreviousTime
        soft previous time
      • softCurrentTime

        private double softCurrentTime
        soft current time
      • finalized

        private boolean finalized
        indicate if the step has been finalized or not.
      • forward

        private boolean forward
        integration direction.
      • dirtyState

        private boolean dirtyState
        indicator for dirty state.
      • primaryMapper

        private EquationsMapper primaryMapper
        Equations mapper for the primary equations set.
      • secondaryMappers

        private EquationsMapper[] secondaryMappers
        Equations mappers for the secondary equations sets.
    • Constructor Detail

      • AbstractStepInterpolator

        protected AbstractStepInterpolator​(double[] y,
                                           boolean forward,
                                           EquationsMapper primaryMapper,
                                           EquationsMapper[] secondaryMappers)
        Simple constructor.
        Parameters:
        y - reference to the integrator array holding the state at the end of the step
        forward - integration direction indicator
        primaryMapper - equations mapper for the primary equations set
        secondaryMappers - equations mappers for the secondary equations sets
      • AbstractStepInterpolator

        protected AbstractStepInterpolator​(AbstractStepInterpolator interpolator)
        Copy constructor.

        The copied interpolator should have been finalized before the copy, otherwise the copy will not be able to perform correctly any derivative computation and will throw a NullPointerException later. Since we don't want this constructor to throw the exceptions finalization may involve and since we don't want this method to modify the state of the copied interpolator, finalization is not done automatically, it remains under user control.

        The copy is a deep copy: its arrays are separated from the original arrays of the instance.

        Parameters:
        interpolator - interpolator to copy from.
    • Method Detail

      • allocateInterpolatedArrays

        private void allocateInterpolatedArrays​(int dimension)
        Allocate the various interpolated states arrays.
        Parameters:
        dimension - total dimension (negative if arrays should be set to null)
      • reinitialize

        protected void reinitialize​(double[] y,
                                    boolean isForward,
                                    EquationsMapper primary,
                                    EquationsMapper[] secondary)
        Reinitialize the instance
        Parameters:
        y - reference to the integrator array holding the state at the end of the step
        isForward - integration direction indicator
        primary - equations mapper for the primary equations set
        secondary - equations mappers for the secondary equations sets
      • doCopy

        protected abstract StepInterpolator doCopy()
        Really copy the finalized instance.

        This method is called by copy() after the step has been finalized. It must perform a deep copy to have an new instance completely independent for the original instance.

        Returns:
        a copy of the finalized instance
      • shift

        public void shift()
        Shift one step forward. Copy the current time into the previous time, hence preparing the interpolator for future calls to storeTime
      • storeTime

        public void storeTime​(double t)
        Store the current step time.
        Parameters:
        t - current time
      • setSoftPreviousTime

        public void setSoftPreviousTime​(double softPreviousTime)
        Restrict step range to a limited part of the global step.

        This method can be used to restrict a step and make it appear as if the original step was smaller. Calling this method only changes the value returned by getPreviousTime(), it does not change any other property

        Parameters:
        softPreviousTime - start of the restricted step
        Since:
        2.2
      • setSoftCurrentTime

        public void setSoftCurrentTime​(double softCurrentTime)
        Restrict step range to a limited part of the global step.

        This method can be used to restrict a step and make it appear as if the original step was smaller. Calling this method only changes the value returned by getCurrentTime(), it does not change any other property

        Parameters:
        softCurrentTime - end of the restricted step
        Since:
        2.2
      • getGlobalPreviousTime

        public double getGlobalPreviousTime()
        Get the previous global grid point time.
        Returns:
        previous global grid point time
      • getGlobalCurrentTime

        public double getGlobalCurrentTime()
        Get the current global grid point time.
        Returns:
        current global grid point time
      • isForward

        public boolean isForward()
        Check if the natural integration direction is forward.

        This method provides the integration direction as specified by the integrator itself, it avoid some nasty problems in degenerated cases like null steps due to cancellation at step initialization, step control or discrete events triggering.

        Specified by:
        isForward in interface StepInterpolator
        Returns:
        true if the integration variable (time) increases during integration
      • computeInterpolatedStateAndDerivatives

        protected abstract void computeInterpolatedStateAndDerivatives​(double theta,
                                                                       double oneMinusThetaH)
                                                                throws MaxCountExceededException
        Compute the state and derivatives at the interpolated time. This is the main processing method that should be implemented by the derived classes to perform the interpolation.
        Parameters:
        theta - normalized interpolation abscissa within the step (theta is zero at the previous time step and one at the current time step)
        oneMinusThetaH - time gap between the interpolated time and the current time
        Throws:
        MaxCountExceededException - if the number of functions evaluations is exceeded
      • evaluateCompleteInterpolatedState

        private void evaluateCompleteInterpolatedState()
                                                throws MaxCountExceededException
        Lazy evaluation of complete interpolated state.
        Throws:
        MaxCountExceededException - if the number of functions evaluations is exceeded
      • finalizeStep

        public final void finalizeStep()
                                throws MaxCountExceededException
        Finalize the step.

        Some embedded Runge-Kutta integrators need fewer functions evaluations than their counterpart step interpolators. These interpolators should perform the last evaluations they need by themselves only if they need them. This method triggers these extra evaluations. It can be called directly by the user step handler and it is called automatically if setInterpolatedTime(double) is called.

        Once this method has been called, no other evaluation will be performed on this step. If there is a need to have some side effects between the step handler and the differential equations (for example update some data in the equations once the step has been done), it is advised to call this method explicitly from the step handler before these side effects are set up. If the step handler induces no side effect, then this method can safely be ignored, it will be called transparently as needed.

        Warning: since the step interpolator provided to the step handler as a parameter of the handleStep is valid only for the duration of the handleStep call, one cannot simply store a reference and reuse it later. One should first finalize the instance, then copy this finalized instance into a new object that can be kept.

        This method calls the protected doFinalize method if it has never been called during this step and set a flag indicating that it has been called once. It is the doFinalize method which should perform the evaluations. This wrapping prevents from calling doFinalize several times and hence evaluating the differential equations too often. Therefore, subclasses are not allowed not reimplement it, they should rather reimplement doFinalize.

        Throws:
        MaxCountExceededException - if the number of functions evaluations is exceeded
      • writeExternal

        public abstract void writeExternal​(java.io.ObjectOutput out)
                                    throws java.io.IOException
        Specified by:
        writeExternal in interface java.io.Externalizable
        Throws:
        java.io.IOException
      • readExternal

        public abstract void readExternal​(java.io.ObjectInput in)
                                   throws java.io.IOException,
                                          java.lang.ClassNotFoundException
        Specified by:
        readExternal in interface java.io.Externalizable
        Throws:
        java.io.IOException
        java.lang.ClassNotFoundException
      • writeBaseExternal

        protected void writeBaseExternal​(java.io.ObjectOutput out)
                                  throws java.io.IOException
        Save the base state of the instance. This method performs step finalization if it has not been done before.
        Parameters:
        out - stream where to save the state
        Throws:
        java.io.IOException - in case of write error
      • readBaseExternal

        protected double readBaseExternal​(java.io.ObjectInput in)
                                   throws java.io.IOException,
                                          java.lang.ClassNotFoundException
        Read the base state of the instance. This method does neither set the interpolated time nor state. It is up to the derived class to reset it properly calling the setInterpolatedTime(double) method later, once all rest of the object state has been set up properly.
        Parameters:
        in - stream where to read the state from
        Returns:
        interpolated time to be set later by the caller
        Throws:
        java.io.IOException - in case of read error
        java.lang.ClassNotFoundException - if an equation mapper class cannot be found