Orbit.java

  1. /* Copyright 2002-2025 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;

  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.OrekitInternalError;
  29. import org.orekit.errors.OrekitMessages;
  30. import org.orekit.frames.Frame;
  31. import org.orekit.frames.StaticTransform;
  32. import org.orekit.frames.Transform;
  33. import org.orekit.time.AbsoluteDate;
  34. import org.orekit.time.TimeOffset;
  35. import org.orekit.time.TimeShiftable;
  36. import org.orekit.time.TimeStamped;
  37. import org.orekit.utils.PVCoordinates;
  38. import org.orekit.utils.PVCoordinatesProvider;
  39. import org.orekit.utils.TimeStampedPVCoordinates;

  41. /**
  42.  * This class handles orbital parameters.

  44.  * <p>
  45.  * For user convenience, both the Cartesian and the equinoctial elements
  46.  * are provided by this class, regardless of the canonical representation
  47.  * implemented in the derived class (which may be classical Keplerian
  48.  * elements for example).
  49.  * </p>
  50.  * <p>
  51.  * The parameters are defined in a frame specified by the user. It is important
  52.  * to make sure this frame is consistent: it probably is inertial and centered
  53.  * on the central body. This information is used for example by some
  54.  * force models.
  55.  * </p>
  56.  * <p>
  57.  * Instance of this class are guaranteed to be immutable.
  58.  * </p>
  59.  * @author Luc Maisonobe
  60.  * @author Guylaine Prat
  61.  * @author Fabien Maussion
  62.  * @author V&eacute;ronique Pommier-Maurussane
  63.  */
  64. public abstract class Orbit
  65.     implements TimeStamped, TimeShiftable<Orbit>, PVCoordinatesProvider {

  67.     /** Absolute tolerance when checking if the rate of the position angle is Keplerian or not. */
  68.     protected static final double TOLERANCE_POSITION_ANGLE_RATE = 1e-15;

  70.     /** Frame in which are defined the orbital parameters. */
  71.     private final Frame frame;

  73.     /** Date of the orbital parameters. */
  74.     private final AbsoluteDate date;

  76.     /** Value of mu used to compute position and velocity (m³/s²). */
  77.     private final double mu;

  79.     /** Computed position.
  80.      * @since 12.0
  81.      */
  82.     private Vector3D position;

  84.     /** Computed PVCoordinates. */
  85.     private TimeStampedPVCoordinates pvCoordinates;

  87.     /** Jacobian of the orbital parameters with mean angle with respect to the Cartesian coordinates. */
  88.     private double[][] jacobianMeanWrtCartesian;

  90.     /** Jacobian of the Cartesian coordinates with respect to the orbital parameters with mean angle. */
  91.     private double[][] jacobianWrtParametersMean;

  93.     /** Jacobian of the orbital parameters with eccentric angle with respect to the Cartesian coordinates. */
  94.     private double[][] jacobianEccentricWrtCartesian;

  96.     /** Jacobian of the Cartesian coordinates with respect to the orbital parameters with eccentric angle. */
  97.     private double[][] jacobianWrtParametersEccentric;

  99.     /** Jacobian of the orbital parameters with true angle with respect to the Cartesian coordinates. */
  100.     private double[][] jacobianTrueWrtCartesian;

  102.     /** Jacobian of the Cartesian coordinates with respect to the orbital parameters with true angle. */
  103.     private double[][] jacobianWrtParametersTrue;

  105.     /** Default constructor.
  106.      * Build a new instance with arbitrary default elements.
  107.      * @param frame the frame in which the parameters are defined
  108.      * (<em>must</em> be a {@link Frame#isPseudoInertial pseudo-inertial frame})
  109.      * @param date date of the orbital parameters
  110.      * @param mu central attraction coefficient (m^3/s^2)
  111.      * @exception IllegalArgumentException if frame is not a {@link
  112.      * Frame#isPseudoInertial pseudo-inertial frame}
  113.      */
  114.     protected Orbit(final Frame frame, final AbsoluteDate date, final double mu)
  115.         throws IllegalArgumentException {
  116.         ensurePseudoInertialFrame(frame);
  117.         this.date                      = date;
  118.         this.mu                        = mu;
  119.         this.pvCoordinates             = null;
  120.         this.frame                     = frame;
  121.         jacobianMeanWrtCartesian       = null;
  122.         jacobianWrtParametersMean      = null;
  123.         jacobianEccentricWrtCartesian  = null;
  124.         jacobianWrtParametersEccentric = null;
  125.         jacobianTrueWrtCartesian       = null;
  126.         jacobianWrtParametersTrue      = null;
  127.     }

  129.     /** Set the orbit from Cartesian parameters.
  130.      *
  131.      * <p> The acceleration provided in {@code pvCoordinates} is accessible using
  132.      * {@link #getPVCoordinates()} and {@link #getPVCoordinates(Frame)}. All other methods
  133.      * use {@code mu} and the position to compute the acceleration, including
  134.      * {@link #shiftedBy(double)} and {@link #getPVCoordinates(AbsoluteDate, Frame)}.
  135.      *
  136.      * @param pvCoordinates the position and velocity in the inertial frame
  137.      * @param frame the frame in which the {@link TimeStampedPVCoordinates} are defined
  138.      * (<em>must</em> be a {@link Frame#isPseudoInertial pseudo-inertial frame})
  139.      * @param mu central attraction coefficient (m^3/s^2)
  140.      * @exception IllegalArgumentException if frame is not a {@link
  141.      * Frame#isPseudoInertial pseudo-inertial frame}
  142.      */
  143.     protected Orbit(final TimeStampedPVCoordinates pvCoordinates, final Frame frame, final double mu)
  144.         throws IllegalArgumentException {
  145.         ensurePseudoInertialFrame(frame);
  146.         this.date = pvCoordinates.getDate();
  147.         this.mu = mu;
  148.         if (pvCoordinates.getAcceleration().getNormSq() == 0) {
  149.             // the acceleration was not provided,
  150.             // compute it from Newtonian attraction
  151.             final double r2 = pvCoordinates.getPosition().getNormSq();
  152.             final double r3 = r2 * FastMath.sqrt(r2);
  153.             this.pvCoordinates = new TimeStampedPVCoordinates(pvCoordinates.getDate(),
  154.                                                               pvCoordinates.getPosition(),
  155.                                                               pvCoordinates.getVelocity(),
  156.                                                               new Vector3D(-mu / r3, pvCoordinates.getPosition()));
  157.         } else {
  158.             this.pvCoordinates = pvCoordinates;
  159.         }
  160.         this.frame = frame;
  161.     }

  163.     /** Compute non-Keplerian part of the acceleration from first time derivatives.
  164.      * @return non-Keplerian part of the acceleration
  165.      * @since 13.1
  166.      */
  167.     protected Vector3D nonKeplerianAcceleration() {

  169.         final double[][] dPdC = new double[6][6];
  170.         final PositionAngleType positionAngleType = PositionAngleType.MEAN;
  171.         getJacobianWrtCartesian(positionAngleType, dPdC);
  172.         final RealMatrix subMatrix = MatrixUtils.createRealMatrix(dPdC);

  174.         final DecompositionSolver solver = getDecompositionSolver(subMatrix);

  176.         final double[] derivatives = new double[6];
  177.         getType().mapOrbitToArray(this, positionAngleType, new double[6], derivatives);
  178.         derivatives[5] -= getKeplerianMeanMotion();

  180.         final RealVector solution = solver.solve(MatrixUtils.createRealVector(derivatives));
  181.         return new Vector3D(solution.getEntry(3), solution.getEntry(4), solution.getEntry(5));

  183.     }

  185.     /** Check if Cartesian coordinates include non-Keplerian acceleration.
  186.      * @param pva Cartesian coordinates
  187.      * @param mu central attraction coefficient
  188.      * @return true if Cartesian coordinates include non-Keplerian acceleration
  189.      */
  190.     protected static boolean hasNonKeplerianAcceleration(final PVCoordinates pva, final double mu) {

  192.         final Vector3D a = pva.getAcceleration();
  193.         if (a == null) {
  194.             return false;
  195.         }

  197.         final Vector3D p = pva.getPosition();
  198.         final double r2 = p.getNormSq();

  200.         // Check if acceleration is relatively close to 0 compared to the Keplerian acceleration
  201.         final double tolerance = mu * 1e-9;
  202.         final Vector3D aTimesR2 = a.scalarMultiply(r2);
  203.         if (aTimesR2.getNorm() < tolerance) {
  204.             return false;
  205.         }

  207.         if ((aTimesR2.add(p.normalize().scalarMultiply(mu))).getNorm() > tolerance) {
  208.             // we have a relevant acceleration, we can compute derivatives
  209.             return true;
  210.         } else {
  211.             // the provided acceleration is either too small to be reliable (probably even 0), or NaN
  212.             return false;
  213.         }
  214.     }

  216.     /** Returns true if and only if the orbit is elliptical i.e. has a non-negative semi-major axis.
  217.      * @return true if getA() is strictly greater than 0
  218.      * @since 12.0
  219.      */
  220.     public boolean isElliptical() {
  221.         return getA() > 0.;
  222.     }

  224.     /** Get the orbit type.
  225.      * @return orbit type
  226.      */
  227.     public abstract OrbitType getType();

  229.     /** Ensure the defining frame is a pseudo-inertial frame.
  230.      * @param frame frame to check
  231.      * @exception IllegalArgumentException if frame is not a {@link
  232.      * Frame#isPseudoInertial pseudo-inertial frame}
  233.      */
  234.     private static void ensurePseudoInertialFrame(final Frame frame)
  235.         throws IllegalArgumentException {
  236.         if (!frame.isPseudoInertial()) {
  237.             throw new OrekitIllegalArgumentException(OrekitMessages.NON_PSEUDO_INERTIAL_FRAME,
  238.                                                      frame.getName());
  239.         }
  240.     }

  242.     /** Get the frame in which the orbital parameters are defined.
  243.      * @return frame in which the orbital parameters are defined
  244.      */
  245.     public Frame getFrame() {
  246.         return frame;
  247.     }

  249.     /** Get the semi-major axis.
  250.      * <p>Note that the semi-major axis is considered negative for hyperbolic orbits.</p>
  251.      * @return semi-major axis (m)
  252.      */
  253.     public abstract double getA();

  255.     /** Get the semi-major axis derivative.
  256.      * <p>Note that the semi-major axis is considered negative for hyperbolic orbits.</p>
  257.      * <p>
  258.      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
  259.      * </p>
  260.      * @return semi-major axis  derivative (m/s)
  261.      * @since 9.0
  262.      */
  263.     public abstract double getADot();

  265.     /** Get the first component of the equinoctial eccentricity vector.
  266.      * @return first component of the equinoctial eccentricity vector
  267.      */
  268.     public abstract double getEquinoctialEx();

  270.     /** Get the first component of the equinoctial eccentricity vector derivative.
  271.      * <p>
  272.      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
  273.      * </p>
  274.      * @return first component of the equinoctial eccentricity vector derivative
  275.      * @since 9.0
  276.      */
  277.     public abstract double getEquinoctialExDot();

  279.     /** Get the second component of the equinoctial eccentricity vector.
  280.      * @return second component of the equinoctial eccentricity vector
  281.      */
  282.     public abstract double getEquinoctialEy();

  284.     /** Get the second component of the equinoctial eccentricity vector derivative.
  285.      * <p>
  286.      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
  287.      * </p>
  288.      * @return second component of the equinoctial eccentricity vector derivative
  289.      * @since 9.0
  290.      */
  291.     public abstract double getEquinoctialEyDot();

  293.     /** Get the first component of the inclination vector.
  294.      * @return first component of the inclination vector
  295.      */
  296.     public abstract double getHx();

  298.     /** Get the first component of the inclination vector derivative.
  299.      * <p>
  300.      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
  301.      * </p>
  302.      * @return first component of the inclination vector derivative

  304.      * @since 9.0
  305.      */
  306.     public abstract double getHxDot();

  308.     /** Get the second component of the inclination vector.
  309.      * @return second component of the inclination vector
  310.      */
  311.     public abstract double getHy();

  313.     /** Get the second component of the inclination vector derivative.
  314.      * <p>
  315.      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
  316.      * </p>
  317.      * @return second component of the inclination vector derivative
  318.      * @since 9.0
  319.      */
  320.     public abstract double getHyDot();

  322.     /** Get the eccentric longitude argument.
  323.      * @return E + ω + Ω eccentric longitude argument (rad)
  324.      */
  325.     public abstract double getLE();

  327.     /** Get the eccentric longitude argument derivative.
  328.      * <p>
  329.      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
  330.      * </p>
  331.      * @return d(E + ω + Ω)/dt eccentric longitude argument derivative (rad/s)
  332.      * @since 9.0
  333.      */
  334.     public abstract double getLEDot();

  336.     /** Get the true longitude argument.
  337.      * @return v + ω + Ω true longitude argument (rad)
  338.      */
  339.     public abstract double getLv();

  341.     /** Get the true longitude argument derivative.
  342.      * <p>
  343.      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
  344.      * </p>
  345.      * @return d(v + ω + Ω)/dt true longitude argument derivative (rad/s)
  346.      * @since 9.0
  347.      */
  348.     public abstract double getLvDot();

  350.     /** Get the mean longitude argument.
  351.      * @return M + ω + Ω mean longitude argument (rad)
  352.      */
  353.     public abstract double getLM();

  355.     /** Get the mean longitude argument derivative.
  356.      * <p>
  357.      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
  358.      * </p>
  359.      * @return d(M + ω + Ω)/dt mean longitude argument derivative (rad/s)
  360.      * @since 9.0
  361.      */
  362.     public abstract double getLMDot();

  364.     // Additional orbital elements

  366.     /** Get the eccentricity.
  367.      * @return eccentricity
  368.      */
  369.     public abstract double getE();

  371.     /** Get the eccentricity derivative.
  372.      * <p>
  373.      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
  374.      * </p>
  375.      * @return eccentricity derivative
  376.      * @since 9.0
  377.      */
  378.     public abstract double getEDot();

  380.     /** Get the inclination.
  381.      * @return inclination (rad)
  382.      */
  383.     public abstract double getI();

  385.     /** Get the inclination derivative.
  386.      * <p>
  387.      * If the orbit was created without derivatives, the value returned is {@link Double#NaN}.
  388.      * </p>
  389.      * @return inclination derivative (rad/s)
  390.      * @since 9.0
  391.      */
  392.     public abstract double getIDot();

  394.     /** Check if orbit includes non-Keplerian rates.
  395.      * @return true if orbit includes non-Keplerian derivatives
  396.      * @see #getADot()
  397.      * @see #getEquinoctialExDot()
  398.      * @see #getEquinoctialEyDot()
  399.      * @see #getHxDot()
  400.      * @see #getHyDot()
  401.      * @see #getLEDot()
  402.      * @see #getLvDot()
  403.      * @see #getLMDot()
  404.      * @see #getEDot()
  405.      * @see #getIDot()
  406.      * @since 13.0
  407.      */
  408.     public boolean hasNonKeplerianAcceleration() {
  409.         return hasNonKeplerianAcceleration(getPVCoordinates(), getMu());
  410.     }

  412.     /** Get the central acceleration constant.
  413.      * @return central acceleration constant
  414.      */
  415.     public double getMu() {
  416.         return mu;
  417.     }

  419.     /** Get the Keplerian period.
  420.      * <p>The Keplerian period is computed directly from semi major axis
  421.      * and central acceleration constant.</p>
  422.      * @return Keplerian period in seconds, or positive infinity for hyperbolic orbits
  423.      */
  424.     public double getKeplerianPeriod() {
  425.         final double a = getA();
  426.         return isElliptical() ? 2.0 * FastMath.PI * a * FastMath.sqrt(a / mu) : Double.POSITIVE_INFINITY;
  427.     }

  429.     /** Get the Keplerian mean motion.
  430.      * <p>The Keplerian mean motion is computed directly from semi major axis
  431.      * and central acceleration constant.</p>
  432.      * @return Keplerian mean motion in radians per second
  433.      */
  434.     public double getKeplerianMeanMotion() {
  435.         final double absA = FastMath.abs(getA());
  436.         return FastMath.sqrt(mu / absA) / absA;
  437.     }

  439.     /** Get the derivative of the mean anomaly with respect to the semi major axis.
  440.      * @return derivative of the mean anomaly with respect to the semi major axis
  441.      */
  442.     public double getMeanAnomalyDotWrtA() {
  443.         return -1.5 * getKeplerianMeanMotion() / getA();
  444.     }

  446.     /** Get the date of orbital parameters.
  447.      * @return date of the orbital parameters
  448.      */
  449.     public AbsoluteDate getDate() {
  450.         return date;
  451.     }

  453.     /** Get the {@link TimeStampedPVCoordinates} in a specified frame.
  454.      * @param outputFrame frame in which the position/velocity coordinates shall be computed
  455.      * @return pvCoordinates in the specified output frame
  456.           * @see #getPVCoordinates()
  457.      */
  458.     public TimeStampedPVCoordinates getPVCoordinates(final Frame outputFrame) {
  459.         if (pvCoordinates == null) {
  460.             pvCoordinates = initPVCoordinates();
  461.         }

  463.         // If output frame requested is the same as definition frame,
  464.         // PV coordinates are returned directly
  465.         if (outputFrame == frame) {
  466.             return pvCoordinates;
  467.         }

  469.         // Else, PV coordinates are transformed to output frame
  470.         final Transform t = frame.getTransformTo(outputFrame, date);
  471.         return t.transformPVCoordinates(pvCoordinates);
  472.     }

  474.     /** {@inheritDoc} */
  475.     public TimeStampedPVCoordinates getPVCoordinates(final AbsoluteDate otherDate, final Frame otherFrame) {
  476.         return shiftedBy(otherDate.durationFrom(getDate())).getPVCoordinates(otherFrame);
  477.     }

  479.     /** {@inheritDoc} */
  480.     @Override
  481.     public Vector3D getPosition(final AbsoluteDate otherDate, final Frame otherFrame) {
  482.         return shiftedBy(otherDate.durationFrom(getDate())).getPosition(otherFrame);
  483.     }

  485.     /** Get the position in a specified frame.
  486.      * @param outputFrame frame in which the position coordinates shall be computed
  487.      * @return position in the specified output frame
  488.      * @see #getPosition()
  489.      * @since 12.0
  490.      */
  491.     public Vector3D getPosition(final Frame outputFrame) {
  492.         if (position == null) {
  493.             position = initPosition();
  494.         }

  496.         // If output frame requested is the same as definition frame,
  497.         // Position vector is returned directly
  498.         if (outputFrame == frame) {
  499.             return position;
  500.         }

  502.         // Else, position vector is transformed to output frame
  503.         final StaticTransform t = frame.getStaticTransformTo(outputFrame, date);
  504.         return t.transformPosition(position);

  506.     }

  508.     /** Get the position in definition frame.
  509.      * @return position in the definition frame
  510.      * @see #getPVCoordinates()
  511.      * @since 12.0
  512.      */
  513.     public Vector3D getPosition() {
  514.         if (position == null) {
  515.             position = initPosition();
  516.         }
  517.         return position;
  518.     }

  520.     /** Get the {@link TimeStampedPVCoordinates} in definition frame.
  521.      * @return pvCoordinates in the definition frame
  522.      * @see #getPVCoordinates(Frame)
  523.      */
  524.     public TimeStampedPVCoordinates getPVCoordinates() {
  525.         if (pvCoordinates == null) {
  526.             pvCoordinates = initPVCoordinates();
  527.             position      = pvCoordinates.getPosition();
  528.         }
  529.         return pvCoordinates;
  530.     }

  532.     /** Compute the position coordinates from the canonical parameters.
  533.      * @return computed position coordinates
  534.      * @since 12.0
  535.      */
  536.     protected abstract Vector3D initPosition();

  538.     /** Compute the position/velocity coordinates from the canonical parameters.
  539.      * @return computed position/velocity coordinates
  540.      */
  541.     protected abstract TimeStampedPVCoordinates initPVCoordinates();

  543.     /**
  544.      * Create a new object representing the same physical orbital state, but attached to a different reference frame.
  545.      * If the new frame is not inertial, an exception will be thrown.
  546.      *
  547.      * @param inertialFrame reference frame of output orbit
  548.      * @return orbit with different frame
  549.      * @since 13.0
  550.      */
  551.     public abstract Orbit inFrame(Frame inertialFrame);

  553.     /** Get a time-shifted orbit.
  554.      * <p>
  555.      * The orbit can be slightly shifted to close dates. The shifting model is a
  556.      * Keplerian one if no derivatives are available in the orbit, or Keplerian
  557.      * plus quadratic effect of the non-Keplerian acceleration if derivatives are
  558.      * available. Shifting is <em>not</em> intended as a replacement for proper
  559.      * orbit propagation but should be sufficient for small time shifts or coarse
  560.      * accuracy.
  561.      * </p>
  562.      * @param dt time shift in seconds
  563.      * @return a new orbit, shifted with respect to the instance (which is immutable)
  564.      */
  565.     @Override
  566.     public abstract Orbit shiftedBy(double dt);

  568.     /** Get a time-shifted orbit.
  569.      * <p>
  570.      * The orbit can be slightly shifted to close dates. The shifting model is a
  571.      * Keplerian one if no derivatives are available in the orbit, or Keplerian
  572.      * plus quadratic effect of the non-Keplerian acceleration if derivatives are
  573.      * available. Shifting is <em>not</em> intended as a replacement for proper
  574.      * orbit propagation but should be sufficient for small time shifts or coarse
  575.      * accuracy.
  576.      * </p>
  577.      * @param dt time shift
  578.      * @return a new orbit, shifted with respect to the instance (which is immutable)
  579.      */
  580.     @Override
  581.     public abstract Orbit shiftedBy(TimeOffset dt);

  583.     /** Compute the Jacobian of the orbital parameters with respect to the Cartesian parameters.
  584.      * <p>
  585.      * Element {@code jacobian[i][j]} is the derivative of parameter i of the orbit with
  586.      * respect to Cartesian coordinate j. This means each row corresponds to one orbital parameter
  587.      * whereas columns 0 to 5 correspond to the Cartesian coordinates x, y, z, xDot, yDot and zDot.
  588.      * </p>
  589.      * @param type type of the position angle to use
  590.      * @param jacobian placeholder 6x6 (or larger) matrix to be filled with the Jacobian, if matrix
  591.      * is larger than 6x6, only the 6x6 upper left corner will be modified
  592.      */
  593.     public void getJacobianWrtCartesian(final PositionAngleType type, final double[][] jacobian) {

  595.         final double[][] cachedJacobian;
  596.         synchronized (this) {
  597.             switch (type) {
  598.                 case MEAN :
  599.                     if (jacobianMeanWrtCartesian == null) {
  600.                         // first call, we need to compute the Jacobian and cache it
  601.                         jacobianMeanWrtCartesian = computeJacobianMeanWrtCartesian();
  602.                     }
  603.                     cachedJacobian = jacobianMeanWrtCartesian;
  604.                     break;
  605.                 case ECCENTRIC :
  606.                     if (jacobianEccentricWrtCartesian == null) {
  607.                         // first call, we need to compute the Jacobian and cache it
  608.                         jacobianEccentricWrtCartesian = computeJacobianEccentricWrtCartesian();
  609.                     }
  610.                     cachedJacobian = jacobianEccentricWrtCartesian;
  611.                     break;
  612.                 case TRUE :
  613.                     if (jacobianTrueWrtCartesian == null) {
  614.                         // first call, we need to compute the Jacobian and cache it
  615.                         jacobianTrueWrtCartesian = computeJacobianTrueWrtCartesian();
  616.                     }
  617.                     cachedJacobian = jacobianTrueWrtCartesian;
  618.                     break;
  619.                 default :
  620.                     throw new OrekitInternalError(null);
  621.             }
  622.         }

  624.         // fill the user provided array
  625.         for (int i = 0; i < cachedJacobian.length; ++i) {
  626.             System.arraycopy(cachedJacobian[i], 0, jacobian[i], 0, cachedJacobian[i].length);
  627.         }

  629.     }

  631.     /** Compute the Jacobian of the Cartesian parameters with respect to the orbital parameters.
  632.      * <p>
  633.      * Element {@code jacobian[i][j]} is the derivative of Cartesian coordinate i of the orbit with
  634.      * respect to orbital parameter j. This means each row corresponds to one Cartesian coordinate
  635.      * x, y, z, xdot, ydot, zdot whereas columns 0 to 5 correspond to the orbital parameters.
  636.      * </p>
  637.      * @param type type of the position angle to use
  638.      * @param jacobian placeholder 6x6 (or larger) matrix to be filled with the Jacobian, if matrix
  639.      * is larger than 6x6, only the 6x6 upper left corner will be modified
  640.      */
  641.     public void getJacobianWrtParameters(final PositionAngleType type, final double[][] jacobian) {

  643.         final double[][] cachedJacobian;
  644.         synchronized (this) {
  645.             switch (type) {
  646.                 case MEAN :
  647.                     if (jacobianWrtParametersMean == null) {
  648.                         // first call, we need to compute the Jacobian and cache it
  649.                         jacobianWrtParametersMean = createInverseJacobian(type);
  650.                     }
  651.                     cachedJacobian = jacobianWrtParametersMean;
  652.                     break;
  653.                 case ECCENTRIC :
  654.                     if (jacobianWrtParametersEccentric == null) {
  655.                         // first call, we need to compute the Jacobian and cache it
  656.                         jacobianWrtParametersEccentric = createInverseJacobian(type);
  657.                     }
  658.                     cachedJacobian = jacobianWrtParametersEccentric;
  659.                     break;
  660.                 case TRUE :
  661.                     if (jacobianWrtParametersTrue == null) {
  662.                         // first call, we need to compute the Jacobian and cache it
  663.                         jacobianWrtParametersTrue = createInverseJacobian(type);
  664.                     }
  665.                     cachedJacobian = jacobianWrtParametersTrue;
  666.                     break;
  667.                 default :
  668.                     throw new OrekitInternalError(null);
  669.             }
  670.         }

  672.         // fill the user-provided array
  673.         for (int i = 0; i < cachedJacobian.length; ++i) {
  674.             System.arraycopy(cachedJacobian[i], 0, jacobian[i], 0, cachedJacobian[i].length);
  675.         }

  677.     }

  679.     /** Create an inverse Jacobian.
  680.      * @param type type of the position angle to use
  681.      * @return inverse Jacobian
  682.      */
  683.     private double[][] createInverseJacobian(final PositionAngleType type) {

  685.         // get the direct Jacobian
  686.         final double[][] directJacobian = new double[6][6];
  687.         getJacobianWrtCartesian(type, directJacobian);

  689.         // invert the direct Jacobian
  690.         final RealMatrix matrix = MatrixUtils.createRealMatrix(directJacobian);
  691.         final DecompositionSolver solver = getDecompositionSolver(matrix);
  692.         return solver.getInverse().getData();

  694.     }

  696.     /**
  697.      * Method to build a matrix decomposition solver.
  698.      * @param realMatrix matrix
  699.      * @return solver
  700.      * @since 13.1
  701.      */
  702.     protected DecompositionSolver getDecompositionSolver(final RealMatrix realMatrix) {
  703.         return new QRDecomposition(realMatrix).getSolver();
  704.     }

  706.     /** Compute the Jacobian of the orbital parameters with mean angle with respect to the Cartesian parameters.
  707.      * <p>
  708.      * Element {@code jacobian[i][j]} is the derivative of parameter i of the orbit with
  709.      * respect to Cartesian coordinate j. This means each row correspond to one orbital parameter
  710.      * whereas columns 0 to 5 correspond to the Cartesian coordinates x, y, z, xDot, yDot and zDot.
  711.      * </p>
  712.      * <p>
  713.      * The array returned by this method will not be modified.
  714.      * </p>
  715.      * @return 6x6 Jacobian matrix
  716.      * @see #computeJacobianEccentricWrtCartesian()
  717.      * @see #computeJacobianTrueWrtCartesian()
  718.      */
  719.     protected abstract double[][] computeJacobianMeanWrtCartesian();

  721.     /** Compute the Jacobian of the orbital parameters with eccentric angle with respect to the Cartesian parameters.
  722.      * <p>
  723.      * Element {@code jacobian[i][j]} is the derivative of parameter i of the orbit with
  724.      * respect to Cartesian coordinate j. This means each row correspond to one orbital parameter
  725.      * whereas columns 0 to 5 correspond to the Cartesian coordinates x, y, z, xDot, yDot and zDot.
  726.      * </p>
  727.      * <p>
  728.      * The array returned by this method will not be modified.
  729.      * </p>
  730.      * @return 6x6 Jacobian matrix
  731.      * @see #computeJacobianMeanWrtCartesian()
  732.      * @see #computeJacobianTrueWrtCartesian()
  733.      */
  734.     protected abstract double[][] computeJacobianEccentricWrtCartesian();

  736.     /** Compute the Jacobian of the orbital parameters with true angle with respect to the Cartesian parameters.
  737.      * <p>
  738.      * Element {@code jacobian[i][j]} is the derivative of parameter i of the orbit with
  739.      * respect to Cartesian coordinate j. This means each row correspond to one orbital parameter
  740.      * whereas columns 0 to 5 correspond to the Cartesian coordinates x, y, z, xDot, yDot and zDot.
  741.      * </p>
  742.      * <p>
  743.      * The array returned by this method will not be modified.
  744.      * </p>
  745.      * @return 6x6 Jacobian matrix
  746.      * @see #computeJacobianMeanWrtCartesian()
  747.      * @see #computeJacobianEccentricWrtCartesian()
  748.      */
  749.     protected abstract double[][] computeJacobianTrueWrtCartesian();

  751.     /** Add the contribution of the Keplerian motion to parameters derivatives
  752.      * <p>
  753.      * This method is used by integration-based propagators to evaluate the part of Keplerian
  754.      * motion to evolution of the orbital state.
  755.      * </p>
  756.      * @param type type of the position angle in the state
  757.      * @param gm attraction coefficient to use
  758.      * @param pDot array containing orbital state derivatives to update (the Keplerian
  759.      * part must be <em>added</em> to the array components, as the array may already
  760.      * contain some non-zero elements corresponding to non-Keplerian parts)
  761.      */
  762.     public abstract void addKeplerContribution(PositionAngleType type, double gm, double[] pDot);

  764.         /** Fill a Jacobian half row with a single vector.
  765.      * @param a coefficient of the vector
  766.      * @param v vector
  767.      * @param row Jacobian matrix row
  768.      * @param j index of the first element to set (row[j], row[j+1] and row[j+2] will all be set)
  769.      */
  770.     protected static void fillHalfRow(final double a, final Vector3D v, final double[] row, final int j) {
  771.         row[j]     = a * v.getX();
  772.         row[j + 1] = a * v.getY();
  773.         row[j + 2] = a * v.getZ();
  774.     }

  776.     /** Fill a Jacobian half row with a linear combination of vectors.
  777.      * @param a1 coefficient of the first vector
  778.      * @param v1 first vector
  779.      * @param a2 coefficient of the second vector
  780.      * @param v2 second vector
  781.      * @param row Jacobian matrix row
  782.      * @param j index of the first element to set (row[j], row[j+1] and row[j+2] will all be set)
  783.      */
  784.     protected static void fillHalfRow(final double a1, final Vector3D v1, final double a2, final Vector3D v2,
  785.                                       final double[] row, final int j) {
  786.         row[j]     = MathArrays.linearCombination(a1, v1.getX(), a2, v2.getX());
  787.         row[j + 1] = MathArrays.linearCombination(a1, v1.getY(), a2, v2.getY());
  788.         row[j + 2] = MathArrays.linearCombination(a1, v1.getZ(), a2, v2.getZ());
  789.     }

  791.     /** Fill a Jacobian half row with a linear combination of vectors.
  792.      * @param a1 coefficient of the first vector
  793.      * @param v1 first vector
  794.      * @param a2 coefficient of the second vector
  795.      * @param v2 second vector
  796.      * @param a3 coefficient of the third vector
  797.      * @param v3 third vector
  798.      * @param row Jacobian matrix row
  799.      * @param j index of the first element to set (row[j], row[j+1] and row[j+2] will all be set)
  800.      */
  801.     protected static void fillHalfRow(final double a1, final Vector3D v1, final double a2, final Vector3D v2,
  802.                                       final double a3, final Vector3D v3,
  803.                                       final double[] row, final int j) {
  804.         row[j]     = MathArrays.linearCombination(a1, v1.getX(), a2, v2.getX(), a3, v3.getX());
  805.         row[j + 1] = MathArrays.linearCombination(a1, v1.getY(), a2, v2.getY(), a3, v3.getY());
  806.         row[j + 2] = MathArrays.linearCombination(a1, v1.getZ(), a2, v2.getZ(), a3, v3.getZ());
  807.     }

  809.     /** Fill a Jacobian half row with a linear combination of vectors.
  810.      * @param a1 coefficient of the first vector
  811.      * @param v1 first vector
  812.      * @param a2 coefficient of the second vector
  813.      * @param v2 second vector
  814.      * @param a3 coefficient of the third vector
  815.      * @param v3 third vector
  816.      * @param a4 coefficient of the fourth vector
  817.      * @param v4 fourth vector
  818.      * @param row Jacobian matrix row
  819.      * @param j index of the first element to set (row[j], row[j+1] and row[j+2] will all be set)
  820.      */
  821.     protected static void fillHalfRow(final double a1, final Vector3D v1, final double a2, final Vector3D v2,
  822.                                       final double a3, final Vector3D v3, final double a4, final Vector3D v4,
  823.                                       final double[] row, final int j) {
  824.         row[j]     = MathArrays.linearCombination(a1, v1.getX(), a2, v2.getX(), a3, v3.getX(), a4, v4.getX());
  825.         row[j + 1] = MathArrays.linearCombination(a1, v1.getY(), a2, v2.getY(), a3, v3.getY(), a4, v4.getY());
  826.         row[j + 2] = MathArrays.linearCombination(a1, v1.getZ(), a2, v2.getZ(), a3, v3.getZ(), a4, v4.getZ());
  827.     }

  829.     /** Fill a Jacobian half row with a linear combination of vectors.
  830.      * @param a1 coefficient of the first vector
  831.      * @param v1 first vector
  832.      * @param a2 coefficient of the second vector
  833.      * @param v2 second vector
  834.      * @param a3 coefficient of the third vector
  835.      * @param v3 third vector
  836.      * @param a4 coefficient of the fourth vector
  837.      * @param v4 fourth vector
  838.      * @param a5 coefficient of the fifth vector
  839.      * @param v5 fifth vector
  840.      * @param row Jacobian matrix row
  841.      * @param j index of the first element to set (row[j], row[j+1] and row[j+2] will all be set)
  842.      */
  843.     protected static void fillHalfRow(final double a1, final Vector3D v1, final double a2, final Vector3D v2,
  844.                                       final double a3, final Vector3D v3, final double a4, final Vector3D v4,
  845.                                       final double a5, final Vector3D v5,
  846.                                       final double[] row, final int j) {
  847.         final double[] a = new double[] {
  848.             a1, a2, a3, a4, a5
  849.         };
  850.         row[j]     = MathArrays.linearCombination(a, new double[] {
  851.             v1.getX(), v2.getX(), v3.getX(), v4.getX(), v5.getX()
  852.         });
  853.         row[j + 1] = MathArrays.linearCombination(a, new double[] {
  854.             v1.getY(), v2.getY(), v3.getY(), v4.getY(), v5.getY()
  855.         });
  856.         row[j + 2] = MathArrays.linearCombination(a, new double[] {
  857.             v1.getZ(), v2.getZ(), v3.getZ(), v4.getZ(), v5.getZ()
  858.         });
  859.     }

  861.     /** Fill a Jacobian half row with a linear combination of vectors.
  862.      * @param a1 coefficient of the first vector
  863.      * @param v1 first vector
  864.      * @param a2 coefficient of the second vector
  865.      * @param v2 second vector
  866.      * @param a3 coefficient of the third vector
  867.      * @param v3 third vector
  868.      * @param a4 coefficient of the fourth vector
  869.      * @param v4 fourth vector
  870.      * @param a5 coefficient of the fifth vector
  871.      * @param v5 fifth vector
  872.      * @param a6 coefficient of the sixth vector
  873.      * @param v6 sixth vector
  874.      * @param row Jacobian matrix row
  875.      * @param j index of the first element to set (row[j], row[j+1] and row[j+2] will all be set)
  876.      */
  877.     protected static void fillHalfRow(final double a1, final Vector3D v1, final double a2, final Vector3D v2,
  878.                                       final double a3, final Vector3D v3, final double a4, final Vector3D v4,
  879.                                       final double a5, final Vector3D v5, final double a6, final Vector3D v6,
  880.                                       final double[] row, final int j) {
  881.         final double[] a = new double[] {
  882.             a1, a2, a3, a4, a5, a6
  883.         };
  884.         row[j]     = MathArrays.linearCombination(a, new double[] {
  885.             v1.getX(), v2.getX(), v3.getX(), v4.getX(), v5.getX(), v6.getX()
  886.         });
  887.         row[j + 1] = MathArrays.linearCombination(a, new double[] {
  888.             v1.getY(), v2.getY(), v3.getY(), v4.getY(), v5.getY(), v6.getY()
  889.         });
  890.         row[j + 2] = MathArrays.linearCombination(a, new double[] {
  891.             v1.getZ(), v2.getZ(), v3.getZ(), v4.getZ(), v5.getZ(), v6.getZ()
  892.         });
  893.     }

  895. }
Created with JaCoCo 0.8.12.202403310830