API Reference

acquire(system, signal, sampling_freq, prns; kwargs...) -> Vector{AcquisitionResults}

Perform parallel code phase search acquisition for multiple satellites.

Searches for GNSS signals by correlating the input signal with locally generated replica codes across a grid of Doppler frequencies and code phases.

Arguments

• system: GNSS system (e.g., GPSL1() from GNSSSignals.jl)
• signal: Complex baseband signal samples
• sampling_freq: Sampling frequency of the signal
• prns: PRN numbers to search (e.g., 1:32)

Keyword Arguments

• interm_freq: Intermediate frequency (default: 0.0Hz)
• max_doppler: Maximum Doppler frequency (default: 7000Hz)
• min_doppler: Minimum Doppler frequency (default: -max_doppler)
• samples_to_integrate_coherently: Number of samples per coherent integration chunk (default: ceil(Int, sampling_freq / get_data_frequency(system)), i.e. one bit period)
• doppler_step_factor: Factor for computing Doppler step from integration time (default: 1//3). The step is doppler_step_factor / T where T = samples_to_integrate_coherently / sampling_freq.
• dopplers: Custom Doppler search range (default: computed from doppler_step_factor)
• max_code_doppler_loss: Maximum acceptable correlation loss in dB from code Doppler mismatch (default: 0.5). Controls how many code replicas are pre-computed at different code Doppler offsets. Works uniformly across all GNSS systems regardless of chip rate.

Returns

Vector of AcquisitionResults, one per PRN, containing:

• carrier_doppler: Estimated Doppler frequency
• code_phase: Estimated code phase in chips
• CN0: Carrier-to-noise density ratio in dB-Hz
• power_bins: Correlation power matrix for plotting

Example

using Acquisition, GNSSSignals
results = acquire(GPSL1(), signal, 5e6Hz, 1:32)

See also

acquire!, coarse_fine_acquire, AcquisitionPlan

acquire(system, signal, sampling_freq, prn::Integer; kwargs...) -> AcquisitionResults

Perform acquisition for a single satellite PRN.

Convenience method that calls the multi-PRN version and returns a single result.

Arguments

• system: GNSS system (e.g., GPSL1())
• signal: Complex baseband signal samples
• sampling_freq: Sampling frequency of the signal
• prn: Single PRN number to search

Keyword Arguments

• interm_freq: Intermediate frequency (default: 0.0Hz)
• max_doppler: Maximum Doppler frequency (default: 7000Hz)
• min_doppler: Minimum Doppler frequency (default: -max_doppler)
• samples_to_integrate_coherently: Number of samples per coherent integration chunk (default: ceil(Int, sampling_freq / get_data_frequency(system)), i.e. one bit period)
• doppler_step_factor: Factor for computing Doppler step from integration time (default: 1//3)
• dopplers: Custom Doppler search range (default: computed from doppler_step_factor)

Returns

Single AcquisitionResults for the requested PRN.

Example

using Acquisition, GNSSSignals
result = acquire(GPSL1(), signal, 5e6Hz, 1)

See also

acquire, coarse_fine_acquire

acquire!(acq_plan, signal, prns; kwargs...) -> Vector{AcquisitionResults}

Perform acquisition using a pre-computed AcquisitionPlan.

Using a pre-computed plan avoids repeated memory allocation and FFT planning, which significantly improves performance when acquiring multiple signals.

Arguments

• acq_plan: Pre-computed AcquisitionPlan
• signal: Complex baseband signal samples
• prns: PRN numbers to search (must be subset of acq_plan.avail_prn_channels)

Keyword Arguments

• interm_freq: Intermediate frequency (default: 0.0Hz)
• doppler_offset: Offset added to Doppler search range (default: 0.0Hz)
• noise_power: Pre-computed noise power, or nothing to estimate (default: nothing)

Returns

Vector of AcquisitionResults, one per PRN.

Example

using Acquisition, GNSSSignals
plan = AcquisitionPlan(GPSL1(), 10000, 5e6Hz; prns = 1:32)
results = acquire!(plan, signal, 1:32)

See also

acquire, AcquisitionPlan

acquire!(plan::KAAcquisitionPlan, signal, prns; kwargs...) -> Vector{AcquisitionResults}

Perform GPU-accelerated acquisition using a pre-computed KAAcquisitionPlan.

Dopplers are processed in batches to limit GPU memory usage. Within each batch, downconversion, FFT, correlation and power computation run on the GPU. The per-batch findmax/sum results are accumulated on the CPU to produce the final result.

Arguments

• plan: Pre-computed KAAcquisitionPlan
• signal: Complex baseband signal samples (GPU array)
• prns: PRN numbers to search (must be subset of plan.avail_prn_channels)

Keyword Arguments

• interm_freq: Intermediate frequency (default: 0.0Hz)
• doppler_offset: Offset added to Doppler search range (default: 0.0Hz)

Returns

Vector of AcquisitionResults, one per PRN.

coarse_fine_acquire(system, signal, sampling_freq, prns; kwargs...) -> Vector{AcquisitionResults}

Perform two-stage coarse-fine acquisition for multiple satellites.

First performs a coarse search with large Doppler steps, then refines the estimate with a fine search around the detected Doppler. This approach provides high Doppler resolution while reducing computational cost compared to a single high-resolution search.

Arguments

• system: GNSS system (e.g., GPSL1())
• signal: Complex baseband signal samples
• sampling_freq: Sampling frequency of the signal
• prns: PRN numbers to search (e.g., 1:32)

Keyword Arguments

• interm_freq: Intermediate frequency (default: 0.0Hz)
• max_doppler: Maximum Doppler frequency (default: 7000Hz)
• min_doppler: Minimum Doppler frequency (default: -max_doppler)
• samples_to_integrate_coherently: Number of samples per coherent integration chunk (default: ceil(Int, sampling_freq / get_data_frequency(system)), i.e. one bit period)
• doppler_step_factor: Factor for computing coarse step from integration time (default: 1//3). The coarse step is doppler_step_factor / T where T = samples_to_integrate_coherently / sampling_freq.
• coarse_step: Doppler step for coarse search (default: computed from doppler_step_factor)
• fine_step: Doppler step for fine search (default: coarse_step / 10)
• max_code_doppler_loss: Maximum acceptable correlation loss in dB from code Doppler mismatch (default: 0.5). Controls how many code replicas are pre-computed at different code Doppler offsets. Works uniformly across all GNSS systems regardless of chip rate.

Returns

Vector of AcquisitionResults, one per PRN, with refined Doppler estimates.

Example

using Acquisition, GNSSSignals
results = coarse_fine_acquire(GPSL1(), signal, 5e6Hz, 1:32)

See also

acquire, coarse_fine_acquire!, CoarseFineAcquisitionPlan

coarse_fine_acquire(system, signal, sampling_freq, prn::Integer; kwargs...) -> AcquisitionResults

Perform two-stage coarse-fine acquisition for a single satellite PRN.

Convenience method that calls the multi-PRN version and returns a single result.

Arguments

• system: GNSS system (e.g., GPSL1())
• signal: Complex baseband signal samples
• sampling_freq: Sampling frequency of the signal
• prn: Single PRN number to search

Keyword Arguments

• interm_freq: Intermediate frequency (default: 0.0Hz)
• max_doppler: Maximum Doppler frequency (default: 7000Hz)
• min_doppler: Minimum Doppler frequency (default: -max_doppler)
• samples_to_integrate_coherently: Number of samples per coherent integration chunk (default: ceil(Int, sampling_freq / get_data_frequency(system)), i.e. one bit period)
• doppler_step_factor: Factor for computing coarse step from integration time (default: 1//3)
• coarse_step: Doppler step for coarse search (default: computed from doppler_step_factor)
• fine_step: Doppler step for fine search (default: coarse_step / 10)

Returns

Single AcquisitionResults for the requested PRN.

Example

using Acquisition, GNSSSignals
result = coarse_fine_acquire(GPSL1(), signal, 5e6Hz, 1)

See also

coarse_fine_acquire, acquire

coarse_fine_acquire!(acq_plan::CoarseFineAcquisitionPlan, signal, prns; kwargs...)

Perform two-stage coarse-fine acquisition using a pre-computed plan.

Alias for acquire!(acq_plan::CoarseFineAcquisitionPlan, ...).

Arguments

• acq_plan: Pre-computed CoarseFineAcquisitionPlan
• signal: Complex baseband signal samples
• prns: PRN numbers to search

Keyword Arguments

• interm_freq: Intermediate frequency (default: 0.0Hz)

Returns

Vector of AcquisitionResults, one per PRN.

Example

using Acquisition, GNSSSignals
plan = CoarseFineAcquisitionPlan(GPSL1(), 10000, 5e6Hz; prns = 1:32)
results = coarse_fine_acquire!(plan, signal, 1:32)

See also

coarse_fine_acquire, CoarseFineAcquisitionPlan

cfar_threshold(pfa, num_cells; num_noncoherent_integrations=1)

Compute the CFAR (Constant False Alarm Rate) detection threshold for a given probability of false alarm.

The threshold is computed so that the probability of any noise-only cell in the search grid exceeding the threshold equals pfa. This accounts for the multiple hypothesis testing across all num_cells search cells (code phases × Doppler bins) using a Bonferroni-like correction.

The test statistic is peak_power / noise_power (the peak_to_noise_ratio field of AcquisitionResults).

Arguments

• pfa: Target probability of false alarm (e.g., 0.01). Must be in (0, 1).
• num_cells: Total number of search cells (typically num_code_phases * num_doppler_bins).

Keyword Arguments

• num_noncoherent_integrations: Number of non-coherent integration dwells (default: 1). More dwells increase the degrees of freedom of the chi-squared distribution.

Returns

Threshold value to compare against result.peak_to_noise_ratio.

Example

using Acquisition, GNSSSignals

system = GPSL1()
(; signal, sampling_freq, interm_freq) = generate_test_signal(system, 1)
results = acquire(system, signal, sampling_freq, 1:32; interm_freq)
detected = filter(is_detected, results)

Mathematical Background

Under the null hypothesis (noise only), each power bin |I|² + |Q|² is χ²(2)-distributed with mean 2 (Springer Handbook of GNSS, Eq. 14.26). After M non-coherent integrations the raw power S_nc ~ χ²(2M) (Eq. 14.28). The test statistic peak_to_noise_ratio = S_nc / noise_power where noise_power ≈ 2M, so peak_to_noise_ratio ~ Gamma(M, 1/M) with mean 1 under H0.

The per-cell false alarm probability is adjusted for multiple testing: pfa_per_cell = 1 - (1 - pfa)^(1/num_cells).

The threshold is then the inverse CDF (quantile) of the chi-squared distribution at 1 - pfa_per_cell.

References

• Springer Handbook of GNSS, Section 14.3.1 "Test Statistics", Eq. 14.28–14.30
• GNSS-SDR PCPS Acquisition: pcps_acquisition::calculate_threshold()
• Kay Borre et al., "A Software-Defined GPS and Galileo Receiver", Birkhäuser, 2007

See also

AcquisitionResults, acquire

is_detected(result::AcquisitionResults; pfa=0.01) -> Bool

Return true if the satellite signal is detected at the given probability of false alarm. Compares result.peak_to_noise_ratio against cfar_threshold, using the number of search cells and non-coherent integrations stored in the result.

get_num_cells(result::AcquisitionResults) -> Int

Return the number of search cells (code phases × Doppler bins) in the acquisition result. This is the num_cells argument expected by cfar_threshold.

generate_test_signal(system, prn; kwargs...) -> NamedTuple

Generate a synthetic noisy GNSS signal. Useful for testing acquisition and demonstrating the API.

Returns a NamedTuple with fields: signal, code, carrier, num_samples, doppler, code_phase, sampling_freq, interm_freq, CN0, prn.

Keywords

• seed=2345: Random seed for reproducibility
• num_samples=60000: Number of signal samples
• doppler=1234Hz: Carrier Doppler frequency
• code_phase=110.613261: True code phase in chips
• sampling_freq=15e6Hz - 1Hz: Sampling frequency
• interm_freq=243.0Hz: Intermediate frequency
• CN0=45: Carrier-to-noise density ratio (dB-Hz)
• phase_offset=π/8: Carrier phase offset
• unit_noise_power=false: When true, scale so noise power ≈ 1; when false, scale so signal power corresponds directly to CN0

Example

using Acquisition, GNSSSignals

(; signal, prn, sampling_freq, interm_freq) = generate_test_signal(GPSL1(), 1)
result = acquire(GPSL1(), signal, sampling_freq, prn; interm_freq)
is_detected(result)  # true

AcquisitionResults{S,T}

Results from GNSS signal acquisition for a single PRN.

Fields

• system::S: GNSS system used for acquisition
• prn::Int: PRN number of the satellite
• sampling_frequency: Sampling frequency of the signal
• carrier_doppler: Estimated carrier Doppler frequency
• code_phase::Float64: Estimated code phase in chips
• CN0::Float64: Carrier-to-noise density ratio in dB-Hz
• noise_power::T: Estimated noise power
• peak_to_noise_ratio::T: Ratio of peak correlation power to estimated noise power (peak_power / noise_power). Compare against cfar_threshold to decide if a satellite is present.
• num_noncoherent_integrations::Int: Number of non-coherent integrations performed
• power_bins::Matrix{T}: Correlation power over code phase and Doppler (for plotting)
• dopplers: Doppler frequencies searched

Plotting

AcquisitionResults can be plotted directly using Plots.jl:

using Plots
plot(result)  # 3D surface plot of correlation power
plot(result, true)  # Use log scale (dB)

See also

acquire, coarse_fine_acquire

AcquisitionPlan

Pre-computed acquisition plan for efficient repeated acquisition over the same signal parameters.

Contains pre-allocated buffers and FFT plans to avoid repeated memory allocation when acquiring multiple signals with the same length and sampling frequency.

Fields

• system: GNSS system (e.g., GPSL1())
• num_samples_to_integrate_coherently: Number of samples per coherent integration chunk
• linear_fft_size: FFT size for linear correlation (2 × numsamplestointegratecoherently)
• sampling_freq: Sampling frequency
• dopplers: Range of Doppler frequencies to search
• avail_prn_channels: PRN channels available in this plan

See also

acquire!, CoarseFineAcquisitionPlan

CoarseFineAcquisitionPlan

Pre-computed acquisition plan for two-stage coarse-fine acquisition.

Performs an initial coarse search to find approximate Doppler, then refines with a fine search around that estimate. This approach is more efficient than a single high-resolution search.

Fields

• coarse_plan: AcquisitionPlan for the initial coarse search
• fine_plan: AcquisitionPlan for the refined fine search

See also

coarse_fine_acquire, AcquisitionPlan

KAAcquisitionPlan

GPU-accelerated acquisition plan using KernelAbstractions.jl for portable GPU execution.

Processes Doppler frequencies in batches to limit GPU memory usage. Downconversion phases are computed at runtime via a GPU kernel (no precomputed phase matrix).

Works with any GPU backend supported by KernelAbstractions.jl (CUDA, ROCm, Metal, oneAPI) via the AbstractFFTs interface.

See also

acquire!, AcquisitionPlan