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é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 }