Python API

This page documents the main Python API exported by the rust_ephem extension module. The native extension is built with maturin and exposed under the module name rust_ephem.

Module Reference

API Overview

The module exposes the following primary classes and helper functions. If the compiled extension is not available at documentation build time these names may be mocked (see docs/README.md).

Classes

Ephemeris (Abstract Base Class)

Common interface for all ephemeris types. All concrete ephemeris classes (TLEEphemeris, SPICEEphemeris, GroundEphemeris, OEMEphemeris, FileEphemeris, ParquetEphemeris) implement this interface and can be used interchangeably where an Ephemeris is expected.

Use isinstance(obj, Ephemeris) to check if an object is any ephemeris type.

Common Properties:

  • timestamp — Array of UTC timestamps

  • gcrs_pv — Position/velocity in GCRS frame

  • itrs_pv — Position/velocity in ITRS frame

  • gcrs — GCRS coordinates as astropy SkyCoord

  • itrs — ITRS coordinates as astropy SkyCoord

  • sun, moon, earth — Celestial body SkyCoord objects

  • sun_pv, moon_pv — Celestial body position/velocity data

  • obsgeoloc, obsgeovel — Observer location/velocity in GCRS

  • latitude_deg, longitude_deg, height_m — Geodetic coordinates

  • sun_radius_deg, moon_radius_deg, earth_radius_deg — Angular radii

  • sun_ra_dec_deg, moon_ra_dec_deg, earth_ra_dec_deg — RA/Dec as Nx2 arrays (cached)

  • sun_ra_deg, sun_dec_deg, etc. — Individual RA or Dec as 1D arrays

  • begin, end, step_size, polar_motion — Time range properties

Common Methods:

  • index(time) — Find closest timestamp index

  • get_body(body, spice_kernel=None, use_horizons=False) — Get SkyCoord for a celestial body. If use_horizons=True, falls back to JPL Horizons when the body is not found in SPICE kernels.

  • get_body_pv(body, spice_kernel=None, use_horizons=False) — Get position/velocity for a celestial body. If use_horizons=True, falls back to JPL Horizons when the body is not found in SPICE kernels.

  • moon_illumination(time_indices=None) — Calculate Moon illumination fraction (0.0-1.0) as seen from observer

  • radec_to_altaz(ra_deg, dec_deg, time_indices=None) — Convert RA/Dec to Alt/Az coordinates

  • calculate_airmass(ra_deg, dec_deg, time_indices=None) — Calculate astronomical airmass for target

Type Alias:

EphemerisType = TLEEphemeris | SPICEEphemeris | OEMEphemeris | GroundEphemeris | FileEphemeris | ParquetEphemeris

TLEEphemeris

Propagate Two-Line Element (TLE) sets with SGP4 and convert to coordinate frames.

Constructor:

TLEEphemeris(tle1=None, tle2=None, begin=None, end=None, step_size=60, *, polar_motion=False, tle=None, norad_id=None, norad_name=None, spacetrack_username=None, spacetrack_password=None, epoch_tolerance_days=None, enforce_source=None)

Parameters:

  • tle1 (str, optional) — First line of TLE (legacy method)

  • tle2 (str, optional) — Second line of TLE (legacy method)

  • tle (str | TLERecord, optional) — Path to TLE file, URL to download TLE from, or a TLERecord object

  • norad_id (int, optional) — NORAD catalog ID to fetch TLE. If Space-Track credentials are available, Space-Track is tried first with failover to Celestrak.

  • norad_name (str, optional) — Satellite name to fetch TLE from Celestrak

  • begin (datetime) — Start time for ephemeris (required)

  • end (datetime) — End time for ephemeris (required)

  • step_size (int) — Time step in seconds (default: 60)

  • polar_motion (bool) — Apply polar motion corrections (default: False)

  • spacetrack_username (str, optional) — Space-Track.org username (or use SPACETRACK_USERNAME env var)

  • spacetrack_password (str, optional) — Space-Track.org password (or use SPACETRACK_PASSWORD env var)

  • epoch_tolerance_days (float, optional) — For Space-Track cache: how many days TLE epoch can differ from target epoch (default: 4.0 days)

  • enforce_source (str, optional) — Enforce use of specific source without failover. Must be "celestrak", "spacetrack", or None

Notes:

  • Must provide exactly one of: (tle1, tle2), tle, norad_id, or norad_name

  • begin and end parameters are required

  • File paths and URLs are cached locally for performance

  • Space-Track.org credentials can also be provided via .env file

Attributes (read-only):

  • tle_epoch — TLE epoch as Python datetime (extracted from line 1)

  • teme_pv — Position/velocity in TEME frame (PositionVelocityData)

  • itrs_pv — Position/velocity in ITRS frame (PositionVelocityData)

  • gcrs_pv — Position/velocity in GCRS frame (PositionVelocityData)

  • sun_pv — Sun position/velocity in GCRS frame (PositionVelocityData)

  • moon_pv — Moon position/velocity in GCRS frame (PositionVelocityData)

  • timestamp — List of Python datetime objects

  • itrs — ITRS coordinates as astropy SkyCoord

  • gcrs — GCRS coordinates as astropy SkyCoord

  • latitude — Observatory latitude as an astropy Quantity array (degrees), one per timestamp

  • latitude_deg — Observatory latitude as NumPy array (degrees), one per timestamp

  • latitude_rad — Observatory latitude as NumPy array (radians), one per timestamp

  • longitude — Observatory longitude as an astropy Quantity array (degrees), one per timestamp

  • longitude_deg — Observatory longitude as NumPy array (degrees), one per timestamp

  • longitude_rad — Observatory longitude as NumPy array (radians), one per timestamp

  • height — Observatory height as an astropy Quantity array (meters), one per timestamp

  • height_m — Observatory height as raw NumPy array (meters), one per timestamp

  • height_km — Observatory height as raw NumPy array (kilometers), one per timestamp

  • earth — Earth position as astropy SkyCoord

  • sun — Sun position as astropy SkyCoord

  • moon — Moon position as astropy SkyCoord

  • obsgeoloc — Observer geocentric location (alias for GCRS position)

  • obsgeovel — Observer geocentric velocity (alias for GCRS velocity)

  • sun_radius — Sun angular radius as astropy Quantity (degrees)

  • sun_radius_deg — Sun angular radius as NumPy array (degrees)

  • sun_radius_rad — Sun angular radius as NumPy array (radians)

  • moon_radius — Moon angular radius as astropy Quantity (degrees)

  • moon_radius_deg — Moon angular radius as NumPy array (degrees)

  • moon_radius_rad — Moon angular radius as NumPy array (radians)

  • earth_radius — Earth angular radius as astropy Quantity (degrees)

  • earth_radius_deg — Earth angular radius as NumPy array (degrees)

  • earth_radius_rad — Earth angular radius as NumPy array (radians)

  • sun_ra_dec_deg — Sun RA/Dec as Nx2 NumPy array (degrees), cached

  • sun_ra_dec_rad — Sun RA/Dec as Nx2 NumPy array (radians), cached

  • moon_ra_dec_deg — Moon RA/Dec as Nx2 NumPy array (degrees), cached

  • moon_ra_dec_rad — Moon RA/Dec as Nx2 NumPy array (radians), cached

  • earth_ra_dec_deg — Earth RA/Dec as Nx2 NumPy array (degrees), cached

  • earth_ra_dec_rad — Earth RA/Dec as Nx2 NumPy array (radians), cached

  • sun_ra_deg, sun_dec_deg — Sun RA and Dec as separate 1D arrays (degrees)

  • sun_ra_rad, sun_dec_rad — Sun RA and Dec as separate 1D arrays (radians)

  • moon_ra_deg, moon_dec_deg — Moon RA and Dec as separate 1D arrays (degrees)

  • moon_ra_rad, moon_dec_rad — Moon RA and Dec as separate 1D arrays (radians)

  • earth_ra_deg, earth_dec_deg — Earth RA and Dec as separate 1D arrays (degrees)

  • earth_ra_rad, earth_dec_rad — Earth RA and Dec as separate 1D arrays (radians)

Methods:

  • index(time) — Find the index of the closest timestamp to the given datetime

    • time — Python datetime object

    • Returns: int index that can be used to access ephemeris arrays

    • Example: idx = eph.index(datetime(2024, 1, 1, 12, 0, 0)) then position = eph.gcrs_pv.position[idx]

  • get_body_pv(body) — Get position/velocity of a solar system body relative to observer

    • body — Body name (e.g., “Sun”, “Moon”, “Mars”) or NAIF ID as string (e.g., “10”, “301”)

    • Returns: PositionVelocityData with position/velocity in GCRS frame

    • Requires: ensure_planetary_ephemeris() called first

  • get_body(body) — Get SkyCoord for a solar system body with observer location set

    • body — Body name or NAIF ID as string

    • Returns: astropy.coordinates.SkyCoord in GCRS frame with obsgeoloc/obsgeovel set

    • Requires: ensure_planetary_ephemeris() called first

SPICEEphemeris

Spacecraft ephemeris from SPICE SPK (Spacecraft and Planet Kernel) files. Use this for missions that provide trajectory data in SPICE format.

Constructor:

SPICEEphemeris(spk_path, naif_id, begin, end, step_size=60, center_id=399, *, polar_motion=False)

  • spk_path — Path to the SPICE SPK file containing spacecraft trajectory

  • naif_id — NAIF ID of the spacecraft (typically negative, e.g., -82 for Cassini)

  • center_id — NAIF ID of the observer center (default: 399 = Earth)

Attributes (read-only):

  • gcrs_pv — Position/velocity in GCRS frame (PositionVelocityData)

  • itrs_pv — Position/velocity in ITRS frame (PositionVelocityData)

  • sun_pv — Sun position/velocity in GCRS frame (PositionVelocityData)

  • moon_pv — Moon position/velocity in GCRS frame (PositionVelocityData)

  • timestamp — List of Python datetime objects

  • itrs — ITRS coordinates as astropy SkyCoord

  • gcrs — GCRS coordinates as astropy SkyCoord

  • earth — Earth position as astropy SkyCoord

  • sun — Sun position as astropy SkyCoord

  • moon — Moon position as astropy SkyCoord

  • latitude — Geodetic latitude as an astropy Quantity array (degrees), one per timestamp

  • latitude_deg — Geodetic latitude as NumPy array (degrees), one per timestamp

  • latitude_rad — Geodetic latitude as NumPy array (radians), one per timestamp

  • longitude — Geodetic longitude as an astropy Quantity array (degrees), one per timestamp

  • longitude_deg — Geodetic longitude as NumPy array (degrees), one per timestamp

  • longitude_rad — Geodetic longitude as NumPy array (radians), one per timestamp

  • height — Height as an astropy Quantity array (meters), one per timestamp

  • height_m — Height as raw NumPy array (meters), one per timestamp

  • height_km — Height as raw NumPy array (kilometers), one per timestamp

  • obsgeoloc — Observer geocentric location (alias for GCRS position)

  • obsgeovel — Observer geocentric velocity (alias for GCRS velocity)

  • sun_radius — Sun angular radius as astropy Quantity (degrees)

  • sun_radius_deg — Sun angular radius as NumPy array (degrees)

  • sun_radius_rad — Sun angular radius as NumPy array (radians)

  • moon_radius — Moon angular radius as astropy Quantity (degrees)

  • moon_radius_deg — Moon angular radius as NumPy array (degrees)

  • moon_radius_rad — Moon angular radius as NumPy array (radians)

  • earth_radius — Earth angular radius as astropy Quantity (degrees)

  • earth_radius_deg — Earth angular radius as NumPy array (degrees)

  • earth_radius_rad — Earth angular radius as NumPy array (radians)

  • sun_ra_dec_deg — Sun RA/Dec as Nx2 NumPy array (degrees), cached

  • sun_ra_dec_rad — Sun RA/Dec as Nx2 NumPy array (radians), cached

  • moon_ra_dec_deg — Moon RA/Dec as Nx2 NumPy array (degrees), cached

  • moon_ra_dec_rad — Moon RA/Dec as Nx2 NumPy array (radians), cached

  • earth_ra_dec_deg — Earth RA/Dec as Nx2 NumPy array (degrees), cached

  • earth_ra_dec_rad — Earth RA/Dec as Nx2 NumPy array (radians), cached

  • sun_ra_deg, sun_dec_deg — Sun RA and Dec as separate 1D arrays (degrees)

  • sun_ra_rad, sun_dec_rad — Sun RA and Dec as separate 1D arrays (radians)

  • moon_ra_deg, moon_dec_deg — Moon RA and Dec as separate 1D arrays (degrees)

  • moon_ra_rad, moon_dec_rad — Moon RA and Dec as separate 1D arrays (radians)

  • earth_ra_deg, earth_dec_deg — Earth RA and Dec as separate 1D arrays (degrees)

  • earth_ra_rad, earth_dec_rad — Earth RA and Dec as separate 1D arrays (radians)

Methods:

  • index(time) — Find the index of the closest timestamp to the given datetime

    • time — Python datetime object

    • Returns: int index that can be used to access ephemeris arrays

    • Example: idx = eph.index(datetime(2024, 1, 1, 12, 0, 0)) then position = eph.gcrs_pv.position[idx]

  • get_body_pv(body) — Get position/velocity of a solar system body relative to observer

    • body — Body name (e.g., “Sun”, “Moon”, “Mars”) or NAIF ID as string

    • Returns: PositionVelocityData with position/velocity in GCRS frame

  • get_body(body) — Get SkyCoord for a solar system body with observer location set

    • body — Body name or NAIF ID as string

    • Returns: astropy.coordinates.SkyCoord in GCRS frame

GroundEphemeris

Ground-based observatory ephemeris for a fixed point on Earth’s surface.

Constructor:

GroundEphemeris(latitude, longitude, height, begin, end, step_size=60, *, polar_motion=False)

  • latitude — Geodetic latitude in degrees (-90 to 90)

  • longitude — Geodetic longitude in degrees (-180 to 180)

  • height — Altitude in meters above WGS84 ellipsoid

Attributes (read-only):

  • latitude — Observatory latitude as an astropy Quantity array (degrees), one per timestamp

  • longitude — Observatory longitude as an astropy Quantity array (degrees), one per timestamp

  • height — Observatory height as an astropy Quantity array (meters), one per timestamp

  • height_m — Observatory height raw numpy array (meters), one per timestamp

  • gcrs_pv — Position/velocity in GCRS frame (PositionVelocityData)

  • itrs_pv — Position/velocity in ITRS frame (PositionVelocityData)

  • sun_pv — Sun position/velocity in GCRS frame (PositionVelocityData)

  • moon_pv — Moon position/velocity in GCRS frame (PositionVelocityData)

  • timestamp — List of Python datetime objects

  • itrs — ITRS coordinates as astropy SkyCoord

  • gcrs — GCRS coordinates as astropy SkyCoord

  • earth — Earth position as astropy SkyCoord

  • sun — Sun position as astropy SkyCoord

  • moon — Moon position as astropy SkyCoord

  • latitude — Geodetic latitude as an astropy Quantity array (degrees), one per timestamp

  • latitude_deg — Geodetic latitude as NumPy array (degrees), one per timestamp

  • latitude_rad — Geodetic latitude as NumPy array (radians), one per timestamp

  • longitude — Geodetic longitude as an astropy Quantity array (degrees), one per timestamp

  • longitude_deg — Geodetic longitude as NumPy array (degrees), one per timestamp

  • longitude_rad — Geodetic longitude as NumPy array (radians), one per timestamp

  • height — Height as an astropy Quantity array (meters), one per timestamp

  • height_m — Height as raw NumPy array (meters), one per timestamp

  • height_km — Height as raw NumPy array (kilometers), one per timestamp

  • obsgeoloc — Observer geocentric location (alias for GCRS position)

  • obsgeovel — Observer geocentric velocity (alias for GCRS velocity)

  • sun_radius — Sun angular radius as astropy Quantity (degrees)

  • sun_radius_deg — Sun angular radius as NumPy array (degrees)

  • sun_radius_rad — Sun angular radius as NumPy array (radians)

  • moon_radius — Moon angular radius as astropy Quantity (degrees)

  • moon_radius_deg — Moon angular radius as NumPy array (degrees)

  • moon_radius_rad — Moon angular radius as NumPy array (radians)

  • earth_radius — Earth angular radius as astropy Quantity (degrees)

  • earth_radius_deg — Earth angular radius as NumPy array (degrees)

  • earth_radius_rad — Earth angular radius as NumPy array (radians)

  • sun_ra_dec_deg — Sun RA/Dec as Nx2 NumPy array (degrees), cached

  • sun_ra_dec_rad — Sun RA/Dec as Nx2 NumPy array (radians), cached

  • moon_ra_dec_deg — Moon RA/Dec as Nx2 NumPy array (degrees), cached

  • moon_ra_dec_rad — Moon RA/Dec as Nx2 NumPy array (radians), cached

  • earth_ra_dec_deg — Earth RA/Dec as Nx2 NumPy array (degrees), cached

  • earth_ra_dec_rad — Earth RA/Dec as Nx2 NumPy array (radians), cached

  • sun_ra_deg, sun_dec_deg — Sun RA and Dec as separate 1D arrays (degrees)

  • sun_ra_rad, sun_dec_rad — Sun RA and Dec as separate 1D arrays (radians)

  • moon_ra_deg, moon_dec_deg — Moon RA and Dec as separate 1D arrays (degrees)

  • moon_ra_rad, moon_dec_rad — Moon RA and Dec as separate 1D arrays (radians)

  • earth_ra_deg, earth_dec_deg — Earth RA and Dec as separate 1D arrays (degrees)

  • earth_ra_rad, earth_dec_rad — Earth RA and Dec as separate 1D arrays (radians)

Methods:

  • index(time) — Find the index of the closest timestamp to the given datetime

    • time — Python datetime object

    • Returns: int index that can be used to access ephemeris arrays

    • Example: idx = eph.index(datetime(2024, 1, 1, 12, 0, 0)) then sun_position = eph.sun_pv.position[idx]

  • get_body_pv(body) — Get position/velocity of a solar system body relative to observer

    • body — Body name (e.g., “Sun”, “Moon”, “Mars”) or NAIF ID as string

    • Returns: PositionVelocityData with position/velocity in GCRS frame

    • Requires: ensure_planetary_ephemeris() called first

  • get_body(body) — Get SkyCoord for a solar system body with observer location set

    • body — Body name or NAIF ID as string

    • Returns: astropy.coordinates.SkyCoord in GCRS frame

OEMEphemeris

Load and interpolate CCSDS Orbit Ephemeris Message (OEM) files for spacecraft ephemeris.

The OEM file must use a GCRS-compatible reference frame such as J2000, EME2000, GCRF, or ICRF. Earth-fixed frames (e.g., ITRF) are not supported and will raise a ValueError.

Constructor:

OEMEphemeris(oem_file_path, begin, end, step_size=60, *, polar_motion=False)

  • oem_file_path — Path to CCSDS OEM file (.oem)

  • begin — Start time for ephemeris (Python datetime)

  • end — End time for ephemeris (Python datetime)

  • step_size — Time step in seconds for interpolated ephemeris (default: 60)

  • polar_motion — Enable polar motion corrections (default: False)

Raises:

  • ValueError — If reference frame is missing or incompatible with GCRS

Attributes (read-only):

  • oem_pv — Original OEM state vectors (PositionVelocityData) without interpolation

  • oem_timestamp — Original OEM timestamps (list of datetime) without interpolation

  • gcrs_pv — Interpolated position/velocity in GCRS frame (PositionVelocityData)

  • itrs_pv — Position/velocity in ITRS frame (PositionVelocityData)

  • sun_pv — Sun position/velocity in GCRS frame (PositionVelocityData)

  • moon_pv — Moon position/velocity in GCRS frame (PositionVelocityData)

  • timestamp — List of Python datetime objects for interpolated ephemeris

  • itrs — ITRS coordinates as astropy SkyCoord

  • gcrs — GCRS coordinates as astropy SkyCoord

  • earth — Earth position as astropy SkyCoord

  • sun — Sun position as astropy SkyCoord

  • moon — Moon position as astropy SkyCoord

  • latitude — Geodetic latitude as an astropy Quantity array (degrees), one per timestamp

  • latitude_deg — Geodetic latitude as NumPy array (degrees), one per timestamp

  • latitude_rad — Geodetic latitude as NumPy array (radians), one per timestamp

  • longitude — Geodetic longitude as an astropy Quantity array (degrees), one per timestamp

  • longitude_deg — Geodetic longitude as NumPy array (degrees), one per timestamp

  • longitude_rad — Geodetic longitude as NumPy array (radians), one per timestamp

  • height — Height as an astropy Quantity array (meters), one per timestamp

  • height_m — Height as raw NumPy array (meters), one per timestamp

  • height_km — Height as raw NumPy array (kilometers), one per timestamp

  • obsgeoloc — Observer geocentric location (alias for GCRS position)

  • obsgeovel — Observer geocentric velocity (alias for GCRS velocity)

  • sun_radius — Sun angular radius as astropy Quantity (degrees)

  • sun_radius_deg — Sun angular radius as NumPy array (degrees)

  • sun_radius_rad — Sun angular radius as NumPy array (radians)

  • moon_radius — Moon angular radius as astropy Quantity (degrees)

  • moon_radius_deg — Moon angular radius as NumPy array (degrees)

  • moon_radius_rad — Moon angular radius as NumPy array (radians)

  • earth_radius — Earth angular radius as astropy Quantity (degrees)

  • earth_radius_deg — Earth angular radius as NumPy array (degrees)

  • earth_radius_rad — Earth angular radius as NumPy array (radians)

  • sun_ra_dec_deg — Sun RA/Dec as Nx2 NumPy array (degrees), cached

  • sun_ra_dec_rad — Sun RA/Dec as Nx2 NumPy array (radians), cached

  • moon_ra_dec_deg — Moon RA/Dec as Nx2 NumPy array (degrees), cached

  • moon_ra_dec_rad — Moon RA/Dec as Nx2 NumPy array (radians), cached

  • earth_ra_dec_deg — Earth RA/Dec as Nx2 NumPy array (degrees), cached

  • earth_ra_dec_rad — Earth RA/Dec as Nx2 NumPy array (radians), cached

  • sun_ra_deg, sun_dec_deg — Sun RA and Dec as separate 1D arrays (degrees)

  • sun_ra_rad, sun_dec_rad — Sun RA and Dec as separate 1D arrays (radians)

  • moon_ra_deg, moon_dec_deg — Moon RA and Dec as separate 1D arrays (degrees)

  • moon_ra_rad, moon_dec_rad — Moon RA and Dec as separate 1D arrays (radians)

  • earth_ra_deg, earth_dec_deg — Earth RA and Dec as separate 1D arrays (degrees)

  • earth_ra_rad, earth_dec_rad — Earth RA and Dec as separate 1D arrays (radians)

Methods:

  • index(time) — Find the index of the closest timestamp to the given datetime

    • time — Python datetime object

    • Returns: int index that can be used to access ephemeris arrays

    • Example: idx = eph.index(datetime(2032, 7, 1, 12, 0, 0)) then position = eph.gcrs_pv.position[idx]

  • get_body_pv(body) — Get position/velocity of a solar system body relative to observer

    • body — Body name (e.g., “Sun”, “Moon”, “Mars”) or NAIF ID as string

    • Returns: PositionVelocityData with position/velocity in GCRS frame

    • Requires: ensure_planetary_ephemeris() called first

  • get_body(body) — Get SkyCoord for a solar system body with observer location set

    • body — Body name or NAIF ID as string

    • Returns: astropy.coordinates.SkyCoord in GCRS frame

FileEphemeris

Load pre-computed state vectors from a simulator output file and resample to a uniform output grid via Hermite interpolation. Supports offset-based simulator output, simple CSV/TSV layouts, and any file where data rows contain seven whitespace-separated values: <time>  <x>  <y>  <z>  <vx>  <vy>  <vz>.

The coordinate frame, reference epoch, and units are auto-detected from header key-value pairs and may be overridden via constructor parameters.

Constructor:

FileEphemeris(file_path, begin, end, step_size=60, *, polar_motion=False, position_unit=None, velocity_unit=None, frame=None, epoch=None, time_format=None)

  • file_path — Path to the ephemeris file

  • begin — Start time for the output grid (Python datetime, UTC)

  • end — End time for the output grid (Python datetime, UTC)

  • step_size — Output time step in seconds (default: 60)

  • polar_motion — Apply polar motion correction (default: False)

  • position_unit — Override detected position unit: "km" (default), "m", "cm"

  • velocity_unit — Override detected velocity unit: "km/s" (default), "m/s", "cm/s"

  • frame — Override detected coordinate frame. GCRS-compatible: "J2000", "EME2000", "GCRF", "GCRS", "ICRF". Earth-fixed: "ITRS", "ECEF", "ECF", "FIXED", "TERRESTRIAL"

  • epoch — Reference epoch (T0) for numeric time offsets; overrides any epoch found in the file header

  • time_format — How to interpret the time column: "auto" (default), "seconds", "days", "iso8601"

Raises:

  • IOError — If the file cannot be opened or read

  • ValueError — If no state vectors are found, the requested time range exceeds the file data range, units are unrecognised, or the frame is unsupported

Attributes (read-only):

  • file_path — Path to the source file

  • source_frame — Coordinate frame as detected/specified

  • source_position_unit — Position unit as detected/specified (before km conversion)

  • source_velocity_unit — Velocity unit as detected/specified (before km/s conversion)

  • file_pv — Raw state vectors from the file (km, km/s) before resampling (PositionVelocityData)

  • file_timestamp — Raw timestamps from the file before resampling (list of datetime)

  • gcrs_pv — Interpolated position/velocity in GCRS frame (PositionVelocityData)

  • itrs_pv — Position/velocity in ITRS frame (PositionVelocityData)

  • sun_pv, moon_pv — Sun/Moon position/velocity in GCRS frame (PositionVelocityData)

  • timestamp — Output grid timestamps (NumPy datetime64 array)

  • gcrs, itrs, earth, sun, moon — astropy SkyCoord objects

  • latitude_deg, longitude_deg, height_m — Geodetic coordinates

  • All other standard Ephemeris properties (angular radii, RA/Dec arrays, etc.)

Methods:

  • index(time) — Find the index of the closest output-grid timestamp to the given datetime

  • get_body_pv(body), get_body(body) — Solar system body position/velocity and SkyCoord

  • moon_illumination(time_indices=None) — Moon illumination fraction (0–1) as seen from spacecraft

  • radec_to_altaz(ra_deg, dec_deg, time_indices=None) — Convert RA/Dec to Alt/Az

  • calculate_airmass(ra_deg, dec_deg, time_indices=None) — Astronomical airmass

See Using FileEphemeris for worked examples.

ParquetEphemeris

Load pre-computed state vectors from a Parquet file via DuckDB and resample to a uniform output grid via Hermite interpolation. Supports local files, globs, and cloud object stores (S3, DigitalOcean Spaces, GCS, R2, HTTPS).

Requires the optional duckdb Python package (pip install rust-ephem[parquet] or pip install duckdb).

Constructor:

ParquetEphemeris(source, begin, end, step_size=60, *, polar_motion=False, time_col=None, pos_cols=None, vel_cols=None, position_unit=None, velocity_unit=None, frame=None, s3_endpoint=None, s3_region=None, where_clause=None)

  • source — Path or URI to the Parquet file. Supports local paths and globs, s3://, gcs://, r2://, http(s)://

  • begin — Start time for the output grid (Python datetime, UTC)

  • end — End time for the output grid (Python datetime, UTC)

  • step_size — Output time step in seconds (default: 60)

  • polar_motion — Apply polar motion correction (default: False)

  • time_col — Name of the timestamp column (default: "time")

  • pos_cols — Names of the three position columns (default: ("x", "y", "z"))

  • vel_cols — Names of the three velocity columns (default: ("vx", "vy", "vz"))

  • position_unit — Position unit in the source: "km" (default), "m", "cm"

  • velocity_unit — Velocity unit in the source: "km/s" (default), "m/s", "cm/s"

  • frame — Coordinate frame of the source. Default "GCRS". GCRS-compatible: "J2000", "EME2000", "GCRF", "GCRS", "ICRF". Earth-fixed: "ITRS", "ECEF", "ECF", "FIXED", "TERRESTRIAL"

  • s3_endpoint — Custom S3 endpoint host for S3-compatible services (e.g. "nyc3.digitaloceanspaces.com" for DigitalOcean Spaces)

  • s3_region — Override S3 region. Falls back to AWS_REGION env var.

  • where_clause — Extra SQL WHERE predicate to apply to the Parquet (e.g. "sat_id = 42"). Combined via AND with the time-range filter.

Authentication:

Cloud access uses DuckDB’s credential_chain SECRET, which transparently picks up the standard AWS environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_SESSION_TOKEN.

Raises:

  • ImportError — If the duckdb package is not installed

  • ValueError — If column names are not safe identifiers, the requested time range exceeds the Parquet’s data range (with a 1 hour margin), units are unrecognised, or the frame is unsupported

Attributes (read-only):

  • source — Path or URI for the Parquet data

  • file_path — Alias for source (matches FileEphemeris for consistency)

  • source_frame — Coordinate frame as specified

  • source_position_unit — Position unit as specified (before km conversion)

  • source_velocity_unit — Velocity unit as specified (before km/s conversion)

  • file_pv — Raw state vectors loaded from the Parquet (km, km/s) before resampling (PositionVelocityData)

  • file_timestamp — Raw timestamps from the Parquet before resampling (list of datetime)

  • gcrs_pv — Interpolated position/velocity in GCRS frame (PositionVelocityData)

  • itrs_pv — Position/velocity in ITRS frame (PositionVelocityData)

  • sun_pv, moon_pv — Sun/Moon position/velocity in GCRS frame (PositionVelocityData)

  • timestamp — Output grid timestamps (NumPy datetime64 array)

  • gcrs, itrs, earth, sun, moon — astropy SkyCoord objects

  • latitude_deg, longitude_deg, height_m — Geodetic coordinates

  • All other standard Ephemeris properties (angular radii, RA/Dec arrays, etc.)

Methods:

  • index(time) — Find the index of the closest output-grid timestamp to the given datetime

  • get_body_pv(body), get_body(body) — Solar system body position/velocity and SkyCoord

  • moon_illumination(time_indices=None) — Moon illumination fraction (0–1) as seen from spacecraft

  • radec_to_altaz(ra_deg, dec_deg, time_indices=None) — Convert RA/Dec to Alt/Az

  • calculate_airmass(ra_deg, dec_deg, time_indices=None) — Astronomical airmass

See Using ParquetEphemeris for worked examples.

Constraint

Evaluate astronomical observation constraints against ephemeris data.

Static Methods:

  • Constraint.sun_proximity(min_angle, max_angle=None) — Create Sun proximity constraint

  • Constraint.moon_proximity(min_angle, max_angle=None) — Create Moon proximity constraint

  • Constraint.earth_limb(min_angle, max_angle=None) — Create Earth limb avoidance constraint * Constraint.earth_limb(min_angle, max_angle=None, include_refraction=False, horizon_dip=False) — Create Earth limb avoidance constraint

  • Constraint.body_proximity(body, min_angle, max_angle=None) — Create solar system body proximity constraint

  • Constraint.eclipse(umbra_only=True) — Create eclipse constraint

  • Constraint.and_(*constraints) — Combine constraints with logical AND

  • Constraint.or_(*constraints) — Combine constraints with logical OR

  • Constraint.xor_(*constraints) — Combine constraints with logical XOR (violation when exactly one sub-constraint is violated)

  • Constraint.at_least(min_violated, constraints) — Threshold combinator (violation when at least min_violated sub-constraints are violated)

  • Constraint.not_(constraint) — Negate a constraint with logical NOT

  • Constraint.boresight_offset(constraint, roll_deg=0.0, roll_clockwise=False, roll_reference="north", pitch_deg=0.0, yaw_deg=0.0) — Wrap a constraint with fixed boresight Euler-angle offsets - roll_deg — Fixed instrument roll offset (degrees) relative to the spacecraft frame. Default 0.0. Spacecraft roll at observation time is a separate concept applied via target_roll on evaluation methods. - roll_reference — Roll-zero reference axis. Default is "north" (celestial-north-projected +Z zero-roll). Use "sun" for Sun-projected +Z zero-roll when needed.

  • Constraint.from_json(json_str) — Create constraint from JSON configuration

Methods:

  • evaluate(ephemeris, target_ra, target_dec, times=None, indices=None) — Evaluate constraint against ephemeris data

    • ephemeris — Any Ephemeris object (TLEEphemeris, SPICEEphemeris, GroundEphemeris, OEMEphemeris, FileEphemeris, or ParquetEphemeris)

    • target_ra — Target right ascension in degrees (ICRS/J2000)

    • target_dec — Target declination in degrees (ICRS/J2000)

    • times — Optional: specific datetime(s) to evaluate (must exist in ephemeris)

    • indices — Optional: specific time index/indices to evaluate

    • Returns: ConstraintResult object

  • evaluate_batch(ephemeris, target_ras, target_decs, times=None, indices=None, target_rolls=None) — Convenience batch API returning one ConstraintResult per target

    • ephemeris — Any Ephemeris object (TLEEphemeris, SPICEEphemeris, GroundEphemeris, OEMEphemeris, FileEphemeris, or ParquetEphemeris)

    • target_ras — List of target right ascensions in degrees (ICRS/J2000)

    • target_decs — List of target declinations in degrees (ICRS/J2000)

    • times — Optional: specific datetime(s) to evaluate (must exist in ephemeris)

    • indices — Optional: specific time index/indices to evaluate

    • target_rolls — Optional: per-target spacecraft roll angles in degrees, one value per target. Each entry may be None to evaluate that target without a fixed spacecraft roll (default: None for all targets)

    • Returns: list of ConstraintResult objects, one per target

    • Best when you want the same per-target summary shape as evaluate() without writing the loop yourself

  • in_constraint_batch(ephemeris, target_ras, target_decs, times=None, indices=None, target_rolls=None) — [Recommended] Vectorized batch evaluation for multiple targets

    • ephemeris — Any Ephemeris object (TLEEphemeris, SPICEEphemeris, GroundEphemeris, OEMEphemeris, FileEphemeris, or ParquetEphemeris)

    • target_ras — List/array of target right ascensions in degrees (ICRS/J2000)

    • target_decs — List/array of target declinations in degrees (ICRS/J2000)

    • times — Optional: specific datetime(s) to evaluate (must exist in ephemeris)

    • indices — Optional: specific time index/indices to evaluate

    • target_rolls — Optional: per-target spacecraft roll angles in degrees, one value per target. Each entry may be None to evaluate that target without a fixed spacecraft roll. When an entry is None and the constraint has boresight offsets with non-zero pitch/yaw, evaluates the target as violated only if it violates at every possible roll angle (default: None for all targets)

    • Returns: 2D NumPy boolean array of shape (n_targets, n_times) where True indicates constraint violation

    • Performance: 3-50x faster than calling evaluate() in a loop

    • Optimized: Uses vectorized operations for batch RA/Dec conversion and constraint evaluation

    • All constraint types supported: Sun/Moon proximity, Earth limb, Eclipse, Body proximity, boresight offsets, and logical combinators (AND, OR, XOR, AT_LEAST, NOT)

  • in_constraint(time, ephemeris, target_ra, target_dec) — Check if target is in-constraint at a single time

    • time — Python datetime object (must exist in ephemeris timestamps)

    • Returns: bool (True if constraint is violated / target is blocked, False if satisfied)

  • instantaneous_field_of_regard(ephemeris, time=None, index=None, n_points=DEFAULT_N_POINTS, n_roll_samples=DEFAULT_N_ROLL_SAMPLES, target_roll=None) — Compute instantaneous visible sky solid angle. When target_roll is not specified, sweeps n_roll_samples spacecraft roll angles for boresight-offset constraints with non-zero pitch/yaw, giving the total accessible sky over all roll states.

    • ephemeris — Any Ephemeris object (TLEEphemeris, SPICEEphemeris, GroundEphemeris, OEMEphemeris, FileEphemeris, or ParquetEphemeris)

    • time — Optional datetime to evaluate (must exist in ephemeris)

    • index — Optional ephemeris index to evaluate

    • n_points — Number of sky samples (Fibonacci sphere integration, default DEFAULT_N_POINTS)

    • target_roll — Spacecraft roll angle (degrees) to evaluate at. When None (default), sweeps all roll angles for boresight-offset FoR.

    • n_roll_samples — Spacecraft roll angles to sweep when target_roll is None and pitch/yaw offsets are present (default DEFAULT_N_ROLL_SAMPLES = 360, i.e. 1° resolution). Can be reduced (e.g., 72 for 5° resolution) for faster evaluation. Ignored otherwise.

    • Returns: float steradians in [0, 4π]

    • Requirement: exactly one of time or index must be provided

    • Semantics: constraints are violated when True; this method integrates visible sky where constraint is False

  • to_json() — Get constraint configuration as JSON string

  • to_dict() — Get constraint configuration as Python dictionary

ConstraintResult

Result of constraint evaluation containing violation information.

Attributes (read-only):

  • violations — List of ConstraintViolation objects

  • all_satisfied — Boolean indicating if constraint was satisfied for entire time range

  • constraint_name — String name/description of the constraint

  • timestamp — NumPy array of Python datetime objects (optimized with caching)

  • constraint_array — NumPy boolean array where True means constraint violated / target blocked (optimized with caching)

  • visibility — List of VisibilityWindow objects for contiguous satisfied periods

Methods:

  • total_violation_duration() — Get total duration of violations in seconds

  • in_constraint(time) — Check if constraint is violated at a given time

    • time — Python datetime object (must exist in result timestamps)

    • Returns: bool (True if violated / target blocked, False if satisfied)

ConstraintViolation

Information about a specific constraint violation time window.

Attributes (read-only):

  • start_time — Start time of violation window (ISO 8601 string)

  • end_time — End time of violation window (ISO 8601 string)

  • max_severity — Maximum severity of violation (0.0 = just violated, 1.0+ = severe)

  • description — Human-readable description of the violation

VisibilityWindow

Time window when observation target is not constrained (visible).

Attributes (read-only):

  • start_time — Start time of visibility window (Python datetime)

  • end_time — End time of visibility window (Python datetime)

  • duration_seconds — Duration of the window in seconds (computed property)

PositionVelocityData

Container for position and velocity data returned by ephemeris calculations.

Attributes (read-only):

  • position — NumPy array of positions (N × 3), in km

  • velocity — NumPy array of velocities (N × 3), in km/s

  • position_unit — String “km”

  • velocity_unit — String “km/s”

Functions

Planetary Ephemeris Management

  • init_planetary_ephemeris(py_path) — Initialize an already-downloaded planetary SPK file.

  • download_planetary_ephemeris(url, dest) — Download a planetary SPK file from a URL.

  • ensure_planetary_ephemeris(py_path=None, download_if_missing=True, spk_url=None) — Download (if missing) and initialize planetary SPK lazily. Uses default de440s.bsp if no path provided.

  • is_planetary_ephemeris_initialized() — Check if planetary ephemeris is initialized. Returns bool.

Time System Conversions

  • get_tai_utc_offset(py_datetime) — Get TAI-UTC offset (leap seconds) for a given datetime. Returns Optional[float] (seconds).

  • get_ut1_utc_offset(py_datetime) — Get UT1-UTC offset for a given datetime. Returns float (seconds).

  • is_ut1_available() — Check if UT1 data is available. Returns bool.

  • init_ut1_provider() — Initialize UT1 provider. Returns bool indicating success.

Earth Orientation Parameters (EOP)

  • get_polar_motion(py_datetime) — Get polar motion parameters (x_p, y_p) for a given datetime. Returns Tuple[float, float] (arcseconds).

  • is_eop_available() — Check if EOP data is available. Returns bool.

  • init_eop_provider() — Initialize EOP provider. Returns bool indicating success.

Cache Management

  • get_cache_dir() — Get the path to the cache directory used by rust_ephem. Returns str.

TLE Fetching

  • fetch_tle(*, tle=None, norad_id=None, norad_name=None, epoch=None, spacetrack_username=None, spacetrack_password=None, epoch_tolerance_days=None, enforce_source=None) — Fetch a TLE from various sources.

    This function provides a unified interface for retrieving TLE data from local files, URLs, Celestrak, or Space-Track.org. Returns a TLERecord object containing the TLE data and metadata.

    Parameters:

    • tle (str, optional) — Path to TLE file or URL to download TLE from

    • norad_id (int, optional) — NORAD catalog ID to fetch TLE. If Space-Track credentials are available, Space-Track is tried first with failover to Celestrak.

    • norad_name (str, optional) — Satellite name to fetch TLE from Celestrak

    • epoch (datetime, optional) — Target epoch for Space-Track queries. If not specified, current time is used. Space-Track will fetch the TLE with epoch closest to this time.

    • spacetrack_username (str, optional) — Space-Track.org username (or use SPACETRACK_USERNAME env var)

    • spacetrack_password (str, optional) — Space-Track.org password (or use SPACETRACK_PASSWORD env var)

    • epoch_tolerance_days (float, optional) — For Space-Track cache: how many days TLE epoch can differ from target epoch (default: 4.0 days)

    • enforce_source (str, optional) — Enforce use of specific source without failover. Must be "celestrak", "spacetrack", or None (default behavior with failover)

    Returns:

    TLERecord — A Pydantic model containing the TLE data and metadata

    Raises:

    ValueError — If no valid TLE source is specified or fetching fails

    Examples:

    import rust_ephem

# Fetch from Celestrak by NORAD ID
tle = rust_ephem.fetch_tle(norad_id=25544)  # ISS
print(tle.name)
print(tle.line1)
print(tle.line2)

# Fetch from file
tle = rust_ephem.fetch_tle(tle="path/to/satellite.tle")

# Fetch from URL
tle = rust_ephem.fetch_tle(tle="https://celestrak.org/NORAD/elements/gp.php?CATNR=25544")

# Fetch from Space-Track with explicit credentials
from datetime import datetime, timezone
tle = rust_ephem.fetch_tle(
    norad_id=25544,
    spacetrack_username="your_username",
    spacetrack_password="your_password",
    epoch=datetime(2020, 1, 1, tzinfo=timezone.utc)
)

# Use TLERecord with TLEEphemeris
ephem = rust_ephem.TLEEphemeris(
    tle=tle,  # Pass TLERecord directly
    begin=datetime(2024, 1, 1, tzinfo=timezone.utc),
    end=datetime(2024, 1, 2, tzinfo=timezone.utc),
    step_size=60
)
    Notes:

    • Must provide exactly one of: tle, norad_id, or norad_name

    • File paths and URLs are cached locally for improved performance

    • Space-Track.org requires free account registration at https://www.space-track.org

    • Credentials can be provided via:

      1. Explicit parameters: spacetrack_username and spacetrack_password

      2. Environment variables: SPACETRACK_USERNAME and SPACETRACK_PASSWORD

      3. .env file in the current directory or home directory (~/.env) containing the same environment variables

Data Models

TLERecord

A Pydantic model representing a Two-Line Element (TLE) record with metadata. Can be passed directly to TLEEphemeris via the tle parameter. Supports JSON serialization for storage and transmission.

Attributes:

  • line1 (str) — First line of the TLE (starts with ‘1’)

  • line2 (str) — Second line of the TLE (starts with ‘2’)

  • name (str | None) — Optional satellite name (from 3-line TLE format)

  • epoch (datetime) — TLE epoch timestamp (extracted from line1)

  • source (str | None) — Source of the TLE data (e.g., ‘celestrak’, ‘spacetrack’, ‘file’, ‘url’)

Derived Fields:

  • norad_id (int) — NORAD catalog ID extracted from line1

  • classification (str) — Classification from line1 (U=unclassified, C=classified, S=secret)

  • international_designator (str) — International designator extracted from line1

  • mean_motion_dot_rev_per_day2 (float) — First derivative of mean motion from line1

  • mean_motion_ddot_rev_per_day3 (float) — Second derivative of mean motion from line1

  • bstar_drag (float) — BSTAR drag term from line1

  • ephemeris_type (int) — Ephemeris type from line1

  • element_set_number (int) — Element set number from line1

  • revolution_number_at_epoch (int) — Revolution number at epoch from line2

  • inclination_deg (float) — Inclination extracted from line2

  • right_ascension_deg (float) — RAAN extracted from line2

  • eccentricity (float) — Eccentricity extracted from line2

  • arg_periapsis_deg (float) — Argument of periapsis extracted from line2

  • mean_anomaly_deg (float) — Mean anomaly extracted from line2

  • mean_motion_rev_per_day (float) — Mean motion extracted from line2

  • mean_motion_rad_s (float) — Mean motion in radians/second

  • true_anomaly_deg (float) — True anomaly derived from mean anomaly and eccentricity

  • semimajor_axis_m (float) — Semimajor axis derived using WGS72 gravitational parameter

Methods:

  • to_tle_string() — Convert to a 2-line or 3-line TLE string format

  • classical_elements(mu_m3_s2=WGS72_EARTH_MU_M3_S2) — Return a dictionary of mean classical elements with keys SemimajorAxis_m, Eccentricity, Inclination_deg, RightAscension_deg, ArgPeriapsis_deg, TrueAnomaly_deg, MeanAnomaly_deg, MeanMotion_rev_per_day, and GravitationalParameter_m3_s2. If mu_m3_s2 is overridden, SemimajorAxis_m is recomputed with the supplied value.

  • model_dump() — Convert to dictionary (Pydantic)

  • model_dump_json() — Convert to JSON string (Pydantic)

Example:

import rust_ephem

tle = rust_ephem.fetch_tle(norad_id=25544)

# Access TLE data
print(f"Satellite: {tle.name}")
print(f"NORAD ID: {tle.norad_id}")
print(f"Epoch: {tle.epoch}")
print(f"Source: {tle.source}")

# Get TLE as string
print(tle.to_tle_string())

# Serialize to JSON
json_str = tle.model_dump_json()

# Pass directly to TLEEphemeris
ephem = rust_ephem.TLEEphemeris(
    tle=tle,
    begin=datetime(2024, 1, 1, tzinfo=timezone.utc),
    end=datetime(2024, 1, 2, tzinfo=timezone.utc)
)

Constraint Configuration Classes

The following Pydantic models are used to configure constraints. These can be serialized to/from JSON and support logical combinations using Python operators.

SunConstraint

Sun proximity constraint.

Constructor:

SunConstraint(min_angle=45.0)

Attributes:

  • type — Always “sun”

  • min_angle — Minimum angular separation from Sun in degrees (0-180)

  • max_angle — Maximum angular separation from Sun in degrees (0-180), optional

MoonConstraint

Moon proximity constraint.

Constructor:

MoonConstraint(min_angle=30.0)

Attributes:

  • type — Always “moon”

  • min_angle — Minimum angular separation from Moon in degrees (0-180)

  • max_angle — Maximum angular separation from Moon in degrees (0-180), optional

EarthLimbConstraint

Earth limb avoidance constraint.

Constructor:

EarthLimbConstraint(min_angle=10.0, include_refraction=False, horizon_dip=False)

Attributes:

  • type — Always “earth_limb”

  • min_angle — Minimum angular separation from Earth’s limb in degrees (0-180)

  • max_angle — Maximum angular separation from Earth’s limb in degrees (0-180), optional * include_refraction — Include atmospheric refraction correction (~0.57°) for ground observers (default: False) * horizon_dip — Include geometric horizon dip correction for ground observers (default: False)

BodyConstraint

Solar system body proximity constraint.

Constructor:

BodyConstraint(body="Mars", min_angle=15.0)

Attributes:

  • type — Always “body”

  • body — Name of the solar system body (e.g., “Mars”, “Jupiter”)

  • min_angle — Minimum angular separation from body in degrees (0-180)

  • max_angle — Maximum angular separation from body in degrees (0-180), optional

EclipseConstraint

Eclipse constraint (Earth shadow). Assumes an Earth-centered ephemeris (Earth at origin).

Constructor:

EclipseConstraint(umbra_only=True)

Attributes:

  • type — Always “eclipse”

  • umbra_only — If True, only umbra counts. If False, includes penumbra.

AndConstraint

Logical AND combination of constraints.

Constructor:

AndConstraint(constraints=[constraint1, constraint2])

Attributes:

  • type — Always “and”

  • constraints — List of constraints to combine with AND

OrConstraint

Logical OR combination of constraints.

Constructor:

OrConstraint(constraints=[constraint1, constraint2])

Attributes:

  • type — Always “or”

  • constraints — List of constraints to combine with OR

XorConstraint

Logical XOR combination of constraints.

Violation semantics: The XOR constraint is violated when exactly one sub-constraint is violated; it is satisfied otherwise (i.e., when either none or more than one sub-constraints are violated). This mirrors boolean XOR over “violation” states.

Constructor:

XorConstraint(constraints=[constraint1, constraint2, ...])

Attributes:

  • type — Always “xor”

  • constraints — List of constraints (minimum 2) evaluated with XOR violation semantics

AtLeastConstraint

Threshold (k-of-n) combination of constraints.

Violation semantics: The AT_LEAST constraint is violated when the number of violated sub-constraints is greater than or equal to min_violated.

Constructor:

AtLeastConstraint(min_violated=2, constraints=[constraint1, constraint2, ...])

Attributes:

  • type — Always “at_least”

  • min_violated — Minimum number of violated sub-constraints required (>=1)

  • constraints — List of constraints (minimum 1)

NotConstraint

Logical NOT (negation) of a constraint.

Constructor:

NotConstraint(constraint=some_constraint)

Attributes:

  • type — Always “not”

  • constraint — Constraint to negate

Common Constraint Methods

All constraint configuration classes (SunConstraint, MoonConstraint, etc.) inherit these methods from RustConstraintMixin:

  • evaluate(ephemeris, target_ra, target_dec, times=None, indices=None) — Evaluate constraint for a single target

    • Returns: ConstraintResult object

    • See Constraint.evaluate() above for parameter details

  • in_constraint(time, ephemeris, target_ra, target_dec) — Check if target satisfies constraint at a single time

    • Returns: bool

  • at_least(min_violated, *others) — Build an AtLeastConstraint from this constraint plus additional constraints

    • Returns: AtLeastConstraint

Constraint Operators

Constraint configurations support Python bitwise operators for convenient combination:

  • constraint1 & constraint2 — Logical AND (equivalent to AndConstraint)

  • constraint1 | constraint2 — Logical OR (equivalent to OrConstraint)

  • constraint1 ^ constraint2 — Logical XOR (equivalent to XorConstraint)

  • ~constraint — Logical NOT (equivalent to NotConstraint)

Usage examples are provided in the examples section of the docs.

Type Aliases

ConstraintConfig

Union type for all constraint configuration classes:

ConstraintConfig = (
    SunConstraint | MoonConstraint | EclipseConstraint |
    EarthLimbConstraint | BodyConstraint | AndConstraint |
  OrConstraint | XorConstraint | AtLeastConstraint | NotConstraint
)
CombinedConstraintConfig

Pydantic TypeAdapter for parsing constraint configurations from JSON.

Performance Notes

Constraint Evaluation Optimizations

The constraint system includes several performance optimizations for efficient evaluation:

  • Property Caching: The timestamp and constraint_array properties on ephemeris and constraint result objects are cached for repeated access (90x+ speedup on subsequent accesses)

  • Subset Evaluation: Use times or indices parameters in evaluate() to compute constraints for specific times only, avoiding full ephemeris evaluation

  • Single Time Checks: For checking a single time, use Constraint.in_constraint() which is optimized for single-point evaluation

  • Vectorized Batch Evaluation: For checking multiple targets, use in_constraint_batch() which evaluates all targets in a single call, eliminating Python call overhead

  • Optimal Usage Patterns:

    • FASTEST (Multiple Targets): Use batch evaluation for multiple targets:

      target_ras = [0.0, 90.0, 180.0, 270.0]
target_decs = [0.0, 30.0, -30.0, 60.0]
violations = constraint.in_constraint_batch(eph, target_ras, target_decs)
# violations is (n_targets, n_times) array
# violations[i, j] = True if target i violates constraint at time j

    • FAST (Single Target): Evaluate once, then use constraint_array property:

      result = constraint.evaluate(eph, ra, dec)
for i in range(len(result.timestamp)):
    if result.constraint_array[i]:  # ~1000x faster than alternatives
        # Target is visible at this time
        pass

    • OK: Evaluate once, then loop over result:

      result = constraint.evaluate(eph, ra, dec)
for i, time in enumerate(result.timestamp):
    if result.in_constraint(time):  # ~100x faster than evaluating each time
        # Target is visible
        pass

    • SLOW (avoid): Calling in_constraint() in a loop:

      # Don't do this - evaluates ephemeris 1000s of times!
for time in eph.timestamp:
    if constraint.in_constraint(time, eph, ra, dec):
        pass

Timestamp Access

All ephemeris and constraint result objects return NumPy arrays for the timestamp property, which is significantly faster than Python lists for indexing operations.