Module source_localization 

Source localization from arrival times.

This sans-I/O module solves for an event position from sensors at known Cartesian coordinates. Coordinates are metres in a caller-chosen 2D or 3D frame, times are seconds, and propagation speeds are metres per second.

Measurement models

Absolute time of arrival (ToA) uses

t_i = t0 + ||x - s_i|| / c_i,

with state [x, t0]: two or three position coordinates followed by the origin time. Time difference of arrival (TDOA) uses

t_i - t_ref = ||x - s_i|| / c_i - ||x - s_ref|| / c_ref,

with position-only state [x]. After a TDOA position solve, the origin time is recovered from the absolute arrivals. Linear loss uses their arithmetic mean exactly; a non-linear loss applies one iteratively reweighted refinement so an arrival downweighted by the position solve is also downweighted in the reported time.

Both modes require at least dimension + 1 sensors: three in 2D or four in 3D. The closed-form seed is the spherical-intersection linearization of H. C. Schau and A. Z. Robinson, IEEE Transactions on Acoustics, Speech, and Signal Processing 35(8), 1987, followed by a quadratic in the reference range (TDOA) or emission-distance unknown c * t0 (ToA). See closed_form_initial_guess.

The solution covariance is (J^T J)^-1 * timing_sigma_s^2, formed from the retained singular vectors and values of the final Jacobian. At the fitted state this is the local estimate covariance. source_crlb evaluates the same timing-information interpretation at a proposed source point through the shared DOP machinery, where it is a Cramer-Rao lower bound (CRLB).

By default locate_source also measures each sensor’s influence by running one complete nonlinear leave-one-out solve per sensor. Each record reports the full-solution ToA residual, held-out ToA residual, state displacement, robust-loss weight, and normalized residual magnitude. Call locate_source_with with a SourceLocateConfig whose include_influence is false to skip those re-solves.

Example

use sidereon_core::source_localization::{
    locate_source_with, Sensor, SourceLocateConfig, SourceLocateOptions, SourceSolveMode,
};

let sensors = vec![
    Sensor::new(vec![0.0, 0.0]),
    Sensor::new(vec![100.0, 0.0]),
    Sensor::new(vec![0.0, 100.0]),
    Sensor::new(vec![100.0, 100.0]),
];
let source_m = [30.0, 40.0];
let origin_time_s = 2.0;
let propagation_speed_m_s = 50.0;
let arrival_times_s = sensors
    .iter()
    .map(|sensor| {
        let dx = source_m[0] - sensor.position_m[0];
        let dy = source_m[1] - sensor.position_m[1];
        origin_time_s + (dx * dx + dy * dy).sqrt() / propagation_speed_m_s
    })
    .collect::<Vec<_>>();

let options = SourceLocateOptions {
    mode: SourceSolveMode::Toa,
    ..SourceLocateOptions::default()
};
let mut config = SourceLocateConfig::from(options);
config.include_influence = false;
let solution = locate_source_with(
    &sensors,
    &arrival_times_s,
    propagation_speed_m_s,
    &config,
)?;

assert!((solution.position_m[0] - source_m[0]).abs() < 1.0e-8);
assert!((solution.position_m[1] - source_m[1]).abs() < 1.0e-8);
assert!((solution.origin_time_s.unwrap() - origin_time_s).abs() < 1.0e-10);

Structs

Sensor

A sensor with a known Cartesian position.

SourceCovariance

Timing-information covariance for a source state.

SourceCrlb

CRLB and DOP for a proposed sensor/source geometry.

SourceInitialGuess

Closed-form seed used to start the iterative solve.

SourceLocateConfig

Full configuration for locate_source_with.

SourceLocateOptions

Options for locate_source.

SourceResidual

One residual associated with a sensor row.

SourceSensorInfluence

Per-sensor leave-one-out diagnostic.

SourceSolution

Source solution from locate_source.

Enums

Loss

SciPy’s loss selector for least_squares.

SourceLocalizationError

Source-localization failure.

SourceSolveMode

Measurement model used by locate_source.

Functions

chan_ho_initial_guessDeprecated

Deprecated name for closed_form_initial_guess.

closed_form_initial_guess

Compute the closed-form spherical-intersection seed used by locate_source.

locate_source

Locate a source from sensor arrival times.

locate_source_with

Locate a source from sensor arrival times with a full SourceLocateConfig.

source_crlb

Compute a timing CRLB for a proposed source location.

source_dop

Compute timing DOP for a proposed source location.