spectraMR

NOT FOR CLINICAL USE. Research software only. See DISCLAIMER.md.

spectraMR is a research framework for MRI reconstruction, super-resolution, quantitative mapping, and generative modelling. It registers 153 training strategies (selectable through 206 training_mode spellings), 586 model architectures, 217 losses, and a single-source-of-truth MRI physics layer (centered FFT, Cartesian / VD / radial / NUFFT sampling masks, ESPIRiT and SIREN-PINN coil maps, hard / soft data consistency, Bloch / motion / B0 / B1⁻ simulation).

These are registration counts, measured on the shipped package rather than estimated, under pip install spectramr[mri] -- the install the quick start prescribes. They are a property of the installed extras, not of the distribution: a bare pip install spectramr registers 175 models rather than 586, because a model whose module fails to import is not registered at all (loudly -- discovery names the module and the missing package). See Installation.

Every registered model, loss, metric and transform is reachable from a cold import — 586 / 217 / 211 / 10, cold-probe equal to walk, verified by scripts/maintenance/prove_reachable.py --audit; the 206 strategy paths are a static dict and all 206 resolve. That is a reachability claim, not a validation one: it says a config can select the component, not that the component is benchmarked. Per-regime maturity is graded LIVE / PARTIAL / EVAL_ONLY / STUB by the Maturity ledger, and docs/known_limitations.rst records what is known not to work. Re-measure rather than quoting these; they move week to week.

Quick start

pip install spectramr[mri]

A single forward pass through a small U-Net via the registry:

import torch
from spectramr.models.init_registry import populate_model_registry
from spectramr.models.registry import MODEL_REGISTRY

# Required. The registry is EMPTY on a plain import -- a model is registered
# only once the module holding its decorator has been imported, and this call
# is what curates those imports. Without it MODEL_REGISTRY.get() returns None
# and the next line raises TypeError.
populate_model_registry()

entry = MODEL_REGISTRY.get("toeplitz_attention_unet")
model = entry["class"](in_channels=2, out_channels=2)
y = model(torch.randn(1, 2, 64, 64))    # -> torch.Size([1, 2, 64, 64])

Counting for yourself:

from spectramr.infrastructure.training.strategy_factory import TrainingStrategyFactory
from spectramr.models.init_registry import populate_model_registry
from spectramr.models.registry import MODEL_REGISTRY
from spectramr.models.losses.registry import LossRegistry
from spectramr.core.metrics.registry import MetricsRegistry

populate_model_registry()
paths = TrainingStrategyFactory.STRATEGY_CLASS_PATHS   # a CLASS attribute
len(MODEL_REGISTRY), len(LossRegistry.list_available()), \
    len(MetricsRegistry.list_available()), len(set(paths.values())), len(paths)

The same model from a YAML:

# an excerpt of experiments/templates/comprehensive_config_template.yaml
config_version: '1.0'
model:
  model_type: toeplitz_attention_unet
  in_channels: 2
  out_channels: 2
training:
  training_mode: reconstruction
  strategy_class: spectramr.infrastructure.training.strategies.reconstruction.ReconstructionTrainingStrategy

config_version: '1.0' is the only accepted value; anything else is refused at load, with the accepted set named in the error.

The excerpt above is a fragment, not a runnable config. The complete template ships and passes the audit as-is:

spectramr audit experiments/templates/comprehensive_config_template.yaml
spectramr train --config experiments/templates/comprehensive_config_template.yaml

audit runs Tier 0 (schema) and Tier 1 (health checks); add --probe for a Tier 2 synthetic forward pass. It exits 0 on a pass, 1 on warnings, 2 on errors -- and it is --strict by default, so a warning is not a pass.

Installation

Optional dependencies come in two kinds. Feature groups gate a capability (absent, it raises at construction — never a silent fallback); role groups gate a workflow and are imported by nothing under src/.

pip install spectramr                 # core only
pip install spectramr[mri]            # TorchIO, MONAI, nibabel, torchkbnufft, pydicom
pip install spectramr[diffusion]      # diffusers — pretrained SD-VAE backbone
pip install spectramr[viz]            # matplotlib, tensorboard, seaborn, plotly
pip install spectramr[hpo]            # Optuna
pip install spectramr[all]            # EVERYTHING that installs in one shot
pip install spectramr[dev]            # all + the config-migration toolchain

The role groups are installable on their own, which is what CI lanes do: [test] (pytest + plugins), [qa] (ruff, mypy, pre-commit, pip-audit, codespell, detect-secrets), [docs] (Sphinx) and [profile] (Scalene, GPUtil, nvtx). [all] contains all four, so it is a superset of whatever any lane installs, and [dev] is [all] plus tooling nothing else needs.

Three groups are not in [all], each because it physically cannot install in a single resolve — not as a matter of curation, and each verified by an actual build rather than assumed: mamba compiles the CUDA selective-scan kernel; attention fails because flash-attn omits torch from its build requirements; radiomics has no cp312 wheel and its C extension fails to compile. (bnb and deepspeed were long excluded on the assumption that they need a CUDA toolchain — both build clean under isolation, so they are in.) On a node with nvcc:

pip install -e '.[all]'
pip install -e '.[mamba]' --no-build-isolation

[mri] is the practical floor, not a convenience. The core install is a genuine subset and it is a small one: it registers 175 of the 586 models, and spectramr.infrastructure.training cannot be imported at all, because the dataset layer imports TorchIO unconditionally. spectramr --help, spectramr --version and the loss registry (217, unaffected) still work. Install [mri] unless you are deliberately vendoring a subset.

Three extras sit deliberately outside [all], because each pulls a heavy or platform-specific build:

pip install spectramr[bnb]          # bitsandbytes
pip install spectramr[deepspeed]    # deepspeed
pip install -e '.[mamba]' --no-build-isolation   # mamba-ssm, causal-conv1d

[mamba] compiles a CUDA selective-scan kernel, needs nvcc, and must be installed after torch is present. Without it, Mamba/SSM models fail loudly rather than degrading silently.

A few registered components need a package that no extra installs -- see docs/known_limitations.rst.

What pip actually resolves

The pytorch-cu126 index pin in pyproject.toml lives under [tool.uv.sources] and [[tool.uv.index]]. Neither reaches wheel metadata -- the published requirement is a bare torch>=2.11 -- so installing from PyPI does not give you the pinned build. Measured on a fresh venv from the published wheel:

So CUDA-enabled PyTorch is not installed separately: you get it by default, at a CUDA version this project does not pin. Pin it yourself if that matters, by installing torch first from the index you want -- afterwards costs a multi-gigabyte reinstall:

# CUDA 12.6 -- what this project pins, and the only wheel lane that still ships
# sm_70 for Volta / V100 (compute capability 7.0) GPUs. `uv.lock` resolves
# torch 2.13.0+cu126 / torchvision 0.28.0+cu126 from this index.
pip install torch --index-url https://download.pytorch.org/whl/cu126

For a CPU-only or air-gapped machine, substitute the cpu index. The CI runs against the CPU wheel; downstream GPU work is your responsibility.

What's in the box

Maturity by regime

A regime is the physical acquisition setting an experiment declares (workflow.regime). Each is graded against the live registries by spectramr.config.schemas.enums.Maturity, and the grades are enforced by tests/unit/domain/workflows/test_maturity_ledger.py -- they are read off the code, not maintained by hand.

The five STUB regimes are declared so the vocabulary is closed and a typo raises instead of silently meaning nothing. They are not implemented, and spectraMR does not claim to be a CT, X-ray, ultrasound or optical framework.

The ledger grades regimes, not individual models. No per-model guarantee is made or implied.

Citing

If you use spectraMR in your research, please cite the software:

@software{gdihi2026spectramr,
  author    = {Gdihi, Adnane},
  title     = {spectraMR: A Multi-Paradigm Research Framework for MRI Reconstruction, Super-Resolution, and Generative Modelling},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.22291316},
  url       = {https://github.com/adnaneGdihi/spectramr},
  version   = {0.1.0}
}

GitHub renders a "Cite this repository" button from CITATION.cff that produces this BibTeX automatically. Citation tools that consume CFF 1.2.0 will pick the version up directly.

Documentation

Full documentation is hosted at https://spectramr.readthedocs.io and follows the Diátaxis quadrants:

• Tutorials — guided walk-throughs from pip install to a first reconstruction.
• How-to guides — add a paradigm, add a model, add a loss, write an experiment YAML.
• Reference — auto-generated API documentation plus the YAML-schema reference and registry catalogues.
• Explanation — clean-architecture layering, the audit ladder, the physics SSOT discipline.

Contributing

See CONTRIBUTING.md. The short version:

1. Fork, branch off main, implement.
2. pre-commit install and let it run on every commit.
3. pytest -m "not gpu" must pass. If you touched a YAML config, run spectramr audit <path> on it -- the audit is --strict by default, so a warning is a failure.
4. PR title uses a Conventional Commits prefix; commits use git commit -s (DCO sign-off).
5. CI runs a single required aggregator over: changed-line lint, repository guards, architecture fitness functions, a collection pass over the unit suite, a physics check, a config-schema audit, and a security scan. The collection pass imports every unit-test module without executing the tests, so a green lane is not "the unit suite passed" -- run pytest locally.

By participating you agree to the Contributor Covenant 2.1.

Licence

Apache License 2.0. See NOTICE for attribution of upstream dependencies.

Disclaimer

spectraMR is NOT FOR CLINICAL USE. It is research software and has not been evaluated by any regulatory authority. See DISCLAIMER.md.