qmb-mvp (0.1.6)
Installation
pip install --index-url /api/packages/qoherent/pypi/simple/ --no-deps qmb-mvpAbout this package
Add your description here
qmb-mvp
qmb-mvp is a command-line toolkit for building and training machine-learning models on radio-frequency datasets. It packages reusable data loaders, preprocessing transforms, and training loops so you can prototype, benchmark, and productionize modulation-classification workloads with a consistent workflow.
Overview
- Hydra-driven configuration system for experiments and reproducibility.
- Modular dataset, transform, and model components designed for rapid iteration.
- CLI entry points (e.g.,
qmb train) that wrap common pipelines and keep logs, checkpoints, and metrics organized.
Prerequisites
- Python 3.13 (the project is validated against this interpreter version).
- Experimental variant-enabled uv 0.9.3 or newer for environment and dependency management (see installation).
- Standard build tooling (e.g.,
build-essentialon Debian/Ubuntu or Xcode Command Line Tools on macOS) for packages with native extensions.
Installation
Linux/macOS (bash/zsh)
curl -LsSf https://astral.sh/uv/install.sh | INSTALLER_DOWNLOAD_URL=https://wheelnext.astral.sh/v0.0.2 sh
uv venv --python 3.13
uv pip install torch torchvision
uv sync --inexact # Leave the PyTorch wheel in place
To force a CPU-only install use:
UV_TORCH_BACKEND=cpu uv pip install torch torchvision
Windows (PowerShell)
powershell -c { $env:INSTALLER_DOWNLOAD_URL = 'https://wheelnext.astral.sh/v0.0.2'; irm https://astral.sh/uv/install.ps1 | iex }
uv venv --python 3.13
uv pip install torch torchvision
uv sync --inexact # Leave the PyTorch wheel in place
To force a CPU-only install use:
UV_TORCH_BACKEND=cpu uv pip install --reinstall torch torchvision
Currently untested whether this workflow succeeds for ROCm and XPU backends.
Quickstart
Once the environment is synced, activate the virtualenv and explore the CLI:
source .venv/bin/activate
qmb --help
qmb train trainer.epochs=1
qmb hpo study.n_trials=5
qmb eval <path_to_checkpoint>
qmb export <path_to_checkpoint> # Export to ONNX (uses onnx_export config)
The qmb binary is added to the virtual environment during uv sync, so every CLI invocation implicitly uses the project's dependencies.
Project Layout
qmb-mvp/
|-- src/
| `-- qmb/
| |-- cli/ Console entry points (`qmb train`, `qmb hpo`) and Hydra launch glue
| |-- configs/ Default Hydra config tree (root `config.yaml` plus dataset/model/evaluation/search_space)
| |-- datasets/ Dataset loaders such as `H5Dataset` (legacy) and `StructuredH5Dataset`
| |-- transforms/ Composable preprocessing transforms instantiated from config
| |-- models/ Model definitions and the configurable `model_factory`
| `-- training/ Training orchestration (`Trainer`, `DataModule`, `TrainerSettings`, device/AMP utilities)
`-- outputs/ Run artifacts written by `qmb train` (timestamped runs, checkpoints, logs, reports)
## ONNX Export
- Config: `onnx_export` group (`src/qmb/configs/onnx_export/onnx.yaml`) controls opset, batch/width dynamics, onnxsim toggle, and strictness. It is enabled by default; override via Hydra or CLI overrides if needed.
- Training/HPO: when `onnx_export.enabled=true`, `qmb train` exports the best model at the end of the run into the Hydra run directory as a single ONNX file (simplified when onnxsim succeeds, otherwise the raw export).
- Standalone: `qmb export <checkpoint>` (or `uv run qmb export <checkpoint>`) loads the checkpoint + dataset config to infer shapes and emits one ONNX artifact. Use `--enable` to force export if the saved config had it disabled, and `--disable-onnxsim` to skip simplification.
- Dynamo exporter: `onnx_export.use_dynamo=true` by default and used when opset ≥ 18; it auto-disables for opset 17 or lower or falls back to eager export if unsupported.
Configuring Runs
The training pipeline is controlled by Hydra. Default configuration lives under src/qmb/configs, with qmb train loading config.yaml from that directory.
- Override individual settings inline:
qmb train trainer.dataset=c2_ota trainer.epochs=5. - Point to a different config directory if you maintain your own experiment suite:
qmb train --config-dir path/to/configs trainer.dataset=custom_radio. - Inspect the active configuration by adding
--cfg job --resolveto print the merged, fully-resolved Hydra config before training starts.
Keep dataset files and workspace paths in sync with the values defined in the configuration to avoid runtime path issues.
Testing
Unit tests run with pytest and are managed through uv dependency groups.
uv sync --group dev
uv run --group dev pytest
The first command installs the development tooling (including pytest). The second executes the suite inside the same resolved environment so the project and dev dependencies stay aligned.