galileo/README.md

# Galileo receiver baseband model

This repository is a modular Python reference model for a Galileo receiver
baseband and a starting point for bit-true/RTL verification. It currently
implements E1B data and E1C pilot processing with a BOC(1,1) local replica,
streaming real-IF or complex-IQ front ends, FFT PCPS acquisition, independent
tracking channels, fixed-point boundary models, and hardware sizing models.
The floating reference uses `numpy.float64`/`numpy.complex128` throughout;
single-precision formats are accepted only when explicitly reading legacy files.

The repository intentionally contains **no fabricated Galileo PRN sequences**.
`SyntheticCodeProvider` creates deterministic non-ICD codes for closed-loop
verification. These codes cannot receive a live Galileo signal. Validated
official tables can be installed under `data/` and loaded through
`FileCodeProvider` without changing acquisition or tracking APIs.

An external `globsky/SignalSim` checkout is now validated as a second code and
sample source. `SignalSimCodeProvider` parses that checkout at run time without
copying its tables. The installed commit generates combined E1B/E1C BOC(1,1)
complex IQ; both acquisition and tracking pass on its IQ8 output. See the
[measured SignalSim integration report](docs/signalsim_integration.md).

## Status and limitations

- E1 profile: 1.023 Mcps, 4092 chips, 4 ms, 1575.42 MHz.
- BOC(1,1) is implemented; CBOC and unambiguous BOC are API extension points.
- E1B bit-transition hypotheses and E1C secondary wipeoff/search are available
  for acquisition. E1C tracking supports known-phase wipeoff.
- The code-table provider, not the DSP engine, determines whether codes are
  synthetic or official.
- The floating-point model is executable. The fixed PCPS model is bit-true at
  I/O, FFT output, product, power, and accumulator boundaries; an FFT
  vendor/butterfly schedule must be selected before claiming bit identity with
  a particular RTL FFT core.
- Channel impairments include Doppler rate, sampling-clock offset, carrier
  offset, AWGN, clipping, and quantization. Multipath, jerk, oscillator phase
  noise, and interference are future channel-model plug-ins.
- Combined E1B/E1C tracking is represented by separate manager channels; a
  weighted combining policy is intentionally not assumed.

## Install and test

Python 3.11 or newer is required.

```bash
python -m pip install -e '.[test]'
python -m pytest
```

All automated tests use deterministic seeds and run headlessly. Plots import
Matplotlib only when explicitly requested.

## Configuration and CLI

YAML keys map to strict dataclasses in `galileo_rx.config`; unknown keys and
unsafe long integrations raise descriptive errors. Physical quantities carry
unit suffixes. See [configuration details](docs/configuration.md).

```bash
python -m galileo_rx.cli generate --config configs/acquisition_example.yaml --output samples.bin
python -m galileo_rx.cli acquire --config configs/acquisition_example.yaml --input samples.bin --output acquisition.json
python -m galileo_rx.cli track --config configs/tracking_example.yaml --input samples.bin --acquisition-result acquisition.json --output tracking.csv
python -m galileo_rx.cli run --config configs/acquisition_example.yaml --input samples.bin
python -m galileo_rx.cli compare-fixed --config configs/acquisition_example.yaml --input samples.bin
python -m galileo_rx.cli validate-signalsim --signalsim-path signalsim/SignalSim --config configs/signalsim_validation.yaml --output-dir reports/signalsim_validation
```

The CLI uses synthetic codes by design. Replace the provider with
`FileCodeProvider` after installing independently validated tables for live
signal work.

`validate-signalsim` is the exception: it explicitly uses the detected external
SignalSim table and IQ conventions and writes quantitative JSON/Markdown/plot
artifacts. Its quick regression is:

```bash
MPLBACKEND=Agg pytest -m signalsim -v
```

Runnable source examples are in `examples/`:

```bash
python examples/generate_e1_signal.py
python examples/run_acquisition.py
python examples/run_tracking.py
python examples/run_complete_receiver.py
```

## Architecture

The generic acquisition and tracking engines depend on `SignalProfile` and
`CodeProvider`, not E1 constants. Adding E5a/E5b therefore means defining a
profile, modulation replica, and validated code provider; engine interfaces do
not change.

```text
sample source -> streaming front end -> sample buffer -> PCPS acquisition
                                            |                 |
                                            +---- tracking manager
                                                  +-- E1B channel
                                                  +-- E1C channel

float blocks <-> fixed block boundaries <-> cycle transactions <-> RTL
```

The floating algorithms and equations are in [algorithms.md](docs/algorithms.md),
fixed-point assumptions and starting widths in
[fixed_point_plan.md](docs/fixed_point_plan.md), and the two acquisition plus two
tracking hardware options in [rtl_mapping.md](docs/rtl_mapping.md). The
module-level contract is duplicated close to the code in
`src/galileo_rx/rtl_model/architecture.md`.

Exact phase-gate test and example commands are recorded in
[development_phases.md](docs/development_phases.md).

## Phase completion record

1. Profiles, typed configuration, code providers, BOC, generator, and I/O.
2. Streaming front end, FFT PCPS, detector metrics, long integration, plots.
3. Stateful EPL/VEVL tracking, FLL/PLL/DLL, locks, C/N0.
4. Multi-channel manager and separate E1B/E1C handling.
5. Fixed formats, NCO, mixer/correlator, PCPS boundary model, comparison/sweep.
6. Cycle transaction types, scheduler/resource equations, RTL documentation.

Assumptions and unresolved implementation choices are called out in the linked
documents rather than hidden in constants.