ShortTermEncounter2DPOCMethod.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.orekit.files.ccsds.ndm.cdm.Cdm;
  20. import org.orekit.orbits.FieldOrbit;
  21. import org.orekit.orbits.Orbit;
  22. import org.orekit.propagation.FieldStateCovariance;
  23. import org.orekit.propagation.StateCovariance;
  24. import org.orekit.ssa.metrics.FieldProbabilityOfCollision;
  25. import org.orekit.ssa.metrics.ProbabilityOfCollision;

  26. /**
  27.  * Interface common to all short-term encounter probability of collision computing methods.
  28.  * <p>
  29.  * All the methods implementing this interface will at least assume the followings :
  30.  * <ul>
  31.  *     <li>Short term encounter leading to a linear relative motion.</li>
  32.  *     <li>Spherical collision object.</li>
  33.  *     <li>Uncorrelated positional covariance.</li>
  34.  *     <li>Gaussian distribution of the position uncertainties.</li>
  35.  *     <li>Deterministic velocity i.e. no velocity uncertainties.</li>
  36.  * </ul>
  37.  * As listed in the assumptions, methods implementing this interface are to be used in short encounter,
  38.  * meaning that there must be a high relative velocity. For ease of computation, the resulting swept volume
  39.  * is extended to infinity so that the integral becomes bivariate instead of trivariate (conservative hypothesis).
  40.  * <p>
  41.  * Consequently and if we consider Earth, methods implementing this interface are <u><b>recommended</b></u> for
  42.  * collision happening in Low/Medium Earth Orbit (LEO and MEO) but are <u><b>not recommended</b></u> for collision
  43.  * happening in Geostationary Earth Orbit (GEO).
  44.  *
  45.  * @author Vincent Cucchietti
  46.  * @since 12.0
  47.  */
  48. public interface ShortTermEncounter2DPOCMethod {

  49.     /** Threshold below which values are considered equal to zero. */
  50.     double DEFAULT_ZERO_THRESHOLD = 1e-15;

  51.     /**
  52.      * Compute the probability of collision using a Conjunction Data Message (CDM).
  53.      *
  54.      * @param cdm conjunction data message input
  55.      * @param primaryRadius primary collision object equivalent sphere radius (m)
  56.      * @param secondaryRadius secondary collision object equivalent sphere radius (m)
  57.      *
  58.      * @return probability of collision
  59.      */
  60.     default ProbabilityOfCollision compute(Cdm cdm, double primaryRadius, double secondaryRadius) {
  61.         return compute(cdm, primaryRadius + secondaryRadius);
  62.     }

  63.     /**
  64.      * Compute the probability of collision using a Conjunction Data Message (CDM).
  65.      *
  66.      * @param cdm conjunction data message input
  67.      * @param combinedRadius combined radius (m)
  68.      *
  69.      * @return probability of collision
  70.      */
  71.     ProbabilityOfCollision compute(Cdm cdm, double combinedRadius);

  72.     /**
  73.      * Compute the probability of collision using a Conjunction Data Message (CDM).
  74.      *
  75.      * @param cdm conjunction data message input
  76.      * @param primaryRadius primary collision object equivalent sphere radius (m)
  77.      * @param secondaryRadius secondary collision object equivalent sphere radius (m)
  78.      * @param <T> type of the field elements
  79.      *
  80.      * @return probability of collision
  81.      */
  82.     default <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(Cdm cdm,
  83.                                                                                        T primaryRadius,
  84.                                                                                        T secondaryRadius) {
  85.         return compute(cdm, primaryRadius.add(secondaryRadius));
  86.     }

  87.     /**
  88.      * Compute the probability of collision using a Conjunction Data Message (CDM).
  89.      *
  90.      * @param cdm conjunction data message input
  91.      * @param combinedRadius combined radius (m)
  92.      * @param <T> type of the field elements
  93.      *
  94.      * @return probability of collision
  95.      */
  96.     default <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(Cdm cdm,
  97.                                                                                        T combinedRadius) {
  98.         return compute(cdm, combinedRadius, DEFAULT_ZERO_THRESHOLD);
  99.     }

  100.     /**
  101.      * Compute the probability of collision using a Conjunction Data Message (CDM).
  102.      *
  103.      * @param cdm conjunction data message input
  104.      * @param combinedRadius combined radius (m)
  105.      * @param zeroThreshold threshold below which values are considered equal to zero
  106.      * @param <T> type of the field elements
  107.      *
  108.      * @return probability of collision
  109.      */
  110.     <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(Cdm cdm, T combinedRadius,
  111.                                                                                double zeroThreshold);

  112.     /**
  113.      * Compute the probability of collision using parameters necessary for creating a
  114.      * {@link ShortTermEncounter2DDefinition collision definition} instance.
  115.      *
  116.      * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
  117.      * @param primaryCovariance primary collision object covariance
  118.      * @param primaryRadius primary collision object equivalent sphere radius (m)
  119.      * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
  120.      * @param secondaryCovariance secondary collision object covariance
  121.      * @param secondaryRadius secondary collision object equivalent sphere radius (m)
  122.      *
  123.      * @return probability of collision
  124.      */
  125.     default ProbabilityOfCollision compute(Orbit primaryAtTCA,
  126.                                            StateCovariance primaryCovariance,
  127.                                            double primaryRadius,
  128.                                            Orbit secondaryAtTCA,
  129.                                            StateCovariance secondaryCovariance,
  130.                                            double secondaryRadius) {
  131.         return compute(primaryAtTCA, primaryCovariance, secondaryAtTCA, secondaryCovariance,
  132.                        primaryRadius + secondaryRadius);
  133.     }

  134.     /**
  135.      * Compute the probability of collision using parameters necessary for creating a
  136.      * {@link ShortTermEncounter2DDefinition collision definition} instance.
  137.      *
  138.      * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
  139.      * @param primaryCovariance primary collision object covariance
  140.      * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
  141.      * @param secondaryCovariance secondary collision object covariance
  142.      * @param combinedRadius combined radius (m)
  143.      *
  144.      * @return probability of collision
  145.      */
  146.     default ProbabilityOfCollision compute(Orbit primaryAtTCA,
  147.                                            StateCovariance primaryCovariance,
  148.                                            Orbit secondaryAtTCA,
  149.                                            StateCovariance secondaryCovariance,
  150.                                            double combinedRadius) {
  151.         return compute(primaryAtTCA, primaryCovariance, secondaryAtTCA, secondaryCovariance,
  152.                        combinedRadius, DEFAULT_ZERO_THRESHOLD);
  153.     }

  154.     /**
  155.      * Compute the probability of collision using parameters necessary for creating a
  156.      * {@link ShortTermEncounter2DDefinition collision definition} instance.
  157.      *
  158.      * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
  159.      * @param primaryCovariance primary collision object covariance
  160.      * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
  161.      * @param secondaryCovariance secondary collision object covariance
  162.      * @param combinedRadius combined radius (m)
  163.      * @param zeroThreshold threshold below which values are considered equal to zero
  164.      *
  165.      * @return probability of collision
  166.      */
  167.     ProbabilityOfCollision compute(Orbit primaryAtTCA, StateCovariance primaryCovariance,
  168.                                    Orbit secondaryAtTCA, StateCovariance secondaryCovariance,
  169.                                    double combinedRadius, double zeroThreshold);

  170.     /**
  171.      * Compute the probability of collision using parameters necessary for creating a
  172.      * {@link ShortTermEncounter2DDefinition collision definition} instance.
  173.      *
  174.      * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
  175.      * @param primaryCovariance primary collision object covariance
  176.      * @param primaryRadius primary collision object equivalent sphere radius (m)
  177.      * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
  178.      * @param secondaryCovariance secondary collision object covariance
  179.      * @param secondaryRadius secondary collision object equivalent sphere radius (m)
  180.      * @param <T> type of the field elements
  181.      *
  182.      * @return probability of collision
  183.      */
  184.     default <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(FieldOrbit<T> primaryAtTCA,
  185.                                                                                        FieldStateCovariance<T> primaryCovariance,
  186.                                                                                        T primaryRadius,
  187.                                                                                        FieldOrbit<T> secondaryAtTCA,
  188.                                                                                        FieldStateCovariance<T> secondaryCovariance,
  189.                                                                                        T secondaryRadius) {
  190.         return compute(primaryAtTCA, primaryCovariance, secondaryAtTCA, secondaryCovariance,
  191.                        primaryRadius.add(secondaryRadius));
  192.     }

  193.     /**
  194.      * Compute the probability of collision using parameters necessary for creating a
  195.      * {@link ShortTermEncounter2DDefinition collision definition} instance.
  196.      *
  197.      * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
  198.      * @param primaryCovariance primary collision object covariance
  199.      * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
  200.      * @param secondaryCovariance secondary collision object covariance
  201.      * @param combinedRadius secondary collision object equivalent sphere radius (m)
  202.      * @param <T> type of the field elements
  203.      *
  204.      * @return probability of collision
  205.      */
  206.     default <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(FieldOrbit<T> primaryAtTCA,
  207.                                                                                        FieldStateCovariance<T> primaryCovariance,
  208.                                                                                        FieldOrbit<T> secondaryAtTCA,
  209.                                                                                        FieldStateCovariance<T> secondaryCovariance,
  210.                                                                                        T combinedRadius) {
  211.         return compute(primaryAtTCA, primaryCovariance, secondaryAtTCA, secondaryCovariance,
  212.                        combinedRadius, DEFAULT_ZERO_THRESHOLD);
  213.     }

  214.     /**
  215.      * Compute the probability of collision using parameters necessary for creating a
  216.      * {@link ShortTermEncounter2DDefinition collision definition} instance.
  217.      *
  218.      * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
  219.      * @param primaryCovariance primary collision object covariance
  220.      * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
  221.      * @param secondaryCovariance secondary collision object covariance
  222.      * @param combinedRadius combined radius (m)
  223.      * @param zeroThreshold threshold below which values are considered equal to zero
  224.      * @param <T> type of the field elements
  225.      *
  226.      * @return probability of collision
  227.      */
  228.     <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(FieldOrbit<T> primaryAtTCA,
  229.                                                                                FieldStateCovariance<T> primaryCovariance,
  230.                                                                                FieldOrbit<T> secondaryAtTCA,
  231.                                                                                FieldStateCovariance<T> secondaryCovariance,
  232.                                                                                T combinedRadius,
  233.                                                                                double zeroThreshold);

  234.     /**
  235.      * Compute the probability of collision using given collision definition.
  236.      *
  237.      * @param encounter encounter definition between a primary and a secondary collision object
  238.      *
  239.      * @return probability of collision
  240.      */
  241.     default ProbabilityOfCollision compute(ShortTermEncounter2DDefinition encounter) {
  242.         return compute(encounter, DEFAULT_ZERO_THRESHOLD);
  243.     }

  244.     /**
  245.      * Compute the probability of collision using given collision definition.
  246.      *
  247.      * @param encounter encounter definition between a primary and a secondary collision object
  248.      * @param zeroThreshold threshold below which values are considered equal to zero
  249.      *
  250.      * @return probability of collision
  251.      */
  252.     ProbabilityOfCollision compute(ShortTermEncounter2DDefinition encounter, double zeroThreshold);

  253.     /**
  254.      * Compute the probability of collision using given collision definition.
  255.      *
  256.      * @param encounter encounter definition between a primary and a secondary collision object
  257.      * @param <T> type of the field elements
  258.      *
  259.      * @return probability of collision
  260.      */
  261.     default <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(
  262.             FieldShortTermEncounter2DDefinition<T> encounter) {
  263.         return compute(encounter, DEFAULT_ZERO_THRESHOLD);
  264.     }

  265.     /**
  266.      * Compute the probability of collision using given collision definition.
  267.      *
  268.      * @param encounter encounter definition between a primary and a secondary collision object
  269.      * @param zeroThreshold threshold below which values are considered equal to zero
  270.      * @param <T> type of the field elements
  271.      *
  272.      * @return probability of collision
  273.      */
  274.     <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(
  275.             FieldShortTermEncounter2DDefinition<T> encounter,
  276.             double zeroThreshold);

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

  298.     /**
  299.      * Compute the probability of collision using arguments specific to the rotated encounter frame.
  300.      * <p>
  301.      * The rotated encounter frame is define by the initial encounter frame (defined in
  302.      * {@link ShortTermEncounter2DDefinition}) rotated by the rotation matrix which is used to diagonalize the combined
  303.      * covariance matrix.
  304.      * </p>
  305.      *
  306.      * @param xm other collision object projected position onto the collision plane in the rotated encounter frame x-axis
  307.      * (m)
  308.      * @param ym other collision object projected position onto the collision plane in the rotated encounter frame y-axis
  309.      * (m)
  310.      * @param sigmaX square root of the x-axis eigen value of the diagonalized combined covariance matrix projected onto the
  311.      * collision plane (m)
  312.      * @param sigmaY square root of the y-axis eigen value of the diagonalized combined covariance matrix projected onto the
  313.      * collision plane (m)
  314.      * @param radius sum of primary and secondary collision object equivalent sphere radii (m)
  315.      * @param <T> type of the field elements
  316.      *
  317.      * @return probability of collision
  318.      */
  319.     <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(T xm, T ym, T sigmaX, T sigmaY, T radius);

  320.     /** Get type of the method.
  321.      * @return type of the method
  322.      */
  323.     ShortTermEncounter2DPOCMethodType getType();

  324.     /** Get name of the method.
  325.      * @return name of the method
  326.      */
  327.     String getName();

  328.     /** Get flag that defines if the method is a maximum probability of collision computing method.
  329.      * @return flag that defines if the method is a maximum probability of collision computing method
  330.      */
  331.     boolean isAMaximumProbabilityOfCollisionMethod();
  332. }