1 /* Copyright 2002-2026 CS GROUP
2 * Licensed to CS GROUP (CS) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * CS 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.orekit.models.earth.ionosphere;
18
19 import org.hipparchus.CalculusFieldElement;
20 import org.hipparchus.geometry.euclidean.threed.FieldVector3D;
21 import org.hipparchus.geometry.euclidean.threed.Vector3D;
22 import org.orekit.bodies.GeodeticPoint;
23 import org.orekit.bodies.OneAxisEllipsoid;
24 import org.orekit.frames.FieldStaticTransform;
25 import org.orekit.frames.Frame;
26 import org.orekit.frames.StaticTransform;
27 import org.orekit.frames.TopocentricFrame;
28 import org.orekit.propagation.FieldSpacecraftState;
29 import org.orekit.propagation.SpacecraftState;
30 import org.orekit.time.AbsoluteDate;
31 import org.orekit.time.FieldAbsoluteDate;
32 import org.orekit.utils.PVCoordinatesProvider;
33 import org.orekit.utils.ParameterDriversProvider;
34
35 /** Defines a ionospheric model, used to calculate the path delay imposed to
36 * electro-magnetic signals between an orbital satellite and a ground station.
37 * <p>
38 * Since 10.0, this interface can be used for models that aspire to estimate
39 * ionospheric parameters.
40 * </p>
41 *
42 * @author Joris Olympio
43 * @author Bryan Cazabonne
44 * @author Luc Maisonobe
45 * @author Brianna Aubin
46 * @since 13.0.3
47 */
48 public interface IonosphericModel extends ParameterDriversProvider {
49
50 /** Lambda header for calculating the path delay.
51 */
52 @FunctionalInterface
53 interface DelayCalculator {
54 Double apply(Vector3D pos);
55 }
56
57 /** Lambda header for calculating the path delay.
58 */
59 @FunctionalInterface
60 interface FieldDelayCalculator<T extends CalculusFieldElement<T>> {
61 T apply(FieldVector3D<T> pos);
62 }
63
64 /** Get the earth body shape for earth-frame calculations.
65 * @return earth body shape
66 * @since 14.0
67 */
68 OneAxisEllipsoid getEarth();
69
70 /**
71 * Calculates the ionospheric path delay for the signal path from an observation
72 * object to the satellite being measured.
73 * <p>
74 * This method is intended to be used for orbit determination issues.
75 * In that respect, if the elevation is below 0° the path delay will be equal to zero.
76 * </p><p>
77 * For individual use of the ionospheric model (i.e. not for orbit determination), another
78 * method signature can be implemented to compute the path delay for any elevation angle.
79 * </p>
80 * @param state spacecraft state
81 * @param coordsProvider coordinates provider for the observing object
82 * @param frequency frequency of the signal in Hz
83 * @param parameters ionospheric model parameters at state date
84 * @return the path delay due to the ionosphere in m
85 */
86 default double pathDelay(final SpacecraftState state,
87 final PVCoordinatesProvider coordsProvider,
88 final double frequency,
89 final double[] parameters) {
90
91 // Solve for the lowest altitude point between p1 and p2
92 final OneAxisEllipsoid earth = getEarth();
93 final Frame bodyFrame = earth.getFrame();
94 final AbsoluteDate receptionDate = state.getDate();
95 final Vector3D p1 = state.getPVCoordinates(bodyFrame).getPosition();
96 final Vector3D p2 = coordsProvider.getPosition(receptionDate, bodyFrame);
97 final GeodeticPoint lowAltPoint = earth.lowestAltitudeIntermediate(p1, p2);
98
99 // Solve for the positions of p1 and p2 in the topocentric frame of
100 // the lowest altitude point
101 final TopocentricFrame baseFrame = new TopocentricFrame(earth, lowAltPoint, null);
102 final StaticTransform base2Inert = baseFrame.getStaticTransformTo(bodyFrame, receptionDate);
103 final Vector3D localP1 = base2Inert.getInverse().transformPosition(p1);
104 final Vector3D localP2 = base2Inert.getInverse().transformPosition(p2);
105
106 return pathDelay(localP1, localP2, baseFrame, receptionDate, frequency, parameters);
107 }
108
109 /**
110 * Calculates the ionospheric path delay for the signal path from a ground
111 * station to an observing object (ground station or satellite).
112 * <p>
113 * This method is intended to be used for orbit determination issues.
114 * In that respect, if the elevation is below 0° the path delay will be equal to zero.
115 * </p><p>
116 * For individual use of the ionospheric model (i.e. not for orbit determination), another
117 * method signature can be implemented to compute the path delay for any elevation angle.
118 * </p>
119 * @param localP1 position of path start point in baseFrame
120 * @param localP2 position of path end point in baseFrame
121 * @param baseFrame topocentric frame of point with lowest altitude between p1 and p2
122 * @param receptionDate date at signal reception
123 * @param frequency frequency of the signal in Hz
124 * @param parameters ionospheric model parameters at state date
125 * @return the path delay due to the ionosphere in m
126 */
127 double pathDelay(Vector3D localP1, Vector3D localP2,
128 TopocentricFrame baseFrame, AbsoluteDate receptionDate,
129 double frequency, double[] parameters);
130
131 /**
132 * Calculates the ionospheric path delay for the signal path from an observation
133 * object to the satellite being measured.
134 * <p>
135 * This method is intended to be used for orbit determination issues.
136 * In that respect, if the elevation is below 0° the path delay will be equal to zero.
137 * </p><p>
138 * For individual use of the ionospheric model (i.e. not for orbit determination), another
139 * method signature can be implemented to compute the path delay for any elevation angle.
140 * </p>
141 * @param <T> type of the elements
142 * @param state spacecraft state
143 * @param coordsProvider coordinates provider for the observing object
144 * @param frequency frequency of the signal in Hz
145 * @param parameters ionospheric model parameters at state date
146 * @return the path delay due to the ionosphere in m
147 */
148 default <T extends CalculusFieldElement<T>> T pathDelay(final FieldSpacecraftState<T> state,
149 final PVCoordinatesProvider coordsProvider,
150 final double frequency,
151 final T[] parameters) {
152
153 // Solve for the lowest altitude point between p1 and p2
154 final OneAxisEllipsoid earth = getEarth();
155 final Frame bodyFrame = earth.getFrame();
156 final FieldAbsoluteDate<T> receptionDate = state.getDate();
157 final FieldVector3D<T> p1 = state.getPVCoordinates(bodyFrame).getPosition();
158 final Vector3D p2 = coordsProvider.getPosition(receptionDate.toAbsoluteDate(), bodyFrame);
159 final GeodeticPoint lowAltPoint = earth.lowestAltitudeIntermediate(p1.toVector3D(), p2);
160
161 final TopocentricFrame baseFrame = new TopocentricFrame(earth, lowAltPoint, null);
162 final FieldStaticTransform<T> base2Inert = baseFrame.getStaticTransformTo(bodyFrame, receptionDate);
163 final FieldVector3D<T> localP1 = base2Inert.getInverse().transformPosition(p1);
164 final FieldVector3D<T> localP2 = base2Inert.getInverse().transformPosition(p2);
165
166 return pathDelay(localP1, localP2, baseFrame, receptionDate, frequency, parameters);
167 }
168
169 /**
170 * Calculates the ionospheric path delay for the signal path from a ground
171 * station to an observing object (ground station or satellite).
172 * <p>
173 * This method is intended to be used for orbit determination issues.
174 * In that respect, if the elevation is below 0° the path delay will be equal to zero.
175 * </p><p>
176 * For individual use of the ionospheric model (i.e. not for orbit determination), another
177 * method signature can be implemented to compute the path delay for any elevation angle.
178 * </p>
179 * @param <T> type of the elements
180 * @param localP1 position of path start point in baseFrame
181 * @param localP2 position of path end point in baseFrame
182 * @param baseFrame topocentric frame of point with lowest altitude between p1 and p2
183 * @param receptionDate date at signal reception
184 * @param frequency frequency of the signal in Hz
185 * @param parameters ionospheric model parameters at state date
186 * @return the path delay due to the ionosphere in m
187 */
188 <T extends CalculusFieldElement<T>> T pathDelay(FieldVector3D<T> localP1, FieldVector3D<T> localP2,
189 TopocentricFrame baseFrame, FieldAbsoluteDate<T> receptionDate,
190 double frequency, T[] parameters);
191
192 }