Initial Galileo receiver and SignalSim integration

README.md

@@ -0,0 +1,126 @@
+# 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.