adam_core.orbits.trajectory module

Piecewise, validity-bounded trajectory of orbit states.

A Trajectory is an ordered set of segments. Each segment is one anchor Orbits state (position, velocity and 6x6 covariance at a single epoch) plus a coverage window – the time interval over which that anchor state is the authoritative source for the object. This mirrors the CCSDS OEM / SPICE notion of an ephemeris segment’s useable interval (see adam_core.orbits.oem_io).

This is the in-memory type a search consumes when an object’s state is only valid piecewise (e.g. spacecraft trajectories reconstructed from an SPK, where solar-radiation-pressure and maneuvers make a single propagated state diverge over time). For a given search span the caller binds the one segment whose coverage window contains the span’s reference time via segment_for(), and fails closed on coverage gaps and overlaps.

A conventional single-state orbit is simply a one-segment trajectory whose coverage window spans the whole search, so callers that never build a Trajectory are unaffected.

class adam_core.orbits.trajectory.Trajectory(table: Table, **kwargs: int | float | str)

Bases: Table

A set of validity-bounded orbit segments (rows are segments).

Segments belonging to the same object_id must have non-overlapping coverage windows; gaps between them are allowed and are treated as “no valid state” (fail closed) rather than silently extrapolated.

object_id

A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

segment_id

A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

coverage_start

A column which represents an embedded quivr table.

Parameters:

• table_type – The type of the table to embed.

• nullable – Whether the column can contain null values.

• metadata – A dictionary of metadata to attach to the column.

coverage_end

A column which represents an embedded quivr table.

Parameters:

• table_type – The type of the table to embed.

• nullable – Whether the column can contain null values.

• metadata – A dictionary of metadata to attach to the column.

orbit

A column which represents an embedded quivr table.

Parameters:

• table_type – The type of the table to embed.

• nullable – Whether the column can contain null values.

• metadata – A dictionary of metadata to attach to the column.

source

A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

source_version

A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

max_propagation_days

A column for storing 64-bit floating point numbers.

is_maneuver_boundary

A column for storing booleans.

coverage_start_mjd() → ndarray[tuple[Any, ...], dtype[float64]]

Coverage-window start times as TDB MJD.

coverage_end_mjd() → ndarray[tuple[Any, ...], dtype[float64]]

Coverage-window end times as TDB MJD.

epoch_mjd() → ndarray[tuple[Any, ...], dtype[float64]]

Anchor-state epochs as TDB MJD.

object_ids() → list[str]

Distinct object ids, in first-seen order.

validate_coverage() → Trajectory

Check structural invariants; raise ValueError on violation.

Enforces, per object: coverage_end strictly after coverage_start, each anchor epoch inside its own coverage window, and non-overlapping coverage windows (touching endpoints are allowed because windows are half-open [start, end)).

segment_for(time_mjd_tdb: float, object_id: str | None = None) → Trajectory | None

Return the single segment whose coverage window contains time.

Coverage windows are half-open [coverage_start, coverage_end). Returns None when no segment covers the time (a gap; fail closed). Raises ValueError when more than one segment matches (an invalid, overlapping trajectory) or when the trajectory holds multiple objects and object_id was not supplied.

schema: ClassVar[pa.Schema] = object_id: large_string not null segment_id: large_string not null coverage_start: struct<days: int64, nanos: int64>   child 0, days: int64   child 1, nanos: int64 coverage_end: struct<days: int64, nanos: int64>   child 0, days: int64   child 1, nanos: int64 orbit: struct<orbit_id: large_string, object_id: large_string, coordinates: struct<x: double, y: double, z: (... 302 chars omitted)   child 0, orbit_id: large_string   child 1, object_id: large_string   child 2, coordinates: struct<x: double, y: double, z: double, vx: double, vy: double, vz: double, time: struct<days: int64 (... 106 chars omitted)       child 0, x: double       child 1, y: double       child 2, z: double       child 3, vx: double       child 4, vy: double       child 5, vz: double       child 6, time: struct<days: int64, nanos: int64>           child 0, days: int64           child 1, nanos: int64       child 7, covariance: struct<values: large_list<item: double>>           child 0, values: large_list<item: double>               child 0, item: double       child 8, origin: struct<code: large_string>           child 0, code: large_string   child 3, physical_parameters: struct<H_v: double, H_v_sigma: double, G: double, G_sigma: double, sigma_eff: double, chi2_red: doub (... 3 chars omitted)       child 0, H_v: double       child 1, H_v_sigma: double       child 2, G: double       child 3, G_sigma: double       child 4, sigma_eff: double       child 5, chi2_red: double source: large_string source_version: large_string max_propagation_days: double is_maneuver_boundary: bool

table: pa.Table