Orbit Determination API

DCEstimate

Bases: NamedTuple

Final parameter estimate from a differential-correction solve.

Parameters:

Name	Type	Description	Default
orbit	Orbit	Estimated orbit. The first six covariance parameters use orbit.array.squeeze() in the native order of the concrete orbit representation.	required
model_params	Float[Array, N_model]	Estimated non-orbit model parameters appended after the six orbit parameters.	required
model_param_names	list[str]	Names corresponding to model_params. This list is empty when the solve estimated only the six orbit parameters.	required
cov_mat_post	Float[Array, 'N_param N_param']	Posterior covariance matrix for [orbit.array.squeeze(), model_params], where N_param = 6 + N_model.	required

DCResult

Bases: NamedTuple

Differential-correction result with the final estimate and residual diagnostics.

Parameters:

Name	Type	Description	Default
estimate	DCEstimate	Final orbit, estimated model parameters, and posterior covariance. Use estimate.cov_mat_post for the covariance matrix in the parameter order documented by :class:DCEstimate.	required
optical	OpticalResult	Residual diagnostics for optical observations.	required
radar	RadarResult	Residual diagnostics for radar observations.	required
lsq_diagnostics	LSQDiagnostics	Final least-squares diagnostics, including covariance validity, rank, condition, and termination state.	required
normalized_residual_rms	float	Root mean square of normalized residuals for the final solution. Dimensionless.	required

quality_code property

IAU MPC Uncertainty Parameter U.

Range: 0 (good) to 9 (poor).

Ref: https://www.minorplanetcenter.net/iau/info/UValue.html

transform(target)

Convert the solved orbit and covariance; pass KepElement from difforb.core for Keplerian-element covariance, returned in estimate.cov_mat_post.

Parameters:

Name	Type	Description	Default
target	Frame or type[KepElement]	Target state frame or the :class:KepElement class.	required

Returns:

Type	Description
DCResult	Result with estimate.orbit and estimate.cov_mat_post transformed to the target representation.

Notes

Model parameters remain appended after the six orbit parameters.

ODAnalysis(observations_data, result, observations, residuals, _layout) dataclass

Analysis tables derived from one differential-correction result.

from_result(observations, result) classmethod

Build standardized analysis tables from observations and one OD or DC result.

Parameters:

Name	Type	Description	Default
observations	ObservationData	Observation bundle used by the fit.	required
result	DCResult or ODResult	Differential-correction result, or an orbit-determination result that contains one.	required

Returns:

Type	Description
ODAnalysis	Analysis object with observation-level and residual-component tables.

Raises:

Type	Description
ValueError	Raised when an ODResult has no differential-correction result.

station_summary()

Return station-level residual and outlier statistics.

tracklet_summary(*, include_contribution=False)

Return tracklet-level residual and outlier statistics.

Parameters:

Name	Type	Description	Default
include_contribution	bool	If True, add weighted and geometric normal-matrix contribution percentages computed from the final Jacobian.	False

DCSolver(lsq_tol=1e-11, lsq_max_iters=20, *, sun=None, earth=None, bucket_policy=None)

Differential-correction solver built on Levenberg-Marquardt least squares.

The solver always runs through :class:RobustLeastSquares so that chi-square diagnostics, inlier masks, and rejection statistics are produced consistently. Disabling outlier rejection only skips the rejection step; it does not disable robust diagnostics. When optical time uncertainties are available, the solver refreshes the time-inflated optical weight matrices at each least-squares linearization point from the modeled sky-plane rates.

Create a differential-correction solver.

Parameters:

Name	Type	Description	Default
lsq_tol	float	Base convergence threshold for the inner least-squares solve. This value controls the relative scaled step norm and the relative loss reduction; the scaled gradient threshold defaults to its square root.	1e-11
lsq_max_iters	int	Maximum number of iterations allowed in each least-squares solve.	20
sun	EphemerisBody or None	Ephemeris-backed Sun body used by the light-time and residual models. If omitted, the solver resolves EphemerisBody("sun") during construction.	None
earth	EphemerisBody or None	Ephemeris-backed Earth body used by the site and light-time models. If omitted, the solver resolves EphemerisBody("earth") during construction.	None
bucket_policy	DCBucketPolicy or None	Optional shape-bucket policy for padding non-empty observation tables before residual and Jacobian evaluation. Padded residuals are structurally masked and are cropped from the returned result.	None

Raises:

Type	Description
ValueError	Raised when a numeric option falls outside its valid range.

solve(data, initial_orbit, force_model, integrator, weight_policy, debias_policy, outlier_policy, *, photocenter_correction=None, event_handler=None, log_detail='iter', event_logger=None)

Run differential correction for a specific orbit-estimation problem.

Parameters:

Name	Type	Description	Default
data	ObservationData	Observations used for the fit.	required
initial_orbit	Orbit	Initial orbital state used as the least-squares starting point.	required
force_model	ForceModel	Dynamical model when propagating the orbit, whose estimable parameters are solved jointly with the orbit, if applicable.	required
integrator	NumericalIntegrator	Integrator used to propagate the orbit.	required
weight_policy	WeightPolicy	Policy for per-observation sigmas and inverse-variance weights.	required
debias_policy	DebiasPolicy	Policy for optical astrometric debias corrections.	required
outlier_policy	InteractiveOutlierPolicy	Policy for initial, manual, and statistical inlier masks.	required
photocenter_correction	PhotocenterCorrection or None	Optional optical center-of-light correction. Estimated photocenter parameters are appended after the dynamical model parameters in the least-squares vector.	None
event_handler	SolverEventHandler or None	Optional callback that receives least-squares and outlier-rejection progress events.	None
log_detail	(quiet, summary, iter, trial)	Minimum solver-log detail emitted to event_handler.	"quiet"
event_logger	SolverEventLogger or None	Context-aware structured event logger shared across staged differential correction.	None

Returns:

Type	Description
DCResult	Final differential-correction result together with residual, chi-square, inlier-mask, and iteration diagnostics.

DCStrategy

Bases: NamedTuple

IODResult

Bases: NamedTuple

Initial orbit solution summary.

The stored orbit keeps its canonical internal units. Human-facing display layers append unit suffixes to labels instead of changing runtime attribute names. used_indices stores the original observation indices of the selected triplet in the mixed input order of the source :class:difforb.astrometry.data2.ObservationData.

IODSolver(max_iter=30, tol=1e-10)

Initial orbit determination solver based on sampled angle-only triplets.

The current implementation samples candidate observation triplets from one prepared optical arc, solves each candidate with the Double-r method, and returns the solution with the smallest full-window angular score.

Initialize an initial-orbit-determination solver.

Parameters:

Name	Type	Description	Default
max_iter	int	Maximum number of Newton iterations allowed in the underlying IOD algorithm.	30
tol	float	Convergence threshold for the final angular residual norm, in radians.	1e-10

Raises:

Type	Description
ValueError	Raised when a numeric parameter falls outside its allowed range.

solve(data, max_arc_days=1.0, candidates_num=10, init_rho=(1.0, 1.0))

Solve for an initial orbit by sampling observation triplets.

Parameters:

Name	Type	Description	Default
data	ObservationData	Single-target observation bundle. Ground-based optical and space-based optical observations are used by this stage. Radar observations are ignored.	required
max_arc_days	float	Width of the sampling window, in days. The window is centered on the middle sorted observation and is used to restrict the pool of optical observations available for IOD triplets. If the nominal window contains fewer than three observations, the full filtered optical arc is used instead.	1.0
candidates_num	int	Number of random triplets to sample and solve.	10
init_rho	tuple[float, float]	Initial line-of-sight range guesses for the first and third observations of each sampled triplet, in au.	(1.0, 1.0)

Returns:

Type	Description
IODResult	Initial orbit estimate, iteration count, full-window angular score, and the selected triplet indices in the original mixed input order.

Raises:

Type	Description
ValueError	Raised when the filtered observation set or the selected window does not contain enough observations, or when a public argument violates its allowed range.
RuntimeError	Raised when no valid IOD candidate can be produced.

IODStrategy

Bases: NamedTuple

LSQDiagnostics

Bases: NamedTuple

Diagnostics from the final robust differential-correction solve.

lsq_iterations counts accepted Levenberg-Marquardt steps accumulated across all inlier-mask solves in the robust loop. outlier_iterations counts outer outlier-rejection iterations evaluated with usable residual, Jacobian, and covariance diagnostics from the inner solves. termination_reason describes why the final least-squares solve stopped at the returned estimate. optical_weight_matrices and radar_weights are the canonical weights used by the solver; flat_weights is only a marginal display view.

ODResult

Bases: NamedTuple

High-level orbit-determination workflow result.

Parameters:

Name	Type	Description	Default
iod_result	IODResult or None	Initial orbit-determination result, if the workflow ran an IOD stage.	required
dc_result	DCResult or None	Final differential-correction result. Use dc_result.estimate to access the solved orbit and posterior covariance; None means no differential-correction covariance is available.	required
dc_stage_records	tuple[DCStageRecord, ...]	Per-stage orchestration records for the differential-correction workflow.	required

ODSolver(iod_solver, dc_solver)

Coordinate the high-level orbit-determination workflow.

The solver delegates numerical work to an initial-orbit-determination solver and a differential-correction solver, while this class manages the observation-arc staging logic and prints plain-text progress messages. The default workflow starts from a short IOD arc, then expands the usable observation span in staged differential-correction passes while keeping the IOD epoch as the orbit epoch. Alternative strategies may recenter each pass to the selected observation-arc midpoint or to the selected observations' weighted mean epoch before solving that stage.

Parameters:

Name	Type	Description	Default
iod_solver	IODSolver	Solver used to generate one or more initial orbit candidates from the input observation arc.	required
dc_solver	DCSolver	Solver used to refine the current orbit estimate on progressively larger observation subsets.	required

See Also

IODSolver Initial-orbit-determination backend. DCSolver Differential-correction backend.

Examples:

>>> # solver = ODSolver(iod_solver, dc_solver)
>>> # result = solver.solve(obs, force_model, integrator)

Initialize the workflow wrapper around the concrete OD solvers.

solve(obs, force_model, integrator, weight_policy, debias_policy, outlier_policy, iod_strategy=IODStrategy(), dc_strategy=DCStrategy(), photocenter_correction=None, event_handler=None, log_detail='iter', event_logger=None)

Execute the full orbit-determination pipeline.

Parameters:

Name	Type	Description	Default
obs	ObservationData	Full observation set available to the orbit-determination run.	required
force_model	ForceModel	Dynamical model passed to the differential-correction stage.	required
integrator	NumericalIntegrator	Numerical propagator used by the differential-correction solver. The required integrator type depends on the configured DC solver.	required
weight_policy	WeightPolicy	Policy for observation weights in each differential-correction stage.	required
debias_policy	DebiasPolicy	Policy for optical astrometric debias corrections in each differential-correction stage.	required
outlier_policy	InteractiveOutlierPolicy	Policy for inlier masks in each differential-correction stage.	required
iod_strategy	IODStrategy	IOD settings. They include the arc width, candidate limit, and initial topocentric range guesses.	IODStrategy()
dc_strategy	DCStrategy	DC staging settings. The solver uses incremental_arc_days exactly as the requested centered arc widths in days. By default, epoch_strategy keeps the orbit epoch at the IOD epoch.	DCStrategy()
photocenter_correction	PhotocenterCorrection or None	Optional optical center-of-light correction passed to each differential-correction stage.	None
event_handler	SolverEventHandler or None	Optional callback for differential-correction progress events. If omitted, events are printed with the surrounding workflow log.	None
log_detail	(quiet, summary, iter, trial)	Minimum differential-correction log detail emitted to event_handler.	"quiet"
event_logger	SolverEventLogger or None	Structured event logger used for staged differential-correction events. If supplied, it takes precedence over event_handler and log_detail for nested solver logs.	None

Returns:

Type	Description
ODResult	High-level workflow result containing the IOD output, all staged differential-correction summaries, and the final DC result.

Notes

The stage epoch is snapped to a TDB Julian date whose fractional part is 0.5. With the default epoch_strategy="keep_initial", the final orbit remains expressed at the snapped IOD epoch. With epoch_strategy="weighted_mean", optical row weights are the sum of the right-ascension and declination inverse variances returned by weight_policy. Stages with too few valid observations are skipped, and stages that would reuse the exact same active observation mask without an epoch recentering are not recomputed.

OpticalResult

Bases: NamedTuple

RadarResult

Bases: NamedTuple

RunLogHandler(writer)

Render solver events as plain text and pass them to a writer callback.

This handler is intended for console output and human-readable run logs. It does not persist structured events.

Initialize the text handler with one line-oriented writer.

__call__(event)

Render and write one solver event.

SolverEvent(component, event, level='info', context=dict(), data=dict()) dataclass

Structured progress event emitted by orbit-determination solvers.

Parameters:

Name	Type	Description	Default
component	str	Solver component that produced the event.	required
event	str	Stable machine-readable event name.	required
level	str	Severity label such as "info" or "warning".	'info'
context	Mapping[str, Any]	Hierarchical solve context, such as stage, outlier iteration, LSQ solve, LSQ step, and damping trial.	dict()
data	Mapping[str, Any]	Event-specific scalar payload.	dict()

SolverEventHandler = Callable[[SolverEvent], None] module-attribute

SolverEventLogger(handler=None, log_detail='iter', context=None)

Context-aware emitter for structured solver events.

The logger owns filtering and hierarchical context. Numerical code can bind the context it knows, emit scalar event payloads, and leave text rendering to an event handler.

Initialize a solver event logger.

bind(**context)

Return a new logger with additional hierarchical context.

enabled(event_name)

Return whether one event would be delivered to the handler.

emit(component, event, level='info', **data)

Emit one structured solver event if it passes the current filter.

SolverLogDetail = Literal['quiet', 'summary', 'iter', 'trial'] module-attribute

CompositeSolverEventHandler(*handlers)

Forward each solver event to multiple handlers.

Initialize the handler list, skipping missing handlers.

__call__(event)

Deliver one event to every configured handler.