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();
}