Track

track(measurements, track_state; kwargs...)

Track one or more BandMeasurements: downconvert, correlate and estimate the Dopplers of every satellite, and return the updated TrackState with new phase/Doppler estimates and decoded bits.

The first argument is one of:

The bare buffer takes sampling_frequency as the next positional argument and an intermediate_frequency keyword (default 0). Every form runs the same per-chunk loop: downconvert and correlate all groups, then estimate.

The returned TrackState is structurally detached from the input: each group's key set and slot vector are copied, so adding, removing or tracking satellites on one never affects the other. The copy is shallow, though, and these are shared with the input (treat it as a stale handle, or deepcopy it first):

• the per-satellite scratch vectors (filtered_prompts, correlator_outputs, the soft bits, the C/N₀ estimator's buffer), overwritten by the next call on either state; a bare downconvert_and_correlate likewise appends to the input's correlator_outputs;
• each signal's noise estimator, which track advances in place: branched states divide by one noise reference, and advancing two concurrently races, so build one TrackState per thread (see downconvert_and_correlate for why the window is not copied);
• the doppler_estimator itself, so results can be read off the instance you passed in. One with state of its own (TrackingLoops' VectorPLLAndDLL) is advanced by track as by track!, and two branches would mix their records in one navigation filter.

For real-time loops, construct the correlator once outside the loop:

dc = CPUThreadedDownconvertAndCorrelator()
while got_chunk(rx)
    chunk = read_chunk!(rx)
    track_state =
        track(chunk, track_state, sampling_frequency; downconvert_and_correlator = dc)
end

The default builds fresh per-thread scratch buffers on every call. See track! for the in-place variant.

The coherent-integration length is set per signal with set_preferred_num_code_blocks_to_integrate!, not passed to track:

set_preferred_num_code_blocks_to_integrate!(track_state, :gps_l5, 1, GPSL5I, 10)  # PRN 1 L5I: 10 ms

The conventional estimator caps the carrier loop bandwidth at 0.09 / T_int and the code loop's at 0.018 / T_int, so longer integration stays stable (see ConventionalPLLAndDLL).

track!(
    measurements,
    track_state;
    downconvert_and_correlator,
    doppler_update_interval
)

In-place version of track: overwrites the satellite slots of track_state and returns it.

After one warmup call the single-threaded path is allocation-free. The threaded path (CPUThreadedDownconvertAndCorrelator) keeps a residual of about 96 B per group per correlate pass (one per doppler_update_interval chunk, so it scales with the buffer length), when running on more than one thread with more than one work item in the group (the noise despreads count, riding the first group); see CPUThreadedDownconvertAndCorrelator for why.

For real-time loops, construct the correlator once outside the loop:

track_state = TrackState(signal, initial_sats)
dc = CPUThreadedDownconvertAndCorrelator()      # hoist!

while got_chunk(rx)
    chunk = read_chunk!(rx)
    track!(chunk, track_state, sampling_frequency; downconvert_and_correlator = dc)
end

Its per-thread scratch buffers grow on first use; the default would regrow them every call.

set_preferred_num_code_blocks_to_integrate!(
    track_state,
    group,
    sat_id,
    sig,
    num_code_blocks
)

Set the preferred coherent-integration length, in primary code blocks, of one signal on one satellite (the addressed TrackedSignal's preferred_num_code_blocks_to_integrate). The actual length is capped by the bit/secondary-code period and held at 1 until sync (see calc_num_code_blocks_to_integrate); the conventional estimator caps its loop bandwidths against the integration time, so the loop stays stable.

For data-bearing signals the length must divide the code blocks per bit (20 for GPS L1 C/A, 10 for GPS L5I), or an ArgumentError is thrown (#128). Pilots accept any length of at least one block.

Addressed like the per-signal accessors; the per-signal form names the group even on a single-group TrackState:

set_preferred_num_code_blocks_to_integrate!(ts, :gps_l5, 1, GPSL5I, 10)  # (group, prn, signal)
set_preferred_num_code_blocks_to_integrate!(ts, :gps_l5, 1, 10)          # single-signal sat
set_preferred_num_code_blocks_to_integrate!(ts, 1, 10)                   # single-group state
set_preferred_num_code_blocks_to_integrate!(ts, 10)                      # 1 group, 1 sat, 1 signal

Mutates track_state in place and returns it.

One band's sample buffer with the sampling_frequency and intermediate_frequency it was captured at.

Fields:

• samples::S: complex sample buffer (Vector for one antenna, Matrix with rows = samples and columns = antennas for an antenna array). Must be dense (unit row stride, columns packed back-to-back), as the SIMD kernels read it through raw pointers; anything else is an ArgumentError. Contiguous views (e.g. view(buf, 1:4000)) are fine.
• sampling_frequency::F: the buffer's sample rate (e.g. 4e6Hz)
• intermediate_frequency::F: the band's IF (defaults to 0.0Hz)

A multi-band track takes a NamedTuple of them keyed by band; a single band may also pass a plain buffer and sample rate.

BandMeasurement(buf, 4e6Hz)                              # IF defaults to 0.0Hz
BandMeasurement(buf, 4e6Hz, 1.575e6Hz)                   # explicit IF
BandMeasurement(buf; sampling_frequency = 4e6Hz)         # kwarg form

A NamedTuple of BandMeasurements, the multi-band input of track / track!, keyed by GNSSSignals.get_band_id (e.g. :L1, :L5), a compile-time constant.

CPU-based implementation of downconversion and correlation. Its scratch buffers grow lazily on first use and are reused thereafter, so a hoisted instance is allocation-free per track! call in steady state.

For real-time loops, construct the correlator once outside the track! loop and pass it via the downconvert_and_correlator keyword argument; the default value rebuilds the buffers on every call.

Multi-threaded CPU downconvert and correlate, parallelized over the satellites (PRNs) of each group. Holds one set of scratch buffers per thread, indexed by Threads.threadid() inside @batch (which pins each iteration to a thread), grown lazily and reused thereafter.

With more than one thread and more than one work item, each @batch launch (one per downconvert_and_correlate! call, so one per code block inside track!) keeps a Polyester allocation of ~96 B. It is bounded per launch and does not scale with the input buffer. Measuring a noise density keeps it at ~96 B (the noise despreads ride the loop as extra items behind one pointer, see _park_noise_items!), but a single-satellite state then pays it too, as its loop has two items; in exchange the despread usually costs a fraction of its ~1.75 µs serial time.

Polyester copies everything the @batch region references into one argument tuple per launch. A tuple of only isbits members (bare Arrays qualify, as PtrArrays) is elided; otherwise it is heap-allocated at its sizeof, with immutable structs copied by value and mutable objects as one pointer. The non-isbits member here is the GNSS signal (GPSL1CA wraps a Matrix{Int16} and a non-isbits SignalLUT), which code-replica generation needs. A prototype that generates from the LUT's bare arrays passed as separate arguments measures 0 B/launch at full throughput, but needs a GNSSSignals API that does not re-wrap them in a struct; a serial code-gen pre-pass also reaches 0 but serializes ~30 % of the work. Neither is worth ~96 B per launch.

For real-time loops, construct the correlator once outside the track! loop and pass it via the downconvert_and_correlator keyword argument; the default value rebuilds the per-thread buffers on every call.

Integer (Complex{Int16}) hybrid-blocked CPU downconvert + correlate backend (single-threaded). Opt-in alternative to [CPUDownconvertAndCorrelator] for Complex{Int16} sample buffers; errors on any other sample element type. Construct it once outside the track! loop and pass it via the downconvert_and_correlator keyword: allocation-free in steady state for SVector sample shifts (EPL/VEPL); runtime AbstractVector shifts allocate only the returned Vector.

Arguments

max_meas (required, no default) is the largest |real|/|imag| any sample will take, i.e. the front end's full-scale (e.g. 2^11 for a 12-bit ADC). The carrier amplitude is the largest with 2·max_meas·amplitude ≤ typemax(Int16), since the complex wipe DI = mᵣ·cos + mᵢ·sin sums two products. Under-declaring max_meas silently overflows the Int16 wipe and corrupts the correlation; over-declaring is safe and only coarsens the carrier quantisation.

blk is the strip-mine block length in samples. It must be ≥ 1 (blk ≤ 0 would hang track!, #169); a larger-than-safe blk is clamped so the accumulators never wrap.

Multi-threaded Int16DownconvertAndCorrelator: one Int16ScratchBuffers per thread, the immutable carrier table shared.

One-bit (hard-limited) bit-wise CPU downconvert + correlate backend (single-threaded). Opt-in alternative to [CPUDownconvertAndCorrelator] for Complex{Int16} sample buffers: it 1-bit-quantises measurement, carrier and code and correlates with XOR + popcount, trading ≈2–3 dB of SNR for bit-wise speed. Construct it once outside the track! loop and pass it via the downconvert_and_correlator keyword for an allocation-free steady state.

Multi-threaded OneBitDownconvertAndCorrelator, one OneBitScratchBuffers per thread.

Two-bit (sign + magnitude) bit-wise CPU downconvert + correlate backend (single-threaded). Opt-in alternative to [CPUDownconvertAndCorrelator] for Complex{Int16} sample buffers, between OneBitDownconvertAndCorrelator and Int16DownconvertAndCorrelator: measurement and carrier are 4-level {±1, ±3}, the code 1-bit, correlated with XOR + masked popcount. Recovers ≈2 dB of correlation SNR over the one-bit backend (≈0.8 dB total quantisation loss vs Float32) at bit-wise speed. Construct it once outside the track! loop and pass it via the downconvert_and_correlator keyword for an allocation-free steady state.

threshold is the measurement magnitude split in ADC counts (|component| ≥ threshold ⇒ ±3); near 1σ of the front end's input is the near-optimal 4-level quantiser.

Multi-threaded TwoBitDownconvertAndCorrelator, one TwoBitScratchBuffers per thread.

Supertype of the downconvert-and-correlate backends.

The downconvert_and_correlate(!) loops are defined once on this type (see downconvert_and_correlate_cpu.jl); a subtype implements the hooks: _despread_one_signal! (the correlation primitive, for satellites and the noise reference alike; alone it gives a working single-signal backend), _correlate_signals / _scratch_buffers (multi-signal kernel and scratch), _threading (default serial) and _check_sample_type (default no-op).