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 
18 package org.apache.commons.math3.ode.sampling;
19 
20 import org.apache.commons.math3.RealFieldElement;
21 import org.apache.commons.math3.exception.MaxCountExceededException;
22 import org.apache.commons.math3.ode.FieldEquationsMapper;
23 import org.apache.commons.math3.ode.FieldODEStateAndDerivative;
24 
25 /** This abstract class represents an interpolator over the last step
26  * during an ODE integration.
27  *
28  * <p>The various ODE integrators provide objects extending this class
29  * to the step handlers. The handlers can use these objects to
30  * retrieve the state vector at intermediate times between the
31  * previous and the current grid points (dense output).</p>
32  *
33  * @see org.apache.commons.math3.ode.FirstOrderFieldIntegrator
34  * @see StepHandler
35  *
36  * @param <T> the type of the field elements
37  * @since 3.6
38  */
39 
40 public abstract class AbstractFieldStepInterpolator<T extends RealFieldElement<T>>
41     implements FieldStepInterpolator<T> {
42 
43     /** Global previous state. */
44     private final FieldODEStateAndDerivative<T> globalPreviousState;
45 
46     /** Global current state. */
47     private final FieldODEStateAndDerivative<T> globalCurrentState;
48 
49     /** Soft previous state. */
50     private final FieldODEStateAndDerivative<T> softPreviousState;
51 
52     /** Soft current state. */
53     private final FieldODEStateAndDerivative<T> softCurrentState;
54 
55     /** integration direction. */
56     private final boolean forward;
57 
58     /** Mapper for ODE equations primary and secondary components. */
59     private FieldEquationsMapper<T> mapper;
60 
61     /** Simple constructor.
62      * @param isForward integration direction indicator
63      * @param globalPreviousState start of the global step
64      * @param globalCurrentState end of the global step
65      * @param softPreviousState start of the restricted step
66      * @param softCurrentState end of the restricted step
67      * @param equationsMapper mapper for ODE equations primary and secondary components
68      */
AbstractFieldStepInterpolator(final boolean isForward, final FieldODEStateAndDerivative<T> globalPreviousState, final FieldODEStateAndDerivative<T> globalCurrentState, final FieldODEStateAndDerivative<T> softPreviousState, final FieldODEStateAndDerivative<T> softCurrentState, final FieldEquationsMapper<T> equationsMapper)69     protected AbstractFieldStepInterpolator(final boolean isForward,
70                                             final FieldODEStateAndDerivative<T> globalPreviousState,
71                                             final FieldODEStateAndDerivative<T> globalCurrentState,
72                                             final FieldODEStateAndDerivative<T> softPreviousState,
73                                             final FieldODEStateAndDerivative<T> softCurrentState,
74                                             final FieldEquationsMapper<T> equationsMapper) {
75         this.forward             = isForward;
76         this.globalPreviousState = globalPreviousState;
77         this.globalCurrentState  = globalCurrentState;
78         this.softPreviousState   = softPreviousState;
79         this.softCurrentState    = softCurrentState;
80         this.mapper              = equationsMapper;
81     }
82 
83     /** Create a new restricted version of the instance.
84      * <p>
85      * The instance is not changed at all.
86      * </p>
87      * @param previousState start of the restricted step
88      * @param currentState end of the restricted step
89      * @return restricted version of the instance
90      * @see #getPreviousState()
91      * @see #getCurrentState()
92      */
restrictStep(final FieldODEStateAndDerivative<T> previousState, final FieldODEStateAndDerivative<T> currentState)93     public AbstractFieldStepInterpolator<T> restrictStep(final FieldODEStateAndDerivative<T> previousState,
94                                                          final FieldODEStateAndDerivative<T> currentState) {
95         return create(forward, globalPreviousState, globalCurrentState, previousState, currentState, mapper);
96     }
97 
98     /** Create a new instance.
99      * @param newForward integration direction indicator
100      * @param newGlobalPreviousState start of the global step
101      * @param newGlobalCurrentState end of the global step
102      * @param newSoftPreviousState start of the restricted step
103      * @param newSoftCurrentState end of the restricted step
104      * @param newMapper equations mapper for the all equations
105      * @return a new instance
106      */
create(boolean newForward, FieldODEStateAndDerivative<T> newGlobalPreviousState, FieldODEStateAndDerivative<T> newGlobalCurrentState, FieldODEStateAndDerivative<T> newSoftPreviousState, FieldODEStateAndDerivative<T> newSoftCurrentState, FieldEquationsMapper<T> newMapper)107     protected abstract AbstractFieldStepInterpolator<T> create(boolean newForward,
108                                                                FieldODEStateAndDerivative<T> newGlobalPreviousState,
109                                                                FieldODEStateAndDerivative<T> newGlobalCurrentState,
110                                                                FieldODEStateAndDerivative<T> newSoftPreviousState,
111                                                                FieldODEStateAndDerivative<T> newSoftCurrentState,
112                                                                FieldEquationsMapper<T> newMapper);
113 
114     /**
115      * Get the previous global grid point state.
116      * @return previous global grid point state
117      */
getGlobalPreviousState()118     public FieldODEStateAndDerivative<T> getGlobalPreviousState() {
119         return globalPreviousState;
120     }
121 
122     /**
123      * Get the current global grid point state.
124      * @return current global grid point state
125      */
getGlobalCurrentState()126     public FieldODEStateAndDerivative<T> getGlobalCurrentState() {
127         return globalCurrentState;
128     }
129 
130     /** {@inheritDoc} */
getPreviousState()131     public FieldODEStateAndDerivative<T> getPreviousState() {
132         return softPreviousState;
133     }
134 
135     /** {@inheritDoc} */
getCurrentState()136     public FieldODEStateAndDerivative<T> getCurrentState() {
137         return softCurrentState;
138     }
139 
140     /** {@inheritDoc} */
getInterpolatedState(final T time)141     public FieldODEStateAndDerivative<T> getInterpolatedState(final T time) {
142         final T thetaH         = time.subtract(globalPreviousState.getTime());
143         final T oneMinusThetaH = globalCurrentState.getTime().subtract(time);
144         final T theta          = thetaH.divide(globalCurrentState.getTime().subtract(globalPreviousState.getTime()));
145         return computeInterpolatedStateAndDerivatives(mapper, time, theta, thetaH, oneMinusThetaH);
146     }
147 
148     /** {@inheritDoc} */
isForward()149     public boolean isForward() {
150         return forward;
151     }
152 
153     /** Compute the state and derivatives at the interpolated time.
154      * This is the main processing method that should be implemented by
155      * the derived classes to perform the interpolation.
156      * @param equationsMapper mapper for ODE equations primary and secondary components
157      * @param time interpolation time
158      * @param theta normalized interpolation abscissa within the step
159      * (theta is zero at the previous time step and one at the current time step)
160      * @param thetaH time gap between the previous time and the interpolated time
161      * @param oneMinusThetaH time gap between the interpolated time and
162      * the current time
163      * @return interpolated state and derivatives
164      * @exception MaxCountExceededException if the number of functions evaluations is exceeded
165      */
computeInterpolatedStateAndDerivatives(FieldEquationsMapper<T> equationsMapper, T time, T theta, T thetaH, T oneMinusThetaH)166     protected abstract FieldODEStateAndDerivative<T> computeInterpolatedStateAndDerivatives(FieldEquationsMapper<T> equationsMapper,
167                                                                                             T time, T theta,
168                                                                                             T thetaH, T oneMinusThetaH)
169         throws MaxCountExceededException;
170 
171 }
172