AbstractShortTermEncounter1DNumerical2DPOCMethod.java

  1. /* Copyright 2002-2024 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.ssa.collision.shorttermencounter.probability.twod;

  18. import org.hipparchus.CalculusFieldElement;
  19. import org.hipparchus.Field;
  20. import org.hipparchus.analysis.integration.FieldTrapezoidIntegrator;
  21. import org.hipparchus.analysis.integration.FieldUnivariateIntegrator;
  22. import org.hipparchus.analysis.integration.UnivariateIntegrator;
  23. import org.hipparchus.geometry.euclidean.twod.FieldVector2D;
  24. import org.hipparchus.geometry.euclidean.twod.Vector2D;
  25. import org.hipparchus.linear.FieldMatrix;
  26. import org.hipparchus.linear.RealMatrix;
  27. import org.hipparchus.util.FastMath;
  28. import org.orekit.data.DataContext;
  29. import org.orekit.files.ccsds.ndm.cdm.Cdm;
  30. import org.orekit.files.ccsds.ndm.cdm.CdmData;
  31. import org.orekit.files.ccsds.ndm.cdm.CdmMetadata;
  32. import org.orekit.files.ccsds.ndm.cdm.CdmRelativeMetadata;
  33. import org.orekit.frames.encounter.EncounterLOFType;
  34. import org.orekit.orbits.FieldOrbit;
  35. import org.orekit.orbits.Orbit;
  36. import org.orekit.propagation.FieldStateCovariance;
  37. import org.orekit.propagation.StateCovariance;
  38. import org.orekit.ssa.metrics.FieldProbabilityOfCollision;
  39. import org.orekit.ssa.metrics.ProbabilityOfCollision;
  40. import org.orekit.utils.Fieldifier;

  41. /**
  42.  * This abstract class serves as a foundation to create 1D numerical 2D probability of collision computing method.
  43.  *
  44.  * @author Vincent Cucchietti
  45.  * @since 12.0
  46.  */
  47. public abstract class AbstractShortTermEncounter1DNumerical2DPOCMethod
  48.         extends AbstractShortTermEncounter2DPOCMethod {

  49.     /** Default univariate function numerical integrator. */
  50.     private final UnivariateIntegrator integrator;

  51.     /** Default maximum number of function evaluation when integrating. */
  52.     private final int maxNbOfEval;

  53.     /**
  54.      * Customizable constructor.
  55.      *
  56.      * @param name name of the method
  57.      * @param integrator integrator
  58.      * @param maxNbOfEval max number of evaluation
  59.      */
  60.     protected AbstractShortTermEncounter1DNumerical2DPOCMethod(final String name,
  61.                                                                final UnivariateIntegrator integrator,
  62.                                                                final int maxNbOfEval) {
  63.         super(name);

  64.         this.integrator  = integrator;
  65.         this.maxNbOfEval = maxNbOfEval;
  66.     }

  67.     /**
  68.      * Compute the probability of collision using an {@link Cdm Orekit Conjunction Data Message}.
  69.      *
  70.      * @param cdm conjunction data message input
  71.      * @param primaryRadius primary collision object equivalent sphere radius (m)
  72.      * @param secondaryRadius secondary collision object equivalent sphere radius (m)
  73.      * @param customIntegrator different univariate function numerical integrator than the one defined in the instance
  74.      * @param customMaxNbOfEval different maximum number of function evaluation when integrating than the one defined in the
  75.      * instance
  76.      * @param zeroThreshold threshold below which values are considered equal to zero
  77.      *
  78.      * @return probability of collision
  79.      */
  80.     public ProbabilityOfCollision compute(final Cdm cdm, final double primaryRadius, final double secondaryRadius,
  81.                                           final UnivariateIntegrator customIntegrator, final int customMaxNbOfEval,
  82.                                           final double zeroThreshold) {

  83.         final CdmRelativeMetadata cdmRelativeMetadata = cdm.getRelativeMetadata();
  84.         final CdmData             primaryData         = cdm.getDataObject1();
  85.         final CdmData             secondaryData       = cdm.getDataObject2();
  86.         final DataContext         cdmDataContext      = cdm.getDataContext();

  87.         // Extract primary data
  88.         final Orbit primaryOrbit =
  89.                 getObjectOrbitFromCdm(cdmRelativeMetadata, primaryData, cdm.getMetadataObject1(), cdmDataContext);
  90.         final StateCovariance primaryCovariance = getObjectStateCovarianceFromCdm(cdmRelativeMetadata, primaryData);

  91.         // Extract secondary data
  92.         final Orbit secondaryOrbit =
  93.                 getObjectOrbitFromCdm(cdmRelativeMetadata, secondaryData, cdm.getMetadataObject2(), cdmDataContext);
  94.         final StateCovariance secondaryCovariance = getObjectStateCovarianceFromCdm(cdmRelativeMetadata, secondaryData);

  95.         return compute(primaryOrbit, primaryCovariance, primaryRadius,
  96.                        secondaryOrbit, secondaryCovariance, secondaryRadius,
  97.                        customIntegrator, customMaxNbOfEval, zeroThreshold);
  98.     }

  99.     /**
  100.      * Compute the probability of collision using an {@link Cdm Orekit Conjunction Data Message}.
  101.      *
  102.      * @param cdm conjunction data message
  103.      * @param primaryRadius primary collision object equivalent sphere radius (m)
  104.      * @param secondaryRadius secondary collision object equivalent sphere radius (m)
  105.      * @param zeroThreshold threshold below which values are considered equal to zero
  106.      * @param customIntegrator different univariate function numerical integrator than the one defined in the instance
  107.      * @param customMaxNbOfEval different maximum number of function evaluation when integrating than the one defined in the
  108.      * instance
  109.      * @param <T> type of the field elements
  110.      *
  111.      * @return probability of collision
  112.      */
  113.     public <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(final Cdm cdm,
  114.                                                                                       final T primaryRadius,
  115.                                                                                       final T secondaryRadius,
  116.                                                                                       final FieldUnivariateIntegrator<T> customIntegrator,
  117.                                                                                       final int customMaxNbOfEval,
  118.                                                                                       final double zeroThreshold) {

  119.         final Field<T>            field               = primaryRadius.getField();
  120.         final CdmRelativeMetadata cdmRelativeMetadata = cdm.getRelativeMetadata();
  121.         final CdmData             primaryData         = cdm.getDataObject1();
  122.         final CdmData             secondaryData       = cdm.getDataObject2();
  123.         final CdmMetadata         primaryMetadata     = cdm.getMetadataObject1();
  124.         final CdmMetadata         secondaryMetadata   = cdm.getMetadataObject2();
  125.         final DataContext         cdmDataContext      = cdm.getDataContext();

  126.         // Extract primary data
  127.         final Orbit primaryOrbitFromCdm = getObjectOrbitFromCdm(cdmRelativeMetadata, primaryData,
  128.                 primaryMetadata, cdmDataContext);
  129.         final FieldOrbit<T> primaryOrbit = primaryOrbitFromCdm.getType().convertToFieldOrbit(field,
  130.                 primaryOrbitFromCdm);
  131.         final FieldStateCovariance<T> primaryCovariance =
  132.                 Fieldifier.fieldify(field, getObjectStateCovarianceFromCdm(cdmRelativeMetadata, primaryData));

  133.         // Extract secondary data
  134.         final Orbit secondaryOrbitFromCdm = getObjectOrbitFromCdm(cdmRelativeMetadata, secondaryData,
  135.                 secondaryMetadata, cdmDataContext);
  136.         final FieldOrbit<T> secondaryOrbit = secondaryOrbitFromCdm.getType().convertToFieldOrbit(field,
  137.                 secondaryOrbitFromCdm);
  138.         final FieldStateCovariance<T> secondaryCovariance =
  139.                 Fieldifier.fieldify(field, getObjectStateCovarianceFromCdm(cdmRelativeMetadata, secondaryData));

  140.         return compute(primaryOrbit, primaryCovariance, primaryRadius,
  141.                        secondaryOrbit, secondaryCovariance, secondaryRadius,
  142.                        customIntegrator, customMaxNbOfEval, zeroThreshold);
  143.     }

  144.     /**
  145.      * Compute the probability of collision using parameters necessary for creating a
  146.      * {@link ShortTermEncounter2DDefinition collision definition} instance.
  147.      *
  148.      * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
  149.      * @param primaryCovariance primary collision object covariance
  150.      * @param primaryRadius primary collision object equivalent sphere radius (m)
  151.      * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
  152.      * @param secondaryCovariance secondary collision object covariance
  153.      * @param secondaryRadius secondary collision object equivalent sphere radius (m)
  154.      * @param customIntegrator different univariate function numerical integrator than the one defined in the instance
  155.      * @param customMaxNbOfEval different maximum number of function evaluation when integrating than the one defined in the
  156.      * instance
  157.      * @param zeroThreshold threshold below which values are considered equal to zero
  158.      *
  159.      * @return probability of collision
  160.      */
  161.     public ProbabilityOfCollision compute(final Orbit primaryAtTCA,
  162.                                           final StateCovariance primaryCovariance,
  163.                                           final double primaryRadius,
  164.                                           final Orbit secondaryAtTCA,
  165.                                           final StateCovariance secondaryCovariance,
  166.                                           final double secondaryRadius,
  167.                                           final UnivariateIntegrator customIntegrator,
  168.                                           final int customMaxNbOfEval,
  169.                                           final double zeroThreshold) {

  170.         final ShortTermEncounter2DDefinition encounterDefinition = new ShortTermEncounter2DDefinition(
  171.                 primaryAtTCA, primaryCovariance, primaryRadius,
  172.                 secondaryAtTCA, secondaryCovariance, secondaryRadius,
  173.                 EncounterLOFType.DEFAULT, DEFAULT_TCA_DIFFERENCE_TOLERANCE);

  174.         return compute(encounterDefinition, customIntegrator, customMaxNbOfEval, zeroThreshold);
  175.     }

  176.     /**
  177.      * Compute the probability of collision using parameters necessary for creating a
  178.      * {@link ShortTermEncounter2DDefinition collision definition} instance.
  179.      *
  180.      * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
  181.      * @param primaryCovariance primary collision object covariance
  182.      * @param primaryRadius primary collision object equivalent sphere radius (m)
  183.      * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
  184.      * @param secondaryCovariance secondary collision object covariance
  185.      * @param secondaryRadius secondary collision object equivalent sphere radius (m)
  186.      * @param customIntegrator different univariate function numerical integrator than the one defined in the instance
  187.      * @param customMaxNbOfEval different maximum number of function evaluation when integrating than the one defined in the
  188.      * instance
  189.      * @param zeroThreshold threshold below which values are considered equal to zero
  190.      * @param <T> type of the field elements
  191.      *
  192.      * @return probability of collision
  193.      */
  194.     public <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(
  195.             final FieldOrbit<T> primaryAtTCA,
  196.             final FieldStateCovariance<T> primaryCovariance,
  197.             final T primaryRadius,
  198.             final FieldOrbit<T> secondaryAtTCA,
  199.             final FieldStateCovariance<T> secondaryCovariance,
  200.             final T secondaryRadius,
  201.             final FieldUnivariateIntegrator<T> customIntegrator,
  202.             final int customMaxNbOfEval,
  203.             final double zeroThreshold) {

  204.         final FieldShortTermEncounter2DDefinition<T> encounterDefinition =
  205.                 new FieldShortTermEncounter2DDefinition<>(
  206.                         primaryAtTCA, primaryCovariance, primaryRadius,
  207.                         secondaryAtTCA, secondaryCovariance, secondaryRadius,
  208.                         EncounterLOFType.DEFAULT, DEFAULT_TCA_DIFFERENCE_TOLERANCE);

  209.         return compute(encounterDefinition, customIntegrator, customMaxNbOfEval, zeroThreshold);
  210.     }

  211.     /**
  212.      * Compute the probability of collision using a given collision definition.
  213.      *
  214.      * @param encounterDefinition probabilityOfCollision definition between a primary and a secondary collision object
  215.      * @param customIntegrator different univariate function numerical integrator than the one defined in the instance
  216.      * @param customMaxNbOfEval different maximum number of function evaluation when integrating than the one defined in the
  217.      * instance
  218.      * @param zeroThreshold threshold below which values are considered equal to zero
  219.      *
  220.      * @return probability of collision
  221.      */
  222.     public ProbabilityOfCollision compute(final ShortTermEncounter2DDefinition encounterDefinition,
  223.                                           final UnivariateIntegrator customIntegrator,
  224.                                           final int customMaxNbOfEval,
  225.                                           final double zeroThreshold) {

  226.         final Vector2D otherPositionAfterRotationInCollisionPlane =
  227.                 encounterDefinition.computeOtherPositionInRotatedCollisionPlane(zeroThreshold);

  228.         final RealMatrix projectedDiagonalizedCombinedPositionalCovarianceMatrix =
  229.                 encounterDefinition.computeProjectedAndDiagonalizedCombinedPositionalCovarianceMatrix();

  230.         return compute(otherPositionAfterRotationInCollisionPlane.getX(),
  231.                        otherPositionAfterRotationInCollisionPlane.getY(),
  232.                        FastMath.sqrt(projectedDiagonalizedCombinedPositionalCovarianceMatrix.getEntry(0, 0)),
  233.                        FastMath.sqrt(projectedDiagonalizedCombinedPositionalCovarianceMatrix.getEntry(1, 1)),
  234.                        encounterDefinition.getCombinedRadius(),
  235.                        customIntegrator,
  236.                        customMaxNbOfEval);
  237.     }

  238.     /**
  239.      * Compute the probability of collision using given collision definition.
  240.      *
  241.      * @param encounterDefinition encounter definition between a primary and a secondary collision object
  242.      * @param customIntegrator custom integrator to use in place of the integrator from the constructor
  243.      * @param customMaxNbOfEval custom maximum number of evaluations to use in place of the custom maximum number from the
  244.      * @param zeroThreshold threshold below which values are considered equal to zero
  245.      * @param <T> type of the field element
  246.      *
  247.      * @return probability of collision
  248.      */
  249.     public <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(
  250.             final FieldShortTermEncounter2DDefinition<T> encounterDefinition,
  251.             final FieldUnivariateIntegrator<T> customIntegrator,
  252.             final int customMaxNbOfEval,
  253.             final double zeroThreshold) {

  254.         final FieldVector2D<T> otherPositionAfterRotationInCollisionPlane =
  255.                 encounterDefinition.computeOtherPositionInRotatedCollisionPlane(zeroThreshold);

  256.         final FieldMatrix<T> projectedDiagonalizedCombinedPositionalCovarianceMatrix =
  257.                 encounterDefinition.computeProjectedAndDiagonalizedCombinedPositionalCovarianceMatrix();

  258.         return compute(otherPositionAfterRotationInCollisionPlane.getX(),
  259.                        otherPositionAfterRotationInCollisionPlane.getY(),
  260.                        projectedDiagonalizedCombinedPositionalCovarianceMatrix.getEntry(0, 0).sqrt(),
  261.                        projectedDiagonalizedCombinedPositionalCovarianceMatrix.getEntry(1, 1).sqrt(),
  262.                        encounterDefinition.getCombinedRadius(),
  263.                        customIntegrator,
  264.                        customMaxNbOfEval);
  265.     }

  266.     /**
  267.      * {@inheritDoc}
  268.      * <p>
  269.      * It uses the defaults integrator and maximum number of function evaluation when integrating.
  270.      */
  271.     public ProbabilityOfCollision compute(final double xm, final double ym, final double sigmaX, final double sigmaY,
  272.                                           final double radius) {
  273.         return compute(xm, ym, sigmaX, sigmaY, radius, integrator, maxNbOfEval);
  274.     }

  275.     /**
  276.      * Compute the probability of collision using arguments specific to the rotated encounter frame.
  277.      * <p>
  278.      * The rotated encounter frame is define by the initial encounter frame (defined in
  279.      * {@link ShortTermEncounter2DDefinition}) rotated by the rotation matrix which is used to diagonalize the combined
  280.      * covariance matrix.
  281.      * </p>
  282.      *
  283.      * @param xm other collision object projected position onto the collision plane in the rotated encounter frame x-axis
  284.      * (m)
  285.      * @param ym other collision object projected position onto the collision plane in the rotated encounter frame y-axis
  286.      * (m)
  287.      * @param sigmaX square root of the x-axis eigen value of the diagonalized combined covariance matrix projected onto the
  288.      * collision plane (m)
  289.      * @param sigmaY square root of the y-axis eigen value of the diagonalized combined covariance matrix projected onto the
  290.      * collision plane (m)
  291.      * @param radius sum of primary and secondary collision object equivalent sphere radii (m)
  292.      * @param <T> type of the field elements
  293.      *
  294.      * @return probability of collision
  295.      */
  296.     public <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(final T xm, final T ym,
  297.                                                                                       final T sigmaX, final T sigmaY,
  298.                                                                                       final T radius) {
  299.         return compute(xm, ym, sigmaX, sigmaY, radius, new FieldTrapezoidIntegrator<>(xm.getField()),
  300.                        maxNbOfEval);
  301.     }

  302.     /**
  303.      * Compute the probability of collision using arguments specific to the rotated encounter frame and custom numerical
  304.      * configuration.
  305.      * <p>
  306.      * The rotated encounter frame is define by the initial encounter frame (defined in
  307.      * {@link ShortTermEncounter2DDefinition}) rotated by the rotation matrix which is used to diagonalize the combined
  308.      * covariance matrix.
  309.      * </p>
  310.      *
  311.      * @param xm other collision object projected position onto the collision plane in the rotated encounter frame x-axis
  312.      * (m)
  313.      * @param ym other collision object projected position onto the collision plane in the rotated encounter frame y-axis
  314.      * (m)
  315.      * @param sigmaX square root of the x-axis eigen value of the diagonalized combined covariance matrix projected onto the
  316.      * collision plane (m)
  317.      * @param sigmaY square root of the y-axis eigen value of the diagonalized combined covariance matrix projected onto the
  318.      * collision plane (m)
  319.      * @param radius sum of primary and secondary collision object equivalent sphere radii (m)
  320.      * @param customIntegrator custom integrator to use in place of the integrator from the constructor
  321.      * @param customMaxNbOfEval custom maximum number of evaluations to use in place of the custom maximum number from the
  322.      * constructor
  323.      *
  324.      * @return probability of collision
  325.      */
  326.     public abstract ProbabilityOfCollision compute(double xm, double ym, double sigmaX, double sigmaY, double radius,
  327.                                                    UnivariateIntegrator customIntegrator, int customMaxNbOfEval);

  328.     /**
  329.      * Compute the probability of collision using arguments specific to the rotated encounter frame and custom numerical
  330.      * configuration.
  331.      * <p>
  332.      * The rotated encounter frame is define by the initial encounter frame (defined in
  333.      * {@link ShortTermEncounter2DDefinition}) rotated by the rotation matrix which is used to diagonalize the combined
  334.      * covariance matrix.
  335.      * </p>
  336.      *
  337.      * @param xm other collision object projected position onto the collision plane in the rotated encounter frame x-axis
  338.      * (m)
  339.      * @param ym other collision object projected position onto the collision plane in the rotated encounter frame y-axis
  340.      * (m)
  341.      * @param sigmaX square root of the x-axis eigen value of the diagonalized combined covariance matrix projected onto the
  342.      * collision plane (m)
  343.      * @param sigmaY square root of the y-axis eigen value of the diagonalized combined covariance matrix projected onto the
  344.      * collision plane (m)
  345.      * @param radius sum of primary and secondary collision object equivalent sphere radii (m)
  346.      * @param customIntegrator custom integrator to use in place of the integrator from the constructor
  347.      * @param customMaxNbOfEval custom maximum number of evaluations to use in place of the custom maximum number from the
  348.      * constructor
  349.      * @param <T> type of the field element
  350.      *
  351.      * @return probability of collision
  352.      */
  353.     public abstract <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(T xm, T ym,
  354.                                                                                                T sigmaX, T sigmaY,
  355.                                                                                                T radius,
  356.                                                                                                FieldUnivariateIntegrator<T> customIntegrator,
  357.                                                                                                int customMaxNbOfEval);

  358. }