ulfsynth 0.1.3__tar.gz

ulfsynth-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toufiq Musah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ulfsynth-0.1.3/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include setup.py
+recursive-include ulfsynth *.py
+recursive-include ulfsynth/_nnunet_src *
+recursive-include assets *
+prune ulfsynth/_nnunet_src/nnunetv2.egg-info
+prune ulfsynth/_nnunet_src/notebooks
+prune ulfsynth/_nnunet_src/documentation

ulfsynth-0.1.3/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: ulfsynth
+Version: 0.1.3
+Summary: Physics-Guided Ultra-Low-Field MRI Enhancement & Simulation
+Author: Toufiq Musah
+License: MIT License
+        
+        Copyright (c) 2026 Toufiq Musah
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: homepage, https://github.com/toufiqmusah/ULF-Synth
+Project-URL: repository, https://github.com/toufiqmusah/ULF-Synth
+Project-URL: documentation, https://github.com/toufiqmusah/ULF-Synth#readme
+Project-URL: Bug Tracker, https://github.com/toufiqmusah/ULF-Synth/issues
+Keywords: mri,ultra-low-field,ulf,medical-image-enhancement,image-synthesis,deep-learning,neuroimaging,nnunet,image-translation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: nibabel>=3.2.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: torch>=2.1.0
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+<p align="center">
+  <img src="assets/method.png" alt="ULF-Synth" width="100%">
+</p>
+
+<h1 align="center">ULF-Synth: Physics-Guided Ultra-Low-Field MRI Enhancement for Pediatric Neuroimaging</h1>
+
+<p align="center">
+  <a href="https://arxiv.org/abs/2605.24625v1"><img src="https://img.shields.io/badge/arXiv-2605.24625-b31b1b.svg" alt="arXiv"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python"></a>
+</p>
+
+## Abstract
+
+Ultra-low-field (ULF) MRI enables portable and accessible neuroimaging, but suffers from low signal-to-noise ratio and limited spatial resolution relative to high-field (HF) systems. Acquiring paired ULF–HF data for supervised enhancement is often infeasible, particularly in resource-limited settings. We introduce **ULF-Synth**, a framework combining: (i) acquisition-based synthesis of realistic ULF images from HF volumes for large-scale paired training, and (ii) a spatial-frequency domain objective that prioritizes recovery of high-frequency anatomical detail. The formulation is architecture-agnostic, consistently improving structural similarity and perceptual fidelity across encoder-decoder, adversarial, and diffusion-based translation models. Trained exclusively on synthetic data, our models generalize to real 64 mT ULF acquisitions, improving multiclass brain segmentation and achieving higher radiologist preference and diagnostic acceptability in a blinded reader study.
+
+---
+
+## Simulation Pipeline
+
+The ULF synthesis module models the key physical phenomena distinguishing ULF from HF acquisitions:
+
+|  | Effect | Implementation |
+|:---:|---|---|
+| 1 | **Signal scaling** | $(B_{{ULF}}/B_{{HF}})^2$ polarization ratio |
+| 2 | **T2\* decay & B0 inhomogeneity** | Spatially-varying exponential decay from random B0 field maps |
+| 3 | **Thermal noise** | Gaussian noise scaled to SNR 15–50 |
+| 4 | **k-space cropping** | Reduced resolution (45–55%) |
+| 5 | **k-space undersampling** | Accelerated acquisition (2×–3×) with center-out sampling |
+| 6 | **B0 off-resonance distortion** | Phase distortion from random B0 field maps |
+
+---
+
+## Qualitative Results
+
+<p align="center">
+  <img src="assets/results.png" alt="Sample results" width="95%">
+</p>
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/toufiqmusah/ULF-Synth.git
+cd ULF-Synth
+pip install -e .
+```
+
+This installs `ulfsynth` and all core dependencies (including PyTorch).
+The bundled [nnUNet translation fork](src/nn-translation/) is automatically
+discovered and installed during setup — no extra steps needed.
+
+### Install from PyPI (future)
+
+```bash
+pip install ulfsynth          # simulation only
+pip install ulfsynth[full]    # with enhancement support
+```
+
+---
+
+## CLI
+
+The `ulfsynth` package provides three commands:
+
+### `ulfsynth simulate` — ULF synthesis from HF volumes
+
+```bash
+# Single volume
+ulfsynth simulate input.nii.gz output.nii.gz
+
+# Folder of NIfTI files
+ulfsynth simulate /path/to/hf/scans/ /path/to/ulf/scans/
+
+# Reproducible seed
+ulfsynth simulate input.nii.gz output.nii.gz --seed 42
+```
+
+### `ulfsynth enhance` — ULF→HF restoration (requires nnUNet)
+
+```bash
+# Single volume (CPU)
+ulfsynth enhance --device cpu input.nii.gz output.nii.gz
+
+# Folder of NIfTI files (GPU)
+ulfsynth enhance /path/to/ulf/scans/ /path/to/enhanced/scans/
+
+# Weights are downloaded from HuggingFace on first use.
+# Pre-download: ulfsynth download-weights
+```
+
+### `ulfsynth download-weights` — cache pretrained weights
+
+```bash
+ulfsynth download-weights
+```
+
+Caches model weights from [HuggingFace](https://huggingface.co/toufiqmusah/ulfsynth-weights) to `~/.cache/ulfsynth/`.
+
+---
+
+## Python API
+
+### Simulation
+
+```python
+from ulfsynth.simulate import simulate_ulf, simulate_file, simulate_folder, sample_params
+
+# Generate one ULF volume with random parameters
+ulf_volume, affine, header, params = simulate_ulf("hf_input.nii.gz")
+
+# With a fixed seed
+ulf_volume, affine, header, params = simulate_ulf("hf_input.nii.gz", seed=42)
+
+# Custom parameters
+params = sample_params()
+params["signal_target"] = 30
+ulf_volume, affine, header, params = simulate_ulf("hf_input.nii.gz", params=params)
+
+# Single-file convenience (returns params dict)
+params = simulate_file("hf_input.nii.gz", "ulf_output.nii.gz", seed=42)
+
+# Batch folder processing (returns list of params)
+results = simulate_folder("hf_scans/", "ulf_scans/", seed=42)
+```
+
+Output preserves the input affine and header metadata.
+
+### Enhancement
+
+```python
+from ulfsynth.enhance import enhance_file, enhance_folder
+
+# Single file
+enhance_file("ulf_input.nii.gz", "enhanced_output.nii.gz", device="cpu")
+
+# Batch folder processing
+enhance_folder("ulf_scans/", "enhanced_scans/", device="cuda")
+```
+
+Requires nnUNet (`pip install -e src/nn-translation/`). Weights are auto-downloaded on first call.
+
+---
+
+## Roadmap
+
+- [x] Physics-guided ULF synthesis pipeline
+- [x] Pre-trained enhancement weights — ULF→HF restoration models
+- [x] Python package — `pip install ulfsynth`
+- [ ] Docker image — zero-config containerized pipeline
+
+---
+
+## Citation
+
+```bibtex
+@misc{musah2026ulfsynth,
+  title        = {ULF-Synth: Physics-Guided Ultra-Low-Field MRI Enhancement for Pediatric Neuroimaging},
+  author       = {Toufiq Musah and Salvatore Calcagno and Federica Proietto Salanitri and Xiaomeng Li and Maruf Adewole and Marawan Elbatel},
+  year         = {2026},
+  eprint       = {2605.24625},
+  archivePrefix = {arXiv},
+  url          = {https://arxiv.org/abs/2605.24625}
+}
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

ulfsynth-0.1.3/README.md

@@ -0,0 +1,172 @@
+<p align="center">
+  <img src="assets/method.png" alt="ULF-Synth" width="100%">
+</p>
+
+<h1 align="center">ULF-Synth: Physics-Guided Ultra-Low-Field MRI Enhancement for Pediatric Neuroimaging</h1>
+
+<p align="center">
+  <a href="https://arxiv.org/abs/2605.24625v1"><img src="https://img.shields.io/badge/arXiv-2605.24625-b31b1b.svg" alt="arXiv"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python"></a>
+</p>
+
+## Abstract
+
+Ultra-low-field (ULF) MRI enables portable and accessible neuroimaging, but suffers from low signal-to-noise ratio and limited spatial resolution relative to high-field (HF) systems. Acquiring paired ULF–HF data for supervised enhancement is often infeasible, particularly in resource-limited settings. We introduce **ULF-Synth**, a framework combining: (i) acquisition-based synthesis of realistic ULF images from HF volumes for large-scale paired training, and (ii) a spatial-frequency domain objective that prioritizes recovery of high-frequency anatomical detail. The formulation is architecture-agnostic, consistently improving structural similarity and perceptual fidelity across encoder-decoder, adversarial, and diffusion-based translation models. Trained exclusively on synthetic data, our models generalize to real 64 mT ULF acquisitions, improving multiclass brain segmentation and achieving higher radiologist preference and diagnostic acceptability in a blinded reader study.
+
+---
+
+## Simulation Pipeline
+
+The ULF synthesis module models the key physical phenomena distinguishing ULF from HF acquisitions:
+
+|  | Effect | Implementation |
+|:---:|---|---|
+| 1 | **Signal scaling** | $(B_{{ULF}}/B_{{HF}})^2$ polarization ratio |
+| 2 | **T2\* decay & B0 inhomogeneity** | Spatially-varying exponential decay from random B0 field maps |
+| 3 | **Thermal noise** | Gaussian noise scaled to SNR 15–50 |
+| 4 | **k-space cropping** | Reduced resolution (45–55%) |
+| 5 | **k-space undersampling** | Accelerated acquisition (2×–3×) with center-out sampling |
+| 6 | **B0 off-resonance distortion** | Phase distortion from random B0 field maps |
+
+---
+
+## Qualitative Results
+
+<p align="center">
+  <img src="assets/results.png" alt="Sample results" width="95%">
+</p>
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/toufiqmusah/ULF-Synth.git
+cd ULF-Synth
+pip install -e .
+```
+
+This installs `ulfsynth` and all core dependencies (including PyTorch).
+The bundled [nnUNet translation fork](src/nn-translation/) is automatically
+discovered and installed during setup — no extra steps needed.
+
+### Install from PyPI (future)
+
+```bash
+pip install ulfsynth          # simulation only
+pip install ulfsynth[full]    # with enhancement support
+```
+
+---
+
+## CLI
+
+The `ulfsynth` package provides three commands:
+
+### `ulfsynth simulate` — ULF synthesis from HF volumes
+
+```bash
+# Single volume
+ulfsynth simulate input.nii.gz output.nii.gz
+
+# Folder of NIfTI files
+ulfsynth simulate /path/to/hf/scans/ /path/to/ulf/scans/
+
+# Reproducible seed
+ulfsynth simulate input.nii.gz output.nii.gz --seed 42
+```
+
+### `ulfsynth enhance` — ULF→HF restoration (requires nnUNet)
+
+```bash
+# Single volume (CPU)
+ulfsynth enhance --device cpu input.nii.gz output.nii.gz
+
+# Folder of NIfTI files (GPU)
+ulfsynth enhance /path/to/ulf/scans/ /path/to/enhanced/scans/
+
+# Weights are downloaded from HuggingFace on first use.
+# Pre-download: ulfsynth download-weights
+```
+
+### `ulfsynth download-weights` — cache pretrained weights
+
+```bash
+ulfsynth download-weights
+```
+
+Caches model weights from [HuggingFace](https://huggingface.co/toufiqmusah/ulfsynth-weights) to `~/.cache/ulfsynth/`.
+
+---
+
+## Python API
+
+### Simulation
+
+```python
+from ulfsynth.simulate import simulate_ulf, simulate_file, simulate_folder, sample_params
+
+# Generate one ULF volume with random parameters
+ulf_volume, affine, header, params = simulate_ulf("hf_input.nii.gz")
+
+# With a fixed seed
+ulf_volume, affine, header, params = simulate_ulf("hf_input.nii.gz", seed=42)
+
+# Custom parameters
+params = sample_params()
+params["signal_target"] = 30
+ulf_volume, affine, header, params = simulate_ulf("hf_input.nii.gz", params=params)
+
+# Single-file convenience (returns params dict)
+params = simulate_file("hf_input.nii.gz", "ulf_output.nii.gz", seed=42)
+
+# Batch folder processing (returns list of params)
+results = simulate_folder("hf_scans/", "ulf_scans/", seed=42)
+```
+
+Output preserves the input affine and header metadata.
+
+### Enhancement
+
+```python
+from ulfsynth.enhance import enhance_file, enhance_folder
+
+# Single file
+enhance_file("ulf_input.nii.gz", "enhanced_output.nii.gz", device="cpu")
+
+# Batch folder processing
+enhance_folder("ulf_scans/", "enhanced_scans/", device="cuda")
+```
+
+Requires nnUNet (`pip install -e src/nn-translation/`). Weights are auto-downloaded on first call.
+
+---
+
+## Roadmap
+
+- [x] Physics-guided ULF synthesis pipeline
+- [x] Pre-trained enhancement weights — ULF→HF restoration models
+- [x] Python package — `pip install ulfsynth`
+- [ ] Docker image — zero-config containerized pipeline
+
+---
+
+## Citation
+
+```bibtex
+@misc{musah2026ulfsynth,
+  title        = {ULF-Synth: Physics-Guided Ultra-Low-Field MRI Enhancement for Pediatric Neuroimaging},
+  author       = {Toufiq Musah and Salvatore Calcagno and Federica Proietto Salanitri and Xiaomeng Li and Maruf Adewole and Marawan Elbatel},
+  year         = {2026},
+  eprint       = {2605.24625},
+  archivePrefix = {arXiv},
+  url          = {https://arxiv.org/abs/2605.24625}
+}
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

ulfsynth-0.1.3/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ulfsynth"
+dynamic = ["version", "description", "dependencies", "optional-dependencies"]
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Toufiq Musah" },
+]
+keywords = [
+    "mri", "ultra-low-field", "ulf", "medical-image-enhancement",
+    "image-synthesis", "deep-learning", "neuroimaging",
+    "nnunet", "image-translation",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Healthcare Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+homepage = "https://github.com/toufiqmusah/ULF-Synth"
+repository = "https://github.com/toufiqmusah/ULF-Synth"
+documentation = "https://github.com/toufiqmusah/ULF-Synth#readme"
+"Bug Tracker" = "https://github.com/toufiqmusah/ULF-Synth/issues"
+
+[project.scripts]
+ulfsynth = "ulfsynth.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["ulfsynth*"]
+
+[tool.ruff]
+exclude = ["ulfsynth/_nnunet_src"]

ulfsynth-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ulfsynth-0.1.3/setup.py

@@ -0,0 +1,22 @@
+"""Setup script for ULF-Synth.
+
+The nnunetv2 fork (with MRCT kspace trainer) is bundled inside the
+package at ``ulfsynth/_nnunet_src/`` and auto-installed on first use.
+"""
+
+import sys
+from setuptools import setup
+
+if sys.version_info < (3, 10):
+    sys.exit(f"ulfsynth requires Python >= 3.10, found {sys.version}")
+
+setup(
+    version="0.1.3",
+    description="Physics-Guided Ultra-Low-Field MRI Enhancement & Simulation",
+    install_requires=[
+        "numpy>=1.21.0",
+        "nibabel>=3.2.0",
+        "scipy>=1.7.0",
+        "torch>=2.1.0",
+    ],
+)

ulfsynth-0.1.3/ulfsynth/__init__.py

@@ -0,0 +1,10 @@
+"""
+ULF-Synth: Physics-Guided Ultra-Low-Field MRI Enhancement & Simulation.
+
+Submodules:
+  simulate   — Synthesize realistic ULF MRI from high-field NIfTI volumes
+  enhance    — Enhance ULF MRI using pretrained restoration models
+  cli        — Command-line interface (ulfsynth simulate, ulfsynth enhance)
+"""
+
+__version__ = "0.1.3"