Emitter

Emitter

The satellite-side loop: strain generation and batching, onboard queue management (live FIFO with absolute priority, archive LIFO backfill), link-gated transmission under the in-flight cap, and ground-truth gen/tx event logging. Re-entrant: a restarted emitter reconstructs its queues and counter from the run directory and event log.

pre_populate(start_sim_time, run_id; kwargs...) -> (instrument, pending_segments)

Simulates satellite downtime prior to the start of the active mission window. Fills the onboard SSD buffer with archived data batches to create a starting backlog.

Returns the InstrumentState used for generation together with any trailing segments that did not fill a complete batch. Both must be handed to run_emitter so that the data stream (in particular an external CSV consumed via ext_index) continues without restarting at the first sample.

Keyword arguments

• sample_rate: instrument sample rate [Hz].
• segment_duration_sec: content span of one segment [mission s].
• batch_size: segments per batch.
• initial_downtime_days: span of the blind spot before start_sim_time [days]; ≤ 0 skips the pre-population and returns an instrument anchored at start_sim_time.
• data_source: "synthetic" or "external".
• ext_path: path of the external CSV series (data_source = "external").
• rng: the instrument's RNG, seeded from simulation.rng_seed.
• markers: event markers, stamped into the batch holding their instant.
• generation_gaps: scheduled (start, stop) intervals without data production (skip_generation_gaps!).
• onboard_capacity_batches: recorder ceiling; data beyond it is discarded.
• confusion_observation_years, noise_f_min_hz: galactic-confusion fit and lower band edge of the synthetic noise model (VirtualInstrument.lisa_noise_psd).

skip_generation_gaps!(vi, pending, gaps, run_dir) -> Bool

Scheduled generation gap: when the instrument's next content instant lies inside one of gaps ((start, stop) intervals), the segments of the incomplete batch are discarded (as in an emitter outage, so batch geometry stays uniform), the gap is bounded in events_tx.csv — gap_start at the first discarded epoch (or the content end when nothing was pending), gap_end at the gap's end, Batch = SCHEDULED — and the instrument's content time jumps to the gap end. Gap boundaries snap to segment boundaries. Returns true when a gap was skipped.

stamp_markers!(batch_dir, batch, batch_name, run_dir, markers, content_end)

Saves batch (TelemetryCore.save_batch) with the labels of the event markers whose instant lies in its content span, and appends one marker row per hit to events_tx.csv (SimTime = the marker instant, Batch = the containing batch) so live consumers learn which batch holds the event the moment it becomes transmittable.

run_emitter(clock, link, run_id; kwargs...)

The main satellite payload loop. Continuously generates scientific data (or reads from external CSV), packages it into batches, and manages the DSN transmission queue using strict priority logic (Live FIFO > Archive LIFO).

link is the composite ChannelEffects.LinkModel (visibility × disruption timeline): batches are stamped LIVE_ and transmitted only while the link is transmittable — during a disruption blackout the satellite keeps generating ARCH_ batches that accumulate onboard.

Pass the instrument and pending_segments returned by pre_populate to continue the pre-populated data stream without gaps or duplication; when instrument === nothing a fresh InstrumentState starting at the current mission time is created instead (seeded by rng).

Generation is paced by the mission clock, not by the loop's own start: a segment is produced once the mission clock has passed the end of its content interval (vi.last_t + segment_duration_sec), and the loop sleeps until the exact wall instant of the next due segment (TelemetryCore.due_wall_time). A late start or a stall is recovered by generating back-to-back (yielding to the partner task on every catch-up iteration) until the content has caught up with the clock, so the content epoch of the stream tracks mission time within one segment period. Each sleep is capped at TelemetryCore.EMITTER_MAX_SLEEP_SEC so the heartbeat and the stop/deadline checks stay responsive at low speed_up. A content lag that persists above one period for longer than TelemetryCore.EMITTER_LAG_WARN_SEC is reported once as a warning (the host cannot keep pace); the maximum lag is logged at loop exit.

Keyword arguments

• sample_rate: instrument sample rate [Hz].
• segment_duration_sec: content span of one segment [mission s].
• batch_size: segments per batch.
• data_source: "synthetic" or "external".
• ext_path: path of the external CSV series (data_source = "external").
• instrument: the InstrumentState returned by pre_populate, or nothing for a fresh instrument anchored at the current mission time.
• pending_segments: the partial batch returned by pre_populate.
• rng: RNG of a freshly created instrument (ignored when instrument is given).
• deadline: absolute wall-clock stop shared by both components.
• stop: cooperative stop flag raised by the supervisor.
• heartbeat_path: liveness file touched every TelemetryCore.HEARTBEAT_INTERVAL_MS when set; removed on exit.
• max_inflight_batches: cap on batches simultaneously on the link.
• markers: event markers, stamped into the batch holding their instant.
• generation_gaps: scheduled (start, stop) intervals without data production (skip_generation_gaps!).
• onboard_capacity_batches: recorder ceiling; new data is discarded while the buffer holds that many batches.
• confusion_observation_years, noise_f_min_hz: galactic-confusion fit and lower band edge of the synthetic noise model of a freshly created instrument (VirtualInstrument.lisa_noise_psd).