ShortTermEncounter2DPOCMethod.java
- /* Copyright 2002-2024 CS GROUP
- * Licensed to CS GROUP (CS) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * CS licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
- package org.orekit.ssa.collision.shorttermencounter.probability.twod;
- import org.hipparchus.CalculusFieldElement;
- import org.orekit.files.ccsds.ndm.cdm.Cdm;
- import org.orekit.orbits.FieldOrbit;
- import org.orekit.orbits.Orbit;
- import org.orekit.propagation.FieldStateCovariance;
- import org.orekit.propagation.StateCovariance;
- import org.orekit.ssa.metrics.FieldProbabilityOfCollision;
- import org.orekit.ssa.metrics.ProbabilityOfCollision;
- /**
- * Interface common to all short-term encounter probability of collision computing methods.
- * <p>
- * All the methods implementing this interface will at least assume the followings :
- * <ul>
- * <li>Short term encounter leading to a linear relative motion.</li>
- * <li>Spherical collision object.</li>
- * <li>Uncorrelated positional covariance.</li>
- * <li>Gaussian distribution of the position uncertainties.</li>
- * <li>Deterministic velocity i.e. no velocity uncertainties.</li>
- * </ul>
- * As listed in the assumptions, methods implementing this interface are to be used in short encounter,
- * meaning that there must be a high relative velocity. For ease of computation, the resulting swept volume
- * is extended to infinity so that the integral becomes bivariate instead of trivariate (conservative hypothesis).
- * <p>
- * Consequently and if we consider Earth, methods implementing this interface are <u><b>recommended</b></u> for
- * collision happening in Low/Medium Earth Orbit (LEO and MEO) but are <u><b>not recommended</b></u> for collision
- * happening in Geostationary Earth Orbit (GEO).
- *
- * @author Vincent Cucchietti
- * @since 12.0
- */
- public interface ShortTermEncounter2DPOCMethod {
- /** Threshold below which values are considered equal to zero. */
- double DEFAULT_ZERO_THRESHOLD = 1e-15;
- /**
- * Compute the probability of collision using a Conjunction Data Message (CDM).
- *
- * @param cdm conjunction data message input
- * @param primaryRadius primary collision object equivalent sphere radius (m)
- * @param secondaryRadius secondary collision object equivalent sphere radius (m)
- *
- * @return probability of collision
- */
- default ProbabilityOfCollision compute(Cdm cdm, double primaryRadius, double secondaryRadius) {
- return compute(cdm, primaryRadius + secondaryRadius);
- }
- /**
- * Compute the probability of collision using a Conjunction Data Message (CDM).
- *
- * @param cdm conjunction data message input
- * @param combinedRadius combined radius (m)
- *
- * @return probability of collision
- */
- ProbabilityOfCollision compute(Cdm cdm, double combinedRadius);
- /**
- * Compute the probability of collision using a Conjunction Data Message (CDM).
- *
- * @param cdm conjunction data message input
- * @param primaryRadius primary collision object equivalent sphere radius (m)
- * @param secondaryRadius secondary collision object equivalent sphere radius (m)
- * @param <T> type of the field elements
- *
- * @return probability of collision
- */
- default <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(Cdm cdm,
- T primaryRadius,
- T secondaryRadius) {
- return compute(cdm, primaryRadius.add(secondaryRadius));
- }
- /**
- * Compute the probability of collision using a Conjunction Data Message (CDM).
- *
- * @param cdm conjunction data message input
- * @param combinedRadius combined radius (m)
- * @param <T> type of the field elements
- *
- * @return probability of collision
- */
- default <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(Cdm cdm,
- T combinedRadius) {
- return compute(cdm, combinedRadius, DEFAULT_ZERO_THRESHOLD);
- }
- /**
- * Compute the probability of collision using a Conjunction Data Message (CDM).
- *
- * @param cdm conjunction data message input
- * @param combinedRadius combined radius (m)
- * @param zeroThreshold threshold below which values are considered equal to zero
- * @param <T> type of the field elements
- *
- * @return probability of collision
- */
- <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(Cdm cdm, T combinedRadius,
- double zeroThreshold);
- /**
- * Compute the probability of collision using parameters necessary for creating a
- * {@link ShortTermEncounter2DDefinition collision definition} instance.
- *
- * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
- * @param primaryCovariance primary collision object covariance
- * @param primaryRadius primary collision object equivalent sphere radius (m)
- * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
- * @param secondaryCovariance secondary collision object covariance
- * @param secondaryRadius secondary collision object equivalent sphere radius (m)
- *
- * @return probability of collision
- */
- default ProbabilityOfCollision compute(Orbit primaryAtTCA,
- StateCovariance primaryCovariance,
- double primaryRadius,
- Orbit secondaryAtTCA,
- StateCovariance secondaryCovariance,
- double secondaryRadius) {
- return compute(primaryAtTCA, primaryCovariance, secondaryAtTCA, secondaryCovariance,
- primaryRadius + secondaryRadius);
- }
- /**
- * Compute the probability of collision using parameters necessary for creating a
- * {@link ShortTermEncounter2DDefinition collision definition} instance.
- *
- * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
- * @param primaryCovariance primary collision object covariance
- * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
- * @param secondaryCovariance secondary collision object covariance
- * @param combinedRadius combined radius (m)
- *
- * @return probability of collision
- */
- default ProbabilityOfCollision compute(Orbit primaryAtTCA,
- StateCovariance primaryCovariance,
- Orbit secondaryAtTCA,
- StateCovariance secondaryCovariance,
- double combinedRadius) {
- return compute(primaryAtTCA, primaryCovariance, secondaryAtTCA, secondaryCovariance,
- combinedRadius, DEFAULT_ZERO_THRESHOLD);
- }
- /**
- * Compute the probability of collision using parameters necessary for creating a
- * {@link ShortTermEncounter2DDefinition collision definition} instance.
- *
- * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
- * @param primaryCovariance primary collision object covariance
- * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
- * @param secondaryCovariance secondary collision object covariance
- * @param combinedRadius combined radius (m)
- * @param zeroThreshold threshold below which values are considered equal to zero
- *
- * @return probability of collision
- */
- ProbabilityOfCollision compute(Orbit primaryAtTCA, StateCovariance primaryCovariance,
- Orbit secondaryAtTCA, StateCovariance secondaryCovariance,
- double combinedRadius, double zeroThreshold);
- /**
- * Compute the probability of collision using parameters necessary for creating a
- * {@link ShortTermEncounter2DDefinition collision definition} instance.
- *
- * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
- * @param primaryCovariance primary collision object covariance
- * @param primaryRadius primary collision object equivalent sphere radius (m)
- * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
- * @param secondaryCovariance secondary collision object covariance
- * @param secondaryRadius secondary collision object equivalent sphere radius (m)
- * @param <T> type of the field elements
- *
- * @return probability of collision
- */
- default <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(FieldOrbit<T> primaryAtTCA,
- FieldStateCovariance<T> primaryCovariance,
- T primaryRadius,
- FieldOrbit<T> secondaryAtTCA,
- FieldStateCovariance<T> secondaryCovariance,
- T secondaryRadius) {
- return compute(primaryAtTCA, primaryCovariance, secondaryAtTCA, secondaryCovariance,
- primaryRadius.add(secondaryRadius));
- }
- /**
- * Compute the probability of collision using parameters necessary for creating a
- * {@link ShortTermEncounter2DDefinition collision definition} instance.
- *
- * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
- * @param primaryCovariance primary collision object covariance
- * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
- * @param secondaryCovariance secondary collision object covariance
- * @param combinedRadius secondary collision object equivalent sphere radius (m)
- * @param <T> type of the field elements
- *
- * @return probability of collision
- */
- default <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(FieldOrbit<T> primaryAtTCA,
- FieldStateCovariance<T> primaryCovariance,
- FieldOrbit<T> secondaryAtTCA,
- FieldStateCovariance<T> secondaryCovariance,
- T combinedRadius) {
- return compute(primaryAtTCA, primaryCovariance, secondaryAtTCA, secondaryCovariance,
- combinedRadius, DEFAULT_ZERO_THRESHOLD);
- }
- /**
- * Compute the probability of collision using parameters necessary for creating a
- * {@link ShortTermEncounter2DDefinition collision definition} instance.
- *
- * @param primaryAtTCA primary collision object spacecraft state at time of closest approach
- * @param primaryCovariance primary collision object covariance
- * @param secondaryAtTCA secondary collision object spacecraft state at time of closest approach
- * @param secondaryCovariance secondary collision object covariance
- * @param combinedRadius combined radius (m)
- * @param zeroThreshold threshold below which values are considered equal to zero
- * @param <T> type of the field elements
- *
- * @return probability of collision
- */
- <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(FieldOrbit<T> primaryAtTCA,
- FieldStateCovariance<T> primaryCovariance,
- FieldOrbit<T> secondaryAtTCA,
- FieldStateCovariance<T> secondaryCovariance,
- T combinedRadius,
- double zeroThreshold);
- /**
- * Compute the probability of collision using given collision definition.
- *
- * @param encounter encounter definition between a primary and a secondary collision object
- *
- * @return probability of collision
- */
- default ProbabilityOfCollision compute(ShortTermEncounter2DDefinition encounter) {
- return compute(encounter, DEFAULT_ZERO_THRESHOLD);
- }
- /**
- * Compute the probability of collision using given collision definition.
- *
- * @param encounter encounter definition between a primary and a secondary collision object
- * @param zeroThreshold threshold below which values are considered equal to zero
- *
- * @return probability of collision
- */
- ProbabilityOfCollision compute(ShortTermEncounter2DDefinition encounter, double zeroThreshold);
- /**
- * Compute the probability of collision using given collision definition.
- *
- * @param encounter encounter definition between a primary and a secondary collision object
- * @param <T> type of the field elements
- *
- * @return probability of collision
- */
- default <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(
- FieldShortTermEncounter2DDefinition<T> encounter) {
- return compute(encounter, DEFAULT_ZERO_THRESHOLD);
- }
- /**
- * Compute the probability of collision using given collision definition.
- *
- * @param encounter encounter definition between a primary and a secondary collision object
- * @param zeroThreshold threshold below which values are considered equal to zero
- * @param <T> type of the field elements
- *
- * @return probability of collision
- */
- <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(
- FieldShortTermEncounter2DDefinition<T> encounter,
- double zeroThreshold);
- /**
- * Compute the probability of collision using arguments specific to the rotated encounter frame.
- * <p>
- * The rotated encounter frame is define by the initial encounter frame (defined in
- * {@link ShortTermEncounter2DDefinition}) rotated by the rotation matrix which is used to diagonalize the combined
- * covariance matrix.
- * </p>
- *
- * @param xm other collision object projected position onto the collision plane in the rotated encounter frame x-axis
- * (m)
- * @param ym other collision object projected position onto the collision plane in the rotated encounter frame y-axis
- * (m)
- * @param sigmaX square root of the x-axis eigen value of the diagonalized combined covariance matrix projected onto the
- * collision plane (m)
- * @param sigmaY square root of the y-axis eigen value of the diagonalized combined covariance matrix projected onto the
- * collision plane (m)
- * @param radius sum of primary and secondary collision object equivalent sphere radii (m)
- *
- * @return probability of collision
- */
- ProbabilityOfCollision compute(double xm, double ym, double sigmaX, double sigmaY, double radius);
- /**
- * Compute the probability of collision using arguments specific to the rotated encounter frame.
- * <p>
- * The rotated encounter frame is define by the initial encounter frame (defined in
- * {@link ShortTermEncounter2DDefinition}) rotated by the rotation matrix which is used to diagonalize the combined
- * covariance matrix.
- * </p>
- *
- * @param xm other collision object projected position onto the collision plane in the rotated encounter frame x-axis
- * (m)
- * @param ym other collision object projected position onto the collision plane in the rotated encounter frame y-axis
- * (m)
- * @param sigmaX square root of the x-axis eigen value of the diagonalized combined covariance matrix projected onto the
- * collision plane (m)
- * @param sigmaY square root of the y-axis eigen value of the diagonalized combined covariance matrix projected onto the
- * collision plane (m)
- * @param radius sum of primary and secondary collision object equivalent sphere radii (m)
- * @param <T> type of the field elements
- *
- * @return probability of collision
- */
- <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(T xm, T ym, T sigmaX, T sigmaY, T radius);
- /** Get type of the method.
- * @return type of the method
- */
- ShortTermEncounter2DPOCMethodType getType();
- /** Get name of the method.
- * @return name of the method
- */
- String getName();
- /** Get flag that defines if the method is a maximum probability of collision computing method.
- * @return flag that defines if the method is a maximum probability of collision computing method
- */
- boolean isAMaximumProbabilityOfCollisionMethod();
- }