Skip to content

Windows

Satellite-ground station access (visibility) prediction.

Computes time windows when a satellite is above a minimum elevation angle as seen from a ground station. The approach is a three-stage hybrid:

  1. JIT-accelerated elevation grid — vmap over a time array (the expensive topocentric math).
  2. Python-level window detection — sign-change detection with NumPy (cheap, avoids JAX's fixed-shape constraint).
  3. JIT-accelerated bisection refinement — jax.lax.while_loop per boundary, vmapped across all boundaries.

All angles are in radians and distances in metres unless noted otherwise.

AccessResult

Bases: NamedTuple

Fixed-shape result from :func:find_access_windows_jit.

All arrays have leading dimension max_windows. Slots where valid[i] is False contain dummy values and should be ignored.

AccessWindow

Bases: NamedTuple

A single satellite access (visibility) window.

All times are in seconds since the reference epoch used by the caller. Angles in radians, distances in metres.

GroundLocation

Bases: NamedTuple

A ground station / observer location.

Stores geodetic coordinates together with pre-computed ECEF position and ECEF-to-ENZ rotation matrix for efficient repeated use.

Construct via :func:ground_location.

compute_azel(sat_ecef, station_ecef, rot_enz=None)

Compute azimuth, elevation, and range of a satellite from a station.

Parameters:

Name Type Description Default
sat_ecef ArrayLike

Satellite ECEF position [x, y, z] in metres.

 required
station_ecef ArrayLike

Station ECEF position [x, y, z] in metres.

 required
rot_enz ArrayLike | None

Optional pre-computed 3x3 ECEF-to-ENZ rotation matrix.

 None

Returns:

Type Description
Array

[azimuth, elevation, range] — azimuth in [0, 2pi) rad,
Array

elevation in [-pi/2, pi/2] rad, range in metres.

compute_elevation(sat_ecef, station_ecef, rot_enz=None)

Compute the elevation angle of a satellite as seen from a station.

This is a JIT-compatible, vmappable building block.

Parameters:

Name Type Description Default
sat_ecef ArrayLike

Satellite ECEF position [x, y, z] in metres.

 required
station_ecef ArrayLike

Station ECEF position [x, y, z] in metres.

 required
rot_enz ArrayLike | None

Optional pre-computed 3x3 ECEF-to-ENZ rotation matrix. If None, it is computed from the station position (slower for repeated calls with the same station).

 None

Returns:

Type Description
Array

Scalar elevation angle in radians.

find_access_windows(position_ecef_fn, location, t_start, t_end, min_elevation=0.0, dt=60.0, tol=0.001, use_degrees=False, *, constraint_fn=None)

Find satellite visibility windows from a ground station.

Takes a callable that returns ECEF position at a given time and finds all windows where the constraint is satisfied.

Parameters:

Name Type Description Default
position_ecef_fn Callable

Callable f(t) -> Array[3] returning the satellite ECEF position in metres at time t (seconds).

 required
location GroundLocation

Ground station as a :class:GroundLocation.

 required
t_start float

Start time in seconds.

 required
t_end float

End time in seconds.

 required
min_elevation float

Minimum elevation threshold. Radians by default, or degrees if use_degrees=True. Ignored when constraint_fn is provided.

 0.0
dt float

Coarse grid step size in seconds (default 60).

 60.0
tol float

Bisection convergence tolerance in seconds (default 0.001).

 0.001
use_degrees bool

If True, interpret min_elevation as degrees.

 False
constraint_fn Callable | None

Constraint function with signature (sat_ecef, station_ecef, rot_enz) -> float. When provided, takes precedence over min_elevation. Defaults to elevation_constraint(min_elevation).

 None

Returns:

Type Description
list[AccessWindow]

List of :class:AccessWindow instances (may be empty).

find_access_windows_from_ephemeris(positions_gcrf, times, location, eop, epochs, min_elevation=0.0, dt=60.0, tol=0.001, use_degrees=False)

Find access windows from pre-computed GCRF ephemeris positions.

Transforms GCRF positions to ITRF/ECEF, builds a linear-interpolation function for boundary refinement, and delegates to :func:find_access_windows.

Parameters:

Name Type Description Default
positions_gcrf ArrayLike

Array of shape (N, 3) with GCRF positions in metres.

 required
times ArrayLike

Array of shape (N,) with times in seconds since the reference epoch.

 required
location GroundLocation

Ground station as a :class:GroundLocation.

 required
eop

:class:~astrojax.eop.EOPData for frame transformation.

 required
epochs list

List of :class:~astrojax.epoch.Epoch instances corresponding to each time step (needed for GCRF→ITRF).

 required
min_elevation float

Minimum elevation threshold (radians, or degrees if use_degrees=True).

 0.0
dt float

Coarse grid step size in seconds (default 60).

 60.0
tol float

Bisection tolerance in seconds (default 0.001).

 0.001
use_degrees bool

If True, interpret min_elevation as degrees.

 False

Returns:

Type Description
list[AccessWindow]

List of :class:AccessWindow instances.

find_access_windows_jit(position_ecef_fn, station_ecef, rot_enz, t_start, t_end, max_windows, n_steps, tol=0.001, constraint_fn=None)

Find satellite visibility windows — fully JIT-compilable.

Unlike :func:find_access_windows, this function uses fixed-shape outputs and lax.scan for window detection, so it can be composed inside larger jax.jit pipelines.

Parameters:

Name Type Description Default
position_ecef_fn Callable

Callable f(t) -> Array[3] returning the satellite ECEF position in metres at time t (seconds).

 required
station_ecef ArrayLike

Station ECEF position [x, y, z] in metres.

 required
rot_enz ArrayLike

Pre-computed 3x3 ECEF-to-ENZ rotation matrix.

 required
t_start ArrayLike

Start time in seconds (scalar).

 required
t_end ArrayLike

End time in seconds (scalar).

 required
max_windows int

Maximum windows to detect. Static — determines output array shapes. Must be passed via static_argnums.

 required
n_steps int

Number of coarse grid samples. Static — determines lax.scan length. Must be passed via static_argnums.

 required
tol float

Bisection convergence tolerance in seconds (default 0.001).

 0.001
constraint_fn Callable | None

Constraint function with signature (sat_ecef, station_ecef, rot_enz) -> float. Positive means satisfied, negative means violated. Defaults to elevation_constraint(0.0) (elevation >= 0).

 None

Returns:

Name Type Description
An AccessResult

class:AccessResult with fixed-shape arrays. Only slots
AccessResult

where valid[i] is True contain meaningful values.

find_all_access_windows(position_ecef_fn, station_ecef, rot_enz, t_start, t_end, max_windows=100, n_steps=181, batch_size=10, tol=0.001, constraint_fn=None)

Find all access windows by paging through the time span.

Repeatedly calls :func:find_access_windows_jit with batch_size windows per call, advancing t_start past the last found window each time the batch fills up. Stops when the batch has room left (time span exhausted) or max_windows total have been collected.

This is a Python-level convenience wrapper — not itself JIT-compilable — but uses the JIT-compiled path for the heavy computation.

Parameters:

Name Type Description Default
position_ecef_fn Callable

Callable f(t) -> Array[3] returning the satellite ECEF position in metres at time t (seconds).

 required
station_ecef ArrayLike

Station ECEF position [x, y, z] in metres (e.g. location.ecef).

 required
rot_enz ArrayLike

Pre-computed 3x3 ECEF-to-ENZ rotation matrix (e.g. location.rot_enz).

 required
t_start float

Start time in seconds.

 required
t_end float

End time in seconds.

 required
max_windows int

Maximum total windows to return (default 100).

 100
n_steps int

Grid samples per JIT call (default 181).

 181
batch_size int

Windows per JIT call (default 10). Kept constant across calls to avoid JIT recompilation.

 10
tol float

Bisection tolerance in seconds (default 0.001).

 0.001
constraint_fn Callable | None

Constraint function with signature (sat_ecef, station_ecef, rot_enz) -> float. Defaults to elevation_constraint(0.0).

 None

Returns:

Type Description
list[AccessWindow]

List of :class:AccessWindow instances, at most max_windows.

ground_location(lon, lat, alt=0.0, use_degrees=True)

Create a :class:GroundLocation with pre-computed ECEF and ENZ rotation.

Parameters:

Name Type Description Default
lon float

Longitude.

 required
lat float

Latitude.

 required
alt float

Altitude above WGS84 ellipsoid in metres.

 0.0
use_degrees bool

If True (default), lon and lat are in degrees.

 True

Returns:

Name Type Description
A GroundLocation

class:GroundLocation instance.