empyrean.DetermineResult¶

class DetermineResult(orbit, observations, summary, iterations, update_norm, converged, covariance, covariance_representation, covariance_9x9, non_grav_delta, rejection_passes, num_oppositions_fit, force_model_used, solve_for_used, acceptability, station_biases, solved_covariance, dt_delta, amrat_delta, thrust_delta_m_per_s, dv_frame, photometry, covariance_trust, dispositions, warnings, termination, gn_step_qnorm, mu_final, accepted_steps, final_solve_iterations, stall_delivery)[source]

Bases: object

Result of orbit determination — returned by both determine() (full IOD + DC pipeline) and refine() (Bayesian-prior fit against an existing orbit + covariance).

Mirrors the Rust wrapper’s empyrean::DetermineResult.

Methods

__init__(orbit, observations, summary, ...)

Attributes

`orbit`	Fitted orbit.
`observations`	Per-observation residuals + rejection / influence diagnostics.
`summary`
`iterations`
`update_norm`	NOT the quantity :attr:`ODConfig.convergence_tol` bounds. The μ-DAMPED last ACCEPTED step's q-norm — the size of the step the solver actually took, after Levenberg-Marquardt damping.
`converged`
`covariance`	Fitted 6×6 state covariance, in `covariance_representation`.
`covariance_representation`
`covariance_9x9`	Full 9×9 covariance over (state, A1, A2, A3) when solving for non-grav.
`non_grav_delta`	Cumulative non-grav corrections (ΔA1, ΔA2, ΔA3) when present.
`rejection_passes`
`num_oppositions_fit`
`force_model_used`
`solve_for_used`
`acceptability`
`station_biases`	Per-station fitted nuisance biases when `ODConfig.fit_station_biases` was active.
`solved_covariance`	Full tagged solved-parameter covariance when the fit solved any wide axis (Marsden / DT / AMRAT / thrust).
`dt_delta`	Cumulative non-grav time-delay correction ΔDT (days), when DT was solved.
`amrat_delta`	Cumulative SRP AMRAT correction (m²/kg), when AMRAT was solved.
`thrust_delta_m_per_s`	Per-segment fitted thrust Δv (m/s), shaped `(k, 3)` and expressed in `dv_frame`.
`dv_frame`	Integration frame the thrust Δv components are expressed in (`"icrf"` / `"eclipticj2000"` / `"itrf93"`).
`photometry`	Post-OD photometric solution when photometry was requested and ran.
`covariance_trust`	Event-aware trust verdict on the delivered covariance.
`dispositions`	What the fit actually did with each parameter axis.
`warnings`	Covariance the fit was given and deliberately did not use.
`termination`	Which criterion ended the solve that produced the published state, as a stable lowercase tag — `"gradient_tolerance"`, `"step_tolerance"`, `"cost_tolerance"`, `"max_iterations"`, `"damping_exhausted"`, `"inner_trials_exhausted"`, `"stalled_delivered"`, `"schur_step_tolerance"`, or `"unrecognized"` for a stop this build cannot name.
`gn_step_qnorm`	Quadratic form of the undamped Gauss-Newton step — the only number here comparable to `ODConfig.convergence_tol`, and the one the solver's step test is decided on.
`mu_final`	Levenberg-Marquardt damping at termination.
`accepted_steps`	Steps the solve actually ACCEPTED — trials that passed the gain-ratio test and moved the iterate.
`final_solve_iterations`	Iterations spent by the solve that produced the published state — the one `update_norm`, `termination`, `gn_step_qnorm` and `accepted_steps` all describe.
`stall_delivery`	Set when this fit was delivered by the stable-stall acceptance rather than by a convergence criterion — see `StallDelivery`.

Parameters:

orbit (CartesianOrbits | KeplerianOrbits | CometaryOrbits | SphericalOrbits)
observations (ObservationResults)
summary (ResidualSummary)
iterations (int)
update_norm (float)
converged (bool)
covariance (ndarray)
covariance_representation (CovarianceRepresentation)
covariance_9x9 (ndarray | None)
non_grav_delta (ndarray | None)
rejection_passes (int)
num_oppositions_fit (int)
force_model_used (ForceModelTier)
solve_for_used (SolveForParams)
acceptability (AcceptabilityReport)
station_biases (StationBiases)
solved_covariance (SolvedCovariance | None)
dt_delta (float | None)
amrat_delta (float | None)
thrust_delta_m_per_s (ndarray | None)
dv_frame (str | None)
photometry (PhotometryResult | None)
covariance_trust (CovarianceTrust | None)
dispositions (SolveFor)
warnings (list[str])
termination (str | None)
gn_step_qnorm (float | None)
mu_final (float | None)
accepted_steps (int)
final_solve_iterations (int | None)
stall_delivery (StallDelivery | None)

orbit: CartesianOrbits | KeplerianOrbits | CometaryOrbits | SphericalOrbits: Fitted orbit. Coordinate flavor matches ODConfig.output_representation.

observations: ObservationResults: Per-observation residuals + rejection / influence diagnostics.

summary: ResidualSummary

iterations: int

update_norm: float

NOT the quantity :attr:`ODConfig.convergence_tol` bounds. The μ-DAMPED last ACCEPTED step’s q-norm — the size of the step the solver actually took, after Levenberg-Marquardt damping.

The tolerance is tested on the undamped Gauss-Newton step, reported as gn_step_qnorm. The two are incomparable in BOTH directions: a converged fit routinely reports an update_norm orders of magnitude ABOVE convergence_tol (damping is light near the optimum, so the step taken is large), while a solve thrashing to "damping_exhausted" reports one orders of magnitude BELOW it (μ has crushed every step to nothing). Read termination and gn_step_qnorm for convergence, or acceptability for the fit-quality verdict.

On the Schur path (station-bias / nuisance fits) this carries that loop’s own step norm under the Schur complement instead — the quantity IT tests against convergence_tol. termination says which loop ran.

Exactly 0.0 with accepted_steps == 0 means the solver latched a criterion at its STARTING point and never accepted a step: the incoming iterate was already stationary. It does not mean “a step of size zero was taken”.

converged: bool

covariance: ndarray: Fitted 6×6 state covariance, in covariance_representation.

covariance_representation: CovarianceRepresentation

covariance_9x9: ndarray | None: Full 9×9 covariance over (state, A1, A2, A3) when solving for non-grav.

non_grav_delta: ndarray | None: Cumulative non-grav corrections (ΔA1, ΔA2, ΔA3) when present.

rejection_passes: int

num_oppositions_fit: int

force_model_used: ForceModelTier

solve_for_used: SolveForParams

acceptability: AcceptabilityReport

station_biases: StationBiases: Per-station fitted nuisance biases when ODConfig.fit_station_biases was active. Empty quivr table otherwise.

solved_covariance: SolvedCovariance | None: Full tagged solved-parameter covariance when the fit solved any wide axis (Marsden / DT / AMRAT / thrust). None for a state-only fit — read it, not the width, to locate solved parameters.

dt_delta: float | None: Cumulative non-grav time-delay correction ΔDT (days), when DT was solved. None otherwise.

amrat_delta: float | None: Cumulative SRP AMRAT correction (m²/kg), when AMRAT was solved. None otherwise.

thrust_delta_m_per_s: ndarray | None: Per-segment fitted thrust Δv (m/s), shaped (k, 3) and expressed in dv_frame. None when no thrust was solved.

dv_frame: str | None: Integration frame the thrust Δv components are expressed in ("icrf" / "eclipticj2000" / "itrf93"). None when no thrust was solved.

photometry: PhotometryResult | None: Post-OD photometric solution when photometry was requested and ran. None otherwise.

covariance_trust: CovarianceTrust | None: Event-aware trust verdict on the delivered covariance. None when the call path ran no trust gate — absence of a verdict is not trust.

dispositions: SolveFor

What the fit actually did with each parameter axis.

The partition the engine ran, not the one that was requested: an axis can be requested and then not opened. Read this rather than solve_for_used to learn whether an axis was considered — not estimated, but contributing its prior uncertainty to the posterior through its measurement partials — because a solved covariance’s slot tags record only what occupied a column, and a considered axis occupies none.

It is also what tells you whether re-attaching a prior to an axis would double-count it.

warnings: list[str]

Covariance the fit was given and deliberately did not use.

Delivered as payload rather than written to a log, because a dropped prior cross term changes how the σ for that slot should be read. Empty when the fit used everything it was given.

termination: str | None

Which criterion ended the solve that produced the published state, as a stable lowercase tag — "gradient_tolerance", "step_tolerance", "cost_tolerance", "max_iterations", "damping_exhausted", "inner_trials_exhausted", "stalled_delivered", "schur_step_tolerance", or "unrecognized" for a stop this build cannot name.

None only on a result that did not come from a solver run; every fit this package delivers names its stop. An unrecognized stop is "unrecognized" rather than None: a stop that fired but cannot be named is not the same as no stop at all.

gn_step_qnorm: float | None

Quadratic form of the undamped Gauss-Newton step — the only number here comparable to ODConfig.convergence_tol, and the one the solver’s step test is decided on. √q is the remaining step measured in the fit’s own formal σ.

q <= convergence_tol is guaranteed only under "step_tolerance" (or "schur_step_tolerance"). Under the gradient, cost and stall verdicts the fit is delivered as converged with q legitimately above the tolerance.

None when the undamped system was singular at the returned point, when the Schur loop ran at solved width > 6 (its only step norm there is λ-shrunken, which is what this field promises it is not), or on a non-solver result.

mu_final: float | None

Levenberg-Marquardt damping at termination. Large μ beside a small update_norm is the signature of a stalled solve rather than a converged one.

None on the Schur path, which runs its own λ schedule and forms no comparable quantity — so its absence, alongside termination == "schur_step_tolerance", is what identifies that path — and on non-solver results.

accepted_steps: int

Steps the solve actually ACCEPTED — trials that passed the gain-ratio test and moved the iterate.

0 says the solver latched a criterion at its starting point and never moved: the incoming orbit was already stationary for this observation set. That is what disambiguates update_norm’s 0.0 sentinel. Counted per SOLVE, so it describes the same solve as final_solve_iterations, never a total across the rejection–refit passes.

final_solve_iterations: int | None

Iterations spent by the solve that produced the published state — the one update_norm, termination, gn_step_qnorm and accepted_steps all describe.

Additive disambiguator for iterations, whose composition varies by entry point; this one never does. None on a result that did not come from a solver run.

stall_delivery: StallDelivery | None

Set when this fit was delivered by the stable-stall acceptance rather than by a convergence criterion — see StallDelivery.

None is the ordinary case. A consumer that wants the strict convergence contract checks stall_delivery is None.