AbstractShortTermEncounter1DNumerical2DPOCMethod.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.hipparchus.Field;
import org.hipparchus.analysis.integration.FieldTrapezoidIntegrator;
import org.hipparchus.analysis.integration.FieldUnivariateIntegrator;
import org.hipparchus.analysis.integration.UnivariateIntegrator;
import org.hipparchus.geometry.euclidean.twod.FieldVector2D;
import org.hipparchus.geometry.euclidean.twod.Vector2D;
import org.hipparchus.linear.FieldMatrix;
import org.hipparchus.linear.RealMatrix;
import org.hipparchus.util.FastMath;
import org.orekit.data.DataContext;
import org.orekit.files.ccsds.ndm.cdm.Cdm;
import org.orekit.files.ccsds.ndm.cdm.CdmData;
import org.orekit.files.ccsds.ndm.cdm.CdmMetadata;
import org.orekit.files.ccsds.ndm.cdm.CdmRelativeMetadata;
import org.orekit.frames.encounter.EncounterLOFType;
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;
import org.orekit.utils.Fieldifier;
/**
* This abstract class serves as a foundation to create 1D numerical 2D probability of collision computing method.
*
* @author Vincent Cucchietti
* @since 12.0
*/
public abstract class AbstractShortTermEncounter1DNumerical2DPOCMethod
extends AbstractShortTermEncounter2DPOCMethod {
/** Default univariate function numerical integrator. */
private final UnivariateIntegrator integrator;
/** Default maximum number of function evaluation when integrating. */
private final int maxNbOfEval;
/**
* Customizable constructor.
*
* @param name name of the method
* @param integrator integrator
* @param maxNbOfEval max number of evaluation
*/
protected AbstractShortTermEncounter1DNumerical2DPOCMethod(final String name,
final UnivariateIntegrator integrator,
final int maxNbOfEval) {
super(name);
this.integrator = integrator;
this.maxNbOfEval = maxNbOfEval;
}
/**
* Compute the probability of collision using an {@link Cdm Orekit Conjunction Data Message}.
*
* @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 customIntegrator different univariate function numerical integrator than the one defined in the instance
* @param customMaxNbOfEval different maximum number of function evaluation when integrating than the one defined in the
* instance
* @param zeroThreshold threshold below which values are considered equal to zero
*
* @return probability of collision
*/
public ProbabilityOfCollision compute(final Cdm cdm, final double primaryRadius, final double secondaryRadius,
final UnivariateIntegrator customIntegrator, final int customMaxNbOfEval,
final double zeroThreshold) {
final CdmRelativeMetadata cdmRelativeMetadata = cdm.getRelativeMetadata();
final CdmData primaryData = cdm.getDataObject1();
final CdmData secondaryData = cdm.getDataObject2();
final DataContext cdmDataContext = cdm.getDataContext();
// Extract primary data
final Orbit primaryOrbit =
getObjectOrbitFromCdm(cdmRelativeMetadata, primaryData, cdm.getMetadataObject1(), cdmDataContext);
final StateCovariance primaryCovariance = getObjectStateCovarianceFromCdm(cdmRelativeMetadata, primaryData);
// Extract secondary data
final Orbit secondaryOrbit =
getObjectOrbitFromCdm(cdmRelativeMetadata, secondaryData, cdm.getMetadataObject2(), cdmDataContext);
final StateCovariance secondaryCovariance = getObjectStateCovarianceFromCdm(cdmRelativeMetadata, secondaryData);
return compute(primaryOrbit, primaryCovariance, primaryRadius,
secondaryOrbit, secondaryCovariance, secondaryRadius,
customIntegrator, customMaxNbOfEval, zeroThreshold);
}
/**
* Compute the probability of collision using an {@link Cdm Orekit Conjunction Data Message}.
*
* @param cdm conjunction data message
* @param primaryRadius primary collision object equivalent sphere radius (m)
* @param secondaryRadius secondary collision object equivalent sphere radius (m)
* @param zeroThreshold threshold below which values are considered equal to zero
* @param customIntegrator different univariate function numerical integrator than the one defined in the instance
* @param customMaxNbOfEval different maximum number of function evaluation when integrating than the one defined in the
* instance
* @param <T> type of the field elements
*
* @return probability of collision
*/
public <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(final Cdm cdm,
final T primaryRadius,
final T secondaryRadius,
final FieldUnivariateIntegrator<T> customIntegrator,
final int customMaxNbOfEval,
final double zeroThreshold) {
final Field<T> field = primaryRadius.getField();
final CdmRelativeMetadata cdmRelativeMetadata = cdm.getRelativeMetadata();
final CdmData primaryData = cdm.getDataObject1();
final CdmData secondaryData = cdm.getDataObject2();
final CdmMetadata primaryMetadata = cdm.getMetadataObject1();
final CdmMetadata secondaryMetadata = cdm.getMetadataObject2();
final DataContext cdmDataContext = cdm.getDataContext();
// Extract primary data
final Orbit primaryOrbitFromCdm = getObjectOrbitFromCdm(cdmRelativeMetadata, primaryData,
primaryMetadata, cdmDataContext);
final FieldOrbit<T> primaryOrbit = primaryOrbitFromCdm.getType().convertToFieldOrbit(field,
primaryOrbitFromCdm);
final FieldStateCovariance<T> primaryCovariance =
Fieldifier.fieldify(field, getObjectStateCovarianceFromCdm(cdmRelativeMetadata, primaryData));
// Extract secondary data
final Orbit secondaryOrbitFromCdm = getObjectOrbitFromCdm(cdmRelativeMetadata, secondaryData,
secondaryMetadata, cdmDataContext);
final FieldOrbit<T> secondaryOrbit = secondaryOrbitFromCdm.getType().convertToFieldOrbit(field,
secondaryOrbitFromCdm);
final FieldStateCovariance<T> secondaryCovariance =
Fieldifier.fieldify(field, getObjectStateCovarianceFromCdm(cdmRelativeMetadata, secondaryData));
return compute(primaryOrbit, primaryCovariance, primaryRadius,
secondaryOrbit, secondaryCovariance, secondaryRadius,
customIntegrator, customMaxNbOfEval, 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 customIntegrator different univariate function numerical integrator than the one defined in the instance
* @param customMaxNbOfEval different maximum number of function evaluation when integrating than the one defined in the
* instance
* @param zeroThreshold threshold below which values are considered equal to zero
*
* @return probability of collision
*/
public ProbabilityOfCollision compute(final Orbit primaryAtTCA,
final StateCovariance primaryCovariance,
final double primaryRadius,
final Orbit secondaryAtTCA,
final StateCovariance secondaryCovariance,
final double secondaryRadius,
final UnivariateIntegrator customIntegrator,
final int customMaxNbOfEval,
final double zeroThreshold) {
final ShortTermEncounter2DDefinition encounterDefinition = new ShortTermEncounter2DDefinition(
primaryAtTCA, primaryCovariance, primaryRadius,
secondaryAtTCA, secondaryCovariance, secondaryRadius,
EncounterLOFType.DEFAULT, DEFAULT_TCA_DIFFERENCE_TOLERANCE);
return compute(encounterDefinition, customIntegrator, customMaxNbOfEval, 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 customIntegrator different univariate function numerical integrator than the one defined in the instance
* @param customMaxNbOfEval different maximum number of function evaluation when integrating than the one defined in the
* instance
* @param zeroThreshold threshold below which values are considered equal to zero
* @param <T> type of the field elements
*
* @return probability of collision
*/
public <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(
final FieldOrbit<T> primaryAtTCA,
final FieldStateCovariance<T> primaryCovariance,
final T primaryRadius,
final FieldOrbit<T> secondaryAtTCA,
final FieldStateCovariance<T> secondaryCovariance,
final T secondaryRadius,
final FieldUnivariateIntegrator<T> customIntegrator,
final int customMaxNbOfEval,
final double zeroThreshold) {
final FieldShortTermEncounter2DDefinition<T> encounterDefinition =
new FieldShortTermEncounter2DDefinition<>(
primaryAtTCA, primaryCovariance, primaryRadius,
secondaryAtTCA, secondaryCovariance, secondaryRadius,
EncounterLOFType.DEFAULT, DEFAULT_TCA_DIFFERENCE_TOLERANCE);
return compute(encounterDefinition, customIntegrator, customMaxNbOfEval, zeroThreshold);
}
/**
* Compute the probability of collision using a given collision definition.
*
* @param encounterDefinition probabilityOfCollision definition between a primary and a secondary collision object
* @param customIntegrator different univariate function numerical integrator than the one defined in the instance
* @param customMaxNbOfEval different maximum number of function evaluation when integrating than the one defined in the
* instance
* @param zeroThreshold threshold below which values are considered equal to zero
*
* @return probability of collision
*/
public ProbabilityOfCollision compute(final ShortTermEncounter2DDefinition encounterDefinition,
final UnivariateIntegrator customIntegrator,
final int customMaxNbOfEval,
final double zeroThreshold) {
final Vector2D otherPositionAfterRotationInCollisionPlane =
encounterDefinition.computeOtherPositionInRotatedCollisionPlane(zeroThreshold);
final RealMatrix projectedDiagonalizedCombinedPositionalCovarianceMatrix =
encounterDefinition.computeProjectedAndDiagonalizedCombinedPositionalCovarianceMatrix();
return compute(otherPositionAfterRotationInCollisionPlane.getX(),
otherPositionAfterRotationInCollisionPlane.getY(),
FastMath.sqrt(projectedDiagonalizedCombinedPositionalCovarianceMatrix.getEntry(0, 0)),
FastMath.sqrt(projectedDiagonalizedCombinedPositionalCovarianceMatrix.getEntry(1, 1)),
encounterDefinition.getCombinedRadius(),
customIntegrator,
customMaxNbOfEval);
}
/**
* Compute the probability of collision using given collision definition.
*
* @param encounterDefinition encounter definition between a primary and a secondary collision object
* @param customIntegrator custom integrator to use in place of the integrator from the constructor
* @param customMaxNbOfEval custom maximum number of evaluations to use in place of the custom maximum number from the
* @param zeroThreshold threshold below which values are considered equal to zero
* @param <T> type of the field element
*
* @return probability of collision
*/
public <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(
final FieldShortTermEncounter2DDefinition<T> encounterDefinition,
final FieldUnivariateIntegrator<T> customIntegrator,
final int customMaxNbOfEval,
final double zeroThreshold) {
final FieldVector2D<T> otherPositionAfterRotationInCollisionPlane =
encounterDefinition.computeOtherPositionInRotatedCollisionPlane(zeroThreshold);
final FieldMatrix<T> projectedDiagonalizedCombinedPositionalCovarianceMatrix =
encounterDefinition.computeProjectedAndDiagonalizedCombinedPositionalCovarianceMatrix();
return compute(otherPositionAfterRotationInCollisionPlane.getX(),
otherPositionAfterRotationInCollisionPlane.getY(),
projectedDiagonalizedCombinedPositionalCovarianceMatrix.getEntry(0, 0).sqrt(),
projectedDiagonalizedCombinedPositionalCovarianceMatrix.getEntry(1, 1).sqrt(),
encounterDefinition.getCombinedRadius(),
customIntegrator,
customMaxNbOfEval);
}
/**
* {@inheritDoc}
* <p>
* It uses the defaults integrator and maximum number of function evaluation when integrating.
*/
public ProbabilityOfCollision compute(final double xm, final double ym, final double sigmaX, final double sigmaY,
final double radius) {
return compute(xm, ym, sigmaX, sigmaY, radius, integrator, maxNbOfEval);
}
/**
* 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
*/
public <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(final T xm, final T ym,
final T sigmaX, final T sigmaY,
final T radius) {
return compute(xm, ym, sigmaX, sigmaY, radius, new FieldTrapezoidIntegrator<>(xm.getField()),
maxNbOfEval);
}
/**
* Compute the probability of collision using arguments specific to the rotated encounter frame and custom numerical
* configuration.
* <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 customIntegrator custom integrator to use in place of the integrator from the constructor
* @param customMaxNbOfEval custom maximum number of evaluations to use in place of the custom maximum number from the
* constructor
*
* @return probability of collision
*/
public abstract ProbabilityOfCollision compute(double xm, double ym, double sigmaX, double sigmaY, double radius,
UnivariateIntegrator customIntegrator, int customMaxNbOfEval);
/**
* Compute the probability of collision using arguments specific to the rotated encounter frame and custom numerical
* configuration.
* <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 customIntegrator custom integrator to use in place of the integrator from the constructor
* @param customMaxNbOfEval custom maximum number of evaluations to use in place of the custom maximum number from the
* constructor
* @param <T> type of the field element
*
* @return probability of collision
*/
public abstract <T extends CalculusFieldElement<T>> FieldProbabilityOfCollision<T> compute(T xm, T ym,
T sigmaX, T sigmaY,
T radius,
FieldUnivariateIntegrator<T> customIntegrator,
int customMaxNbOfEval);
}