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.orbits;
18  
19  import org.hipparchus.geometry.euclidean.threed.Vector3D;
20  import org.hipparchus.linear.DecompositionSolver;
21  import org.hipparchus.linear.MatrixUtils;
22  import org.hipparchus.linear.QRDecomposition;
23  import org.hipparchus.linear.RealMatrix;
24  import org.hipparchus.linear.RealVector;
25  import org.hipparchus.util.FastMath;
26  import org.hipparchus.util.MathArrays;
27  import org.orekit.errors.OrekitIllegalArgumentException;
28  import org.orekit.errors.OrekitMessages;
29  import org.orekit.frames.Frame;
30  import org.orekit.frames.KinematicTransform;
31  import org.orekit.frames.Transform;
32  import org.orekit.time.AbsoluteDate;
33  import org.orekit.time.TimeOffset;
34  import org.orekit.time.TimeShiftable;
35  import org.orekit.utils.PVCoordinates;
36  import org.orekit.utils.PVCoordinatesProvider;
37  import org.orekit.utils.TimeStampedPVCoordinates;
38  
39  /**
40   * This class handles orbital parameters.
41  
42   * <p>
43   * For user convenience, both the Cartesian and the equinoctial elements
44   * are provided by this class, regardless of the canonical representation
45   * implemented in the derived class (which may be classical Keplerian
46   * elements for example).
47   * </p>
48   * <p>
49   * The parameters are defined in a frame specified by the user. It is important
50   * to make sure this frame is consistent: it probably is inertial and centered
51   * on the central body. This information is used for example by some
52   * force models.
53   * </p>
54   * <p>
55   * Instance of this class are guaranteed to be immutable.
56   * </p>
57   * @author Luc Maisonobe
58   * @author Guylaine Prat
59   * @author Fabien Maussion
60   * @author V&eacute;ronique Pommier-Maurussane
61   */
62  public abstract class Orbit
63      implements TimeShiftable<Orbit>, OrbitalState, PVCoordinatesProvider {
64  
65      /** Absolute tolerance when checking if the rate of the position angle is Keplerian or not. */
66      protected static final double TOLERANCE_POSITION_ANGLE_RATE = 1e-15;
67  
68      /** Frame in which are defined the orbital parameters. */
69      private final Frame frame;
70  
71      /** Date of the orbital parameters. */
72      private final AbsoluteDate date;
73  
74      /** Value of mu used to compute position and velocity (m³/s²). */
75      private final double mu;
76  
77      /** Computed position.
78       * @since 12.0
79       */
80      private Vector3D position;
81  
82      /** Computed PVCoordinates. */
83      private TimeStampedPVCoordinates pvCoordinates;
84  
85      /** Jacobian of the orbital parameters with mean angle with respect to the Cartesian coordinates. */
86      private double[][] jacobianMeanWrtCartesian;
87  
88      /** Jacobian of the Cartesian coordinates with respect to the orbital parameters with mean angle. */
89      private double[][] jacobianWrtParametersMean;
90  
91      /** Jacobian of the orbital parameters with eccentric angle with respect to the Cartesian coordinates. */
92      private double[][] jacobianEccentricWrtCartesian;
93  
94      /** Jacobian of the Cartesian coordinates with respect to the orbital parameters with eccentric angle. */
95      private double[][] jacobianWrtParametersEccentric;
96  
97      /** Jacobian of the orbital parameters with true angle with respect to the Cartesian coordinates. */
98      private double[][] jacobianTrueWrtCartesian;
99  
100     /** Jacobian of the Cartesian coordinates with respect to the orbital parameters with true angle. */
101     private double[][] jacobianWrtParametersTrue;
102 
103     /** Default constructor.
104      * Build a new instance with arbitrary default elements.
105      * @param frame the frame in which the parameters are defined
106      * (<em>must</em> be a {@link Frame#isPseudoInertial pseudo-inertial frame})
107      * @param date date of the orbital parameters
108      * @param mu central attraction coefficient (m^3/s^2)
109      * @exception IllegalArgumentException if frame is not a {@link
110      * Frame#isPseudoInertial pseudo-inertial frame}
111      */
112     protected Orbit(final Frame frame, final AbsoluteDate date, final double mu)
113         throws IllegalArgumentException {
114         ensurePseudoInertialFrame(frame);
115         this.date                      = date;
116         this.mu                        = mu;
117         this.pvCoordinates             = null;
118         this.frame                     = frame;
119         jacobianMeanWrtCartesian       = null;
120         jacobianWrtParametersMean      = null;
121         jacobianEccentricWrtCartesian  = null;
122         jacobianWrtParametersEccentric = null;
123         jacobianTrueWrtCartesian       = null;
124         jacobianWrtParametersTrue      = null;
125     }
126 
127     /** Set the orbit from Cartesian parameters.
128      *
129      * <p> The acceleration provided in {@code pvCoordinates} is accessible using
130      * {@link #getPVCoordinates()} and {@link #getPVCoordinates(Frame)}. All other methods
131      * use {@code mu} and the position to compute the acceleration, including
132      * {@link #shiftedBy(double)} and {@link #getPVCoordinates(AbsoluteDate, Frame)}.
133      *
134      * @param pvCoordinates the position and velocity in the inertial frame
135      * @param frame the frame in which the {@link TimeStampedPVCoordinates} are defined
136      * (<em>must</em> be a {@link Frame#isPseudoInertial pseudo-inertial frame})
137      * @param mu central attraction coefficient (m^3/s^2)
138      * @exception IllegalArgumentException if frame is not a {@link
139      * Frame#isPseudoInertial pseudo-inertial frame}
140      */
141     protected Orbit(final TimeStampedPVCoordinates pvCoordinates, final Frame frame, final double mu)
142         throws IllegalArgumentException {
143         ensurePseudoInertialFrame(frame);
144         this.date = pvCoordinates.getDate();
145         this.mu = mu;
146         if (pvCoordinates.getAcceleration().getNorm2Sq() == 0) {
147             // the acceleration was not provided,
148             // compute it from Newtonian attraction
149             final double r2 = pvCoordinates.getPosition().getNorm2Sq();
150             final double r3 = r2 * FastMath.sqrt(r2);
151             this.pvCoordinates = new TimeStampedPVCoordinates(pvCoordinates.getDate(),
152                                                               pvCoordinates.getPosition(),
153                                                               pvCoordinates.getVelocity(),
154                                                               new Vector3D(-mu / r3, pvCoordinates.getPosition()));
155         } else {
156             this.pvCoordinates = pvCoordinates;
157         }
158         this.frame = frame;
159     }
160 
161     /** Compute non-Keplerian part of the acceleration from first time derivatives.
162      * @return non-Keplerian part of the acceleration
163      * @since 13.1
164      */
165     protected Vector3D nonKeplerianAcceleration() {
166 
167         final double[][] dPdC = new double[6][6];
168         final PositionAngleType positionAngleType = PositionAngleType.MEAN;
169         getJacobianWrtCartesian(positionAngleType, dPdC);
170         final RealMatrix subMatrix = MatrixUtils.createRealMatrix(dPdC);
171 
172         final DecompositionSolver solver = getDecompositionSolver(subMatrix);
173 
174         final double[] derivatives = new double[6];
175         getType().mapOrbitToArray(this, positionAngleType, new double[6], derivatives);
176         derivatives[5] -= getKeplerianMeanMotion();
177 
178         final RealVector solution = solver.solve(MatrixUtils.createRealVector(derivatives));
179         return new Vector3D(solution.getEntry(3), solution.getEntry(4), solution.getEntry(5));
180 
181     }
182 
183     /** Check if Cartesian coordinates include non-Keplerian acceleration.
184      * @param pva Cartesian coordinates
185      * @param mu central attraction coefficient
186      * @return true if Cartesian coordinates include non-Keplerian acceleration
187      */
188     protected static boolean hasNonKeplerianAcceleration(final PVCoordinates pva, final double mu) {
189 
190         final Vector3D a = pva.getAcceleration();
191         if (a == null) {
192             return false;
193         }
194 
195         final Vector3D p = pva.getPosition();
196         final double r2 = p.getNorm2Sq();
197 
198         // Check if acceleration is relatively close to 0 compared to the Keplerian acceleration
199         final double tolerance = mu * 1e-9;
200         final Vector3D aTimesR2 = a.scalarMultiply(r2);
201         if (aTimesR2.getNorm() < tolerance) {
202             return false;
203         }
204 
205         if ((aTimesR2.add(p.normalize().scalarMultiply(mu))).getNorm() > tolerance) {
206             // we have a relevant acceleration, we can compute derivatives
207             return true;
208         } else {
209             // the provided acceleration is either too small to be reliable (probably even 0), or NaN
210             return false;
211         }
212     }
213 
214     /**
215      * Compute corrected shift from non-Keplerian part.
216      * @param keplerianShifted Keplerian shift
217      * @param dt time shift
218      * @return corrected position-velocity-acceleration vector
219      * @since 14.0
220      */
221     protected PVCoordinates shiftPVNonKeplerian(final PVCoordinates keplerianShifted, final double dt) {
222         // extract non-Keplerian acceleration from first time derivatives
223         final Vector3D nonKeplerianAcceleration = nonKeplerianAcceleration();
224 
225         // add second order effect of non-Keplerian acceleration to Keplerian-only shift
226         final Vector3D fixedV = nonKeplerianAcceleration.scalarMultiply(dt).add(keplerianShifted.getVelocity());
227         final Vector3D fixedP   = nonKeplerianAcceleration.scalarMultiply(dt * dt / 2.).add(keplerianShifted.getPosition());
228         final double   fixedR2 = fixedP.getNorm2Sq();
229         final double   fixedR  = FastMath.sqrt(fixedR2);
230         final Vector3D fixedA  = nonKeplerianAcceleration.add(new Vector3D(-getMu() / (fixedR2 * fixedR),
231                 keplerianShifted.getPosition()));
232         return new PVCoordinates(fixedP, fixedV, fixedA);
233     }
234 
235     /** Returns true if and only if the orbit is elliptical i.e. has a non-negative semi-major axis.
236      * @return true if getA() is strictly greater than 0
237      * @since 12.0
238      */
239     public boolean isElliptical() {
240         return getA() > 0.;
241     }
242 
243     /** Get the orbit type.
244      * @return orbit type
245      */
246     public abstract OrbitParamsType getType();
247 
248     /**
249      * Get a factory for the current orbit type.
250      *
251      * @param positionAngleType position angle type to use
252      * @param positionScale     position scale used to scale the orbital drivers
253      * @return factory building orbit instance of the correct type
254      * @since 14.0
255      */
256     public abstract AbstractOrbitFactory<? extends Orbit> factory(PositionAngleType positionAngleType,
257                                                                   double positionScale);
258 
259     /** Ensure the defining frame is a pseudo-inertial frame.
260      * @param frame frame to check
261      * @exception IllegalArgumentException if frame is not a {@link
262      * Frame#isPseudoInertial pseudo-inertial frame}
263      */
264     private static void ensurePseudoInertialFrame(final Frame frame)
265         throws IllegalArgumentException {
266         if (!frame.isPseudoInertial()) {
267             throw new OrekitIllegalArgumentException(OrekitMessages.NON_PSEUDO_INERTIAL_FRAME,
268                                                      frame.getName());
269         }
270     }
271 
272     /** Get the frame in which the orbital parameters are defined.
273      * @return frame in which the orbital parameters are defined
274      */
275     public Frame getFrame() {
276         return frame;
277     }
278 
279     /** Get the semi-major axis.
280      * <p>Note that the semi-major axis is considered negative for hyperbolic orbits.</p>
281      * @return semi-major axis (m)
282      */
283     public abstract double getA();
284 
285     /** Get the semi-major axis derivative.
286      * <p>Note that the semi-major axis is considered negative for hyperbolic orbits.</p>
287      * <p>
288      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
289      * </p>
290      * @return semi-major axis  derivative (m/s)
291      * @since 9.0
292      */
293     public abstract double getADot();
294 
295     /** Get the first component of the equinoctial eccentricity vector.
296      * @return first component of the equinoctial eccentricity vector
297      */
298     public abstract double getEquinoctialEx();
299 
300     /** Get the first component of the equinoctial eccentricity vector derivative.
301      * <p>
302      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
303      * </p>
304      * @return first component of the equinoctial eccentricity vector derivative
305      * @since 9.0
306      */
307     public abstract double getEquinoctialExDot();
308 
309     /** Get the second component of the equinoctial eccentricity vector.
310      * @return second component of the equinoctial eccentricity vector
311      */
312     public abstract double getEquinoctialEy();
313 
314     /** Get the second component of the equinoctial eccentricity vector derivative.
315      * <p>
316      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
317      * </p>
318      * @return second component of the equinoctial eccentricity vector derivative
319      * @since 9.0
320      */
321     public abstract double getEquinoctialEyDot();
322 
323     /** Get the first component of the inclination vector.
324      * @return first component of the inclination vector
325      */
326     public abstract double getHx();
327 
328     /** Get the first component of the inclination vector derivative.
329      * <p>
330      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
331      * </p>
332      * @return first component of the inclination vector derivative
333 
334      * @since 9.0
335      */
336     public abstract double getHxDot();
337 
338     /** Get the second component of the inclination vector.
339      * @return second component of the inclination vector
340      */
341     public abstract double getHy();
342 
343     /** Get the second component of the inclination vector derivative.
344      * <p>
345      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
346      * </p>
347      * @return second component of the inclination vector derivative
348      * @since 9.0
349      */
350     public abstract double getHyDot();
351 
352     /** Get the eccentric longitude argument.
353      * @return E + ω + Ω eccentric longitude argument (rad)
354      */
355     public abstract double getLE();
356 
357     /** Get the eccentric longitude argument derivative.
358      * <p>
359      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
360      * </p>
361      * @return d(E + ω + Ω)/dt eccentric longitude argument derivative (rad/s)
362      * @since 9.0
363      */
364     public abstract double getLEDot();
365 
366     /** Get the true longitude argument.
367      * @return v + ω + Ω true longitude argument (rad)
368      */
369     public abstract double getLv();
370 
371     /** Get the true longitude argument derivative.
372      * <p>
373      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
374      * </p>
375      * @return d(v + ω + Ω)/dt true longitude argument derivative (rad/s)
376      * @since 9.0
377      */
378     public abstract double getLvDot();
379 
380     /** Get the mean longitude argument.
381      * @return M + ω + Ω mean longitude argument (rad)
382      */
383     public abstract double getLM();
384 
385     /** Get the mean longitude argument derivative.
386      * <p>
387      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
388      * </p>
389      * @return d(M + ω + Ω)/dt mean longitude argument derivative (rad/s)
390      * @since 9.0
391      */
392     public abstract double getLMDot();
393 
394     // Additional orbital elements
395 
396     /** Get the eccentricity.
397      * @return eccentricity
398      */
399     public abstract double getE();
400 
401     /** Get the eccentricity derivative.
402      * <p>
403      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
404      * </p>
405      * @return eccentricity derivative
406      * @since 9.0
407      */
408     public abstract double getEDot();
409 
410     /** Get the inclination.
411      * @return inclination (rad)
412      */
413     public abstract double getI();
414 
415     /** Get the inclination derivative.
416      * <p>
417      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
418      * </p>
419      * @return inclination derivative (rad/s)
420      * @since 9.0
421      */
422     public abstract double getIDot();
423 
424     /** Check if orbit includes non-Keplerian rates.
425      * @return true if orbit includes non-Keplerian derivatives
426      * @see #getADot()
427      * @see #getEquinoctialExDot()
428      * @see #getEquinoctialEyDot()
429      * @see #getHxDot()
430      * @see #getHyDot()
431      * @see #getLEDot()
432      * @see #getLvDot()
433      * @see #getLMDot()
434      * @see #getEDot()
435      * @see #getIDot()
436      * @since 13.0
437      */
438     public boolean hasNonKeplerianAcceleration() {
439         return hasNonKeplerianAcceleration(getPVCoordinates(), getMu());
440     }
441 
442     /** Get the central acceleration constant.
443      * @return central acceleration constant
444      */
445     public double getMu() {
446         return mu;
447     }
448 
449     /** Get the Keplerian period.
450      * <p>The Keplerian period is computed directly from semi major axis
451      * and central acceleration constant.</p>
452      * @return Keplerian period in seconds, or positive infinity for hyperbolic orbits
453      */
454     public double getKeplerianPeriod() {
455         final double a = getA();
456         return isElliptical() ? 2.0 * FastMath.PI * a * FastMath.sqrt(a / mu) : Double.POSITIVE_INFINITY;
457     }
458 
459     /** Get the Keplerian mean motion.
460      * <p>The Keplerian mean motion is computed directly from semi major axis
461      * and central acceleration constant.</p>
462      * @return Keplerian mean motion in radians per second
463      */
464     public double getKeplerianMeanMotion() {
465         final double absA = FastMath.abs(getA());
466         return FastMath.sqrt(mu / absA) / absA;
467     }
468 
469     /** Get the derivative of the mean anomaly with respect to the semi major axis.
470      * @return derivative of the mean anomaly with respect to the semi major axis
471      */
472     public double getMeanAnomalyDotWrtA() {
473         return -1.5 * getKeplerianMeanMotion() / getA();
474     }
475 
476     /** Get the date of orbital parameters.
477      * @return date of the orbital parameters
478      */
479     public AbsoluteDate getDate() {
480         return date;
481     }
482 
483     /** {@inheritDoc} */
484     @Override
485     public Vector3D getPosition(final AbsoluteDate otherDate, final Frame outputFrame) {
486         // use Keplerian-only motion
487         final double dt = otherDate.durationFrom(date);
488         final Orbit keplerianShifted = dt == 0. ? this : keplerianShiftedBy(dt);
489         final Vector3D positionInFrame;
490         // Non-Keplerian acceleration shall be considered
491         if (dt != 0. && hasNonKeplerianAcceleration()) {
492             // extract non-Keplerian acceleration from first time derivatives
493             final Vector3D nonKeplerianAcceleration = nonKeplerianAcceleration();
494             // add second order effect of non-Keplerian acceleration to Keplerian-only shift
495             positionInFrame = nonKeplerianAcceleration.scalarMultiply(dt * dt / 2.).add(keplerianShifted.getPosition());
496         }
497         else {  // Keplerian-only motion is all we can do
498             positionInFrame = keplerianShifted.getPosition();
499         }
500         if (outputFrame == getFrame()) {
501             return positionInFrame;
502         } else {
503             return getFrame().getStaticTransformTo(outputFrame, otherDate).transformPosition(positionInFrame);
504         }
505     }
506 
507     /** Get the position in definition frame.
508      * @return position in the definition frame
509      * @see #getPVCoordinates()
510      * @since 12.0
511      */
512     public Vector3D getPosition() {
513         if (position == null) {
514             position = initPosition();
515         }
516         return position;
517     }
518 
519     /**
520      * Method returning the position vector in the specified frame.
521      * @param outputFrame target frame
522      * @return position vector
523      */
524     public Vector3D getPosition(final Frame outputFrame) {
525         return getPosition(getDate(), outputFrame);
526     }
527 
528     /**
529      * Getter for the velocity vector.
530      * @return velocity
531      */
532     public Vector3D getVelocity() {
533         return getPVCoordinates().getVelocity();
534     }
535 
536     /**
537      * Method returning the velocity vector in the specified frame.
538      * @param outputFrame target frame
539      * @return velocity vector
540      */
541     public Vector3D getVelocity(final Frame outputFrame) {
542         if (outputFrame == getFrame()) {
543             return getVelocity();
544         }
545         final KinematicTransform kinematicTransform = getFrame().getKinematicTransformTo(outputFrame, getDate());
546         final PVCoordinates transformedPV = kinematicTransform.transformOnlyPV(getPVCoordinates());
547         return transformedPV.getVelocity();
548     }
549 
550     /** {@inheritDoc} */
551     @Override
552     public Vector3D getVelocity(final AbsoluteDate otherDate, final Frame outputFrame) {
553         final TimeStampedPVCoordinates timeStampedPVCoordinates = otherDate.equals(getDate()) ? getPVCoordinates() :
554                 getPVCoordinates(otherDate, getFrame());
555         final KinematicTransform kinematicTransform = getFrame().getKinematicTransformTo(outputFrame, getDate());
556         final PVCoordinates transformedPV = kinematicTransform.transformOnlyPV(timeStampedPVCoordinates);
557         return transformedPV.getVelocity();
558     }
559 
560     /** Get the {@link TimeStampedPVCoordinates} in definition frame.
561      * @return pvCoordinates in the definition frame
562      * @see #getPVCoordinates(Frame)
563      */
564     public TimeStampedPVCoordinates getPVCoordinates() {
565         if (pvCoordinates == null) {
566             pvCoordinates = initPVCoordinates();
567             position      = pvCoordinates.getPosition();
568         }
569         return pvCoordinates;
570     }
571 
572     /** Get the {@link TimeStampedPVCoordinates} in a specified frame.
573      * @param outputFrame frame for conversion
574      * @return pvCoordinates in the given frame
575      * @see #getPVCoordinates(AbsoluteDate, Frame)
576      */
577     public TimeStampedPVCoordinates getPVCoordinates(final Frame outputFrame) {
578         if (outputFrame == getFrame()) {
579             return getPVCoordinates();
580         } else {
581             final Transform transform = getFrame().getTransformTo(outputFrame, getDate());
582             return transform.transformPVCoordinates(getPVCoordinates());
583         }
584     }
585 
586     /** Shift the orbit and provides the {@link TimeStampedPVCoordinates} in a specified frame.
587      * @param otherDate target date
588      * @param outputFrame frame for conversion
589      * @return pvCoordinates in the given frame
590      */
591     public TimeStampedPVCoordinates getPVCoordinates(final AbsoluteDate otherDate, final Frame outputFrame) {
592         final Orbit shifted = shiftedBy(otherDate.accurateDurationFrom(getDate()));
593         final TimeStampedPVCoordinates pv = shifted.getPVCoordinates();
594         if (outputFrame == getFrame()) {
595             return pv;
596         }
597         final Transform transform = getFrame().getTransformTo(outputFrame, otherDate);
598         return transform.transformPVCoordinates(pv);
599     }
600 
601     /** Compute the position coordinates from the canonical parameters.
602      * @return computed position coordinates
603      * @since 12.0
604      */
605     protected abstract Vector3D initPosition();
606 
607     /** Compute the position/velocity coordinates from the canonical parameters.
608      * @return computed position/velocity coordinates
609      */
610     protected abstract TimeStampedPVCoordinates initPVCoordinates();
611 
612     /**
613      * Create a new object representing the same physical orbital state, but attached to a different reference frame.
614      * If the new frame is not inertial, an exception will be thrown.
615      *
616      * @param inertialFrame reference frame of output orbit
617      * @return orbit with different frame
618      * @since 13.0
619      */
620     public abstract Orbit inFrame(Frame inertialFrame);
621 
622     /** Get a time-shifted orbit.
623      * <p>
624      * The orbit can be slightly shifted to close dates. The shifting model is a
625      * Keplerian one if no derivatives are available in the orbit, or Keplerian
626      * plus quadratic effect of the non-Keplerian acceleration if derivatives are
627      * available. Shifting is <em>not</em> intended as a replacement for proper
628      * orbit propagation but should be sufficient for small time shifts or coarse
629      * accuracy.
630      * </p>
631      * @param dt time shift in seconds
632      * @return a new orbit, shifted with respect to the instance (which is immutable)
633      */
634     @Override
635     public abstract Orbit shiftedBy(double dt);
636 
637     /** Get a time-shifted orbit.
638      * <p>
639      * The orbit can be slightly shifted to close dates. The shifting model is a
640      * Keplerian one if no derivatives are available in the orbit, or Keplerian
641      * plus quadratic effect of the non-Keplerian acceleration if derivatives are
642      * available. Shifting is <em>not</em> intended as a replacement for proper
643      * orbit propagation but should be sufficient for small time shifts or coarse
644      * accuracy.
645      * </p>
646      * @param dt time shift
647      * @return a new orbit, shifted with respect to the instance (which is immutable)
648      */
649     @Override
650     public abstract Orbit shiftedBy(TimeOffset dt);
651 
652     /** Get a time-shifted orbit assuming pure Keplerian motion.
653      * @param dt time shift
654      * @return a new orbit, shifted with respect to the instance (which is immutable)
655      * @since 14.0
656      */
657     protected abstract Orbit keplerianShiftedBy(double dt);
658 
659     /** Compute the Jacobian of the orbital parameters with respect to the Cartesian parameters.
660      * <p>
661      * Element {@code jacobian[i][j]} is the derivative of parameter i of the orbit with
662      * respect to Cartesian coordinate j. This means each row corresponds to one orbital parameter
663      * whereas columns 0 to 5 correspond to the Cartesian coordinates x, y, z, xDot, yDot and zDot.
664      * </p>
665      * @param type type of the position angle to use
666      * @param jacobian placeholder 6x6 (or larger) matrix to be filled with the Jacobian, if matrix
667      * is larger than 6x6, only the 6x6 upper left corner will be modified
668      */
669     public void getJacobianWrtCartesian(final PositionAngleType type, final double[][] jacobian) {
670 
671         final double[][] cachedJacobian;
672         synchronized (this) {
673             cachedJacobian = switch (type) {
674                 case MEAN -> {
675                     if (jacobianMeanWrtCartesian == null) {
676                         // first call, we need to compute the Jacobian and cache it
677                         jacobianMeanWrtCartesian = computeJacobianMeanWrtCartesian();
678                     }
679                     yield jacobianMeanWrtCartesian;
680                 }
681                 case ECCENTRIC -> {
682                     if (jacobianEccentricWrtCartesian == null) {
683                         // first call, we need to compute the Jacobian and cache it
684                         jacobianEccentricWrtCartesian = computeJacobianEccentricWrtCartesian();
685                     }
686                     yield jacobianEccentricWrtCartesian;
687                 }
688                 case TRUE -> {
689                     if (jacobianTrueWrtCartesian == null) {
690                         // first call, we need to compute the Jacobian and cache it
691                         jacobianTrueWrtCartesian = computeJacobianTrueWrtCartesian();
692                     }
693                     yield jacobianTrueWrtCartesian;
694                 }
695             };
696         }
697 
698         // fill the user provided array
699         for (int i = 0; i < cachedJacobian.length; ++i) {
700             System.arraycopy(cachedJacobian[i], 0, jacobian[i], 0, cachedJacobian[i].length);
701         }
702 
703     }
704 
705     /** Compute the Jacobian of the Cartesian parameters with respect to the orbital parameters.
706      * <p>
707      * Element {@code jacobian[i][j]} is the derivative of Cartesian coordinate i of the orbit with
708      * respect to orbital parameter j. This means each row corresponds to one Cartesian coordinate
709      * x, y, z, xdot, ydot, zdot whereas columns 0 to 5 correspond to the orbital parameters.
710      * </p>
711      * @param type type of the position angle to use
712      * @param jacobian placeholder 6x6 (or larger) matrix to be filled with the Jacobian, if matrix
713      * is larger than 6x6, only the 6x6 upper left corner will be modified
714      */
715     public void getJacobianWrtParameters(final PositionAngleType type, final double[][] jacobian) {
716 
717         final double[][] cachedJacobian;
718         synchronized (this) {
719             cachedJacobian = switch (type) {
720                 case MEAN -> {
721                     if (jacobianWrtParametersMean == null) {
722                         // first call, we need to compute the Jacobian and cache it
723                         jacobianWrtParametersMean = createInverseJacobian(type);
724                     }
725                     yield jacobianWrtParametersMean;
726                 }
727                 case ECCENTRIC -> {
728                     if (jacobianWrtParametersEccentric == null) {
729                         // first call, we need to compute the Jacobian and cache it
730                         jacobianWrtParametersEccentric = createInverseJacobian(type);
731                     }
732                     yield jacobianWrtParametersEccentric;
733                 }
734                 case TRUE -> {
735                     if (jacobianWrtParametersTrue == null) {
736                         // first call, we need to compute the Jacobian and cache it
737                         jacobianWrtParametersTrue = createInverseJacobian(type);
738                     }
739                     yield jacobianWrtParametersTrue;
740                 }
741             };
742         }
743 
744         // fill the user-provided array
745         for (int i = 0; i < cachedJacobian.length; ++i) {
746             System.arraycopy(cachedJacobian[i], 0, jacobian[i], 0, cachedJacobian[i].length);
747         }
748 
749     }
750 
751     /** Create an inverse Jacobian.
752      * @param type type of the position angle to use
753      * @return inverse Jacobian
754      */
755     private double[][] createInverseJacobian(final PositionAngleType type) {
756 
757         // get the direct Jacobian
758         final double[][] directJacobian = new double[6][6];
759         getJacobianWrtCartesian(type, directJacobian);
760 
761         // invert the direct Jacobian
762         final RealMatrix matrix = MatrixUtils.createRealMatrix(directJacobian);
763         final DecompositionSolver solver = getDecompositionSolver(matrix);
764         return solver.getInverse().getData();
765 
766     }
767 
768     /**
769      * Method to build a matrix decomposition solver.
770      * @param realMatrix matrix
771      * @return solver
772      * @since 13.1
773      */
774     protected DecompositionSolver getDecompositionSolver(final RealMatrix realMatrix) {
775         return new QRDecomposition(realMatrix).getSolver();
776     }
777 
778     /** Compute the Jacobian of the orbital parameters with mean angle with respect to the Cartesian parameters.
779      * <p>
780      * Element {@code jacobian[i][j]} is the derivative of parameter i of the orbit with
781      * respect to Cartesian coordinate j. This means each row correspond to one orbital parameter
782      * whereas columns 0 to 5 correspond to the Cartesian coordinates x, y, z, xDot, yDot and zDot.
783      * </p>
784      * <p>
785      * The array returned by this method will not be modified.
786      * </p>
787      * @return 6x6 Jacobian matrix
788      * @see #computeJacobianEccentricWrtCartesian()
789      * @see #computeJacobianTrueWrtCartesian()
790      */
791     protected abstract double[][] computeJacobianMeanWrtCartesian();
792 
793     /** Compute the Jacobian of the orbital parameters with eccentric angle with respect to the Cartesian parameters.
794      * <p>
795      * Element {@code jacobian[i][j]} is the derivative of parameter i of the orbit with
796      * respect to Cartesian coordinate j. This means each row correspond to one orbital parameter
797      * whereas columns 0 to 5 correspond to the Cartesian coordinates x, y, z, xDot, yDot and zDot.
798      * </p>
799      * <p>
800      * The array returned by this method will not be modified.
801      * </p>
802      * @return 6x6 Jacobian matrix
803      * @see #computeJacobianMeanWrtCartesian()
804      * @see #computeJacobianTrueWrtCartesian()
805      */
806     protected abstract double[][] computeJacobianEccentricWrtCartesian();
807 
808     /** Compute the Jacobian of the orbital parameters with true angle with respect to the Cartesian parameters.
809      * <p>
810      * Element {@code jacobian[i][j]} is the derivative of parameter i of the orbit with
811      * respect to Cartesian coordinate j. This means each row correspond to one orbital parameter
812      * whereas columns 0 to 5 correspond to the Cartesian coordinates x, y, z, xDot, yDot and zDot.
813      * </p>
814      * <p>
815      * The array returned by this method will not be modified.
816      * </p>
817      * @return 6x6 Jacobian matrix
818      * @see #computeJacobianMeanWrtCartesian()
819      * @see #computeJacobianEccentricWrtCartesian()
820      */
821     protected abstract double[][] computeJacobianTrueWrtCartesian();
822 
823     /** Add the contribution of the Keplerian motion to parameters derivatives.
824      * <p>
825      * This method is used by integration-based propagators to evaluate the part of Keplerian
826      * motion to evolution of the orbital state.
827      * </p>
828      * @param type type of the position angle in the state
829      * @param gm attraction coefficient to use
830      * @param pDot array containing orbital state derivatives to update (the Keplerian
831      * part must be <em>added</em> to the array components, as the array may already
832      * contain some non-zero elements corresponding to non-Keplerian parts)
833      */
834     public abstract void addKeplerContribution(PositionAngleType type, double gm, double[] pDot);
835 
836         /** Fill a Jacobian half row with a single vector.
837      * @param a coefficient of the vector
838      * @param v vector
839      * @param row Jacobian matrix row
840      * @param j index of the first element to set (row[j], row[j+1] and row[j+2] will all be set)
841      */
842     protected static void fillHalfRow(final double a, final Vector3D v, final double[] row, final int j) {
843         row[j]     = a * v.getX();
844         row[j + 1] = a * v.getY();
845         row[j + 2] = a * v.getZ();
846     }
847 
848     /** Fill a Jacobian half row with a linear combination of vectors.
849      * @param a1 coefficient of the first vector
850      * @param v1 first vector
851      * @param a2 coefficient of the second vector
852      * @param v2 second vector
853      * @param row Jacobian matrix row
854      * @param j index of the first element to set (row[j], row[j+1] and row[j+2] will all be set)
855      */
856     protected static void fillHalfRow(final double a1, final Vector3D v1, final double a2, final Vector3D v2,
857                                       final double[] row, final int j) {
858         row[j]     = MathArrays.linearCombination(a1, v1.getX(), a2, v2.getX());
859         row[j + 1] = MathArrays.linearCombination(a1, v1.getY(), a2, v2.getY());
860         row[j + 2] = MathArrays.linearCombination(a1, v1.getZ(), a2, v2.getZ());
861     }
862 
863     /** Fill a Jacobian half row with a linear combination of vectors.
864      * @param a1 coefficient of the first vector
865      * @param v1 first vector
866      * @param a2 coefficient of the second vector
867      * @param v2 second vector
868      * @param a3 coefficient of the third vector
869      * @param v3 third vector
870      * @param row Jacobian matrix row
871      * @param j index of the first element to set (row[j], row[j+1] and row[j+2] will all be set)
872      */
873     protected static void fillHalfRow(final double a1, final Vector3D v1, final double a2, final Vector3D v2,
874                                       final double a3, final Vector3D v3,
875                                       final double[] row, final int j) {
876         row[j]     = MathArrays.linearCombination(a1, v1.getX(), a2, v2.getX(), a3, v3.getX());
877         row[j + 1] = MathArrays.linearCombination(a1, v1.getY(), a2, v2.getY(), a3, v3.getY());
878         row[j + 2] = MathArrays.linearCombination(a1, v1.getZ(), a2, v2.getZ(), a3, v3.getZ());
879     }
880 
881     /** Fill a Jacobian half row with a linear combination of vectors.
882      * @param a1 coefficient of the first vector
883      * @param v1 first vector
884      * @param a2 coefficient of the second vector
885      * @param v2 second vector
886      * @param a3 coefficient of the third vector
887      * @param v3 third vector
888      * @param a4 coefficient of the fourth vector
889      * @param v4 fourth vector
890      * @param row Jacobian matrix row
891      * @param j index of the first element to set (row[j], row[j+1] and row[j+2] will all be set)
892      */
893     protected static void fillHalfRow(final double a1, final Vector3D v1, final double a2, final Vector3D v2,
894                                       final double a3, final Vector3D v3, final double a4, final Vector3D v4,
895                                       final double[] row, final int j) {
896         row[j]     = MathArrays.linearCombination(a1, v1.getX(), a2, v2.getX(), a3, v3.getX(), a4, v4.getX());
897         row[j + 1] = MathArrays.linearCombination(a1, v1.getY(), a2, v2.getY(), a3, v3.getY(), a4, v4.getY());
898         row[j + 2] = MathArrays.linearCombination(a1, v1.getZ(), a2, v2.getZ(), a3, v3.getZ(), a4, v4.getZ());
899     }
900 
901     /** Fill a Jacobian half row with a linear combination of vectors.
902      * @param a1 coefficient of the first vector
903      * @param v1 first vector
904      * @param a2 coefficient of the second vector
905      * @param v2 second vector
906      * @param a3 coefficient of the third vector
907      * @param v3 third vector
908      * @param a4 coefficient of the fourth vector
909      * @param v4 fourth vector
910      * @param a5 coefficient of the fifth vector
911      * @param v5 fifth vector
912      * @param row Jacobian matrix row
913      * @param j index of the first element to set (row[j], row[j+1] and row[j+2] will all be set)
914      */
915     protected static void fillHalfRow(final double a1, final Vector3D v1, final double a2, final Vector3D v2,
916                                       final double a3, final Vector3D v3, final double a4, final Vector3D v4,
917                                       final double a5, final Vector3D v5,
918                                       final double[] row, final int j) {
919         final double[] a = new double[] {
920             a1, a2, a3, a4, a5
921         };
922         row[j]     = MathArrays.linearCombination(a, new double[] {
923             v1.getX(), v2.getX(), v3.getX(), v4.getX(), v5.getX()
924         });
925         row[j + 1] = MathArrays.linearCombination(a, new double[] {
926             v1.getY(), v2.getY(), v3.getY(), v4.getY(), v5.getY()
927         });
928         row[j + 2] = MathArrays.linearCombination(a, new double[] {
929             v1.getZ(), v2.getZ(), v3.getZ(), v4.getZ(), v5.getZ()
930         });
931     }
932 
933     /** Fill a Jacobian half row with a linear combination of vectors.
934      * @param a1 coefficient of the first vector
935      * @param v1 first vector
936      * @param a2 coefficient of the second vector
937      * @param v2 second vector
938      * @param a3 coefficient of the third vector
939      * @param v3 third vector
940      * @param a4 coefficient of the fourth vector
941      * @param v4 fourth vector
942      * @param a5 coefficient of the fifth vector
943      * @param v5 fifth vector
944      * @param a6 coefficient of the sixth vector
945      * @param v6 sixth vector
946      * @param row Jacobian matrix row
947      * @param j index of the first element to set (row[j], row[j+1] and row[j+2] will all be set)
948      */
949     protected static void fillHalfRow(final double a1, final Vector3D v1, final double a2, final Vector3D v2,
950                                       final double a3, final Vector3D v3, final double a4, final Vector3D v4,
951                                       final double a5, final Vector3D v5, final double a6, final Vector3D v6,
952                                       final double[] row, final int j) {
953         final double[] a = new double[] {
954             a1, a2, a3, a4, a5, a6
955         };
956         row[j]     = MathArrays.linearCombination(a, new double[] {
957             v1.getX(), v2.getX(), v3.getX(), v4.getX(), v5.getX(), v6.getX()
958         });
959         row[j + 1] = MathArrays.linearCombination(a, new double[] {
960             v1.getY(), v2.getY(), v3.getY(), v4.getY(), v5.getY(), v6.getY()
961         });
962         row[j + 2] = MathArrays.linearCombination(a, new double[] {
963             v1.getZ(), v2.getZ(), v3.getZ(), v4.getZ(), v5.getZ(), v6.getZ()
964         });
965     }
966 
967 }