Trajectories

py_outfit.trajectories.Key `module-attribute`

Key = Union[int, str]

Key used to identify a trajectory (either by its MPC code, a string ID or just an integer).

py_outfit.trajectories.PathLike `module-attribute`

PathLike = Union[str, Path]

Path-like type (either a str or a Path from pathlib).

py_outfit.trajectories.TrajectorySet

Container for time‑ordered astrometric observations grouped by object identifiers, designed as the primary entry point for batch workflows.

A TrajectorySet represents a mapping from a user-supplied key to a time‑ordered view of observations for that object. It enables loading large collections of observations, inspecting basic statistics, and running Gauss-based Initial Orbit Determination across all trajectories in a single operation. Keys can be integers or strings and are preserved end‑to‑end, making it straightforward to relate results back to upstream catalogs or pipeline identifiers.

The container behaves like a Python dictionary for common operations such as membership tests, iteration, indexing, and length queries. Each entry provides a read‑only Observations view that exposes per‑trajectory data without copying, keeping memory usage predictable. This structure is intended to integrate cleanly with scientific Python workflows while delegating all heavy computation to the Rust engine underneath.

Ingestion supports two main paths. A zero‑copy path accepts right ascension and declination in radians, epochs in MJD (TT), and a single Observer for the entire batch. A compatible degrees and arcseconds path performs a single conversion to radians before storing data. Trajectories can also be constructed from standard astronomy formats such as MPC 80‑column and ADES (JSON or XML), and an existing set can be extended by appending additional files when needed.

The container is optimized for batch IOD. The dedicated batch method executes the Gauss solver over all stored trajectories using parameters supplied by IODParams and returns per‑trajectory outcomes together with error messages for failures. Execution may be sequential or parallel depending on configuration, with optional deterministic seeding for reproducibility. When run sequentially, cooperative cancellation allows returning partial results if interrupted by the user.

The type does not perform de‑duplication or cross‑trajectory merging and assumes inputs are pre‑grouped as intended. Units follow the package conventions: angles are treated in radians internally, epochs use MJD (TT), and when ingesting degrees the provided uncertainties are interpreted in arcseconds. A single observing site applies per ingestion call. The overall goal is to make data flow explicit, predictable, and efficient for production pipelines.

keys

keys() -> list[Key]

Return the list of keys (like dict.keys()).

RETURNS	DESCRIPTION
`list[Key]`	A list of all object identifiers currently stored.

See also

values – All trajectories.
items – Key/value pairs.

values

values() -> list[Observations]

Return the list of trajectories (like dict.values()).

RETURNS	DESCRIPTION
`list[Observations]`	A list of all `Observations` currently stored.

See also

keys – All keys.
items – Key/value pairs.

items

items() -> list[tuple[Key, Observations]]

Return the list of (key, Observations) pairs (like dict.items()).

RETURNS	DESCRIPTION
`list[tuple[Key, Observations]]`	A list of all `(object_id, Observations)` pairs currently stored.

See also

keys – All keys.
values – All trajectories.

total_observations

total_observations() -> int

Total number of observations across all trajectories.

RETURNS	DESCRIPTION
`int`	sum over all per-trajectory counts.

number_of_trajectories

number_of_trajectories() -> int

Number of trajectories currently stored.

RETURNS	DESCRIPTION
`int`	number of distinct trajectory IDs.

get_traj_stat

get_traj_stat() -> str

Pretty-printed statistics about observations per trajectory.

RETURNS	DESCRIPTION
`str`	A formatted `str` (histogram/stats), or `"No trajectories available."` if empty.

from_numpy_radians `staticmethod`

from_numpy_radians(
    pyoutfit: PyOutfit,
    trajectory_id: NDArray[uint32],
    ra: NDArray[float64],
    dec: NDArray[float64],
    error_ra_rad: float,
    error_dec_rad: float,
    mjd_tt: NDArray[float64],
    observer: Observer,
) -> "TrajectorySet"

Build a TrajectorySet from arrays already in radians (RA/DEC) and MJD (TT).

This path uses a zero-copy ingestion under the hood.

PARAMETER	DESCRIPTION
`pyoutfit`	Global environment (ephemerides, observers, error model). TYPE: `PyOutfit`
`trajectory_id`	`np.uint32` array — one ID per observation. TYPE: `NDArray[uint32]`
`ra`	`np.float64` array — Right Ascension in radians. TYPE: `NDArray[float64]`
`dec`	`np.float64` array — Declination in radians. TYPE: `NDArray[float64]`
`error_ra_rad`	1-σ RA uncertainty (radians) applied to the whole batch. TYPE: `float`
`error_dec_rad`	1-σ DEC uncertainty (radians) applied to the whole batch. TYPE: `float`
`mjd_tt`	`np.float64` array — epochs in MJD (TT) (days). TYPE: `NDArray[float64]`
`observer`	Single observing site for the whole batch. TYPE: `Observer`

RETURNS	DESCRIPTION
`TrajectorySet`	A new `TrajectorySet` populated from the provided inputs.

RAISES	DESCRIPTION
`ValueError`	if input arrays have mismatched lengths.

from_numpy_degrees `staticmethod`

from_numpy_degrees(
    pyoutfit: PyOutfit,
    trajectory_id: NDArray[uint32],
    ra_deg: NDArray[float64],
    dec_deg: NDArray[float64],
    error_ra_arcsec: float,
    error_dec_arcsec: float,
    mjd_tt: NDArray[float64],
    observer: Observer,
) -> "TrajectorySet"

Build a TrajectorySet from degrees (RA/DEC), arcseconds (uncertainties), and MJD (TT) for epochs.

Internally converts once to radians, then ingests.

PARAMETER	DESCRIPTION
`pyoutfit`	Global environment (ephemerides, observers, error model). TYPE: `PyOutfit`
`trajectory_id`	`np.uint32` array — one ID per observation. TYPE: `NDArray[uint32]`
`ra_deg`	`np.float64` array — Right Ascension in degrees. TYPE: `NDArray[float64]`
`dec_deg`	`np.float64` array — Declination in degrees. TYPE: `NDArray[float64]`
`error_ra_arcsec`	1-σ RA uncertainty (arcseconds) applied to the batch. TYPE: `float`
`error_dec_arcsec`	1-σ DEC uncertainty (arcseconds) applied to the batch. TYPE: `float`
`mjd_tt`	`np.float64` array — epochs in MJD (TT) (days). TYPE: `NDArray[float64]`
`observer`	Single observing site for the whole batch. TYPE: `Observer`

RETURNS	DESCRIPTION
`TrajectorySet`	A new `TrajectorySet` populated from the provided inputs.

RAISES	DESCRIPTION
`ValueError`	if input arrays have mismatched lengths.

See also

from_numpy_radians — Zero-copy variant for radian inputs.

new_from_mpc_80col `staticmethod`

new_from_mpc_80col(pyoutfit: PyOutfit, path: PathLike) -> 'TrajectorySet'

Build a TrajectorySet from a MPC 80-column file.

PARAMETER	DESCRIPTION
`pyoutfit`	Global environment (ephemerides, observers, error model). TYPE: `PyOutfit`
`path`	File path (`str` or Path from pathlib) to a MPC 80-column text file. TYPE: `PathLike`

RETURNS	DESCRIPTION
`TrajectorySet`	A new `TrajectorySet` populated from the file contents.

Notes

Mirrors the Rust API semantics and may panic on parse errors.

See also

add_from_mpc_80col — Append a second 80-column file into an existing set.
new_from_ades — Create from ADES JSON/XML.

add_from_mpc_80col

add_from_mpc_80col(pyoutfit: PyOutfit, path: PathLike) -> None

Append observations from a MPC 80-column file into this set.

PARAMETER	DESCRIPTION
`pyoutfit`	Global environment (ephemerides, observers, error model). TYPE: `PyOutfit`
`path`	File path (`str` or Path from pathlib) to a MPC 80-column text file. TYPE: `PathLike`

RETURNS	DESCRIPTION
`None`	The internal map is updated in place.

Notes

No de-duplication is performed; avoid ingesting the same file twice.

See also

new_from_mpc_80col — Create a brand-new set from a single file.

new_from_ades `staticmethod`

new_from_ades(
    pyoutfit: PyOutfit,
    path: PathLike,
    error_ra_arcsec: Optional[float],
    error_dec_arcsec: Optional[float],
) -> "TrajectorySet"

Build a TrajectorySet from an ADES file (JSON or XML).

PARAMETER	DESCRIPTION
`pyoutfit`	Global environment (ephemerides, observers, error model). TYPE: `PyOutfit`
`path`	File path (`str` or Path from pathlib) to an ADES JSON/XML file. TYPE: `PathLike`
`error_ra_arcsec`	Optional global RA 1-σ (arcsec) if not specified per row. TYPE: `Optional[float]`
`error_dec_arcsec`	Optional global DEC 1-σ (arcsec) if not specified per row. TYPE: `Optional[float]`

RETURNS	DESCRIPTION
`TrajectorySet`	A new `TrajectorySet` populated from the ADES file.

Notes

Error-handling policy follows the underlying parser (may log or panic).

See also

add_from_ades — Append ADES observations into an existing set.

add_from_ades

add_from_ades(
    pyoutfit: PyOutfit,
    path: PathLike,
    error_ra_arcsec: Optional[float],
    error_dec_arcsec: Optional[float],
) -> None

Append observations from an ADES file (JSON/XML) into this set.

PARAMETER	DESCRIPTION
`pyoutfit`	Global environment (ephemerides, observers, error model). TYPE: `PyOutfit`
`path`	File path (`str` or Path from pathlib) to an ADES JSON/XML file. TYPE: `PathLike`
`error_ra_arcsec`	Optional global RA 1-σ (arcsec) if not specified per row. TYPE: `Optional[float]`
`error_dec_arcsec`	Optional global DEC 1-σ (arcsec) if not specified per row. TYPE: `Optional[float]`

RETURNS	DESCRIPTION
`None`	The internal map is updated in place.

Notes

No de-duplication is performed; avoid re-ingesting the same file.

See also

new_from_ades — Create a brand-new set from a single ADES file.

estimate_all_orbits

estimate_all_orbits(
    env: PyOutfit, params: IODParams, seed: Optional[int] = ...
) -> Tuple[Dict[Any, Tuple[GaussResult, float]], Dict[Any, str]]

Estimate the best orbit for all trajectories in this set.

Runs Gauss-based IOD for each trajectory using the provided environment and parameters. Internally creates a RNG: - if seed is provided → deterministic StdRng::seed_from_u64(seed); - else → StdRng::from_os_rng().

Cancellation

The computation periodically checks for KeyboardInterrupt (Ctrl-C). This work only if parallel is disabled (params.do_parallel() == False). If parallel is enabled, the computation cannot be interrupted and you will need to kill the process manually.

If cancellation is triggered, partial results accumulated so far are returned:

the first dict contains successful (GaussResult, rms) per object,
the second dict contains error messages per object.

PARAMETER	DESCRIPTION
`env`	Global environment (ephemerides, observers, error model). TYPE: `PyOutfit`
`params`	IOD tuning parameters (`IODParams`). If `params.do_parallel()` is `True`, a parallel path is used internally; otherwise a sequential path with cooperative cancellation. TYPE: `IODParams`
`seed`	Optional RNG seed for reproducibility. TYPE: `Optional[int]` DEFAULT: `...`

RETURNS	DESCRIPTION
`ok`	successful gauss results with RMS, TYPE: `Dict[object_id, (GaussResult, float)]`
`err`	error messages for failed trajectories. TYPE: `Dict[object_id, str]`

Notes

object_id preserves the input trajectory identifiers (either int or str, depending on how trajectories were ingested).
The RMS value is engine-defined (e.g., post-fit residual RMS in radians).

Trajectories

py_outfit.trajectories.Key module-attribute

py_outfit.trajectories.PathLike module-attribute

py_outfit.trajectories.TrajectorySet

keys

values

items

total_observations

number_of_trajectories

get_traj_stat

from_numpy_radians staticmethod

from_numpy_degrees staticmethod

new_from_mpc_80col staticmethod

add_from_mpc_80col

new_from_ades staticmethod

add_from_ades

estimate_all_orbits

py_outfit.trajectories.Key `module-attribute`

py_outfit.trajectories.PathLike `module-attribute`

from_numpy_radians `staticmethod`

from_numpy_degrees `staticmethod`

new_from_mpc_80col `staticmethod`

new_from_ades `staticmethod`