Estimation

`estimation`

`AdaptiveOrbitEstimator`

Self-relaxing sequential orbit determination.

Drives an UnscentedKalmanFilter (seeded from an a-priori satellite) observation by observation, exposing its health via mode. When the filter rejects a sustained run of observations the mode moves from Nominal to Recovering.

A-priori observations (the past arc the seed was fit from) may be supplied at construction; when present they are tracked for back-propagation consistency — how well the current estimate, propagated back to those past epochs, still explains them (back_propagation_clos_rms).

`a_priori_observation_count` `property`

Number of a-priori observations tracked for back-propagation consistency.

`back_propagation_clos_rms` `property`

Cross-line-of-sight RMS [km] of the a-priori observations against the current estimate — a single back-propagation-consistency scalar (lower is better). None when there are no a-priori observations (tracking disabled).

Raises:

Type	Description
`ValueError`	If the back-propagation computation fails (e.g. a singular smoother step or a residual that cannot be formed) — a real failure is not folded into `None`.

`consecutive_rejections` `property`

Consecutive rejected observations since the last accepted one.

`current_estimate` `property`

Current best satellite estimate with covariance attached.

Raises:

Type	Description
`ValueError`	If no observation has been processed yet.

`epoch` `property`

Epoch of the current estimate, or None before the first observation.

`escalation_rejections` `property` `writable`

Additional consecutive rejections in Recovering before escalating to Failing (the multi-hypothesis search; clamped to >= 1).

`has_converged` `property`

Whether the filter has ever established a trusted fit on the incoming arc.

False (cold) until at least 6 observations have been accepted; a stall while cold is recovered by re-fitting over the a-priori arc plus incoming observations, while a stall once True (warm) uses the covariance-inflation → heavy-BLS ladder.

`inflation_factor` `property` `writable`

Per-step covariance inflation factor used by the cheap recovery tier (clamped to >= 1).

`last_innovation_chi_squared` `property`

Normalized innovation squared (NIS) of the most recent update on the underlying filter.

None before the first update. Pair with last_measurement_dimension for the NIS / m consistency check (≈ 1 when consistent).

`last_measurement_dimension` `property`

Measurement dimension of the most recent update on the underlying filter.

2 for angles, +1 per range / Doppler component; None before the first update. The denominator for the normalized-NIS consistency check.

`last_recovery_observations_recovered` `property`

Number of buffered observations the most recent adopted candidate brought within the gate, or None if none has been adopted.

`last_recovery_strategy` `property`

Strategy label of the most recent adopted recovery candidate ("bls" / "maneuver"), or None if none has been adopted.

`mode` `property`

Current operating mode.

`plausibility_gate` `property` `writable`

Mahalanobis-squared plausibility gate a recovery candidate must satisfy against the last-Nominal estimate (clamped to >= 0).

`promotion_accepts` `property` `writable`

Consecutive accepts in Recovering before promotion to Nominal (clamped to >= 1).

`recovery_trigger` `property` `writable`

Consecutive rejections that trigger Recovering (clamped to >= 1).

`init(a_priori, a_priori_observations)`

Creates a AdaptiveOrbitEstimator.

Parameters:

Name	Type	Description	Default
`a_priori`	`Satellite`	A-priori satellite carrying `cartesian_state` (and ideally a covariance); seeds the underlying filter.	required
`a_priori_observations`	`list[Observation]`	Observations from the arc before the seed epoch, tracked for back-propagation consistency. Pass an empty list to disable that tracking.	required

Raises:

Type	Description
`ValueError`	If `a_priori` has no attached Cartesian state.

`back_propagation_residuals()`

Residuals of the a-priori observations against the current estimate, propagated back to each past epoch in one batched pass.

Returns:

Type	Description
`list[ObservationResidual]`	One `ObservationResidual` per
`list[ObservationResidual]`	a-priori observation; empty when none were supplied.

Raises:

Type	Description
`ValueError`	If reconstructing the estimate or a residual fails.

`process_observation(observation)`

Processes one observation and returns whether the filter accepted it.

On acceptance the rejection counter resets and mode returns to Nominal; once recovery_trigger consecutive rejections accumulate, mode moves to Recovering.

Parameters:

Name	Type	Description	Default
`observation`	`Observation`	Observation to process.	required

Returns:

Type	Description
`bool`	`True` when accepted by the innovation gate.

Raises:

Type	Description
`ValueError`	If propagation or measurement update setup fails.

`set_adaptive_process_noise(enabled)`

Enables or disables adaptive process noise on the underlying filter.

Parameters:

Name	Type	Description	Default
`enabled`	`bool`	`True` to adapt Q online so the windowed NIS tracks 1.	required

`set_innovation_gate_chi_squared(value)`

Sets the normalized innovation-squared gate on the underlying filter.

Parameters:

Name	Type	Description	Default
`value`	`float \| None`	Maximum allowed normalized innovation squared (NIS); `None` disables gating.	required

`set_process_noise(process_noise)`

Sets the process-noise model on the underlying filter.

Parameters:

Name	Type	Description	Default
`process_noise`	`ProcessNoise`	Process-noise model applied between observations.	required

`set_smoothing_lag(lag)`

Sets the fixed-lag smoothing lag on the underlying filter.

Parameters:

Name	Type	Description	Default
`lag`	`TimeSpan`	Smoothing lag; zero disables smoothing.	required

`AnglesOnlyObservation`

A single angles-only observation used as input to GaussIOD.

Carries the observer position together with the observed right-ascension and declination to a target body at a given epoch.

Attributes:

Name	Type	Description
`epoch`	`ModifiedJulianDate`	Epoch of the measurement.
`right_ascension`	`float`	Right ascension of the line-of-sight to the target [rad; 0..2π).
`declination`	`float`	Declination of the line-of-sight to the target [rad; -π/2..π/2].
`observer_position`	`list[float]`	Inertial observer position [km; 3 components].

`declination` `property`

Declination of the line-of-sight [rad; -π/2..π/2].

`epoch` `property`

Epoch of the measurement.

`observer_position` `property`

Inertial observer position [km; 3 components].

`right_ascension` `property`

Right ascension of the line-of-sight [rad; 0..2π).

`init(epoch, right_ascension, declination, observer_position)`

Creates an angles-only observation.

Parameters:

Name	Type	Description	Default
`epoch`	`ModifiedJulianDate`	Epoch of the measurement.	required
`right_ascension`	`float`	Right ascension of the line-of-sight [rad].	required
`declination`	`float`	Declination of the line-of-sight [rad].	required
`observer_position`	`list[float]`	Inertial observer position [km; 3 components].	required

`AssociationConfig`

Association thresholds by observable type.

Each observable carries three nested cutoffs — high for a high-confidence match, medium for medium confidence, and low for the maximum residual still accepted as an association. A residual above the low bound is rejected outright.

The defaults match the built-in configs.toml fallback values:

Observable	High	Medium	Low
Range [km]	5	50	500
Range-rate [km/s]	1e-4	1e-3	1e-2
Angle-rate [rad/s]	1e-8	1e-7	1e-6
FDOA [Hz]	0.5	5	50

Attributes:

Name	Type	Description
`high_range`	`float`	High-confidence range cutoff [km].
`medium_range`	`float`	Medium-confidence range cutoff [km].
`low_range`	`float`	Maximum accepted range cutoff [km].
`high_range_rate`	`float`	High-confidence range-rate cutoff [km/s].
`medium_range_rate`	`float`	Medium-confidence range-rate cutoff [km/s].
`low_range_rate`	`float`	Maximum accepted range-rate cutoff [km/s].
`high_angle_rate`	`float`	High-confidence angular-rate cutoff [rad/s].
`medium_angle_rate`	`float`	Medium-confidence angular-rate cutoff [rad/s].
`low_angle_rate`	`float`	Maximum accepted angular-rate cutoff [rad/s].
`high_fdoa`	`float`	High-confidence FDOA cutoff [Hz].
`medium_fdoa`	`float`	Medium-confidence FDOA cutoff [Hz].
`low_fdoa`	`float`	Maximum accepted FDOA cutoff [Hz].

`high_angle_rate` `property` `writable`

High-confidence angular-rate cutoff [rad/s].

`high_fdoa` `property` `writable`

High-confidence FDOA cutoff [Hz].

`high_range` `property` `writable`

High-confidence range or cross-line-of-sight cutoff [km].

`high_range_rate` `property` `writable`

High-confidence range-rate cutoff [km/s].

`low_angle_rate` `property` `writable`

Maximum accepted angular-rate cutoff [rad/s].

`low_fdoa` `property` `writable`

Maximum accepted FDOA cutoff [Hz].

`low_range` `property` `writable`

Maximum accepted range or cross-line-of-sight cutoff [km].

`low_range_rate` `property` `writable`

Maximum accepted range-rate cutoff [km/s].

`medium_angle_rate` `property` `writable`

Medium-confidence angular-rate cutoff [rad/s].

`medium_fdoa` `property` `writable`

Medium-confidence FDOA cutoff [Hz].

`medium_range` `property` `writable`

Medium-confidence range or cross-line-of-sight cutoff [km].

`medium_range_rate` `property` `writable`

Medium-confidence range-rate cutoff [km/s].

`init(range, range_rate, angle_rate, fdoa)`

Creates an AssociationConfig from grouped (high, medium, low) threshold tuples.

Each observable's thresholds are supplied as a (high, medium, low) triple. Values should satisfy high <= medium <= low for meaningful filtering. Use AssociationConfig.default to obtain the built-in fallback values.

Parameters:

Name	Type	Description	Default
`range`	`tuple[float, float, float]`	`(high, medium, low)` range or cross-line-of-sight cutoffs [km].	required
`range_rate`	`tuple[float, float, float]`	`(high, medium, low)` range-rate cutoffs [km/s].	required
`angle_rate`	`tuple[float, float, float]`	`(high, medium, low)` angular-rate cutoffs [rad/s].	required
`fdoa`	`tuple[float, float, float]`	`(high, medium, low)` FDOA cutoffs [Hz].	required

`default()` `staticmethod`

Creates an AssociationConfig with the built-in default thresholds.

Returns:

Type	Description
`AssociationConfig`	AssociationConfig with default cutoffs (range: 5/50/500 km,
`AssociationConfig`	range-rate: 1e-4/1e-3/1e-2 km/s, angle-rate: 1e-8/1e-7/1e-6
`AssociationConfig`	rad/s, FDOA: 0.5/5/50 Hz).

`BatchLeastSquares`

Batch weighted-least-squares orbit-determination solver.

Implements a Gauss-Newton iteration in equinoctial elements, optionally including drag (B*) and SRP (A/m) parameters. Convergence is declared when the relative change in weighted RMS between iterations falls below 1e-4 (i.e., a 0.01 % improvement). Up to max_iterations Gauss-Newton steps are run; the default is 20. Reference: Vallado §10.3 (batch differential correction) and the Orekit BatchLSEstimator / GMAT BatchEstimator formulations.

The post-fit covariance returned by covariance is rotated into the orbit-relative RIC frame (Cartesian position [km], velocity [km/s]); see CovarianceMatrix for the layout.

Optional maneuver estimation (estimate_maneuver) jointly solves for a single Cartesian Δv and its epoch within the fit window; by default the radial component is unconstrained, but allow_radial_delta_v may be set to False to penalize it.

Attributes:

Name	Type	Description
`a_priori`	`Satellite`	A-priori satellite, used as the initial guess and force-model template.
`observations`	`list[Observation]`	Observations being fit.
`residuals`	`list[ObservationResidual]`	Residuals at the current estimate. Available after `solve` or `iterate`.
`rms`	`float \| None`	Unweighted RMS [km; ≥ 0] of the dominant residual component over active (non-rejected) observations.
`weighted_rms`	`float \| None`	Weighted RMS in measurement-sigma units [dimensionless; ≥ 0].
`converged`	`bool`	Whether the last solve met the convergence criterion.
`iteration_count`	`int`	Number of Gauss-Newton steps taken in the most recent solve.
`max_iterations`	`int`	Maximum number of Gauss-Newton steps. Default `20`.
`estimate_drag`	`bool`	If `True`, solve for the TLE B-term (ballistic coefficient).
`estimate_srp`	`bool`	If `True`, solve for the TLE A/m (SRP) term.
`analytic_jacobian`	`bool`	If `True`, build the measurement Jacobian analytically (default). If `False`, use finite differences.
`covariance`	`CovarianceMatrix`	6×6 post-fit covariance in the RIC frame.
`report`	`OrbitDeterminationReport`	Quality report computed from the post-fit residuals and covariance.
`current_estimate`	`Satellite`	Current best satellite estimate.
`estimate_maneuver`	`bool`	If `True`, jointly solve for a single Δv within the fit window.
`maneuver_epoch`	`ModifiedJulianDate \| None`	Epoch of the recovered maneuver, when one was solved for.
`delta_v`	`CartesianVector \| None`	Recovered Δv [km/s], when one was solved for.
`allow_radial_delta_v`	`bool`	When maneuver estimation is on, allow the radial component of Δv (default `True`).
`reject_bad_observations`	`bool`	If `True`, iteratively flag and reject observations whose post-fit residual exceeds the gating threshold and re-solve.
`rejected_observation_ids`	`list[str]`	Identifiers of observations rejected by the last solve.
`minimum_maneuver_epoch`	`ModifiedJulianDate \| None`	Lower bound on the maneuver-search window. `None` to use the default `first_obs - 3/4 period` window.
`minimum_fit_span`	`TimeSpan \| None`	Lower bound on the fit-window duration. `None` to use the natural span of the observations.
`output_type`	`KeplerianType`	Keplerian flavor of the satellite written on output (mean Kozai GP, osculating, etc.).

`a_priori` `property` `writable`

A-priori satellite (initial guess and force-model template).

`allow_radial_delta_v` `property` `writable`

When maneuver estimation is on, allow the radial component of Δv (default True).

`analytic_jacobian` `property` `writable`

If True, build the measurement Jacobian analytically (default). If False, use finite differences.

The analytic path linearises the orbital block with a two-body STM and finite-differences only the drag / SRP columns. For MeanKozaiGP / MeanBrouwerGP outputs with estimate_drag enabled the two-body STM is internally inconsistent with the SGP4-propagated FD drag column over multi-day LEO arcs, and the LM gain-ratio gate stalls the solve at a wildly wrong B-term; the solver detects that combination and transparently falls back to a fully finite-difference Jacobian regardless of this flag.

`converged` `property`

Whether the last solve met the convergence criterion (relative weighted-RMS change below 1e-4).

`covariance` `property`

6×6 post-fit covariance in the orbit-relative RIC frame.

Scaled a-posteriori by max(weighted_rms**2, 1) (the variance of unit weight, σ₀²) so the covariance reflects the actual fit residuals: the formal (HᵀR⁻¹H)⁻¹ alone is overconfident by σ₀² when the residuals exceed the noise model (e.g. accumulated force-model error over a long arc). Never tightened below the formal (σ₀ < 1 is floored to 1).

Raises:

Type	Description
`ValueError`	If `solve` has not yet been called or the normal matrix is not positive definite.

`current_estimate` `property`

Current best satellite estimate.

`delta_v` `property`

Recovered Δv [km/s], or None.

`estimate_drag` `property` `writable`

Whether to solve for the drag (decay) parameter.

The solve-for is whichever parameter the output propagator integrates: the ballistic B-term for MeanKozaiGP, MeanBrouwerGP, MeanBrouwerXP, and Osculating outputs, and mean_motion_dot for MeanKozaiPPT3 (PPT3 integrates the mean-motion derivative and ignores B*).

`estimate_maneuver` `property` `writable`

If True, jointly solve for a single Δv within the fit window.

`estimate_srp` `property` `writable`

Whether to solve for the TLE A/m (SRP) term.

`iteration_count` `property`

Number of Gauss-Newton steps taken in the most recent solve.

`maneuver_epoch` `property`

Epoch of the recovered maneuver, or None.

`max_iterations` `property` `writable`

Maximum number of Gauss-Newton steps. Default 20.

`minimum_fit_span` `property` `writable`

Lower bound on the fit-window duration, or None.

`minimum_maneuver_epoch` `property` `writable`

Lower bound on the maneuver-search window.

`observations` `property` `writable`

Observations being fit.

`output_type` `property` `writable`

Keplerian flavor of the satellite written on output.

`reject_bad_observations` `property` `writable`

If True, iteratively flag and reject observations whose post-fit residual exceeds the gating threshold.

`rejected_observation_ids` `property`

Identifiers of observations rejected by the last solve.

`report` `property`

Quality report computed from the post-fit residuals and covariance.

Raises:

Type	Description
`ValueError`	If the report cannot be computed (e.g., no observations or covariance unavailable).

`residuals` `property`

Residuals at the current estimate.

Raises:

Type	Description
`ValueError`	If propagation of the current estimate fails.

`rms` `property`

Unweighted RMS [km; ≥ 0] of the dominant residual component.

`weighted_rms` `property`

Weighted RMS in measurement-sigma units [dimensionless; ≥ 0].

`init(observations, a_priori)`

Creates a BatchLeastSquares solver.

Parameters:

Name	Type	Description	Default
`observations`	`list[Observation]`	Observations to fit.	required
`a_priori`	`Satellite`	A-priori satellite. The solver inherits the keplerian type of `a_priori.tle` when present; otherwise it defaults to `MeanKozaiGP`.	required

`iterate()`

Runs a single Gauss-Newton step.

Useful for stepping through the solver one iteration at a time (debugging or interactive convergence monitoring).

Raises:

Type	Description
`ValueError`	If the observation list is empty or propagation fails.

`reset()`

Discards solve state and reverts current_estimate to a_priori.

`solve()`

Runs Gauss-Newton iterations until convergence or max_iterations is reached.

Updates current_estimate, residuals, rms, weighted_rms, converged, and iteration_count.

Raises:

Type	Description
`ValueError`	If the observation list is empty or any propagation fails during the solve.

`CollectionAssociationReport`

Result of associating a single ObservationCollection against a constellation.

Attributes:

Name	Type	Description
`orphan_observations`	`list[Observation]`	Observations from the collection that did not associate with any catalog member.
`associations`	`list[ObservationAssociation]`	All gate-passing associations, including duplicates when multiple satellites match a single observation.
`moving_satellite_ids`	`list[str]`	Identifiers of catalog satellites whose predicted state moved across the collection's field of view during the epoch (used for streak detection).

`associations` `property`

All gate-passing associations.

`moving_satellite_ids` `property`

Identifiers of catalog satellites that moved across the field of view during the collection epoch.

`orphan_observations` `property`

Observations that did not associate with any catalog member.

`Covariance`

Lightweight diagonal-only covariance description.

Stores per-element 1-σ standard deviations together with the frame convention used to interpret them. For full off-diagonal covariance use CovarianceMatrix instead.

Attributes:

Name	Type	Description
`sigmas`	`list[float]`	Per-element 1-σ standard deviations. Units depend on `covariance_type`: `Relative` / `Inertial` Cartesian use [km] for position elements and [km/s] for velocity elements; `Equinoctial` uses [km] for the semi-major-axis element and [dimensionless] or [rad] for the remaining equinoctial elements.
`covariance_type`	`CovarianceType`	Frame and parameterization the sigmas are expressed in.

`covariance_type` `property`

Frame and parameterization the sigmas are expressed in.

`sigmas` `property`

Per-element 1-σ standard deviations. Units depend on covariance_type.

`init(sigmas=..., covariance_type=...)`

Creates a Covariance from per-element sigmas.

Parameters:

Name	Type	Description	Default
`sigmas`	`list[float] \| None`	Per-element 1-σ standard deviations. Defaults to an empty list when omitted.	`...`
`covariance_type`	`CovarianceType \| None`	Frame and parameterization the sigmas are expressed in. Defaults to `CovarianceType.Relative` when omitted.	`...`

`CovarianceMatrix`

Square covariance matrix with an explicit frame convention.

Used to express both a priori filter covariances and post-fit BLS covariances. The Cartesian 6×6 layout is ordered [r_x, r_y, r_z, v_x, v_y, v_z] with position elements in [km] and velocity elements in [km/s]; the upper-left 3×3 block is position [km²] and the lower-right 3×3 block is velocity [km²/s²]. Larger Cartesian matrices append uncoupled drag (B*) and SRP (A/m) terms. The equinoctial 6×6 layout is ordered [a, h, k, p, q, L].

The covariance_type tag distinguishes Cartesian-in-an-inertial frame (Inertial, parameterised by which inertial frame), Cartesian-in-RIC (Relative), and equinoctial element-set covariance (Equinoctial).

Attributes:

Name	Type	Description
`sigmas`	`list[float]`	Per-element 1-σ standard deviations (`sqrt` of diagonal entries).
`covariance_type`	`CovarianceType`	Frame and parameterization the matrix is expressed in.
`dimension`	`int`	Number of rows / columns.
`matrix`	`list[list[float]]`	Full square matrix as a list of rows.
`position_sigma`	`float`	RSS of the first three diagonal sigmas (the position block), in [km]. Requires a ≥ 6×6 matrix.
`velocity_sigma`	`float`	RSS of diagonal sigmas 3..6 (the velocity block), in [km/s]. Requires a ≥ 6×6 matrix.

`covariance_type` `property`

Frame and parameterization the matrix is expressed in.

`dimension` `property`

Number of rows / columns.

`matrix` `property`

Full square matrix as a list of rows.

`position_sigma` `property`

RSS of the first three diagonal sigmas (position block) [km].

`sigmas` `property`

Per-element 1-σ standard deviations (sqrt of diagonal entries).

`velocity_sigma` `property`

RSS of diagonal sigmas 3..6 (velocity block) [km/s].

`init(sigmas, covariance_type)`

Creates a diagonal CovarianceMatrix from per-element sigmas.

For full off-diagonal terms (e.g., from a filter solution), use from_matrix instead.

Parameters:

Name	Type	Description	Default
`sigmas`	`list[float]`	Per-element 1-σ standard deviations. Units depend on `covariance_type`: see class docstring.	required
`covariance_type`	`CovarianceType`	Frame and parameterization the sigmas are expressed in.	required

Raises:

Type	Description
`ValueError`	If `covariance_type` is `Inertial(_)` with an embedded frame that is not `TEME`, `J2000`, or `GCRS`.

`from_matrix(rows, covariance_type)` `staticmethod`

Builds a CovarianceMatrix from an explicit square matrix.

Use this instead of the diagonal-only __init__ when full off-diagonal terms (e.g., from a filter solution) need to be carried.

Parameters:

Name	Type	Description	Default
`rows`	`list[list[float]]`	List of N rows of length N (any positive N).	required
`covariance_type`	`CovarianceType`	Frame and parameterization the matrix is expressed in.	required

Returns:

Type	Description
`CovarianceMatrix`	New `CovarianceMatrix`.

Raises:

Type	Description
`ValueError`	If `rows` is empty or non-square, or if `covariance_type` is `Inertial(_)` with an embedded frame that is not `TEME`, `J2000`, or `GCRS`.

`to_type(target, reference_state)`

Converts this covariance to a different CovarianceType.

Single unified method for all covariance-type conversions: inertial↔inertial rotations, inertial↔RIC, and inertial↔equinoctial. Matrices larger than 6×6 keep appended drag/SRP parameters and transform their cross-covariances with the orbital block.

Parameters:

Name	Type	Description	Default
`target`	`CovarianceType`	Target type. Construct `CovarianceType.Inertial(frame)` with a valid inertial frame, or use `CovarianceType.Relative` / `CovarianceType.Equinoctial`.	required
`reference_state`	`CartesianState`	State used to define RIC axes, supply the epoch for epoch-dependent inertial-inertial rotations, and evaluate the equinoctial jacobian. Must be in an inertial frame and carry a velocity.	required

Returns:

Type	Description
`CovarianceMatrix`	New covariance with `covariance_type == target`.

Raises:

Type	Description
`ValueError`	If the matrix is smaller than 6×6, `reference_state` is not in an inertial frame, `reference_state` lacks a velocity, or the equinoctial jacobian is singular.

`DoubleRIOD`

Double-R iteration for angles-only IOD (Vallado §7.3).

Solves for the Cartesian state at the middle observation epoch by iterating on the endpoint slant ranges and enforcing the middle line-of-sight.

Attributes:

Name	Type	Description
`observations`	`list[AnglesOnlyObservation]`	The three observations.
`mu`	`float`	Central-body gravitational parameter [km³/s²].
`max_iterations`	`int`	Maximum Newton iterations on (ρ₁, ρ₃).

`max_iterations` `property`

Maximum Newton iterations on (ρ₁, ρ₃).

`mu` `property`

Central-body gravitational parameter [km³/s²].

`observations` `property`

The three observations supplied at construction.

`init(observations, mu, max_iterations=...)`

Creates a Double-R IOD solver for three angles-only observations.

Parameters:

Name	Type	Description	Default
`observations`	`list[AnglesOnlyObservation]`	Exactly three observations of the same target, in time order.	required
`mu`	`float`	Central-body gravitational parameter [km³/s²].	required
`max_iterations`	`int`	Maximum Newton iterations on (ρ₁, ρ₃). Default `50`.	`...`

Raises:

Type	Description
`ValueError`	If `observations` does not have length 3.

`solve()`

Runs the Double-R iteration.

Returns:

Type	Description
`CartesianState`	Estimated state at the middle observation epoch.

Raises:

Type	Description
`ValueError`	If the input geometry is degenerate or iteration does not converge within `max_iterations` steps.

`ExtendedKalmanFilter`

Extended Kalman Filter for sequential orbit determination.

Linearizes the propagation through the two-body state-transition matrix (or a finite-difference STM for longer steps; threshold is set internally) and the measurement model around the current estimate. Reference: Vallado §10.4 (sequential filters) and the Orekit KalmanEstimator formulation.

The internal state vector is Cartesian [x, y, z, vx, vy, vz] in [km] and [km/s], optionally extended with drag (B*) and SRP (A/m) parameters when estimate_drag or estimate_srp is enabled.

Attributes:

Name	Type	Description
`residuals`	`list[ObservationResidual]`	Residuals from the last solve.
`estimate_drag`	`bool`	Whether the drag B-term is part of the estimated state. Defaults to `False`.
`estimate_srp`	`bool`	Whether the SRP A/m term is part of the estimated state. Defaults to `False`.
`analytic_jacobian`	`bool`	If `True`, build the measurement Jacobian analytically. Defaults to `False` (finite differences).
`current_estimate`	`Satellite`	Current best satellite estimate with the filter covariance attached.
`covariance`	`CovarianceMatrix`	Current filter covariance.
`epoch`	`ModifiedJulianDate \| None`	Epoch of `current_estimate`, or `None` before the first observation.
`innovation_gate_chi_squared`	`float \| None`	Normalized innovation-squared gate; `None` disables rejection.
`last_update_accepted`	`bool \| None`	Acceptance status for the most recent observation.
`last_observation_id`	`str \| None`	Identifier of the most recent observation.
`last_innovation_chi_squared`	`float \| None`	Normalized innovation squared for the most recent observation.
`last_measurement_dimension`	`int \| None`	Measurement-vector length for the most recent observation.
`accepted_observation_ids`	`list[str]`	Observation ids accepted by the innovation gate.
`rejected_observation_ids`	`list[str]`	Observation ids rejected by the innovation gate.

`accepted_observation_ids` `property`

Observation identifiers accepted by the innovation gate.

`adaptive_process_noise` `property` `writable`

Whether online adaptive process noise (covariance matching) is on.

When enabled, the discrete process noise Q is multiplied by process_noise_scale, nudged after each accepted update so the windowed mean normalized innovation squared (NIS / m) tracks 1 — keeping the filter statistically consistent over the arc. Enabling also pins the measurement-noise scale to 1 (honest R): persistent surprise is absorbed as dynamics uncertainty by Q. Toggling resets the scale and clears the window. Default False.

`analytic_jacobian` `property` `writable`

If True, build the measurement Jacobian analytically. If False, use finite differences (default).

`covariance` `property`

Current filter covariance.

The returned matrix uses CovarianceType.Inertial(TEME) and the filter's Cartesian state-vector layout [x, y, z, vx, vy, vz] in [km, km/s], with optional drag/SRP states appended when enabled.

Raises:

Type	Description
`ValueError`	If no state has been produced yet (e.g., `solve` has not been called).

`current_estimate` `property`

Current best satellite estimate with covariance attached.

Raises:

Type	Description
`ValueError`	If no state has been produced yet (e.g., `solve` has not been called).

`epoch` `property`

Epoch of current_estimate, or None before the first accepted or rejected observation is processed.

`estimate_drag` `property` `writable`

Whether the drag B-term is part of the estimated state.

`estimate_srp` `property` `writable`

Whether the SRP A/m term is part of the estimated state.

`innovation_gate_chi_squared` `property` `writable`

Normalized innovation-squared rejection gate, or None.

`last_innovation_chi_squared` `property`

Normalized innovation squared for the most recent observation.

`last_measurement_dimension` `property`

Measurement-vector length for the most recent observation.

`last_observation_id` `property`

Identifier of the most recently processed observation.

`last_update_accepted` `property`

Whether the most recent observation update was accepted.

`process_noise_scale` `property`

Current adaptive multiplier on the nominal discrete Q.

1.0 when adaptive_process_noise is disabled or has not yet filled its first averaging window; otherwise the latest covariance-matching scale.

`rejected_observation_ids` `property`

Observation identifiers rejected by the innovation gate.

`residuals` `property`

Residuals from the last solve.

`init(observations, a_priori)`

Creates an ExtendedKalmanFilter.

Parameters:

Name	Type	Description	Default
`observations`	`list[Observation]`	Observations to process. Must be in chronological order.	required
`a_priori`	`Satellite`	A-priori satellite carrying `cartesian_state`. The filter uses that state epoch and either the attached covariance (used as-is, never floored) or a default 0.5 km / 5e-5 km/s per-axis Cartesian covariance when none is attached, before propagating to the first observation.	required

Raises:

Type	Description
`ValueError`	If `a_priori` has no attached Cartesian state.

`process_observation(observation)`

Processes one observation through the filter.

The filter predicts from the current estimate epoch to the observation epoch, computes the normalized innovation squared, and applies the measurement update only when it passes innovation_gate_chi_squared. When the gate is None the update is always accepted.

Parameters:

Name	Type	Description	Default
`observation`	`Observation`	Observation to process.	required

Returns:

Type	Description
`bool`	`True` when the update was accepted, or `False` when it was
`bool`	rejected by the innovation gate.

Raises:

Type	Description
`ValueError`	If propagation or measurement update setup fails.

`set_a_priori(a_priori)`

Replaces the a-priori satellite used as the initial state.

Parameters:

Name	Type	Description	Default
`a_priori`	`Satellite`	New a-priori satellite.	required

`set_adaptive_process_noise_parameters(window, scale_min, scale_max, ewma)`

Sets the adaptive-feedback tuning.

Parameters:

Name	Type	Description	Default
`window`	`int`	Accepted updates averaged before each scale nudge [clamped to >= 1].	required
`scale_min`	`float`	Lower clamp on the `Q` multiplier.	required
`scale_max`	`float`	Upper clamp on the `Q` multiplier.	required
`ewma`	`float`	EWMA exponent of the multiplicative update; smaller values adapt more gently.	required

`set_observations(observations)`

Replaces the filter's observation queue.

Parameters:

Name	Type	Description	Default
`observations`	`list[Observation]`	New observation queue. Must be chronologically ordered.	required

`set_process_noise(process_noise)`

Sets the process-noise model used during the propagation step.

Parameters:

Name	Type	Description	Default
`process_noise`	`ProcessNoise`	Process-noise model to apply between observations.	required

`solve()`

Processes every observation in chronological order, alternating propagate and measurement-update steps.

Updates current_estimate, its attached covariance, and the acceptance diagnostics in place.

Returns:

Name	Type	Description
`FilterResult`	`FilterResult`	Per-step diagnostics and the final filter state.

Raises:

Type	Description
`ValueError`	If propagation or measurement update fails.

`FilterResult`

Complete filter output after processing all observations.

Returned by ExtendedKalmanFilter.solve and UnscentedKalmanFilter.solve. Contains per-step diagnostics for every processed observation and the final filter state.

Attributes:

Name	Type	Description
`steps`	`list[FilterStepResult]`	Per-observation diagnostics, one entry per processed observation.
`final_state`	`FilterState`	Filter state after the last measurement update.

`final_state` `property`

Filter state after the last measurement update.

`steps` `property`

Per-observation diagnostics, one entry per processed observation.

`FilterState`

Filter state at a particular epoch.

Carries the epoch, the Cartesian state vector, and the associated covariance matrix. Returned by FilterStepResult (pre- and post-fit) and FilterResult (final state).

Attributes:

Name	Type	Description
`epoch`	`ModifiedJulianDate`	Epoch of this state.
`state_vector`	`list[float]`	State vector components. Length is 6 for position+velocity only, 7 when drag is estimated, 8 when both drag and SRP are estimated [km; km/s; dimensionless].
`covariance`	`list[list[float]]`	Square covariance matrix in the same units as `state_vector`. Dimensions match `len(state_vector)`.

`covariance` `property`

Square covariance matrix. Dimensions match len(state_vector).

`epoch` `property`

Epoch of this filter state.

`state_vector` `property`

State vector [x, y, z, vx, vy, vz] in TEME, optionally extended with drag B* and/or SRP A/m [km; km/s; dimensionless].

`FilterStepResult`

Per-observation diagnostic from a Kalman predict/update cycle.

Records the pre-fit state, post-fit state, innovation vector, innovation covariance, Kalman gain, and acceptance status for one measurement update. Collected in FilterResult.steps after calling ExtendedKalmanFilter.solve or UnscentedKalmanFilter.solve.

Attributes:

Name	Type	Description
`observation_id`	`str`	Identifier of the processed observation.
`pre_fit_state`	`FilterState`	Predicted state before the measurement update.
`post_fit_state`	`FilterState`	State after an accepted update, or the predicted state when rejected.
`innovation`	`list[float]`	Measurement innovation `z - h(x)` in observation units.
`innovation_covariance`	`list[list[float]]`	Innovation covariance matrix `S` in measurement units squared.
`kalman_gain`	`list[list[float]]`	Kalman gain matrix.
`innovation_chi_squared`	`float`	Normalized innovation squared `innovation^T S^-1 innovation`.
`accepted`	`bool`	`True` when the innovation gate accepted this observation.

`accepted` `property`

True when the innovation gate accepted this observation.

`innovation` `property`

Measurement innovation z - h(x) in observation units.

`innovation_chi_squared` `property`

Normalized innovation squared innovation^T S^-1 innovation.

`innovation_covariance` `property`

Innovation covariance matrix S in measurement units squared.

`kalman_gain` `property`

Kalman gain matrix used for the accepted update.

`observation_id` `property`

Identifier of the processed observation.

`post_fit_state` `property`

State and covariance after the measurement update, or the predicted state when the observation was rejected.

`pre_fit_state` `property`

Predicted state and covariance before the measurement update.

`GaussIOD`

Gauss angles-only initial orbit determination.

Estimates a CartesianState at the middle observation epoch given exactly three angles-only observations of the same target. Uses the classical Gauss method with iterative refinement of the Lagrange ratios via the f and g series.

The output state is expressed in the TEME frame. Recovery accuracy depends strongly on observation geometry; coplanar line-of-sight vectors yield a singular system and raise ValueError from solve.

Construct with the three observations and the central-body gravitational parameter; call solve to run the iteration.

Attributes:

Name	Type	Description
`observations`	`list[AnglesOnlyObservation]`	The three observations (mutable; setter validates length).
`mu`	`float`	Central-body gravitational parameter [km³/s²].
`max_iterations`	`int`	Maximum f/g series refinement iterations.

`max_iterations` `property` `writable`

Maximum f/g series refinement iterations.

`mu` `property` `writable`

Central-body gravitational parameter [km³/s²].

`observations` `property` `writable`

The three observations supplied at construction.

`init(observations, mu, max_iterations=50)`

Creates a Gauss IOD solver for three angles-only observations.

Parameters:

Name	Type	Description	Default
`observations`	`list[AnglesOnlyObservation]`	Exactly three observations of the same target, in time order.	required
`mu`	`float`	Central-body gravitational parameter [km³/s²].	required
`max_iterations`	`int`	Maximum f/g series refinement iterations.	`50`

Raises:

Type	Description
`ValueError`	If `observations` does not have length 3.

`solve()`

Runs the Gauss IOD iteration.

Returns:

Name	Type	Description
`CartesianState`	`CartesianState`	Estimated state at the middle observation epoch
	`CartesianState`	[position in km, velocity in km/s, TEME frame].

Raises:

Type	Description
`ValueError`	If `mu` is non-positive, observation epochs are not distinct, the line-of-sight vectors are coplanar, or the f/g series fails to produce a finite estimate.

`GoodingIOD`

Gooding's robust angles-only IOD (RAE TR 91004 / 1996 refinement).

Solves for the Cartesian state at the middle observation epoch using Gooding's range-search formulation.

Attributes:

Name	Type	Description
`observations`	`list[AnglesOnlyObservation]`	The three observations.
`mu`	`float`	Central-body gravitational parameter [km³/s²].
`max_iterations`	`int`	Maximum search iterations.

`max_iterations` `property`

Maximum range-search iterations.

`mu` `property`

Central-body gravitational parameter [km³/s²].

`observations` `property`

The three observations supplied at construction.

`init(observations, mu, max_iterations=...)`

Creates a Gooding IOD solver for three angles-only observations.

Parameters:

Name	Type	Description	Default
`observations`	`list[AnglesOnlyObservation]`	Exactly three observations of the same target, in time order.	required
`mu`	`float`	Central-body gravitational parameter [km³/s²].	required
`max_iterations`	`int`	Maximum range-search iterations. Default `50`.	`...`

Raises:

Type	Description
`ValueError`	If `observations` does not have length 3.

`solve()`

Runs Gooding's IOD.

Returns:

Type	Description
`CartesianState`	Estimated state at the middle observation epoch.

Raises:

Type	Description
`ValueError`	If the input geometry is degenerate or iteration does not converge within `max_iterations` steps.

`HerrickGibbsIOD`

Herrick–Gibbs initial orbit determination from three position states.

Estimates a CartesianState at the middle state's epoch given three position-bearing CartesianState inputs. The method is O(Δt⁴) accurate for two-body motion and is best suited to closely spaced (small angular separation) observations.

Only the position and epoch of each input state are read; velocity may be None. The output state is expressed in the TEME frame.

Construct with the three states and the central-body gravitational parameter; call solve to compute the velocity at the middle epoch.

Attributes:

Name	Type	Description
`states`	`list[CartesianState]`	The three position states (mutable; setter validates length).
`mu`	`float`	Central-body gravitational parameter [km³/s²].

`mu` `property` `writable`

Central-body gravitational parameter [km³/s²].

`states` `property` `writable`

The three input states supplied at construction.

`init(states, mu)`

Creates a Herrick–Gibbs IOD solver for three position states.

Parameters:

Name	Type	Description	Default
`states`	`list[CartesianState]`	Exactly three position-bearing states of the same target, in time order. Velocities may be `None` — only `position` and `epoch` are used.	required
`mu`	`float`	Central-body gravitational parameter [km³/s²].	required

Raises:

Type	Description
`ValueError`	If `states` does not have length 3.

`solve()`

Runs the Herrick–Gibbs estimator.

Returns:

Name	Type	Description
`CartesianState`	`CartesianState`	State at the middle input epoch with the
	`CartesianState`	Herrick–Gibbs velocity estimate
	`CartesianState`	[position in km, velocity in km/s, TEME frame].

Raises:

Type	Description
`ValueError`	If `mu` is non-positive, any input position is near-zero, the three positions are not sufficiently coplanar, or the input epochs are not distinct.

`KarimiMortariIOD`

Karimi-Mortari unified IOD (Karimi & Mortari, JGCD 2011).

Solves for the Cartesian state at the middle observation epoch from angles-only, range-assisted, or mixed three-observation inputs.

Attributes:

Name	Type	Description
`observations`	`list[AnglesOnlyObservation]`	The three observations.
`ranges`	`list[float \| None]`	Optional measured ranges [km] at each observation; `None` for angle-only entries.
`mu`	`float`	Central-body gravitational parameter [km³/s²].

`mu` `property`

Central-body gravitational parameter [km³/s²].

`observations` `property`

The three observations supplied at construction.

`ranges` `property`

Optional measured ranges [km] at each observation; None for angle-only entries.

`init(observations, ranges, mu)`

Creates a Karimi-Mortari IOD solver for three observations.

Parameters:

Name	Type	Description	Default
`observations`	`list[AnglesOnlyObservation]`	Exactly three observations of the same target, in time order.	required
`ranges`	`list[float \| None]`	Optional measured ranges [km] at each observation; use `None` for angle-only entries. List length must equal 3.	required
`mu`	`float`	Central-body gravitational parameter [km³/s²].	required

Raises:

Type	Description
`ValueError`	If `observations` or `ranges` does not have length 3.

`solve()`

Runs the Karimi-Mortari unified IOD.

Returns:

Type	Description
`CartesianState`	Estimated state at the middle observation epoch.

Raises:

Type	Description
`ValueError`	If the input geometry is degenerate or the algebraic solve fails.

`LambertIOD`

Lambert two-body boundary value problem solver.

Given two CartesianState boundary points with known positions and epochs, computes the departure and arrival velocity vectors of the connecting two-body trajectory. Uses the universal-variable formulation from Vallado, Fundamentals of Astrodynamics and Applications.

Time of flight is derived as state_2.epoch − state_1.epoch and must be strictly positive. Only the position and epoch of each input state are read; velocity may be None.

Construct with the two endpoint states, the central-body gravitational parameter, and the direction-of-motion flag; call solve to obtain the LambertSolution.

Attributes:

Name	Type	Description
`state_1`	`CartesianState`	Departure state (position + epoch).
`state_2`	`CartesianState`	Arrival state (position + epoch).
`mu`	`float`	Central-body gravitational parameter [km³/s²].
`prograde`	`bool`	If `True`, select the prograde (counter-clockwise about +Z) branch of the transfer; otherwise retrograde.
`max_iterations`	`int`	Maximum Newton–Raphson iterations on the universal variable.

`max_iterations` `property` `writable`

Maximum Newton–Raphson iterations on the universal variable.

`mu` `property` `writable`

Central-body gravitational parameter [km³/s²].

`prograde` `property` `writable`

Prograde (True) vs retrograde (False) branch flag.

`state_1` `property` `writable`

Departure state.

`state_2` `property` `writable`

Arrival state.

`init(state_1, state_2, mu, prograde, max_iterations=100)`

Creates a Lambert solver between two boundary states.

Parameters:

Name	Type	Description	Default
`state_1`	`CartesianState`	Departure state. Only `position` and `epoch` are read; `velocity` may be `None`.	required
`state_2`	`CartesianState`	Arrival state. Only `position` and `epoch` are read; `velocity` may be `None`.	required
`mu`	`float`	Central-body gravitational parameter [km³/s²].	required
`prograde`	`bool`	If `True`, choose the prograde branch.	required
`max_iterations`	`int`	Maximum Newton–Raphson iterations on the universal variable.	`100`

`solve()`

Runs the Lambert solver.

Returns:

Name	Type	Description
`LambertSolution`	`LambertSolution`	Departure (`v1`) and arrival (`v2`)
	`LambertSolution`	velocity vectors [km/s; 3 components each].

Raises:

Type	Description
`ValueError`	If the time of flight is non-positive, `mu` is non-positive, either input position is near zero, the transfer angle is 0 or 180 degrees, or the universal variable iteration fails to converge.

`LambertSolution`

Solution of Lambert's problem.

Terminal velocity vectors of the two-body transfer between two known position vectors. Velocities are expressed in the same inertial frame as the input states and apply at the corresponding endpoint epochs.

Attributes:

Name	Type	Description
`v1`	`list[float]`	Velocity at the departure position [km/s; 3 components].
`v2`	`list[float]`	Velocity at the arrival position [km/s; 3 components].

`v1` `property`

Velocity at the departure position [km/s; 3 components].

`v2` `property`

Velocity at the arrival position [km/s; 3 components].

`LaplaceIOD`

Laplace's angles-only initial orbit determination (Vallado §7.2).

Solves for the Cartesian state at the middle observation epoch from three angles-only observations by finite-differencing the line-of-sight and observer-position histories.

Attributes:

Name	Type	Description
`observations`	`list[AnglesOnlyObservation]`	The three observations.
`mu`	`float`	Central-body gravitational parameter [km³/s²].

`mu` `property`

Central-body gravitational parameter [km³/s²].

`observations` `property`

The three observations supplied at construction.

`init(observations, mu)`

Creates a Laplace IOD solver for three angles-only observations.

Parameters:

Name	Type	Description	Default
`observations`	`list[AnglesOnlyObservation]`	Exactly three observations of the same target, in time order.	required
`mu`	`float`	Central-body gravitational parameter [km³/s²].	required

Raises:

Type	Description
`ValueError`	If `observations` does not have length 3.

`solve()`

Runs Laplace's method.

Returns:

Type	Description
`CartesianState`	Estimated state at the middle observation epoch.

Raises:

Type	Description
`ValueError`	If the input geometry or polynomial solve fails.

`MultiRevGaussIOD`

Multi-revolution Gauss angles-only IOD.

Handles the zero-revolution Gauss case. Positive revolution counts raise ValueError until a true multi-revolution seed is implemented.

Attributes:

Name	Type	Description
`observations`	`list[AnglesOnlyObservation]`	The three observations.
`mu`	`float`	Central-body gravitational parameter [km³/s²].
`max_revs`	`int`	Maximum revolution count to enumerate. Must be 0.
`max_iterations`	`int`	Maximum f/g series iterations per hypothesis.

`max_iterations` `property`

Maximum f/g series iterations per hypothesis.

`max_revs` `property`

Maximum revolution count to enumerate.

`mu` `property`

Central-body gravitational parameter [km³/s²].

`observations` `property`

The three observations supplied at construction.

`init(observations, mu, max_revs=..., max_iterations=...)`

Creates a MultiRevGauss IOD solver for three angles-only observations.

Parameters:

Name	Type	Description	Default
`observations`	`list[AnglesOnlyObservation]`	Exactly three observations of the same target, in time order.	required
`mu`	`float`	Central-body gravitational parameter [km³/s²].	required
`max_revs`	`int`	Maximum revolution count to enumerate. Must be `0` (positive counts raise `ValueError`). Default `0`.	`...`
`max_iterations`	`int`	Maximum f/g series iterations per hypothesis. Default `50`.	`...`

Raises:

Type	Description
`ValueError`	If `observations` does not have length 3.

`solve()`

Runs zero-revolution Gauss.

Returns:

Type	Description
`list[CartesianState]`	Candidate states at the middle observation epoch. Empty list when
`list[CartesianState]`	Gauss did not converge.

Raises:

Type	Description
`ValueError`	If `mu` is non-positive, `max_revs` is positive, or epochs are inverted.

`Observation`

A single sensor observation of a space object.

An observation pairs a Sensor with a TopocentricState that captures epoch, observer location, and any subset of measured quantities (right ascension, declination, range, range-rate, angle rates). Optional SignalMeasurement payloads carry TDOA/FDOA pairs for bistatic geometries. Observations are the primary input to BatchLeastSquares, ExtendedKalmanFilter, and UnscentedKalmanFilter.

Attributes:

Name	Type	Description
`id`	`str`	Unique identifier (UUID4 by default) used to identify rejected residuals in the BLS report.
`sensor`	`Sensor`	Sensor that produced the observation, including measurement-noise sigmas used to weight residuals.
`epoch`	`ModifiedJulianDate`	Observation epoch (read from `topocentric_state`).
`topocentric_state`	`TopocentricState`	Observer location and observed elements (RA/Dec [rad], range [km], range-rate [km/s], angle rates [rad/s]).
`signal_measurement`	`SignalMeasurement \| None`	Optional bistatic / DOA payload.
`observed_satellite_id`	`str \| None`	Optional truth-association tag propagated into the residual when the observation came from a tagged catalog.
`expected_satellite_id`	`str \| None`	Optional expected object identifier carried by upstream screening or provider metadata.
`tdoa`	`float \| None`	Convenience accessor for `signal_measurement.tdoa` [s].
`fdoa`	`float \| None`	Convenience accessor for `signal_measurement.fdoa` [Hz].
`visual_magnitude`	`float \| None`	Optional measured visual magnitude [mag]. Used by the photometric residual computations.
`radar_cross_section`	`float \| None`	Optional measured radar cross section [m^2].
`phase_angle`	`float \| None`	Sun-target-observer phase angle [rad], computed on demand. `None` when geometry information is absent.

`epoch` `property`

Observation epoch.

`expected_satellite_id` `property` `writable`

Optional expected object identifier from upstream metadata.

`fdoa` `property`

Convenience accessor for signal_measurement.fdoa [Hz].

`id` `property` `writable`

Unique identifier (UUID4 by default).

`observed_satellite_id` `property` `writable`

Optional truth-association tag of the observed object.

`phase_angle` `property`

Sun-target-observer phase angle [rad; 0..π], computed on demand.

None when the geometry needed to compute the phase angle is unavailable (e.g., missing topocentric direction).

`radar_cross_section` `property` `writable`

Measured radar cross section [m^2], or None.

`sensor` `property`

Sensor that produced the observation.

`signal_measurement` `property`

Optional bistatic / DOA signal payload.

`tdoa` `property`

Convenience accessor for signal_measurement.tdoa [s].

`topocentric_state` `property`

Observer location and observed elements (RA/Dec [rad], range [km], range-rate [km/s]).

`visual_magnitude` `property` `writable`

Measured visual magnitude [mag], or None.

`init(sensor, topocentric_state)`

Creates an Observation from a sensor and topocentric state.

The new observation receives a fresh UUID4 id and no signal measurement.

Parameters:

Name	Type	Description	Default
`sensor`	`Sensor`	Sensor that produced the measurement.	required
`topocentric_state`	`TopocentricState`	Observer location and observed angle/range elements.	required

`from_citra_doa_observation(payload)` `staticmethod`

Builds an Observation from a CITRA DOA (TDOA/FDOA) record.

The resulting observation has no angle elements; only the SignalMeasurement payload (TDOA [s], optional FDOA [Hz]).

Parameters:

Name	Type	Description	Default
`payload`	`dict[str, object]`	Mapping with the CITRA DOA schema fields (`id`, primary/secondary antenna ids, `epoch`, `tdoa` [s], `tdoa_noise` [s], optional `fdoa` [Hz], primary/secondary sensor lat/lon/alt).	required

Returns:

Type	Description
`Observation`	DOA observation in the TEME frame.

Raises:

Type	Description
`ValueError`	If required fields are missing or the epoch fails to parse.

`from_citra_optical_observation(payload)` `staticmethod`

Builds an Observation from a CITRA optical-observation record.

Sensor latitude and longitude are read in degrees and converted to radians internally; right ascension, declination, and angle-rate noise fields likewise convert from degrees to radians.

Parameters:

Name	Type	Description	Default
`payload`	`dict[str, object]`	Mapping with the CITRA optical schema fields (`id`, `telescope_id`, `epoch`, `right_ascension`, `declination`, `angular_noise`, sensor latitude/longitude/ altitude, optional rate fields).	required

Returns:

Type	Description
`Observation`	Optical observation in the TEME frame.

Raises:

Type	Description
`ValueError`	If required fields are missing or the epoch fails to parse.

`from_citra_radar_observation(payload)` `staticmethod`

Builds an Observation from a CITRA radar-observation record.

When all three secondary-sensor coordinates are present the observation is treated as bistatic and a SignalMeasurement is attached; the range field is then interpreted as the bistatic path length ρ₁ + ρ₂.

Missing measurement noise is defaulted to the package constants when the corresponding measurement is present: range to 0.1 km, range-rate to 0.001 km/s, and angles to 0.0005 deg. A reported noise value always takes precedence, and a measurement that is itself absent leaves its noise unset.

Parameters:

Name	Type	Description	Default
`payload`	`dict[str, object]`	Mapping with the CITRA radar schema fields (`id`, `antenna_id`, `epoch`, optional `range` [km] / `range_rate` [km/s], optional angles, sensor location).	required

Returns:

Type	Description
`Observation`	Radar (mono- or bistatic) observation in the TEME frame.

Raises:

Type	Description
`ValueError`	If required fields are missing or the epoch fails to parse.

`get_associations(sats)`

Returns the candidate associations of this observation against a constellation.

Internally evaluates get_residual for every member and keeps the candidates whose residuals fall inside the per-confidence-level gates configured on the sensor.

Parameters:

Name	Type	Description	Default
`sats`	`Constellation`	Catalog of candidate satellites.	required

Returns:

Type	Description
`list[ObservationAssociation]`	All candidate associations sorted strongest-first.

Raises:

Type	Description
`ValueError`	If propagation fails for any catalog member.

`get_residual(sat)`

Computes the observed-minus-expected residual against a satellite.

Propagates sat to epoch in TEME and forms the residual from the predicted topocentric state. None when the observation cannot be projected against the given satellite (e.g., line of sight below the horizon for an angles-only optical observation).

Parameters:

Name	Type	Description	Default
`sat`	`Satellite`	Candidate satellite to evaluate against.	required

Returns:

Type	Description
`ObservationResidual \| None`	Populated residual, or `None`.

Raises:

Type	Description
`ValueError`	If satellite propagation fails.

`with_fdoa(fdoa)`

Returns a copy with the FDOA component of the signal measurement replaced.

Parameters:

Name	Type	Description	Default
`fdoa`	`float \| None`	New frequency-difference-of-arrival [Hz], or `None` to clear.	required

Returns:

Type	Description
`Observation`	New observation with the updated FDOA value.

`with_signal_measurement(signal_measurement)`

Returns a copy with the signal-measurement payload replaced.

Parameters:

Name	Type	Description	Default
`signal_measurement`	`SignalMeasurement \| None`	Bistatic / DOA payload, or `None` to clear.	required

Returns:

Type	Description
`Observation`	New observation with `signal_measurement` replaced.

`with_tdoa(tdoa)`

Returns a copy with the TDOA component of the signal measurement replaced.

Parameters:

Name	Type	Description	Default
`tdoa`	`float \| None`	New time-difference-of-arrival [s], or `None` to clear.	required

Returns:

Type	Description
`Observation`	New observation with the updated TDOA value.

`with_visual_magnitude(vismag)`

Returns a copy with the visual magnitude replaced.

Parameters:

Name	Type	Description	Default
`vismag`	`float \| None`	Visual magnitude [mag], or `None` to clear.	required

Returns:

Type	Description
`Observation`	New observation with the updated visual magnitude.

`ObservationAssociation`

Association between an observation and a candidate satellite.

Produced by get_associations and get_association_report. Carries the residual that drove the gate-pass plus the discrete confidence level assigned by the sensor's noise model.

Attributes:

Name	Type	Description
`observation_id`	`str`	Identifier of the source observation.
`satellite_id`	`str`	Identifier of the associated satellite.
`residual`	`ObservationResidual`	Residual evaluated for this pairing.
`confidence`	`AssociationConfidence`	Discrete association confidence level (None / Low / Medium / High).

`confidence` `property`

Discrete association confidence level.

`observation_id` `property`

Identifier of the source observation.

`residual` `property`

Residual evaluated for this pairing.

`satellite_id` `property`

Identifier of the associated satellite.

`init(observation_id, satellite_id, residual, confidence)`

Creates an ObservationAssociation.

Parameters:

Name	Type	Description	Default
`observation_id`	`str`	Identifier of the source observation.	required
`satellite_id`	`str`	Identifier of the associated satellite.	required
`residual`	`ObservationResidual`	Residual evaluated for this pairing.	required
`confidence`	`AssociationConfidence`	Discrete association confidence level.	required

`ObservationCollection`

A group of observations sharing one epoch, sensor, and observer location.

The constructor enforces this invariant: every observation must share exactly the same epoch, id, and observer position. The aggregate boresight direction and field-of-view diameter are derived from the spread of observed line-of-sight vectors.

Attributes:

Name	Type	Description
`sensor_position`	`CartesianVector`	Inertial position of the sensor at the collection epoch [km].
`sensor_direction`	`CartesianVector`	Unit vector of the mean boresight across the collection [dimensionless].
`field_of_view`	`float`	Twice the maximum angular distance from any observation's line of sight to `sensor_direction` [rad].
`observations`	`list[Observation]`	Observations in the collection.
`epoch`	`ModifiedJulianDate`	Shared epoch of all observations.

`epoch` `property`

Shared epoch of all observations.

`field_of_view` `property`

Twice the maximum angular distance from any observation's line of sight to sensor_direction [rad].

`observations` `property`

Observations in the collection.

`sensor_direction` `property`

Unit vector of the mean boresight across the collection [dimensionless].

`sensor_position` `property`

Inertial position of the sensor at the collection epoch [km].

`init(observations)`

Creates an ObservationCollection.

Parameters:

Name	Type	Description	Default
`observations`	`list[Observation]`	Observations to group. Must be non-empty and share a single epoch, sensor id, and observer position.	required

Raises:

Type	Description
`ValueError`	If the list is empty or any observation violates the shared-epoch / shared-sensor / shared-position invariant.

`get_association(satellite)`

Returns the strongest association of this collection with a single satellite.

Parameters:

Name	Type	Description	Default
`satellite`	`Satellite`	Candidate satellite.	required

Returns:

Type	Description
`ObservationAssociation \| None`	Strongest gate-passing association, or `None` when no
`ObservationAssociation \| None`	observation in the collection associates with `satellite`.

Raises:

Type	Description
`ValueError`	If propagation of `satellite` fails.

`get_association_report(satellites)`

Associates this collection against a constellation.

Parameters:

Name	Type	Description	Default
`satellites`	`Constellation`	Catalog of candidate satellites.	required

Returns:

Type	Description
`CollectionAssociationReport`	Per-collection report of orphan observations and associations.

Raises:

Type	Description
`ValueError`	If the constellation argument is missing or propagation of any catalog member fails.

`get_list(observations)` `staticmethod`

Groups a flat list of observations into collections by (epoch, sensor_id).

Observations whose grouping fails the collection invariant (e.g., differing observer positions for the same sensor id) are silently dropped; this is intended for converting a heterogeneous CITRA dump into an iterable of well-formed collections.

Parameters:

Name	Type	Description	Default
`observations`	`list[Observation]`	Mixed observations.	required

Returns:

Type	Description
`list[ObservationCollection]`	One `ObservationCollection` per `(epoch, sensor_id)`
`list[ObservationCollection]`	group that satisfied the invariant.

`get_visibility(satellite)`

Checks whether a satellite is geometrically inside the collection's field of view at epoch.

Parameters:

Name	Type	Description	Default
`satellite`	`Satellite`	Candidate satellite.	required

Returns:

Type	Description
`bool`	`True` when the satellite's predicted line of sight from
`bool`	`sensor_position` falls within
`bool`	`field_of_view` / 2 of `sensor_direction`.

`ObservationResidual`

Observed-minus-expected residual in topocentric and orbit-relative frames.

The residual carries both raw topocentric deltas (RA/Dec/range/range-rate) and a derived orbit-relative ("RIC") closure expressed in radial / in-track / cross-track components, so downstream consumers (BLS, Kalman filter, association report) can pick whichever projection they need.

Attributes:

Name	Type	Description
`epoch`	`ModifiedJulianDate`	Epoch the residual is evaluated at.
`cross_line_of_sight`	`float`	Cross-line-of-sight closure magnitude [km; ≥ 0]. For angle-only observations this is the magnitude of the relative position vector between the observed line of sight (extended to the expected slant range) and the expected satellite position.
`time`	`float`	Along-track time offset [s].
`radial`	`float`	Radial position component [km].
`in_track`	`float`	In-track position component [km].
`cross_track`	`float`	Cross-track position component [km].
`velocity`	`float`	Relative velocity magnitude [km/s; ≥ 0].
`radial_velocity`	`float`	Radial velocity component [km/s].
`in_track_velocity`	`float`	In-track velocity component [km/s].
`cross_track_velocity`	`float`	Cross-track velocity component [km/s].
`beta`	`float`	Cross-track beta angle [rad].
`height`	`float`	Height residual [km].
`range`	`float \| None`	Observed-minus-expected range [km].
`right_ascension`	`float \| None`	Observed-minus-expected right ascension [rad; wrapped to (-π, π]].
`declination`	`float \| None`	Observed-minus-expected declination [rad].
`range_rate`	`float \| None`	Observed-minus-expected range-rate [km/s].
`right_ascension_rate`	`float \| None`	Observed-minus-expected right ascension rate [rad/s].
`declination_rate`	`float \| None`	Observed-minus-expected declination rate [rad/s].
`tdoa`	`float \| None`	Observed-minus-expected time-difference-of-arrival [s].
`fdoa`	`float \| None`	Observed-minus-expected frequency-difference-of-arrival [Hz].
`angle`	`float \| None`	Great-circle angular separation between observed and expected pointing [rad; ≥ 0]. `None` when the observation lacks RA or Dec.
`angular_rate`	`float \| None`	Magnitude of the angular-rate residual with the standard `cos(dec)` scaling on the right-ascension-rate component [rad/s; ≥ 0]. `None` when the observation lacks an angle-rate measurement.

`angle` `property`

Great-circle angular separation between observed and expected pointing [rad; ≥ 0]. None when the observation lacks RA or Dec.

`angular_rate` `property`

Magnitude of the angular-rate residual with the standard cos(dec) scaling on the right-ascension-rate component [rad/s; ≥ 0]. None when the observation lacks an angle-rate measurement.

`beta` `property`

Cross-track beta angle [rad].

`cross_line_of_sight` `property`

Cross-line-of-sight closure magnitude [km; ≥ 0].

For angle-only observations this is the magnitude of the relative position vector between the observed line of sight (extended to the expected slant range) and the expected satellite position.

`cross_track` `property`

Cross-track position component [km].

`cross_track_velocity` `property`

Cross-track velocity component [km/s].

`declination` `property`

Observed-minus-expected declination [rad].

`declination_rate` `property`

Observed-minus-expected declination rate [rad/s].

`epoch` `property`

Epoch the residual is evaluated at.

`fdoa` `property`

Observed-minus-expected frequency-difference-of-arrival [Hz].

`height` `property`

Height residual [km].

`in_track` `property`

In-track position component [km].

`in_track_velocity` `property`

In-track velocity component [km/s].

`radial` `property`

Radial position component [km].

`radial_velocity` `property`

Radial velocity component [km/s].

`range` `property`

Observed-minus-expected range [km].

`range_rate` `property`

Observed-minus-expected range-rate [km/s].

`right_ascension` `property`

Observed-minus-expected right ascension [rad; wrapped to (-π, π]].

`right_ascension_rate` `property`

Observed-minus-expected right ascension rate [rad/s].

`tdoa` `property`

Observed-minus-expected time-difference-of-arrival [s].

`time` `property`

Along-track time offset [s].

`velocity` `property`

Relative velocity magnitude [km/s; ≥ 0].

`init(epoch, cross_line_of_sight, time, radial, in_track, cross_track, velocity, radial_velocity, in_track_velocity, cross_track_velocity, beta, height)`

Creates an ObservationResidual from the orbit-relative components.

Optional measurement-frame residuals (RA/Dec/range/...) start as None and are populated separately by the residual builder.

Parameters:

Name	Type	Description	Default
`epoch`	`ModifiedJulianDate`	Epoch the residual is evaluated at.	required
`cross_line_of_sight`	`float`	Cross-line-of-sight closure magnitude [km; ≥ 0].	required
`time`	`float`	Along-track time offset [s].	required
`radial`	`float`	Radial position component [km].	required
`in_track`	`float`	In-track position component [km].	required
`cross_track`	`float`	Cross-track position component [km].	required
`velocity`	`float`	Relative velocity magnitude [km/s; ≥ 0].	required
`radial_velocity`	`float`	Radial velocity component [km/s].	required
`in_track_velocity`	`float`	In-track velocity component [km/s].	required
`cross_track_velocity`	`float`	Cross-track velocity component [km/s].	required
`beta`	`float`	Cross-track beta angle [rad].	required
`height`	`float`	Height residual [km].	required

`OrbitDeterminationReport`

Quality summary produced after a BatchLeastSquares solve.

The metrics are computed from the post-fit residuals, the post-fit covariance, and a single propagation pass over the fit observations. The overall quality label is computed from a fixed ruleset over the individual metrics; see OrbitDeterminationQuality.

Attributes:

Name	Type	Description
`coverage`	`float`	Fraction of 24 mean-anomaly bins (15° wide) covered by the fit observations [dimensionless; 0..1].
`periods`	`float`	Span of the fit window expressed in orbital periods [dimensionless; ≥ 0].
`number_of_sensors`	`int`	Count of distinct sensor ids that contributed observations to the fit.
`number_of_phenomenologies`	`int`	Count of distinct measurement phenomenologies (range / angles-only / TDOA) used in the fit [dimensionless; 0..3].
`position_sigma`	`float`	Trace-RSS position sigma from the post-fit covariance, in the RIC frame [km; ≥ 0].
`velocity_sigma`	`float`	Trace-RSS velocity sigma from the post-fit covariance, in the RIC frame [km/s; ≥ 0].
`geometry`	`float`	Sensor-to-target geometric diversity expressed as a `2·atan(s_mid / s_max)` mapping of the mid/max singular values of the line-of-sight matrix [deg; 0..90].
`rms`	`float \| None`	Unweighted RMS of the dominant residual component (range when present, else cross-line-of-sight) [km; ≥ 0]. `None` when no residuals are available.
`weighted_rms`	`float \| None`	Weighted RMS in measurement-sigma units [dimensionless; ≥ 0]. `None` when the solver has not yet built a weighted residual.
`converged`	`bool`	Whether the solver reported convergence.
`residual_trend_r_squared`	`float`	R² of a linear fit of the dominant residual component versus epoch [dimensionless; 0..1]. Used to flag systematic post-fit drift.
`quality`	`OrbitDeterminationQuality`	Discrete overall quality label (Low / Medium / High).

`converged` `property`

Whether the solver reported convergence.

`coverage` `property`

Fraction of the 24 mean-anomaly bins covered by the fit [dimensionless; 0..1].

`geometry` `property`

Sensor-to-target geometric diversity from the line-of-sight SVD [deg; 0..90].

`number_of_phenomenologies` `property`

Count of distinct phenomenologies (range / angles-only / TDOA) used in the fit [0..3].

`number_of_sensors` `property`

Count of distinct sensor ids that contributed to the fit.

`periods` `property`

Span of the fit window in orbital periods [dimensionless; ≥ 0].

`position_sigma` `property`

Trace-RSS position sigma from the post-fit RIC covariance [km; ≥ 0].

`quality` `property`

Discrete overall quality label.

`residual_trend_r_squared` `property`

R² of a linear fit of residual versus epoch [dimensionless; 0..1].

`rms` `property`

Unweighted RMS of the dominant residual component [km; ≥ 0].

`velocity_sigma` `property`

Trace-RSS velocity sigma from the post-fit RIC covariance [km/s; ≥ 0].

`weighted_rms` `property`

Weighted RMS in measurement-sigma units [dimensionless; ≥ 0].

`ProcessNoise`

Continuous-to-discrete process-noise model for Kalman filters.

Two layouts are supported:

Diagonal (uncoupled): one spectral density per state element. Builds Q = diag(spectral_densities) · |dt| and is intended for equinoctial states or any parameterization without explicit pos/vel pairing.
Coupled Cartesian: per-axis acceleration spectral densities drive paired (position_i, velocity_{i + n_axes}) 2×2 blocks using the piecewise-constant acceleration model (Q_pp = q · dt³/3, Q_pv = q · dt²/2, Q_vv = q · dt). Optional uncoupled extra_psd terms are appended for drag (B*) and SRP (A/m) parameters.

See default_cartesian and default_equinoctial for the canonical defaults used throughout the filter test suite.

Attributes:

Name	Type	Description
`dimension`	`int`	Total state-vector dimension covered by the model.

`dimension` `property`

Total state-vector dimension covered by the model.

`init(spectral_densities)`

Creates an uncoupled diagonal ProcessNoise.

Parameters:

Name	Type	Description	Default
`spectral_densities`	`list[float]`	Per-element continuous spectral densities [unit² / s]; multiplied by `\|dt\|` to form the discrete Q.	required

`cartesian(acceleration_psd, extra_psd)` `staticmethod`

Builds coupled-Cartesian process noise from acceleration spectral densities.

Parameters:

Name	Type	Description	Default
`acceleration_psd`	`list[float]`	Per-axis acceleration spectral densities [km²/s⁵]; one entry per Cartesian axis. Three entries produce a 6-element pos/vel block.	required
`extra_psd`	`list[float]`	Spectral densities for additional uncoupled parameters appended after the pos/vel block (drag, SRP, etc.).	required

Returns:

Type	Description
`ProcessNoise`	Configured `ProcessNoise`.

`default_cartesian()` `staticmethod`

Default 6-element Cartesian process noise.

Uses the piecewise-constant acceleration model with per-axis spectral density 5e-18 km²/s⁵ on each of the three position/velocity pairs.

The density trades clean-arc stiffness for robustness to unmodeled dynamics. A stiffer 5e-20 gives a tighter final-state span-fit on a clean arc, but mass-rejects on real LEO arcs with unmodeled drag — where the looser 5e-18 keeps the innovation gate open (e.g. it lifts a drag-dominated CSSWE handoff from ~0% to ~99% accept). 5e-18 is the better general default for operational LEO OD; supply 5e-20 explicitly for clean, well-determined arcs that want the stiffest span-fit, or enable adaptive_process_noise to let the filter scale this nominal level to match its innovations.

Returns:

Type	Description
`ProcessNoise`	Configured `ProcessNoise`.

`default_cartesian_with_drag()` `staticmethod`

Default 7-element Cartesian process noise (adds drag B-term).

Returns:

Type	Description
`ProcessNoise`	Configured `ProcessNoise`.

`default_cartesian_with_drag_srp()` `staticmethod`

Default 8-element Cartesian process noise (adds drag and SRP).

Returns:

Type	Description
`ProcessNoise`	Configured `ProcessNoise`.

`default_equinoctial()` `staticmethod`

Default 6-element equinoctial process noise.

Layout [a (km), af, ag, chi, psi, mean_longitude (rad)] with spectral densities chosen to match canonical equinoctial filter tuning (semi-major-axis term 1e-6 km²/s; angular terms 1e-12 rad²/s).

Returns:

Type	Description
`ProcessNoise`	Configured `ProcessNoise`.

`default_equinoctial_with_drag()` `staticmethod`

Default 7-element equinoctial process noise (adds drag B-term).

Returns:

Type	Description
`ProcessNoise`	Configured `ProcessNoise`.

`default_equinoctial_with_drag_srp()` `staticmethod`

Default 8-element equinoctial process noise (adds drag and SRP).

Returns:

Type	Description
`ProcessNoise`	Configured `ProcessNoise`.

`SigmaPointParameters`

Sigma-point scaling parameters for the Van der Merwe scaled UKF.

Attributes:

Name	Type	Description
`alpha`	`float`	Sigma-point spread parameter [dimensionless; small positive]. Default `1e-3`.
`beta`	`float`	Distribution-shape parameter [dimensionless]. `2.0` is optimal for Gaussian state distributions.
`kappa`	`float`	Secondary scaling parameter [dimensionless]. `0.0` is the standard choice for state estimation.

`alpha` `property`

Sigma-point spread parameter [dimensionless].

`beta` `property`

Distribution-shape parameter [dimensionless].

`kappa` `property`

Secondary scaling parameter [dimensionless].

`init(alpha=0.001, beta=2.0, kappa=0.0)`

Creates a SigmaPointParameters tuple.

Parameters:

Name	Type	Description	Default
`alpha`	`float`	Sigma-point spread parameter. Defaults to `1e-3`.	`0.001`
`beta`	`float`	Distribution-shape parameter. Defaults to `2.0` (Gaussian optimum).	`2.0`
`kappa`	`float`	Secondary scaling parameter. Defaults to `0.0`.	`0.0`

`SignalMeasurement`

Bistatic / passive-RF signal measurement attached to an observation.

Carries the second sensor location together with the time-difference-of-arrival (TDOA) and optional frequency-difference-of-arrival (FDOA) used for multi-static geolocation. Presence of a SignalMeasurement on an Observation triggers the bistatic-residual code path in get_residual.

Attributes:

Name	Type	Description
`second_origin_state`	`CartesianState`	Inertial state of the second sensor at the measurement epoch [km, km/s].
`tdoa`	`float`	Time-difference-of-arrival (path 2 minus path 1) [s].
`fdoa`	`float \| None`	Frequency-difference-of-arrival [Hz]. `None` when the system did not measure FDOA.
`transmission_frequency`	`float \| None`	Carrier frequency of the emitter [Hz], required to convert FDOA to a range-rate residual.

`fdoa` `property`

Frequency-difference-of-arrival [Hz], or None.

`second_origin_state` `property`

Inertial state of the second sensor at the measurement epoch [km, km/s].

`tdoa` `property`

Time-difference-of-arrival (path 2 minus path 1) [s].

`transmission_frequency` `property`

Carrier frequency of the emitter [Hz], or None.

`init(second_origin_state, tdoa, fdoa=..., transmission_frequency=...)`

Creates a SignalMeasurement.

Parameters:

Name	Type	Description	Default
`second_origin_state`	`CartesianState`	Inertial state of the second sensor at the measurement epoch [km, km/s].	required
`tdoa`	`float`	Time-difference-of-arrival (path 2 minus path 1) [s].	required
`fdoa`	`float \| None`	Frequency-difference-of-arrival [Hz]. Optional.	`...`
`transmission_frequency`	`float \| None`	Carrier frequency of the emitter [Hz]. Required to convert FDOA into a range-rate residual.	`...`

`TrackletAssociation`

Association between a tracklet and a candidate catalog satellite.

Produced by Tracklet.get_associations. Carries the satellite the tracklet matched, the aggregate TrackletResidual (mean and slope offsets) that drove the gate, and the discrete confidence assigned by the worst-matching component.

Attributes:

Name	Type	Description
`satellite_id`	`str`	Identifier of the associated satellite.
`residual`	`TrackletResidual`	Aggregate offset between the tracklet's measured track and the satellite's predicted track.
`confidence`	`AssociationConfidence`	Discrete association confidence (Low / Medium / High).

`confidence` `property`

Discrete association confidence (Low / Medium / High).

`residual` `property`

Aggregate offset between the tracklet and the predicted track.

`satellite_id` `property`

Identifier of the associated satellite.

`TrackletAssociationConfig`

Gate thresholds for tracklet-to-catalog association, by component.

Used by Tracklet.get_associations. Each component carries three nested cutoffs — high for a high-confidence match, medium for medium confidence, and low for the largest offset still accepted. An offset above low rejects the pairing on that component; the tracklet's overall confidence is the worst across present components.

Distinct from AssociationConfig (which gates instantaneous per-observation residuals): these gates act on whole-arc fitted statistics. The angular components are always present; the range components apply only when every observation carries that measurement.

Attributes:

Name	Type	Description
`high_angle`	`float`	High-confidence angular-position offset cutoff [rad].
`medium_angle`	`float`	Medium-confidence angular-position offset cutoff [rad].
`low_angle`	`float`	Maximum accepted angular-position offset cutoff [rad].
`high_angle_rate`	`float`	High-confidence angular-rate (slope) offset cutoff [rad/s].
`medium_angle_rate`	`float`	Medium-confidence angular-rate (slope) offset cutoff [rad/s].
`low_angle_rate`	`float`	Maximum accepted angular-rate (slope) offset cutoff [rad/s].
`high_range`	`float`	High-confidence range mean-offset cutoff [km].
`medium_range`	`float`	Medium-confidence range mean-offset cutoff [km].
`low_range`	`float`	Maximum accepted range mean-offset cutoff [km].
`high_range_slope`	`float`	High-confidence range-slope offset cutoff [km/s].
`medium_range_slope`	`float`	Medium-confidence range-slope offset cutoff [km/s].
`low_range_slope`	`float`	Maximum accepted range-slope offset cutoff [km/s].
`high_range_rate`	`float`	High-confidence range-rate mean-offset cutoff [km/s].
`medium_range_rate`	`float`	Medium-confidence range-rate mean-offset cutoff [km/s].
`low_range_rate`	`float`	Maximum accepted range-rate mean-offset cutoff [km/s].

`init(angle, angle_rate, range, range_slope, range_rate)`

Creates a TrackletAssociationConfig from grouped (high, medium, low) triples.

Parameters:

Name	Type	Description	Default
`angle`	`tuple[float, float, float]`	`(high, medium, low)` angular-position offset cutoffs [rad].	required
`angle_rate`	`tuple[float, float, float]`	`(high, medium, low)` angular-rate (slope) offset cutoffs [rad/s].	required
`range`	`tuple[float, float, float]`	`(high, medium, low)` range mean-offset cutoffs [km].	required
`range_slope`	`tuple[float, float, float]`	`(high, medium, low)` range-slope offset cutoffs [km/s].	required
`range_rate`	`tuple[float, float, float]`	`(high, medium, low)` range-rate mean-offset cutoffs [km/s].	required

`default()` `staticmethod`

Creates a TrackletAssociationConfig with the built-in default thresholds.

Returns:

Type	Description
`TrackletAssociationConfig`	Configuration with default cutoffs (angle: 1e-4/1e-3/1e-2 rad,
`TrackletAssociationConfig`	angle-rate: 1e-7/1e-6/1e-5 rad/s, range: 5/50/500 km, range-slope
`TrackletAssociationConfig`	and range-rate: 1e-3/1e-2/1e-1 km/s).

`TrackletResidual`

Aggregate offset between a tracklet's track and a satellite's predicted track.

Produced by Tracklet.get_associations and carried on each TrackletAssociation. Every field is an observed-minus-predicted offset derived from the per-observation residual series: the arc mean of the residual is the mean-vs-expected offset and its slope is the slope-vs-expected-rate offset. The range fields are None for angles-only (optical) tracklets.

Attributes:

Name	Type	Description
`mid_epoch`	`ModifiedJulianDate`	Arc mid-epoch the offsets are reported at.
`observation_count`	`int`	Number of observations behind the fit.
`angular_position`	`float`	Arc-centroid angular offset `sqrt((mean(dRA)*cos(dec))^2 + mean(dDec)^2)` [rad; >= 0].
`angular_rate`	`float`	Angular-rate (slope) offset `sqrt((slope(dRA)*cos(dec))^2 + slope(dDec)^2)` [rad/s; >= 0].
`range`	`float \| None`	Range mean offset `mean(dRange)` [km], or `None` for angles-only tracklets.
`range_slope`	`float \| None`	Range-slope offset `slope(dRange)` [km/s], or `None`.
`range_rate`	`float \| None`	Range-rate mean offset `mean(dRangeRate)` [km/s], or `None`.

`angular_position` `property`

Arc-centroid angular-position offset [rad; >= 0].

`angular_rate` `property`

Angular-rate (slope) offset [rad/s; >= 0].

`mid_epoch` `property`

Arc mid-epoch the offsets are reported at.

`observation_count` `property`

Number of observations behind the fit.

`range` `property`

Range mean offset [km], or None for angles-only tracklets.

`range_rate` `property`

Range-rate mean offset [km/s], or None.

`range_slope` `property`

Range-slope offset [km/s], or None.

`UnscentedKalmanFilter`

Unscented Kalman Filter for sequential orbit determination.

Uses the Van der Merwe scaled sigma-point formulation (parameters configured by set_sigma_parameters) to propagate the state distribution through the (nonlinear) propagation and measurement models without requiring analytic Jacobians. Reference: Vallado §10.4 and the Orekit UnscentedKalmanEstimator formulation.

The internal state vector is Cartesian [x, y, z, vx, vy, vz] in [km] and [km/s], optionally extended with drag and SRP parameters when those flags are enabled.

Attributes:

Name	Type	Description
`residuals`	`list[ObservationResidual]`	Residuals from the last solve.
`estimate_drag`	`bool`	Whether the drag B-term is part of the estimated state.
`estimate_srp`	`bool`	Whether the SRP A/m term is part of the estimated state.
`current_estimate`	`Satellite`	Current best satellite estimate with the filter covariance attached.
`covariance`	`CovarianceMatrix`	Current filter covariance.
`epoch`	`ModifiedJulianDate \| None`	Epoch of `current_estimate`, or `None` before the first observation.
`innovation_gate_chi_squared`	`float \| None`	Normalized innovation-squared gate; `None` disables rejection.
`last_update_accepted`	`bool \| None`	Acceptance status for the most recent observation.
`last_observation_id`	`str \| None`	Identifier of the most recent observation.
`last_innovation_chi_squared`	`float \| None`	Normalized innovation squared for the most recent observation.
`last_measurement_dimension`	`int \| None`	Measurement-vector length for the most recent observation.
`accepted_observation_ids`	`list[str]`	Observation ids accepted by the innovation gate.
`rejected_observation_ids`	`list[str]`	Observation ids rejected by the innovation gate.

`accepted_observation_ids` `property`

Observation identifiers accepted by the innovation gate.

`adaptive_process_noise` `property` `writable`

Whether online adaptive process noise (covariance matching) is on.

When enabled, the discrete process noise Q is multiplied by process_noise_scale, nudged after each accepted update so the windowed mean normalized innovation squared (NIS / m) tracks 1 — the filter stays statistically consistent over the arc instead of relying on a hand-tuned nominal level. Enabling also pins measurement_noise_scale to 1 (honest R): persistent surprise is absorbed as dynamics uncertainty by Q, while transient outliers stay the job of robust_huber_threshold and the χ² gate. Toggling resets the scale and clears the window. Default False.

`covariance` `property`

Covariance of the current estimate.

Matches the covariance attached to current_estimate: the fixed-lag-smoothed covariance when smoothing is engaged (the default), otherwise the forward-filtered covariance — so the mean and covariance you persist always come from the same computation. The returned matrix uses CovarianceType.Inertial(TEME) and the Cartesian state-vector layout [x, y, z, vx, vy, vz] in [km, km/s], with optional drag/SRP states appended when enabled.

Raises:

Type	Description
`ValueError`	If no state has been produced yet, or a smoothing step fails.

`current_estimate` `property`

Current best satellite estimate, epoched at the latest observation.

Fixed-lag smoothing is on by default (120 h), so this is the fixed-lag-smoothed orbit: the RTS-smoothed state at now − lag propagated forward to the latest epoch, carrying the arc-consistent velocity/energy that makes it accurate under extended propagation. On a short or sparse arc that does not yet span the lag, it is smoothed best-available (anchored at the earliest observation); with smoothing_lag == 0 it falls back to the latest filtered state. The attached covariance is the same matrix returned by covariance.

Raises:

Type	Description
`ValueError`	If no state has been produced yet, or a smoothing step fails.

`epoch` `property`

Epoch of current_estimate, or None before the first accepted or rejected observation is processed.

`estimate_drag` `property` `writable`

Whether the drag B-term is part of the estimated state.

`estimate_srp` `property` `writable`

Whether the SRP A/m term is part of the estimated state.

`innovation_gate_chi_squared` `property` `writable`

Normalized innovation-squared rejection gate, or None.

`last_innovation_chi_squared` `property`

Normalized innovation squared for the most recent observation.

`last_measurement_dimension` `property`

Measurement-vector length for the most recent observation.

`last_observation_id` `property`

Identifier of the most recently processed observation.

`last_update_accepted` `property`

Whether the most recent observation update was accepted.

`measurement_noise_scale` `property` `writable`

Multiplier on measurement-noise standard deviations (the noise covariance R is scaled by the square). 1.0 uses the sensor noise as-is; values > 1 underweight observations to reflect un-modeled error so the assumed noise matches the achievable fit (e.g. set from the batch weighted-RMS).

`process_noise_scale` `property`

Current adaptive multiplier on the nominal discrete Q.

1.0 when adaptive_process_noise is disabled or has not yet filled its first averaging window; otherwise the latest covariance-matching scale.

`rejected_observation_ids` `property`

Observation identifiers rejected by the innovation gate.

`residuals` `property`

Residuals from the last solve.

`robust_huber_threshold` `property` `writable`

Huber robust-weighting threshold on the standardized innovation (sqrt of the NIS). None disables robust weighting. When set, an observation whose standardized innovation exceeds this value is soft down-weighted (its measurement noise is inflated) instead of being fully trusted or hard-rejected; the reported innovation/NIS stay un-weighted.

`smoothing_lag` `property` `writable`

Fixed-lag smoothing lag.

Defaults to 120 h (on). A positive lag turns on fixed-lag smoothing: current_estimate becomes the smoothed orbit — conditioned on the observations up to lag behind the latest, then propagated to the latest epoch — which is accurate over extended propagation. On an arc shorter than the lag the estimate is smoothed best-available (anchored at the earliest observation), so there is no smoothing dead-zone during ramp-up. Set zero for a pure forward filter, so current_estimate is the latest filtered state.

`init(observations, a_priori)`

Creates an UnscentedKalmanFilter.

Parameters:

Name	Type	Description	Default
`observations`	`list[Observation]`	Observations to process, in chronological order.	required
`a_priori`	`Satellite`	A-priori satellite carrying `cartesian_state`. The filter uses that state epoch and either the attached covariance (used as-is, never floored) or a default 0.5 km / 5e-5 km/s per-axis Cartesian covariance when none is attached, before propagating to the first observation.	required

Raises:

Type	Description
`ValueError`	If `a_priori` has no attached Cartesian state.

`process_observation(observation)`

Processes one observation through the filter.

The filter predicts from the current estimate epoch to the observation epoch, computes the normalized innovation squared, and applies the measurement update only when it passes innovation_gate_chi_squared. When the gate is None the update is always accepted.

Parameters:

Name	Type	Description	Default
`observation`	`Observation`	Observation to process.	required

Returns:

Type	Description
`bool`	`True` when the update was accepted, or `False` when it was
`bool`	rejected by the innovation gate.

Raises:

Type	Description
`ValueError`	If propagation or measurement update setup fails.

`set_adaptive_process_noise_parameters(window, scale_min, scale_max, ewma)`

Sets the adaptive-feedback tuning.

Parameters:

Name	Type	Description	Default
`window`	`int`	Accepted updates averaged before each scale nudge [clamped to >= 1].	required
`scale_min`	`float`	Lower clamp on the `Q` multiplier.	required
`scale_max`	`float`	Upper clamp on the `Q` multiplier.	required
`ewma`	`float`	EWMA exponent of the multiplicative update; smaller values adapt more gently.	required

`set_process_noise(process_noise)`

Sets the process-noise model used during the propagation step.

Parameters:

Name	Type	Description	Default
`process_noise`	`ProcessNoise`	Process-noise model to apply between observations.	required

`set_sigma_parameters(params)`

Sets the sigma-point scaling parameters.

Parameters:

Name	Type	Description	Default
`params`	`SigmaPointParameters`	New scaling parameters.	required

`smooth()`

Run the Rauch-Tung-Striebel smoother and return arc-consistent estimates.

The forward filter is sequential, so current_estimate is recency-weighted and a single forward-filter state does not fit the whole observation arc. The RTS backward pass produces a state at each processed-observation epoch that conditions on all observations, so a single smoothed state fits the whole arc — down toward measurement noise — far better than the forward-only estimate.

Returns:

Type	Description
`list[Satellite]`	Smoothed estimates with covariance, at each processed-observation
`list[Satellite]`	epoch, in chronological order.

Raises:

Type	Description
`ValueError`	If the filter has processed no observations, or a step cannot be smoothed (e.g. a singular predicted covariance).

`smoothed_residuals()`

Per-epoch smoothed residuals, computed in one parallel pass.

Each processed observation is scored against the RTS-smoothed state at its own epoch (the honest filter-health view). Prefer this over a per-observation get_residual loop: the work runs once in Rust across cores instead of N Python calls.

Returns:

Type	Description
`list[ObservationResidual]`	One `ObservationResidual`
`list[ObservationResidual]`	per processed observation, in chronological order (aligned with
`list[ObservationResidual]`	`smooth`).

Raises:

Type	Description
`ValueError`	If the filter has processed no observations, or a residual cannot be formed for an observation.

`solve()`

Processes every observation in chronological order, alternating sigma-point propagation and measurement-update steps.

Returns:

Name	Type	Description
`FilterResult`	`FilterResult`	Per-step diagnostics and the final filter state.

Raises:

Type	Description
`ValueError`	If propagation or measurement update fails.

`with_a_priori_observations(a_priori_observations)`

Primes the fixed-lag smoother with recent a-priori (past-arc) obs.

Processes the a-priori observations within the trailing smoothing_lag window before the seed epoch (in chronological order), so the filter enters the incoming arc with smoother history built from the recent past: current_estimate is then smoothed across the seed boundary rather than resting on the seed prior alone. Bounded to the lag span — it does not re-filter the entire past arc. A no-op when smoothing is disabled, the seed carries no Cartesian state, or no observation falls within the window; observations that fail to process are skipped.

Parameters:

Name	Type	Description	Default
`a_priori_observations`	`list[Observation]`	Past-arc observations (those outside the lag window are ignored).	required

Returns:

Type	Description
`UnscentedKalmanFilter`	A new filter primed over the lag window.

Estimation

estimation

AdaptiveOrbitEstimator

a_priori_observation_count property

back_propagation_clos_rms property

consecutive_rejections property

current_estimate property

epoch property

escalation_rejections property writable

has_converged property

inflation_factor property writable

last_innovation_chi_squared property

last_measurement_dimension property

last_recovery_observations_recovered property

last_recovery_strategy property

mode property

plausibility_gate property writable

promotion_accepts property writable

recovery_trigger property writable

__init__(a_priori, a_priori_observations)

back_propagation_residuals()

process_observation(observation)

set_adaptive_process_noise(enabled)

set_innovation_gate_chi_squared(value)

set_process_noise(process_noise)

set_smoothing_lag(lag)

AnglesOnlyObservation

declination property

epoch property

observer_position property

right_ascension property

__init__(epoch, right_ascension, declination, observer_position)

AssociationConfig

high_angle_rate property writable

high_fdoa property writable

high_range property writable

high_range_rate property writable

low_angle_rate property writable

low_fdoa property writable

low_range property writable

low_range_rate property writable

medium_angle_rate property writable

medium_fdoa property writable

medium_range property writable

medium_range_rate property writable

__init__(range, range_rate, angle_rate, fdoa)

default() staticmethod

BatchLeastSquares

a_priori property writable

allow_radial_delta_v property writable

analytic_jacobian property writable

converged property

covariance property

current_estimate property

delta_v property

estimate_drag property writable

estimate_maneuver property writable

estimate_srp property writable

iteration_count property

maneuver_epoch property

max_iterations property writable

minimum_fit_span property writable

minimum_maneuver_epoch property writable

observations property writable

output_type property writable

reject_bad_observations property writable

rejected_observation_ids property

report property

residuals property

rms property

weighted_rms property

__init__(observations, a_priori)

iterate()

reset()

solve()

CollectionAssociationReport

associations property

moving_satellite_ids property

orphan_observations property

Covariance

`estimation`

`AdaptiveOrbitEstimator`

`a_priori_observation_count` `property`

`back_propagation_clos_rms` `property`

`consecutive_rejections` `property`

`current_estimate` `property`

`epoch` `property`

`escalation_rejections` `property` `writable`

`has_converged` `property`

`inflation_factor` `property` `writable`

`last_innovation_chi_squared` `property`

`last_measurement_dimension` `property`

`last_recovery_observations_recovered` `property`

`last_recovery_strategy` `property`

`mode` `property`

`plausibility_gate` `property` `writable`

`promotion_accepts` `property` `writable`

`recovery_trigger` `property` `writable`

`init(a_priori, a_priori_observations)`

`back_propagation_residuals()`

`process_observation(observation)`

`set_adaptive_process_noise(enabled)`

`set_innovation_gate_chi_squared(value)`

`set_process_noise(process_noise)`

`set_smoothing_lag(lag)`

`AnglesOnlyObservation`

`declination` `property`

`epoch` `property`

`observer_position` `property`

`right_ascension` `property`

`init(epoch, right_ascension, declination, observer_position)`

`AssociationConfig`

`high_angle_rate` `property` `writable`

`high_fdoa` `property` `writable`

`high_range` `property` `writable`

`high_range_rate` `property` `writable`

`low_angle_rate` `property` `writable`

`low_fdoa` `property` `writable`

`low_range` `property` `writable`

`low_range_rate` `property` `writable`

`medium_angle_rate` `property` `writable`

`medium_fdoa` `property` `writable`

`medium_range` `property` `writable`

`medium_range_rate` `property` `writable`

`init(range, range_rate, angle_rate, fdoa)`

`default()` `staticmethod`

`BatchLeastSquares`

`a_priori` `property` `writable`

`allow_radial_delta_v` `property` `writable`

`analytic_jacobian` `property` `writable`

`converged` `property`

`covariance` `property`

`current_estimate` `property`

`delta_v` `property`

`estimate_drag` `property` `writable`

`estimate_maneuver` `property` `writable`

`estimate_srp` `property` `writable`

`iteration_count` `property`

`maneuver_epoch` `property`

`max_iterations` `property` `writable`

`minimum_fit_span` `property` `writable`

`minimum_maneuver_epoch` `property` `writable`

`observations` `property` `writable`

`output_type` `property` `writable`

`reject_bad_observations` `property` `writable`

`rejected_observation_ids` `property`

`report` `property`

`residuals` `property`

`rms` `property`

`weighted_rms` `property`

`init(observations, a_priori)`

`iterate()`

`reset()`

`solve()`

`CollectionAssociationReport`

`associations` `property`

`moving_satellite_ids` `property`

`orphan_observations` `property`

`Covariance`

`covariance_type` `property`