use thiserror::Error;
#[derive(Clone, Copy, Debug, Eq, PartialEq, Error)]
pub enum CoordinateError {
#[error("axis coordinates are unknown")]
Unknown,
#[error("coordinate index {index} exceeds {points} points")]
OutOfBounds {
index: usize,
points: usize,
},
}
pub(crate) fn coordinate(
coordinates: &AxisCoordinates,
points: usize,
index: usize,
) -> Result<f64, CoordinateError> {
if index >= points {
return Err(CoordinateError::OutOfBounds { index, points });
}
match coordinates {
AxisCoordinates::Unknown => Err(CoordinateError::Unknown),
AxisCoordinates::Uniform { start, step } => Ok(step.mul_add(index as f64, *start)),
AxisCoordinates::Explicit(values) => Ok(values[index]),
}
}
pub struct CoordinateIter<'a> {
coordinates: &'a AxisCoordinates,
indices: std::ops::Range<usize>,
}
impl<'a> CoordinateIter<'a> {
pub(crate) fn new(
coordinates: &'a AxisCoordinates,
points: usize,
) -> Result<Self, CoordinateError> {
if matches!(coordinates, AxisCoordinates::Unknown) {
return Err(CoordinateError::Unknown);
}
Ok(Self {
coordinates,
indices: 0..points,
})
}
}
impl Iterator for CoordinateIter<'_> {
type Item = f64;
fn next(&mut self) -> Option<f64> {
let index = self.indices.next()?;
Some(match self.coordinates {
AxisCoordinates::Uniform { start, step } => step.mul_add(index as f64, *start),
AxisCoordinates::Explicit(values) => values[index],
AxisCoordinates::Unknown => unreachable!("checked coordinate iterator"),
})
}
fn size_hint(&self) -> (usize, Option<usize>) {
self.indices.size_hint()
}
}
impl ExactSizeIterator for CoordinateIter<'_> {}
impl std::iter::FusedIterator for CoordinateIter<'_> {}
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum AxisDomain {
Time,
Frequency,
Parameter,
Unknown,
}
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum AxisRole {
DirectAcquisition,
IndirectAcquisition,
ArrayParameter,
Signal,
Unknown,
}
impl AxisRole {
pub(crate) fn is_signal(self) -> bool {
matches!(
self,
Self::DirectAcquisition | Self::IndirectAcquisition | Self::Signal
)
}
}
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum AxisUnit {
Second,
Hertz,
Ppm,
Tesla,
TeslaPerMeter,
}
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum AxisQuantity {
MagneticFieldGradientStrength,
TimeDelay,
}
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq)]
pub enum AxisCoordinates {
Unknown,
Uniform {
start: f64,
step: f64,
},
Explicit(Vec<f64>),
}
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum AxisDirection {
Ascending,
Descending,
Unknown,
}
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct FrequencyEvidence {
observe_frequency_mhz: Option<f64>,
transmitter_offset_hz: Option<f64>,
}
impl FrequencyEvidence {
pub fn new(
observe_frequency_mhz: Option<f64>,
transmitter_offset_hz: Option<f64>,
) -> Result<Self, AxisValidationError> {
let value = Self {
observe_frequency_mhz,
transmitter_offset_hz,
};
value.validate()?;
Ok(value)
}
pub fn observe_frequency_mhz(&self) -> Option<f64> {
self.observe_frequency_mhz
}
pub fn transmitter_offset_hz(&self) -> Option<f64> {
self.transmitter_offset_hz
}
pub(crate) fn validate(&self) -> Result<(), AxisValidationError> {
for (name, value, positive) in [
("observe frequency", self.observe_frequency_mhz, true),
("transmitter offset", self.transmitter_offset_hz, false),
] {
if value.is_some_and(|v| !v.is_finite() || positive && v <= 0.0) {
return Err(AxisValidationError::InvalidNumber(name));
}
}
Ok(())
}
}
#[non_exhaustive]
#[derive(Clone, Debug, Error, Eq, PartialEq)]
pub enum AxisValidationError {
#[error("axis has zero points")]
ZeroPoints,
#[error("axis coordinates are invalid for the declared domain")]
InvalidCoordinates,
#[error("axis domain, unit, and coordinates disagree")]
DomainContractMismatch,
#[error("axis quantity, role, domain, and unit disagree")]
QuantityContractMismatch,
#[error("invalid numeric value for {0}")]
InvalidNumber(&'static str),
}
pub(crate) fn validate_quantity(
role: AxisRole,
domain: AxisDomain,
unit: Option<AxisUnit>,
quantity: Option<AxisQuantity>,
) -> Result<(), AxisValidationError> {
let Some(quantity) = quantity else {
return Ok(());
};
if role != AxisRole::ArrayParameter || domain != AxisDomain::Parameter {
return Err(AxisValidationError::QuantityContractMismatch);
}
let matches = match quantity {
AxisQuantity::MagneticFieldGradientStrength => unit == Some(AxisUnit::TeslaPerMeter),
AxisQuantity::TimeDelay => unit == Some(AxisUnit::Second),
};
matches
.then_some(())
.ok_or(AxisValidationError::QuantityContractMismatch)
}
pub(crate) fn validate_axis(
domain: AxisDomain,
unit: Option<AxisUnit>,
points: usize,
coordinates: &AxisCoordinates,
) -> Result<(), AxisValidationError> {
if points == 0 {
return Err(AxisValidationError::ZeroPoints);
}
match coordinates {
AxisCoordinates::Unknown => {}
AxisCoordinates::Uniform { start, step } => {
if !start.is_finite() || !step.is_finite() || points > 1 && *step == 0.0 {
return Err(AxisValidationError::InvalidCoordinates);
}
validate_uniform(*start, *step, points)?;
}
AxisCoordinates::Explicit(values) => {
if values.len() != points || values.iter().any(|value| !value.is_finite()) {
return Err(AxisValidationError::InvalidCoordinates);
}
}
}
let contract_matches = match domain {
AxisDomain::Time => unit == Some(AxisUnit::Second),
AxisDomain::Frequency => {
matches!(unit, Some(AxisUnit::Hertz | AxisUnit::Ppm))
&& !matches!(coordinates, AxisCoordinates::Unknown)
}
AxisDomain::Parameter => true,
AxisDomain::Unknown => unit.is_none() && matches!(coordinates, AxisCoordinates::Unknown),
};
if !contract_matches {
return Err(AxisValidationError::DomainContractMismatch);
}
if matches!(domain, AxisDomain::Time | AxisDomain::Frequency)
&& points > 1
&& !matches!(coordinates, AxisCoordinates::Unknown)
&& direction(coordinates, points) == AxisDirection::Unknown
{
return Err(AxisValidationError::InvalidCoordinates);
}
Ok(())
}
fn validate_uniform(start: f64, step: f64, points: usize) -> Result<(), AxisValidationError> {
let invalid = AxisValidationError::InvalidCoordinates;
if (points - 1) as u128 > (1_u128 << 53) {
return Err(invalid);
}
let last = step.mul_add((points - 1) as f64, start);
if !last.is_finite() {
return Err(invalid);
}
if points == 1 {
return Ok(());
}
let exponent = ((start.abs().max(last.abs()).to_bits() >> 52) & 0x7ff) as u32;
let resolution = if exponent > 52 {
f64::from_bits(u64::from(exponent - 52) << 52)
} else {
f64::from_bits(1_u64 << exponent.saturating_sub(1))
};
if step.abs() > resolution || (step.abs() == resolution && (start / resolution).fract() == 0.0)
{
return Ok(());
}
let mut previous = start;
for index in 1..points {
let current = step.mul_add(index as f64, start);
if (step > 0.0 && current <= previous) || (step < 0.0 && current >= previous) {
return Err(invalid);
}
previous = current;
}
Ok(())
}
pub(crate) fn direction(coordinates: &AxisCoordinates, points: usize) -> AxisDirection {
if points <= 1 {
return AxisDirection::Unknown;
}
match coordinates {
AxisCoordinates::Uniform { step, .. } if *step > 0.0 => AxisDirection::Ascending,
AxisCoordinates::Uniform { step, .. } if *step < 0.0 => AxisDirection::Descending,
AxisCoordinates::Explicit(values) => {
let ascending = values.windows(2).all(|pair| pair[0] < pair[1]);
let descending = values.windows(2).all(|pair| pair[0] > pair[1]);
match (ascending, descending) {
(true, false) => AxisDirection::Ascending,
(false, true) => AxisDirection::Descending,
_ => AxisDirection::Unknown,
}
}
_ => AxisDirection::Unknown,
}
}
pub(crate) fn coordinate_span(coordinates: &AxisCoordinates, points: usize) -> Option<f64> {
if points <= 1 {
return None;
}
let span = match coordinates {
AxisCoordinates::Uniform { step, .. } => step.abs() * (points - 1) as f64,
AxisCoordinates::Explicit(values) => (values.last()? - values.first()?).abs(),
AxisCoordinates::Unknown => return None,
};
span.is_finite().then_some(span)
}
impl FrequencyEvidence {
#[allow(clippy::type_complexity)]
pub(crate) fn model_parts(&self) -> (&Option<f64>, &Option<f64>) {
(&self.observe_frequency_mhz, &self.transmitter_offset_hz)
}
#[allow(clippy::type_complexity)]
pub(crate) fn from_model_parts(
parts: (Option<f64>, Option<f64>),
) -> Result<Self, crate::internal::ModelError> {
let (observe_frequency_mhz, transmitter_offset_hz) = parts;
let value = Self {
observe_frequency_mhz,
transmitter_offset_hz,
};
value
.validate()
.map_err(|e| crate::internal::ModelError::Validation(e.to_string()))?;
Ok(value)
}
}