#![allow(clippy::needless_range_loop, clippy::many_single_char_names)]
use crate::conjunction::ConjunctionGeometry;
pub const DURATION_TAIL_FRACTION: f64 = 1.0e-6;
#[allow(clippy::excessive_precision)]
pub const DURATION_WIDTHS: f64 = 9.783_276_951_397_180_772_462_244_919_914_047_240_392;
pub const OFFSET_LIMIT: f64 = 0.01;
pub const EXTENDED_LIMIT: f64 = 0.02;
pub const INACCURACY_LIMIT: f64 = 0.02;
pub const MAX_WINDOW_EXPANSIONS: usize = 8;
pub const MAX_WIDTH_EXPANSIONS: usize = 24;
const COARSE_INTERVALS: usize = 32;
const GOLDEN_STEPS: usize = 48;
const RISE_BISECTIONS: usize = 64;
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct RelativeSample {
pub position: [f64; 3],
pub velocity: [f64; 3],
pub covariance: [[f64; 3]; 3],
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct RectilinearEncounter {
quadratic: f64,
linear: f64,
constant: f64,
speed: f64,
non_positive_definite: bool,
}
impl RectilinearEncounter {
pub fn from_geometry(geometry: &ConjunctionGeometry) -> Result<Self, DomainError> {
let position = geometry.relative_position;
let velocity = geometry.relative_velocity;
for component in position.iter().chain(velocity.iter()) {
if !component.is_finite() {
return Err(DomainError::NonFiniteState);
}
}
let mut joint = [[0.0_f64; 3]; 3];
for i in 0..3 {
for j in 0..3 {
joint[i][j] =
geometry.primary_covariance[i][j] + geometry.secondary_covariance[i][j];
}
}
let factor = Cholesky3::factor(&joint).ok_or(DomainError::NonPositiveDefiniteCovariance)?;
let non_positive_definite = Cholesky3::factor(&geometry.primary_covariance).is_none()
|| Cholesky3::factor(&geometry.secondary_covariance).is_none();
let quadratic = factor.bilinear_inverse(&velocity, &velocity);
if !quadratic.is_finite() || quadratic <= 0.0 {
return Err(DomainError::DegenerateEncounterVelocity);
}
Ok(Self {
quadratic,
linear: 2.0 * factor.bilinear_inverse(&position, &velocity),
constant: factor.bilinear_inverse(&position, &position),
speed: norm3(&velocity),
non_positive_definite,
})
}
#[must_use]
pub fn modified_mahalanobis(&self, offset: f64) -> f64 {
(self.quadratic * offset + self.linear) * offset + self.constant
}
#[must_use]
pub fn time_of_minimum(&self) -> f64 {
-self.linear / (2.0 * self.quadratic)
}
#[must_use]
pub fn minimum(&self) -> f64 {
self.constant - self.linear * self.linear / (4.0 * self.quadratic)
}
#[must_use]
pub fn width(&self) -> f64 {
1.0 / libm::sqrt(self.quadratic)
}
#[must_use]
pub fn duration(&self) -> f64 {
DURATION_WIDTHS * self.width()
}
#[must_use]
pub const fn speed(&self) -> f64 {
self.speed
}
#[must_use]
pub const fn non_positive_definite(&self) -> bool {
self.non_positive_definite
}
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CurvilinearEncounter {
time_of_minimum: f64,
minimum: f64,
width: f64,
speed: f64,
}
impl CurvilinearEncounter {
pub fn locate<F>(rectilinear: &RectilinearEncounter, mut sample: F) -> Result<Self, DomainError>
where
F: FnMut(f64) -> RelativeSample,
{
let reference = Cholesky3::factor(&sample(0.0).covariance)
.ok_or(DomainError::NonPositiveDefiniteSample)?;
let log_determinant_at_tca = reference.log_determinant();
let mut curve = |t: f64| -> Result<f64, DomainError> {
let state = sample(t);
let factor = Cholesky3::factor(&state.covariance)
.ok_or(DomainError::NonPositiveDefiniteSample)?;
let value = factor.bilinear_inverse(&state.position, &state.position)
+ factor.log_determinant()
- log_determinant_at_tca;
if value.is_finite() {
Ok(value)
} else {
Err(DomainError::NonFiniteSample)
}
};
let bracket = bracket_minimum(
&mut curve,
rectilinear.time_of_minimum(),
rectilinear.duration(),
)?;
let (time_of_minimum, minimum) = golden_minimum(&mut curve, bracket)?;
let trial = rectilinear.width();
let forward = unit_rise(&mut curve, time_of_minimum, minimum, trial, 1.0)?;
let backward = unit_rise(&mut curve, time_of_minimum, minimum, trial, -1.0)?;
let speed = norm3(&sample(time_of_minimum).velocity);
if !speed.is_finite() || speed <= 0.0 {
return Err(DomainError::DegenerateEncounterVelocity);
}
Ok(Self {
time_of_minimum,
minimum,
width: f64::midpoint(forward, backward),
speed,
})
}
#[must_use]
pub const fn time_of_minimum(&self) -> f64 {
self.time_of_minimum
}
#[must_use]
pub const fn minimum(&self) -> f64 {
self.minimum
}
#[must_use]
pub const fn width(&self) -> f64 {
self.width
}
#[must_use]
pub const fn speed(&self) -> f64 {
self.speed
}
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct UsageViolations {
non_positive_definite: bool,
offset_indicator: f64,
extended_indicator: f64,
inaccuracy_indicator: f64,
correction_factor: f64,
}
impl UsageViolations {
pub fn assess(
rectilinear: &RectilinearEncounter,
curvilinear: &CurvilinearEncounter,
minimum_period: f64,
) -> Result<Self, DomainError> {
check_period(minimum_period)?;
let offset_indicator = libm::fabs(rectilinear.time_of_minimum()) / minimum_period;
let extended_indicator = rectilinear.duration() / minimum_period;
let log_correction = libm::log(curvilinear.speed() / rectilinear.speed())
+ libm::log(curvilinear.width() / rectilinear.width())
- 0.5 * (curvilinear.minimum() - rectilinear.minimum());
let inaccuracy_indicator = 1.0 - libm::exp(-libm::fabs(log_correction));
Ok(Self {
non_positive_definite: rectilinear.non_positive_definite(),
offset_indicator,
extended_indicator,
inaccuracy_indicator,
correction_factor: libm::exp(log_correction),
})
}
#[must_use]
pub fn any(&self) -> bool {
self.non_positive_definite || self.offset() || self.extended() || self.inaccuracy()
}
#[must_use]
pub const fn non_positive_definite(&self) -> bool {
self.non_positive_definite
}
#[must_use]
pub fn offset(&self) -> bool {
exceeds(self.offset_indicator, OFFSET_LIMIT)
}
#[must_use]
pub fn extended(&self) -> bool {
exceeds(self.extended_indicator, EXTENDED_LIMIT)
}
#[must_use]
pub fn inaccuracy(&self) -> bool {
exceeds(self.inaccuracy_indicator, INACCURACY_LIMIT)
}
#[must_use]
pub const fn offset_indicator(&self) -> f64 {
self.offset_indicator
}
#[must_use]
pub const fn extended_indicator(&self) -> f64 {
self.extended_indicator
}
#[must_use]
pub const fn inaccuracy_indicator(&self) -> f64 {
self.inaccuracy_indicator
}
#[must_use]
pub const fn correction_factor(&self) -> f64 {
self.correction_factor
}
}
pub fn usage_violations<F>(
geometry: &ConjunctionGeometry,
minimum_period: f64,
sample: F,
) -> Result<UsageViolations, DomainError>
where
F: FnMut(f64) -> RelativeSample,
{
check_period(minimum_period)?;
let rectilinear = RectilinearEncounter::from_geometry(geometry)?;
let curvilinear = CurvilinearEncounter::locate(&rectilinear, sample)?;
UsageViolations::assess(&rectilinear, &curvilinear, minimum_period)
}
fn exceeds(indicator: f64, limit: f64) -> bool {
indicator > limit
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DomainError {
NonFiniteState,
NonPositiveDefiniteCovariance,
DegenerateEncounterVelocity,
NonPositiveDefiniteSample,
NonFiniteSample,
InvalidOrbitalPeriod,
CurvilinearMinimumNotBracketed,
CurvilinearWidthNotBracketed,
}
impl core::fmt::Display for DomainError {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
match self {
Self::NonFiniteState => {
write!(f, "relative position or velocity at TCA is not finite")
}
Self::NonPositiveDefiniteCovariance => write!(
f,
"joint position covariance at TCA is not positive definite; no Mahalanobis distance is defined"
),
Self::DegenerateEncounterVelocity => {
write!(f, "relative velocity is zero or not finite")
}
Self::NonPositiveDefiniteSample => {
write!(f, "sampled joint covariance is not positive definite")
}
Self::NonFiniteSample => {
write!(
f,
"sampled trajectory gave a non-finite Mahalanobis distance"
)
}
Self::InvalidOrbitalPeriod => {
write!(f, "minimum orbital period is not finite and positive")
}
Self::CurvilinearMinimumNotBracketed => write!(
f,
"curvilinear Mahalanobis minimum lies outside every window the search opened"
),
Self::CurvilinearWidthNotBracketed => write!(
f,
"curvilinear Mahalanobis curve does not rise by one within the widths searched"
),
}
}
}
impl core::error::Error for DomainError {}
fn check_period(minimum_period: f64) -> Result<(), DomainError> {
if !minimum_period.is_finite() || minimum_period <= 0.0 {
return Err(DomainError::InvalidOrbitalPeriod);
}
Ok(())
}
fn bracket_minimum<F>(curve: &mut F, seed: f64, duration: f64) -> Result<(f64, f64), DomainError>
where
F: FnMut(f64) -> Result<f64, DomainError>,
{
let mut half = duration;
for _ in 0..=MAX_WINDOW_EXPANSIONS {
let step = 2.0 * half / index_as_f64(COARSE_INTERVALS);
let node = |i: usize| seed - half + step * index_as_f64(i);
let mut best = 0usize;
let mut best_value = f64::INFINITY;
for i in 0..=COARSE_INTERVALS {
let value = curve(node(i))?;
if value < best_value {
best_value = value;
best = i;
}
}
if best > 0 && best < COARSE_INTERVALS {
return Ok((node(best - 1), node(best + 1)));
}
half *= 2.0;
}
Err(DomainError::CurvilinearMinimumNotBracketed)
}
fn golden_minimum<F>(curve: &mut F, bracket: (f64, f64)) -> Result<(f64, f64), DomainError>
where
F: FnMut(f64) -> Result<f64, DomainError>,
{
let (mut lo, mut hi) = bracket;
let span = hi - lo;
let ratio = 0.5 * (libm::sqrt(5.0) - 1.0);
let mut left = hi - ratio * span;
let mut right = lo + ratio * span;
let mut f_left = curve(left)?;
let mut f_right = curve(right)?;
for _ in 0..GOLDEN_STEPS {
if f_left < f_right {
hi = right;
right = left;
f_right = f_left;
left = hi - ratio * (hi - lo);
f_left = curve(left)?;
} else {
lo = left;
left = right;
f_left = f_right;
right = lo + ratio * (hi - lo);
f_right = curve(right)?;
}
if hi - lo <= f64::EPSILON * span {
break;
}
}
if f_left < f_right {
Ok((left, f_left))
} else {
Ok((right, f_right))
}
}
fn unit_rise<F>(
curve: &mut F,
centre: f64,
minimum: f64,
seed: f64,
direction: f64,
) -> Result<f64, DomainError>
where
F: FnMut(f64) -> Result<f64, DomainError>,
{
let mut hi = seed;
for expansion in 0..=MAX_WIDTH_EXPANSIONS {
if curve(centre + direction * hi)? - minimum >= 1.0 {
break;
}
if expansion == MAX_WIDTH_EXPANSIONS {
return Err(DomainError::CurvilinearWidthNotBracketed);
}
hi *= 2.0;
}
let mut lo = 0.0;
for _ in 0..RISE_BISECTIONS {
let mid = f64::midpoint(lo, hi);
if mid <= lo || mid >= hi {
break;
}
if curve(centre + direction * mid)? - minimum < 1.0 {
lo = mid;
} else {
hi = mid;
}
}
Ok(f64::midpoint(lo, hi))
}
#[derive(Debug, Clone, Copy)]
struct Cholesky3 {
l: [[f64; 3]; 3],
}
impl Cholesky3 {
fn factor(m: &[[f64; 3]; 3]) -> Option<Self> {
let mut l = [[0.0_f64; 3]; 3];
for i in 0..3 {
for j in 0..=i {
let mut sum = f64::midpoint(m[i][j], m[j][i]);
for k in 0..j {
sum -= l[i][k] * l[j][k];
}
if i == j {
if !sum.is_finite() || sum <= 0.0 {
return None;
}
l[i][i] = libm::sqrt(sum);
} else {
l[i][j] = sum / l[j][j];
if !l[i][j].is_finite() {
return None;
}
}
}
}
Some(Self { l })
}
fn forward(&self, b: &[f64; 3]) -> [f64; 3] {
let mut x = [0.0_f64; 3];
for i in 0..3 {
let mut sum = b[i];
for k in 0..i {
sum -= self.l[i][k] * x[k];
}
x[i] = sum / self.l[i][i];
}
x
}
fn bilinear_inverse(&self, u: &[f64; 3], v: &[f64; 3]) -> f64 {
let a = self.forward(u);
let b = self.forward(v);
a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
}
fn log_determinant(&self) -> f64 {
2.0 * (libm::log(self.l[0][0]) + libm::log(self.l[1][1]) + libm::log(self.l[2][2]))
}
}
fn norm3(v: &[f64; 3]) -> f64 {
libm::sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2])
}
#[allow(clippy::cast_precision_loss)]
fn index_as_f64(n: usize) -> f64 {
n as f64
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::float_cmp)]
use super::*;
use proptest::prelude::*;
fn spd(l: [f64; 6]) -> [[f64; 3]; 3] {
let lower = [[l[0], 0.0, 0.0], [l[1], l[2], 0.0], [l[3], l[4], l[5]]];
let mut a = [[0.0_f64; 3]; 3];
for i in 0..3 {
for j in 0..3 {
for k in 0..3 {
a[i][j] += lower[i][k] * lower[j][k];
}
}
}
a
}
fn inverse3(m: &[[f64; 3]; 3]) -> [[f64; 3]; 3] {
let cofactor = |i: usize, j: usize| {
let rows: [usize; 2] = [(i + 1) % 3, (i + 2) % 3];
let cols: [usize; 2] = [(j + 1) % 3, (j + 2) % 3];
m[rows[0]][cols[0]] * m[rows[1]][cols[1]] - m[rows[0]][cols[1]] * m[rows[1]][cols[0]]
};
let det = m[0][0] * cofactor(0, 0) + m[0][1] * cofactor(0, 1) + m[0][2] * cofactor(0, 2);
let mut inverse = [[0.0_f64; 3]; 3];
for i in 0..3 {
for j in 0..3 {
inverse[i][j] = cofactor(j, i) / det;
}
}
inverse
}
fn quadratic_form(inverse: &[[f64; 3]; 3], u: &[f64; 3]) -> f64 {
let mut acc = 0.0;
for i in 0..3 {
for j in 0..3 {
acc += u[i] * inverse[i][j] * u[j];
}
}
acc
}
fn sum3(a: &[[f64; 3]; 3], b: &[[f64; 3]; 3]) -> [[f64; 3]; 3] {
let mut c = [[0.0_f64; 3]; 3];
for i in 0..3 {
for j in 0..3 {
c[i][j] = a[i][j] + b[i][j];
}
}
c
}
fn drift(origin: [f64; 3], velocity: [f64; 3], t: f64) -> [f64; 3] {
[
origin[0] + velocity[0] * t,
origin[1] + velocity[1] * t,
origin[2] + velocity[2] * t,
]
}
fn head_on() -> ConjunctionGeometry {
ConjunctionGeometry::new(
[120.0, -45.0, 30.0],
[-13_900.0, 900.0, 250.0],
spd([180.0, 40.0, 90.0, -25.0, 15.0, 60.0]),
spd([260.0, -70.0, 140.0, 30.0, -20.0, 110.0]),
3.0,
1.5,
)
}
fn frozen(geometry: &ConjunctionGeometry) -> impl FnMut(f64) -> RelativeSample + use<> {
let position = geometry.relative_position;
let velocity = geometry.relative_velocity;
let covariance = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
move |t| RelativeSample {
position: drift(position, velocity, t),
velocity,
covariance,
}
}
#[test]
fn the_rectilinear_curve_is_the_mahalanobis_distance_it_claims_to_be() {
let geometry = head_on();
let curve = RectilinearEncounter::from_geometry(&geometry).unwrap();
let inverse = inverse3(&sum3(
&geometry.primary_covariance,
&geometry.secondary_covariance,
));
let mut worst = 0.0_f64;
for offset in [-60.0, -12.5, 0.0, 3.25, 40.0] {
let direct = quadratic_form(
&inverse,
&drift(
geometry.relative_position,
geometry.relative_velocity,
offset,
),
);
let carried = curve.modified_mahalanobis(offset);
worst = worst.max((carried - direct).abs() / direct);
}
assert!(
worst < 1e-12,
"the quadratic and the direct form disagree by {worst:e}"
);
let v = geometry.relative_velocity;
let expected = libm::sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
assert!((curve.speed() - expected).abs() < 1e-9 * expected);
}
#[test]
fn a_determinant_that_grows_shifts_the_curve_by_the_log_of_the_volume_ratio() {
let isotropic = spd([100.0, 0.0, 100.0, 0.0, 0.0, 100.0]);
let geometry = ConjunctionGeometry::new(
[400.0, 0.0, 0.0],
[0.0, 7_500.0, 0.0],
isotropic,
isotropic,
1.0,
1.0,
);
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
assert_eq!(rectilinear.time_of_minimum(), 0.0, "the miss is transverse");
let base = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
let c = rectilinear.modified_mahalanobis(0.0);
let tau = rectilinear.width();
let curvilinear = CurvilinearEncounter::locate(&rectilinear, |t| {
let factor = libm::exp(t / tau);
let mut inflated = [[0.0_f64; 3]; 3];
for i in 0..3 {
for j in 0..3 {
inflated[i][j] = base[i][j] * factor;
}
}
RelativeSample {
position: [400.0, 0.0, 0.0],
velocity: geometry.relative_velocity,
covariance: inflated,
}
})
.unwrap();
let expected_minimum = 3.0 + 3.0 * libm::log(c / 3.0);
assert!(
(curvilinear.minimum() - expected_minimum).abs() < 1e-9 * libm::fabs(expected_minimum),
"M_min = {} against {expected_minimum}",
curvilinear.minimum()
);
let expected_time = tau * libm::log(c / 3.0);
assert!(
(curvilinear.time_of_minimum() - expected_time).abs() < 1e-6 * tau,
"T = {} against {expected_time}",
curvilinear.time_of_minimum()
);
let rise = |x: f64| 3.0 * (libm::exp(-x) + x - 1.0) - 1.0;
let slope = |x: f64| 3.0 * (1.0 - libm::exp(-x));
let root = |mut x: f64| {
for _ in 0..60 {
x -= rise(x) / slope(x);
}
x
};
let expected_width = tau * 0.5 * (root(1.0) - root(-1.0));
assert!(
(curvilinear.width() - expected_width).abs() < 1e-7 * expected_width,
"w = {} against {expected_width}",
curvilinear.width()
);
let violations = UsageViolations::assess(&rectilinear, &curvilinear, 5_400.0).unwrap();
let log_correction =
libm::log(expected_width / tau) - 0.5 * (expected_minimum - rectilinear.minimum());
let expected_factor = libm::exp(log_correction);
assert!(
(violations.correction_factor() - expected_factor).abs() < 1e-7 * expected_factor,
"F_c = {} against {expected_factor}",
violations.correction_factor()
);
let expected_indicator = 1.0 - libm::exp(-libm::fabs(log_correction));
assert!(
(violations.inaccuracy_indicator() - expected_indicator).abs() < 1e-7,
"V_i = {} against {expected_indicator}",
violations.inaccuracy_indicator()
);
assert!(violations.inaccuracy());
assert!(
violations.any(),
"an inaccuracy violation on its own is a usage violation"
);
}
#[test]
fn the_speed_ratio_enters_the_correction_factor_and_nothing_else_does() {
let geometry = head_on();
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let covariance = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
let position = geometry.relative_position;
let velocity = geometry.relative_velocity;
let ratio = 2.0;
let curvilinear = CurvilinearEncounter::locate(&rectilinear, |t| RelativeSample {
position: drift(position, velocity, t),
velocity: [
velocity[0] * ratio,
velocity[1] * ratio,
velocity[2] * ratio,
],
covariance,
})
.unwrap();
let violations = UsageViolations::assess(&rectilinear, &curvilinear, 5_400.0).unwrap();
assert!(
(violations.correction_factor() - ratio).abs() < 1e-9 * ratio,
"F_c = {} where only the speed ratio {ratio} differs",
violations.correction_factor()
);
assert!(
(violations.inaccuracy_indicator() - 0.5).abs() < 1e-9,
"V_i = {} where the closed form is 1 − 1/{ratio}",
violations.inaccuracy_indicator()
);
}
#[test]
fn the_closed_forms_summarise_the_curve_they_claim_to_summarise() {
let curve = RectilinearEncounter::from_geometry(&head_on()).unwrap();
let (peak, minimum, width) = (curve.time_of_minimum(), curve.minimum(), curve.width());
assert!((curve.modified_mahalanobis(peak) - minimum).abs() < 1e-9 * minimum.abs());
for step in [-4.0, -1.5, -0.25, 0.25, 1.5, 4.0] {
assert!(
curve.modified_mahalanobis(peak + step * width) > minimum,
"the claimed minimum is not one, {step} widths away"
);
}
for side in [-1.0, 1.0] {
let rise = curve.modified_mahalanobis(peak + side * width) - minimum;
assert!((rise - 1.0).abs() < 1e-9, "rise at one width is {rise}");
}
}
#[test]
fn the_duration_leaves_exactly_the_named_tail_outside_it() {
let curve = RectilinearEncounter::from_geometry(&head_on()).unwrap();
let argument = curve.duration() / (2.0 * libm::sqrt(2.0) * curve.width());
let tail = libm::erfc(argument);
assert!(
(tail - DURATION_TAIL_FRACTION).abs() < 1e-12 * DURATION_TAIL_FRACTION,
"the duration leaves {tail:e} outside it, not {DURATION_TAIL_FRACTION:e}"
);
}
#[test]
fn the_leo_thresholds_are_the_sixty_and_hundred_twenty_seconds_the_paper_names() {
let period = 100.0 * 60.0;
assert!((OFFSET_LIMIT * period - 60.0).abs() < 1e-12);
assert!((EXTENDED_LIMIT * period - 120.0).abs() < 1e-12);
}
#[test]
fn a_frozen_rectilinear_sampler_reproduces_the_closed_form_curve() {
let geometry = head_on();
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let curvilinear = CurvilinearEncounter::locate(&rectilinear, frozen(&geometry)).unwrap();
let width = rectilinear.width();
assert!(
(curvilinear.time_of_minimum() - rectilinear.time_of_minimum()).abs() < 1e-6 * width
);
assert!((curvilinear.minimum() - rectilinear.minimum()).abs() < 1e-9);
assert!((curvilinear.width() - width).abs() < 1e-9 * width);
assert!((curvilinear.speed() - rectilinear.speed()).abs() < 1e-12 * rectilinear.speed());
let violations = UsageViolations::assess(&rectilinear, &curvilinear, 5_400.0).unwrap();
assert!(
violations.inaccuracy_indicator() < 1e-9,
"V_i = {} on a trajectory that is rectilinear by construction",
violations.inaccuracy_indicator()
);
assert!((violations.correction_factor() - 1.0).abs() < 1e-9);
assert!(!violations.inaccuracy());
}
#[test]
fn a_bending_trajectory_is_flagged_where_the_straight_one_through_it_is_not() {
let geometry = ConjunctionGeometry::new(
[50.0, 0.0, 0.0],
[0.0, 1.0, 0.0],
spd([70.0, 0.0, 70.0, 0.0, 0.0, 70.0]),
spd([70.0, 0.0, 70.0, 0.0, 0.0, 70.0]),
2.0,
2.0,
);
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let straight = CurvilinearEncounter::locate(&rectilinear, frozen(&geometry)).unwrap();
let unflagged = UsageViolations::assess(&rectilinear, &straight, 5_400.0).unwrap();
assert!(!unflagged.inaccuracy());
let covariance = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
let bent = CurvilinearEncounter::locate(&rectilinear, |t| RelativeSample {
position: [50.0 + 0.5e-3 * t * t, t, 0.0],
velocity: [1.0e-3 * t, 1.0, 0.0],
covariance,
})
.unwrap();
let flagged = UsageViolations::assess(&rectilinear, &bent, 5_400.0).unwrap();
assert!(
flagged.inaccuracy(),
"V_i = {} on a trajectory bending away from the primary",
flagged.inaccuracy_indicator()
);
assert!(
flagged.correction_factor() < 1.0,
"F_c = {} where the curved trajectory misses by more than the straight one",
flagged.correction_factor()
);
}
#[test]
fn a_trajectory_bending_towards_the_primary_corrects_the_estimate_upwards() {
let geometry = ConjunctionGeometry::new(
[50.0, 0.0, 0.0],
[0.0, 1.0, 0.0],
spd([70.0, 0.0, 70.0, 0.0, 0.0, 70.0]),
spd([70.0, 0.0, 70.0, 0.0, 0.0, 70.0]),
2.0,
2.0,
);
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let covariance = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
let bent = CurvilinearEncounter::locate(&rectilinear, |t| RelativeSample {
position: [50.0 - 0.5e-3 * t * t, t, 0.0],
velocity: [-1.0e-3 * t, 1.0, 0.0],
covariance,
})
.unwrap();
let violations = UsageViolations::assess(&rectilinear, &bent, 5_400.0).unwrap();
assert!(
violations.correction_factor() > 1.0,
"F_c = {} where the curved trajectory passes closer than the straight one",
violations.correction_factor()
);
assert!(violations.inaccuracy());
}
#[test]
fn a_covariance_that_grows_through_the_encounter_is_flagged_on_its_own() {
let geometry = head_on();
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let position = geometry.relative_position;
let velocity = geometry.relative_velocity;
let covariance = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
let scale = rectilinear.width();
let growing = CurvilinearEncounter::locate(&rectilinear, |t| {
let factor = 1.0 + (t / scale) * (t / scale);
let mut inflated = [[0.0_f64; 3]; 3];
for i in 0..3 {
for j in 0..3 {
inflated[i][j] = covariance[i][j] * factor;
}
}
RelativeSample {
position: drift(position, velocity, t),
velocity,
covariance: inflated,
}
})
.unwrap();
let violations = UsageViolations::assess(&rectilinear, &growing, 5_400.0).unwrap();
assert!(
violations.inaccuracy(),
"V_i = {} on a covariance that triples in volume within one width",
violations.inaccuracy_indicator()
);
}
#[test]
fn a_minimum_off_the_other_end_of_every_window_is_refused_too() {
let geometry = head_on();
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let covariance = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
let velocity = geometry.relative_velocity;
let far = -1.0e6;
let outcome = CurvilinearEncounter::locate(&rectilinear, |t| RelativeSample {
position: drift([0.0, 0.0, 0.0], velocity, t - far),
velocity,
covariance,
});
assert_eq!(outcome, Err(DomainError::CurvilinearMinimumNotBracketed));
}
fn slow_pair() -> ConjunctionGeometry {
ConjunctionGeometry::new(
[50.0, 0.0, 0.0],
[0.0, 1.0, 0.0],
spd([70.0, 0.0, 70.0, 0.0, 0.0, 70.0]),
spd([70.0, 0.0, 70.0, 0.0, 0.0, 70.0]),
2.0,
2.0,
)
}
#[test]
fn a_minimum_the_first_window_misses_is_found_by_the_second() {
let geometry = slow_pair();
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let covariance = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
let position = geometry.relative_position;
let velocity = geometry.relative_velocity;
let width = rectilinear.width();
let duration = rectilinear.duration();
for offset in [1_500.0_f64, 1_530.0, 1_560.0] {
assert!(
offset > duration && offset < 2.0 * duration,
"{offset} is not between one window and two"
);
let shifted = CurvilinearEncounter::locate(&rectilinear, |t| RelativeSample {
position: drift(position, velocity, t - offset),
velocity,
covariance,
})
.unwrap();
assert!(
(shifted.time_of_minimum() - offset).abs() < 1e-6 * width,
"T = {} against a curve translated to {offset}",
shifted.time_of_minimum()
);
assert!((shifted.minimum() - rectilinear.minimum()).abs() < 1e-9);
assert!((shifted.width() - width).abs() < 1e-9 * width);
}
}
#[test]
fn a_width_the_seed_does_not_reach_is_found_by_doubling() {
const STRETCH: f64 = 20.0;
let geometry = slow_pair();
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let covariance = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
let position = geometry.relative_position;
let velocity = geometry.relative_velocity;
let stretched = CurvilinearEncounter::locate(&rectilinear, |t| RelativeSample {
position: drift(position, velocity, t / STRETCH),
velocity,
covariance,
})
.unwrap();
let expected = STRETCH * rectilinear.width();
assert!(
(stretched.width() - expected).abs() < 1e-9 * expected,
"w = {} against {expected}",
stretched.width()
);
}
#[test]
fn every_refusal_names_the_input_it_refused() {
let messages = [
(
DomainError::NonFiniteState,
"relative position or velocity at TCA is not finite",
),
(
DomainError::NonPositiveDefiniteCovariance,
"joint position covariance at TCA is not positive definite; no Mahalanobis distance is defined",
),
(
DomainError::DegenerateEncounterVelocity,
"relative velocity is zero or not finite",
),
(
DomainError::NonPositiveDefiniteSample,
"sampled joint covariance is not positive definite",
),
(
DomainError::NonFiniteSample,
"sampled trajectory gave a non-finite Mahalanobis distance",
),
(
DomainError::InvalidOrbitalPeriod,
"minimum orbital period is not finite and positive",
),
(
DomainError::CurvilinearMinimumNotBracketed,
"curvilinear Mahalanobis minimum lies outside every window the search opened",
),
(
DomainError::CurvilinearWidthNotBracketed,
"curvilinear Mahalanobis curve does not rise by one within the widths searched",
),
];
for (error, expected) in messages {
assert_eq!(format!("{error}"), expected);
let dynamic: &dyn core::error::Error = &error;
assert_eq!(format!("{dynamic}"), expected);
}
}
#[test]
fn the_offset_check_stands_on_both_sides_of_its_threshold() {
let isotropic = spd([100.0, 0.0, 100.0, 0.0, 0.0, 100.0]);
let velocity = [0.0, 7_500.0, 0.0];
let period = 6_000.0;
let slide = |d: f64| {
let geometry = ConjunctionGeometry::new(
[200.0, velocity[1] * d, 0.0],
velocity,
isotropic,
isotropic,
1.0,
1.0,
);
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let curvilinear =
CurvilinearEncounter::locate(&rectilinear, frozen(&geometry)).unwrap();
UsageViolations::assess(&rectilinear, &curvilinear, period).unwrap()
};
let at_threshold = slide(OFFSET_LIMIT * period);
assert!(
(at_threshold.offset_indicator() - OFFSET_LIMIT).abs() < 1e-12,
"V_o = {} where the construction says {OFFSET_LIMIT}",
at_threshold.offset_indicator()
);
assert!(
!at_threshold.offset(),
"the threshold itself is not above it"
);
assert!(
!at_threshold.any(),
"at this geometry the offset check is the only one that can flag, and it does not"
);
assert!(
slide(-OFFSET_LIMIT * period - 1.0).offset(),
"a minimum one second before TCA-minus-sixty is a violation, sign notwithstanding"
);
let over = slide(OFFSET_LIMIT * period + 1.0);
assert!(over.offset());
assert!(
over.any(),
"an offset violation on its own is a usage violation"
);
}
#[test]
fn the_extended_check_stands_on_both_sides_of_its_threshold() {
let isotropic = spd([100.0, 0.0, 100.0, 0.0, 0.0, 100.0]);
let geometry = ConjunctionGeometry::new(
[200.0, 0.0, 0.0],
[0.0, 7_500.0, 0.0],
isotropic,
isotropic,
1.0,
1.0,
);
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
assert_eq!(rectilinear.time_of_minimum(), 0.0, "the miss is transverse");
let curvilinear = CurvilinearEncounter::locate(&rectilinear, frozen(&geometry)).unwrap();
let duration = rectilinear.duration();
let at_threshold =
UsageViolations::assess(&rectilinear, &curvilinear, duration / EXTENDED_LIMIT).unwrap();
assert!((at_threshold.extended_indicator() - EXTENDED_LIMIT).abs() < 1e-12);
assert!(!at_threshold.extended());
assert!(!at_threshold.any(), "the threshold itself flags nothing");
let over = UsageViolations::assess(
&rectilinear,
&curvilinear,
duration / (EXTENDED_LIMIT + 1e-3),
)
.unwrap();
assert!(over.extended());
assert_eq!(over.offset_indicator(), 0.0);
assert!(
over.any(),
"an extended-duration violation on its own is a usage violation"
);
}
#[test]
fn an_object_covariance_that_is_not_positive_definite_is_a_flag_and_not_a_refusal() {
let singular = [[100.0, 0.0, 0.0], [0.0, 100.0, 0.0], [0.0, 0.0, 0.0]];
let geometry = ConjunctionGeometry::new(
[120.0, -45.0, 30.0],
[-7_100.0, 900.0, 250.0],
singular,
spd([180.0, 40.0, 90.0, -25.0, 15.0, 60.0]),
3.0,
1.5,
);
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
assert!(rectilinear.non_positive_definite());
let curvilinear = CurvilinearEncounter::locate(&rectilinear, frozen(&geometry)).unwrap();
let violations = UsageViolations::assess(&rectilinear, &curvilinear, 5_400.0).unwrap();
assert!(violations.non_positive_definite());
assert!(violations.any());
}
#[test]
fn a_joint_covariance_that_is_not_positive_definite_is_a_refusal() {
let flat = [[100.0, 0.0, 0.0], [0.0, 100.0, 0.0], [0.0, 0.0, 0.0]];
let geometry =
ConjunctionGeometry::new([1.0, 2.0, 3.0], [-7_100.0, 0.0, 0.0], flat, flat, 1.0, 1.0);
assert_eq!(
RectilinearEncounter::from_geometry(&geometry),
Err(DomainError::NonPositiveDefiniteCovariance)
);
}
#[test]
fn a_zero_relative_velocity_has_no_curve_and_says_so() {
let covariance = spd([100.0, 0.0, 100.0, 0.0, 0.0, 100.0]);
let geometry = ConjunctionGeometry::new(
[1.0, 2.0, 3.0],
[0.0, 0.0, 0.0],
covariance,
covariance,
1.0,
1.0,
);
assert_eq!(
RectilinearEncounter::from_geometry(&geometry),
Err(DomainError::DegenerateEncounterVelocity)
);
}
#[test]
fn a_non_finite_relative_state_is_named_for_what_it_is() {
let covariance = spd([100.0, 0.0, 100.0, 0.0, 0.0, 100.0]);
for state in [
([f64::NAN, 2.0, 3.0], [-7_100.0, 0.0, 0.0]),
([1.0, 2.0, 3.0], [-7_100.0, f64::INFINITY, 0.0]),
] {
let geometry =
ConjunctionGeometry::new(state.0, state.1, covariance, covariance, 1.0, 1.0);
assert_eq!(
RectilinearEncounter::from_geometry(&geometry),
Err(DomainError::NonFiniteState)
);
}
}
#[test]
fn a_period_that_is_not_a_period_is_refused_before_a_single_propagation() {
let geometry = head_on();
for period in [0.0, -5_400.0, f64::NAN, f64::INFINITY] {
let mut calls = 0usize;
let outcome = usage_violations(&geometry, period, |t| {
calls += 1;
frozen(&geometry)(t)
});
assert_eq!(outcome, Err(DomainError::InvalidOrbitalPeriod));
assert_eq!(calls, 0, "the sampler ran for a period of {period}");
}
}
#[test]
fn a_minimum_outside_every_window_the_search_opens_is_refused() {
let geometry = head_on();
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let covariance = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
let velocity = geometry.relative_velocity;
let far = 1.0e6;
let outcome = CurvilinearEncounter::locate(&rectilinear, |t| RelativeSample {
position: drift([0.0, 0.0, 0.0], velocity, t - far),
velocity,
covariance,
});
assert_eq!(outcome, Err(DomainError::CurvilinearMinimumNotBracketed));
}
#[test]
fn a_curve_too_flat_to_have_a_width_is_refused() {
let isotropic = spd([300.0, 0.0, 300.0, 0.0, 0.0, 300.0]);
let geometry = ConjunctionGeometry::new(
[400.0, 0.0, 0.0],
[0.0, 7_500.0, 0.0],
isotropic,
isotropic,
1.0,
1.0,
);
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
assert_eq!(rectilinear.time_of_minimum(), 0.0, "the miss is transverse");
let stop = 0.5 * rectilinear.width();
let covariance = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
let position = geometry.relative_position;
let velocity = geometry.relative_velocity;
let outcome = CurvilinearEncounter::locate(&rectilinear, |t| RelativeSample {
position: drift(position, velocity, t.clamp(-stop, stop)),
velocity,
covariance,
});
assert_eq!(outcome, Err(DomainError::CurvilinearWidthNotBracketed));
}
#[test]
fn a_sampler_that_stops_being_a_trajectory_ends_the_search() {
let geometry = head_on();
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let covariance = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
let velocity = geometry.relative_velocity;
let non_finite = CurvilinearEncounter::locate(&rectilinear, |_| RelativeSample {
position: [f64::NAN, 0.0, 0.0],
velocity,
covariance,
});
assert_eq!(non_finite, Err(DomainError::NonFiniteSample));
let singular = CurvilinearEncounter::locate(&rectilinear, |t| RelativeSample {
position: drift(geometry.relative_position, velocity, t),
velocity,
covariance: [[100.0, 0.0, 0.0], [0.0, 100.0, 0.0], [0.0, 0.0, 0.0]],
});
assert_eq!(singular, Err(DomainError::NonPositiveDefiniteSample));
}
#[test]
fn a_zero_relative_speed_at_the_curvilinear_minimum_is_refused() {
let geometry = head_on();
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let covariance = sum3(&geometry.primary_covariance, &geometry.secondary_covariance);
let velocity = geometry.relative_velocity;
let outcome = CurvilinearEncounter::locate(&rectilinear, |t| RelativeSample {
position: drift(geometry.relative_position, velocity, t),
velocity: [0.0, 0.0, 0.0],
covariance,
});
assert_eq!(outcome, Err(DomainError::DegenerateEncounterVelocity));
}
fn any_geometry() -> impl Strategy<Value = ConjunctionGeometry> {
(
proptest::array::uniform3(-2_000.0_f64..2_000.0),
proptest::array::uniform3(-9_000.0_f64..9_000.0),
proptest::array::uniform6(-300.0_f64..300.0),
proptest::array::uniform6(-300.0_f64..300.0),
5.0_f64..900.0,
5.0_f64..900.0,
)
.prop_map(
|(position, velocity, mut first, mut second, floor, ceiling)| {
for (entries, scale) in [(&mut first, floor), (&mut second, ceiling)] {
entries[0] = entries[0].abs() + scale;
entries[2] = entries[2].abs() + scale;
entries[5] = entries[5].abs() + scale;
}
let speed = velocity[0].abs() + velocity[1].abs() + velocity[2].abs();
let velocity = if speed < 1.0 {
[1.0, 0.0, 0.0]
} else {
velocity
};
ConjunctionGeometry::new(position, velocity, spd(first), spd(second), 3.0, 2.0)
},
)
}
proptest! {
#[test]
fn the_carried_quadratic_is_the_direct_mahalanobis_distance(
geometry in any_geometry(),
offset in -400.0_f64..400.0,
) {
let curve = RectilinearEncounter::from_geometry(&geometry).unwrap();
let inverse = inverse3(&sum3(&geometry.primary_covariance, &geometry.secondary_covariance));
let direct = quadratic_form(
&inverse,
&drift(geometry.relative_position, geometry.relative_velocity, offset),
);
let carried = curve.modified_mahalanobis(offset);
prop_assert!(
(carried - direct).abs() <= 1e-9 * direct.abs().max(1.0),
"carried {carried} against direct {direct}"
);
}
#[test]
fn a_rectilinear_sampler_never_registers_an_inaccuracy_violation(
geometry in any_geometry(),
) {
let rectilinear = RectilinearEncounter::from_geometry(&geometry).unwrap();
let curvilinear = CurvilinearEncounter::locate(&rectilinear, frozen(&geometry)).unwrap();
let violations = UsageViolations::assess(&rectilinear, &curvilinear, 5_400.0).unwrap();
prop_assert!(
violations.inaccuracy_indicator() < 1e-6,
"V_i = {} with F_c = {}",
violations.inaccuracy_indicator(),
violations.correction_factor()
);
prop_assert!(!violations.inaccuracy());
}
}
}