Skip to content

IOD Parameters

py_outfit.iod_params.IODParams 

IODParams()

Configuration for Gauss Initial Orbit Determination (IOD).

Purpose

This configuration centralizes all tunable parameters used by the Gauss pipeline. It covers candidate triplet selection, Monte Carlo perturbations, physical and numerical filters, solver tolerances, and RMS evaluation. The objective is to allow fine-grained control over the Gauss IOD process in a single container object.

Pipeline overview

The pipeline proceeds in four main stages:

  1. Triplet generation. Candidate observation triplets are constrained by dt_min, dt_max_triplet, and optimal_interval_time. Oversized datasets may be downsampled to max_obs_for_triplets before selection.

  2. Monte Carlo perturbation. Each triplet is expanded into multiple noisy copies (n_noise_realizations) drawn from Gaussian perturbations scaled by noise_scale.

  3. Orbit computation and filtering. Candidate orbits are produced by the Gauss solver and filtered by physical plausibility (max_ecc, max_perihelion_au, r2_min_au, r2_max_au, min_rho2_au) and numerical tolerances (newton_eps, newton_max_it, root_imag_eps, aberth_max_iter, aberth_eps, kepler_eps). A maximum of max_tested_solutions is retained.

  4. RMS evaluation. Candidates are scored by RMS residuals in a time window derived from extf × (triplet span) and clamped to at least dtmax. The candidate with the lowest RMS is selected.

Defaults

The default values are as follows (matching the Rust Default implementation).

  1. Triplet / Monte Carlo parameters:

    • n_noise_realizations : 20
    • noise_scale : 1.0
    • extf : -1.0 (negative = broad fallback window)
    • dtmax : 30.0 (days)
    • dt_min : 0.03 (days)
    • dt_max_triplet : 150.0 (days)
    • optimal_interval_time: 20.0 (days)
    • max_obs_for_triplets : 100
    • max_triplets : 10
    • gap_max : 8/24 (days; 8 hours)

  2. Physical filters:

    • max_ecc : 5.0
    • max_perihelion_au : 1.0e3
    • min_rho2_au : 0.01 (AU)

  3. Heliocentric r2 bounds:

    • r2_min_au : 0.05 (AU)
    • r2_max_au : 200.0 (AU)

  4. Polynomial solver / numerics:

    • aberth_max_iter : 50
    • aberth_eps : 1.0e-6
    • kepler_eps : ≈ 2.22e-13 (1e3 × machine epsilon)
    • newton_eps : 1.0e-10
    • newton_max_it : 50
    • root_imag_eps : 1.0e-6

  5. Parallelization:

    • batch_size : 4 (only effective if compiled with parallel features)
Notes

RMS evaluation window is computed as: dt_window = (last − first) × extf, clamped so that dt_window ≥ dtmax. If extf < 0, a broad fallback window is used (typically a multiple of the dataset span).

The parameter min_rho2_au applies a topocentric distance constraint at the central epoch to avoid near-observer pathologies.

Bounds r2_min_au ≤ r2_max_au provide plausibility constraints for the heliocentric distance when selecting roots of the degree-8 Gauss polynomial.

Typical constraints are: max_ecc ≥ 0, max_perihelion_au > 0, min_rho2_au > 0, aberth_max_iter ≥ 1, aberth_eps > 0, kepler_eps > 0, newton_eps > 0, newton_max_it ≥ 1, root_imag_eps ≥ 0, max_tested_solutions ≥ 1.

n_noise_realizations property 

n_noise_realizations: int

Number of Monte Carlo perturbations per original triplet. Default: 20.

noise_scale property 

noise_scale: float

Scale applied to nominal RA/DEC uncertainties (1.0 ⇒ nominal). Default: 1.0.

extf property 

extf: float

Extrapolation factor for the RMS evaluation window: dt_window = (triplet span) × extf, then clamped so dt_window ≥ dtmax. Negative values trigger a broad fallback window. Default: -1.0.

dtmax property 

dtmax: float

Floor (days) for the RMS evaluation window. Default: 30.0.

dt_min property 

dt_min: float

Minimum allowed span (days) between the first and last observations in a triplet. Default: 0.03.

dt_max_triplet property 

dt_max_triplet: float

Maximum allowed span (days) within any candidate triplet. Default: 150.0.

optimal_interval_time property 

optimal_interval_time: float

Target intra-triplet spacing (days) to favor well-separated observations. Default: 20.0.

max_obs_for_triplets property 

max_obs_for_triplets: int

Cap on observations used to build triplets (with uniform downsampling if exceeded). Default: 100.

max_triplets property 

max_triplets: int

Maximum number of triplets evaluated per trajectory (post-filter). Default: 10.

gap_max property 

gap_max: float

Maximum allowed intra-batch time gap (days) for RMS calibration. Default: 8/24 (≈ 0.3333).

max_ecc property 

max_ecc: float

Maximum accepted eccentricity. Default: 5.0.

max_perihelion_au property 

max_perihelion_au: float

Maximum accepted perihelion distance (AU). Default: 1.0e3.

min_rho2_au property 

min_rho2_au: float

Minimum admissible topocentric distance at the central epoch (AU). Default: 0.01.

r2_min_au property 

r2_min_au: float

Lower plausibility bound on central heliocentric distance (AU). Default: 0.05.

r2_max_au property 

r2_max_au: float

Upper plausibility bound on central heliocentric distance (AU). Default: 200.0.

aberth_max_iter property 

aberth_max_iter: int

Maximum iterations for the Aberth–Ehrlich polynomial solver. Default: 50.

aberth_eps property 

aberth_eps: float

Convergence tolerance for the Aberth solver. Default: 1.0e-6.

kepler_eps property 

kepler_eps: float

Tolerance used by the universal Kepler solver in velocity correction. Default: 1e3 * f64::EPSILON.

max_tested_solutions property 

max_tested_solutions: int

Cap on admissible Gauss solutions kept after root finding. Default: 3.

newton_eps property 

newton_eps: float

Absolute tolerance for Newton–Raphson inner solves. Default: 1.0e-10.

newton_max_it property 

newton_max_it: int

Maximum iterations for Newton–Raphson inner solves. Default: 50.

root_imag_eps property 

root_imag_eps: float

Max imaginary part magnitude to treat a complex root as real. Default: 1.0e-6.

batch_size property 

batch_size: int

Batch size for parallel trajectory processing. Only effective if the crate is compiled with the parallel/rayon feature. Default: 4.

do_parallel property 

do_parallel: bool

Whether this configuration requests parallel execution in higher-level APIs.

Notes

This is carried alongside IODParams in the Python binding and consumed by callers (the core Rust struct is independent of this advisory flag).

builder staticmethod 

builder() -> IODParamsBuilder

Create a new IODParamsBuilder initialized with the Default values listed above.

RETURNS DESCRIPTION
IODParamsBuilder

A fresh builder to customize and produce an IODParams.

py_outfit.iod_params.IODParamsBuilder 

IODParamsBuilder()

Fluent builder for IODParams.

Defaults

The builder starts with the exact defaults documented in IODParams (see there).

n_noise_realizations 

n_noise_realizations(v: int) -> IODParamsBuilder

Set the number of Monte Carlo perturbations per original triplet. Default: 20.

noise_scale 

noise_scale(v: float) -> IODParamsBuilder

Set the scale applied to nominal astrometric uncertainties. Default: 1.0.

extf 

extf(v: float) -> IODParamsBuilder

Set the extrapolation factor for the RMS window (negative ⇒ broad fallback). Window formula: dt_window = (triplet span) × v, then clamp ≥ dtmax. Default: -1.0.

dtmax 

dtmax(v: float) -> IODParamsBuilder

Set the minimum RMS window size (days). Default: 30.0.

dt_min 

dt_min(v: float) -> IODParamsBuilder

Set the minimum allowed span (days) between first and last obs in a triplet. Default: 0.03.

dt_max_triplet 

dt_max_triplet(v: float) -> IODParamsBuilder

Set the maximum allowed span (days) within a triplet. Default: 150.0.

optimal_interval_time 

optimal_interval_time(v: float) -> IODParamsBuilder

Set the target intra-triplet spacing (days). Default: 20.0.

max_obs_for_triplets 

max_obs_for_triplets(v: int) -> IODParamsBuilder

Cap observations used to build triplets (uniform downsampling if exceeded). Default: 100.

max_triplets 

max_triplets(v: int) -> IODParamsBuilder

Cap the number of triplets evaluated per trajectory. Default: 10.

gap_max 

gap_max(v: float) -> IODParamsBuilder

Set the maximum intra-batch time gap (days) for RMS calibration. Default: 8/24.

max_ecc 

max_ecc(v: float) -> IODParamsBuilder

Set the maximum eccentricity accepted. Default: 5.0.

max_perihelion_au 

max_perihelion_au(v: float) -> IODParamsBuilder

Set the maximum perihelion distance (AU). Default: 1.0e3.

min_rho2_au 

min_rho2_au(v: float) -> IODParamsBuilder

Set the minimum topocentric distance at the central epoch (AU). Default: 0.01.

r2_min_au 

r2_min_au(v: float) -> IODParamsBuilder

Set the lower plausibility bound on heliocentric distance (AU). Default: 0.05.

r2_max_au 

r2_max_au(v: float) -> IODParamsBuilder

Set the upper plausibility bound on heliocentric distance (AU). Default: 200.0.

aberth_max_iter 

aberth_max_iter(v: int) -> IODParamsBuilder

Set the maximum iterations for the Aberth–Ehrlich solver. Default: 50.

aberth_eps 

aberth_eps(v: float) -> IODParamsBuilder

Set the Aberth convergence tolerance. Default: 1.0e-6.

kepler_eps 

kepler_eps(v: float) -> IODParamsBuilder

Set the universal Kepler solver tolerance. Default: 1e3 * f64::EPSILON.

max_tested_solutions 

max_tested_solutions(v: int) -> IODParamsBuilder

Cap the number of admissible solutions retained. Default: 3.

newton_eps 

newton_eps(v: float) -> IODParamsBuilder

Set the Newton–Raphson absolute tolerance. Default: 1.0e-10.

newton_max_it 

newton_max_it(v: int) -> IODParamsBuilder

Set the maximum Newton–Raphson iterations. Default: 50.

root_imag_eps 

root_imag_eps(v: float) -> IODParamsBuilder

Set the imaginary-part threshold to accept nearly-real roots. Default: 1.0e-6.

batch_size 

batch_size(v: int) -> IODParamsBuilder

Set the batch size for parallel scheduling. Effective only when the crate is compiled with the parallel/rayon feature. Default: 4.

do_parallel 

do_parallel() -> IODParamsBuilder

Request parallel execution (Rayon-backed) in higher-level APIs that accept it. (Advisory flag carried by the Python binding; core Rust struct is independent.)

do_sequential 

do_sequential() -> IODParamsBuilder

Request sequential execution in higher-level APIs that accept it.

build 

build() -> IODParams

Finalize and materialize an immutable IODParams with the chosen settings.

RETURNS DESCRIPTION
IODParams

A read-only IODParams instance with the configured parameters.