@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 emission_media_batch_detailed(
  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, detailed_emission_media_batch()} | {:error, term()}

Like emission_media_batch/4, with typed cause maps for each failed row in element_errors. The legacy API keeps its existing error representation.

@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_batch_detailed(
  Sidereon.GNSS.SP3.t(),
  [{String.t(), vec3() | map(), NaiveDateTime.t()}],
  keyword()
) :: [ok: observables(), error: prediction_error()]

Predict a request batch with one structured result per original request.

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

Predict observables and retain the structured cause of native prediction errors.

The result uses the same success map as predict/5; failures from the core include the observable field and validation category or a nested core error detail map. The existing predict/5 return values are unchanged.

@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.

@spec pseudorange_transmit_geometry(
  Sidereon.GNSS.SP3.t()
  | Sidereon.GNSS.Broadcast.t()
  | Sidereon.GNSS.PreciseEphemeris.t()
  | Sidereon.GNSS.PreciseEphemeris.Interpolant.t()
  | Sidereon.GNSS.PreciseEphemeris.InterpolantArtifact.t(),
  String.t(),
  Sidereon.GNSS.Core.Types.ecef_input(),
  NaiveDateTime.t(),
  number(),
  keyword()
) :: {:ok, pseudorange_geometry()} | {:error, term()}

The transmit-time geometry of satellite_id's pseudorange pseudorange_m, time-tagged epoch by a receiver at receiver_ecef, placed as SPP, the static solve, DGNSS and PPP place it (RTKLIB satposs).

The transmission epoch is t_rx - P / c less the satellite clock read there, from the record selected at the reception epoch, so the receiver clock offset the pseudorange carries places the satellite where the signal left it. The geometry is the source's state at that epoch, not rotated: the range is |r_s - r_r| plus the Sagnac term ω (x_s y_r - y_s x_r) / c (RTKLIB geodist), and the line of sight, elevation and azimuth are those of the unrotated vector. signal_flight_time_s is t_rx - t_tx, which holds both clock offsets with the flight time.

epoch is the receiver's time tag, a NaiveDateTime in the source's time scale, converted to seconds since J2000 as the positioning solves convert it. sat_clock_relativity_s and single_frequency_group_delay_s are the terms a single-frequency model applies to sat_clock_s at the transmission epoch, as in predict/5.

source is an SP3 product, a broadcast store, a precise-sample source or a precise interpolant. pseudorange_m has to be a positive finite distance.

Options

• :sagnac - add the Sagnac term, default true.