001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.math3.ode.sampling;
019
020import org.apache.commons.math3.RealFieldElement;
021import org.apache.commons.math3.ode.FieldODEStateAndDerivative;
022
023/** This interface represents an interpolator over the last step
024 * during an ODE integration.
025 *
026 * <p>The various ODE integrators provide objects implementing this
027 * interface to the step handlers. These objects are often custom
028 * objects tightly bound to the integrator internal algorithms. The
029 * handlers can use these objects to retrieve the state vector at
030 * intermediate times between the previous and the current grid points
031 * (this feature is often called dense output).</p>
032 *
033 * @param <T> the type of the field elements
034 * @see org.apache.commons.math3.ode.FirstOrderFieldIntegrator
035 * @see FieldStepHandler
036 * @since 3.6
037 */
038
039public interface FieldStepInterpolator<T extends RealFieldElement<T>> {
040
041  /**
042   * Get the state at previous grid point time.
043   * @return state at previous grid point time
044   */
045  FieldODEStateAndDerivative<T> getPreviousState();
046
047  /**
048   * Get the state at current grid point time.
049   * @return state at current grid point time
050   */
051  FieldODEStateAndDerivative<T> getCurrentState();
052
053  /**
054   * Get the state at interpolated time.
055   * <p>Setting the time outside of the current step is allowed, but
056   * should be used with care since the accuracy of the interpolator will
057   * probably be very poor far from this step. This allowance has been
058   * added to simplify implementation of search algorithms near the
059   * step endpoints.</p>
060   * @param time time of the interpolated point
061   * @return state at interpolated time
062   */
063  FieldODEStateAndDerivative<T> getInterpolatedState(T time);
064
065  /** Check if the natural integration direction is forward.
066   * <p>This method provides the integration direction as specified by
067   * the integrator itself, it avoid some nasty problems in
068   * degenerated cases like null steps due to cancellation at step
069   * initialization, step control or discrete events
070   * triggering.</p>
071   * @return true if the integration variable (time) increases during
072   * integration
073   */
074  boolean isForward();
075
076}