@spec emission_media_batch(
  Sidereon.GNSS.SP3.t()
  | Sidereon.GNSS.PreciseEphemeris.t()
  | Sidereon.GNSS.PreciseEphemeris.Interpolant.t()
  | Sidereon.GNSS.PreciseEphemeris.InterpolantArtifact.t(),
  [emission_media_request()],
  vec3() | map(),
  keyword()
) :: {:ok, emission_media_batch()} | {:error, term()}

Predict emission-epoch satellite states and media delays in one batch call.

Each request is {satellite_id, emission_epoch_j2000_s}. The source is a parsed SP3 product, a sample-built precise source, or any Sidereon.GNSS.PreciseEphemeris.Interpolant, including one opened from artifact bytes. The output is a map of index-aligned arrays:

%{
  positions_ecef_m: [vec3() | nil],
  clocks_s: [float() | nil],
  ionosphere_slant_delays_m: [float() | nil],
  troposphere_delays_m: [float() | nil],
  statuses: [:valid | :gap | :below_elevation_cutoff | :error],
  element_errors: [term() | nil]
}

Options:

• :carrier_hz - carrier frequency for ionospheric group delay, default GPS L1.
• :troposphere - false, true, or a keyword list with :pressure_hpa, :temperature_k, and :relative_humidity.
• :ionosphere - nil, {:klobuchar, alpha, beta}, {:klobuchar, %{alpha: alpha, beta: beta}}, or {:ionex, handle}.
• :min_elevation_deg - optional minimum receiver elevation. Rows below the cutoff keep state and clock outputs but have nil media delays.

@spec predict(
  Sidereon.GNSS.SP3.t() | Sidereon.GNSS.Broadcast.t(),
  String.t(),
  vec3() | map(),
  NaiveDateTime.t(),
  keyword()
) :: {:ok, observables()} | {:error, term()}

Predict the observables for satellite_id seen from receiver_ecef at epoch.

receiver_ecef is the static receiver position in ITRF/ECEF metres, given as {x_m, y_m, z_m} or %{x_m: _, y_m: _, z_m: _}. epoch is the receive epoch, a NaiveDateTime (interpreted in the ephemeris source's own time scale).

Options

• :carrier_hz - carrier frequency for the Doppler, default the L1 carrier 1575.42 MHz.
• :light_time - apply the light-time / transmit-time correction, default true. When false, the satellite is evaluated at epoch.
• :sagnac - apply the Sagnac / Earth-rotation correction, default true.
• :extrapolate - for SP3 sources, allow evaluation outside the parsed product coverage. Default false.

Returns {:ok, observables}, {:error, :invalid_receiver} for a malformed receiver position, or propagates any ephemeris position error (e.g. an unknown satellite or a malformed satellite token) verbatim as {:error, reason}. Never raises.

@spec predict_all(Sidereon.GNSS.SP3.t(), vec3() | map(), NaiveDateTime.t(), keyword()) ::
  %{
    optional(String.t()) => {:ok, observables()} | {:error, term()}
  }

Predict observables for every satellite in the product, seen from receiver_ecef.

Returns a map satellite_id => {:ok, observables} | {:error, reason}, so one satellite failing (e.g. no estimate at this epoch) does not sink the batch. Options are the same as predict/5.

@spec predict_batch(
  Sidereon.GNSS.SP3.t(),
  [{String.t(), vec3() | map(), NaiveDateTime.t()}],
  keyword()
) ::
  [ok: observables(), error: term()]

Predict observables for many {satellite_id, receiver_ecef, epoch} requests against one loaded SP3 product in a single NIF call.

Each request is fully independent (its own satellite, receiver, and epoch), so one batch can mix many satellites, receivers, and epochs. The result list is index-aligned with requests: element i is {:ok, observables} or {:error, reason} for requests[i], so one bad request does not sink the batch. The valid requests are predicted as a batch inside the core (one boundary crossing); options are the same as predict/5.

@spec predict_ranges(
  Sidereon.GNSS.SP3.t()
  | Sidereon.GNSS.PreciseEphemeris.t()
  | Sidereon.GNSS.PreciseEphemeris.Interpolant.t()
  | Sidereon.GNSS.PreciseEphemeris.InterpolantArtifact.t(),
  [range_request()],
  keyword()
) :: {:ok, [range_result()]} | {:error, term()}

Predict geometry-only ranges for many {satellite_id, receiver_ecef, t_rx_j2000_s} requests against one precise-ephemeris source in a single NIF call.

source is a loaded Sidereon.GNSS.SP3 product, a Sidereon.GNSS.PreciseEphemeris sample-built source, or a Sidereon.GNSS.PreciseEphemeris.Interpolant cached source. Each request carries its own satellite token, static receiver ECEF position ({x_m, y_m, z_m} or %{x_m: _, y_m: _, z_m: _}), and receive epoch as seconds since J2000 in the source's own time scale.

This is the transmit-time geometry a range-only consumer needs, without the Doppler / topocentric fields of predict/5. On success returns {:ok, results} where each result is a map:

%{
  geometric_range_m:      float(),         # metres, after light-time + Sagnac
  sat_clock_s:            float() | nil,   # satellite clock at transmit time
  transmit_time_j2000_s:  float(),         # transmit epoch, seconds since J2000
  sat_pos_ecef_m:         {float(), float(), float()}  # Sagnac-transported sat position
}

The core range batch aborts on the first failing request, so a malformed request or an ephemeris error (unknown satellite, epoch out of coverage) returns {:error, reason} for the whole call. Never raises.

Options

• :light_time - apply the light-time / transmit-time correction, default true. When false, the satellite is evaluated at the receive epoch.
• :sagnac - apply the Sagnac / Earth-rotation correction, default true.