GenSig

RF signal generation application (Python port of the MATLAB GenSig app). See doc/spec.md for the application specification (v1.1) and doc/sigv3.md for the SigV3.1 output format.

Status: the full v1 generation chain is live — project model + JSON persistence, validation engine, global settings, the main-window UI (panels, model binding, dynamic enable/disable rules, frequency-bands table, load/save/new/close), and the headless generate chain (generate() → post-processing → SigV3.1 write → spectrum preview) for five waveforms (AGWN, Frequency Comb, Frequency Comb IQ, Up Chirp; Multi IQ / Other IQ still show the not-implemented notice). Remaining: the Multi IQ / Other IQ generators, memory/performance hardening and the later post-processing rounds.

Requirements

• Python ≥ 3.10 (3.12 recommended)

• NumPy, SciPy, Matplotlib

• Tkinter (bundled with the standard Windows and macOS Python installers; on Debian/Ubuntu it is a system package, not a pip package):

  sudo apt install python3-tk
  

Setup

The project is a standard Python package — it works with either uv or plain pip.

With uv (recommended)

uv venv
uv pip install -e ".[dev]"

With pip only (no uv) — e.g. a Windows machine

:: 1) create and activate a virtual environment (optional but recommended)
python -m venv .venv
.venv\Scripts\activate

:: 2) install the app + its dependencies
pip install -e ".[dev]"

:: 3) run it
python -m gensig.app

No setuptools/wheel install step is needed — modern pip (≥ 21.3) builds editable installs automatically. On the Windows installer build of Python, Tkinter is included out of the box, so nothing extra is required.

The [dev] extra (pytest, ruff, mypy, hypothesis, pytest-cov) is optional — for running the app only: pip install -e .

Run

uv run gensig          # or: python -m gensig.app        (opens the window)

Without a display or Tkinter, gensig exits with code 2 and an explanatory message instead of a traceback.

Test

uv run pytest
uv run ruff check gensig tests && uv run ruff format --check gensig tests
uv run mypy gensig

pytest runs the suite with coverage (gate: 85%). The GUI entry and the placeholder areas (signal processing, IQ I/O, settings, UI panels) are excluded from the coverage gate until their tickets land.

Build binaries (GitHub Actions)

.github/workflows/build.yml builds a one-file executable for Linux and Windows with PyInstaller. It runs on push to main/master or manual dispatch, and on v* tags additionally publishes a GitHub release with both binaries. Tkinter is supplied by the system python3-tk package on the Linux runner and by the setup-python build on Windows.

Local (Linux/macOS) equivalent:

pip install pyinstaller
pyinstaller --noconfirm --clean --onefile --windowed --name gensig --collect-all gensig gensig/app.py

Layout

gensig/
├── app.py            # GUI entry point (window shell in this round)
├── core/
│   ├── model.py      # ProjectData + Band (single source of state)
│   ├── validation.py # spec §7 limits/derived checks
│   ├── units.py      # UI-unit ↔ core-unit converters
│   ├── constants.py  # memory budget & limits
│   └── io/           # project JSON persistence (sig I/O later)
└── ui/               # panels arrive in later tickets