ulfsynth 0.1.0__py3-none-any.whl

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.0"

ulfsynth/cli.py

@@ -0,0 +1,85 @@
+"""
+Command-line interface for ULF-Synth.
+
+Usage:
+    ulfsynth simulate input output [--seed N] [--quiet]
+    ulfsynth enhance input output [--device DEVICE] [--quiet]
+    ulfsynth download-weights [--force]
+"""
+
+import argparse
+import os
+
+
+def add_simulate_parser(subparsers):
+    p = subparsers.add_parser("simulate", help="Synthesize ULF MRI from HF volumes")
+    p.add_argument("input", help="Path to .nii/.nii.gz file or folder of NIfTI files")
+    p.add_argument("output", help="Output file path or folder")
+    p.add_argument("--seed", type=int, default=None, help="Random seed")
+    p.add_argument("--quiet", action="store_true", help="Suppress per-file output")
+    p.set_defaults(func=_run_simulate)
+
+
+def _run_simulate(args):
+    from ulfsynth.simulate import simulate_file, simulate_folder
+    verbose = not args.quiet
+    if os.path.isdir(args.input):
+        simulate_folder(args.input, args.output, seed=args.seed, verbose=verbose)
+    elif os.path.isfile(args.input):
+        simulate_file(args.input, args.output, seed=args.seed, verbose=verbose)
+    else:
+        raise FileNotFoundError(f"Input not found: {args.input}")
+
+
+def add_enhance_parser(subparsers):
+    p = subparsers.add_parser("enhance", help="Enhance ULF MRI using pretrained model")
+    p.add_argument("input", help="Path to .nii/.nii.gz file or folder of NIfTI files")
+    p.add_argument("output", help="Output file path or folder")
+    p.add_argument("--device", type=str, default="cuda",
+                   choices=["cuda", "cpu", "mps"],
+                   help="Device for inference (default: cuda)")
+    p.add_argument("--quiet", action="store_true", help="Suppress progress output")
+    p.set_defaults(func=_run_enhance)
+
+
+def _run_enhance(args):
+    from ulfsynth.enhance import enhance_file, enhance_folder
+    verbose = not args.quiet
+    if os.path.isdir(args.input):
+        enhance_folder(args.input, args.output, device=args.device, verbose=verbose)
+    elif os.path.isfile(args.input):
+        enhance_file(args.input, args.output, device=args.device, verbose=verbose)
+    else:
+        raise FileNotFoundError(f"Input not found: {args.input}")
+
+
+def add_download_parser(subparsers):
+    p = subparsers.add_parser("download-weights",
+                              help="Download pretrained model weights from HuggingFace")
+    p.add_argument("--force", action="store_true",
+                   help="Force re-download even if cached")
+    p.set_defaults(func=_run_download)
+
+
+def _run_download(args):
+    from ulfsynth.enhance import _download_weights
+    _download_weights(force=args.force)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="ULF-Synth: Physics-Guided Ultra-Low-Field MRI Enhancement & Simulation"
+    )
+    subparsers = parser.add_subparsers(title="commands", dest="command")
+    subparsers.required = True
+
+    add_simulate_parser(subparsers)
+    add_enhance_parser(subparsers)
+    add_download_parser(subparsers)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

ulfsynth/enhance.py

@@ -0,0 +1,245 @@
+"""
+Enhance ULF MRI volumes using pretrained restoration models.
+
+Downloads weights from HuggingFace on first use, then runs nnU-Net
+translation inference to produce enhanced (HF-like) volumes.
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.request
+from pathlib import Path
+
+CACHE_DIR = os.path.join(os.path.expanduser("~"), ".cache", "ulfsynth")
+WEIGHTS_REPO = "https://huggingface.co/toufiqmusah/ulfsynth-weights/resolve/main"
+MODEL_DIR = "Dataset2023/nnUNetTrainerMRCT_kspace__nnResUNetPlans__3d_fullres"
+WEIGHT_FILES = [
+    f"{MODEL_DIR}/dataset.json",
+    f"{MODEL_DIR}/dataset_fingerprint.json",
+    f"{MODEL_DIR}/plans.json",
+    f"{MODEL_DIR}/fold_all/checkpoint_best.pth",
+    f"{MODEL_DIR}/fold_all/checkpoint_final.pth",
+]
+
+
+def _ensure_nnunet():
+    """Import nnunetv2 or raise a clear error with install instructions."""
+    try:
+        import nnunetv2  # noqa: F401
+    except ImportError:
+        # Look for the bundled fork relative to this package
+        here = Path(__file__).resolve().parent
+        for candidate in [here.parent / "src" / "nn-translation",
+                          here / "_nnunet",
+                          Path.cwd() / "src" / "nn-translation"]:
+            if (candidate / "setup.py").exists() or (candidate / "pyproject.toml").exists():
+                print(f"Installing nnunetv2 fork from {candidate}...")
+                subprocess.check_call(
+                    [sys.executable, "-m", "pip", "install", "-e", str(candidate)],
+                )
+                import nnunetv2  # noqa: F401
+                return
+        raise ImportError(
+            "nnunetv2 is required for enhancement. Install it with:\n\n"
+            f"    pip install -e {here.parent / 'src' / 'nn-translation'}\n\n"
+            "Or if you installed ulfsynth from PyPI:\n\n"
+            "    pip install ulfsynth[enhance]\n"
+            "    pip install nnunetv2\n"
+        )
+
+
+def _download_weights(force=False):
+    """Download model weights from HuggingFace to cache directory."""
+    weights_dir = os.path.join(CACHE_DIR, "weights")
+    os.makedirs(weights_dir, exist_ok=True)
+
+    missing = []
+    for fname in WEIGHT_FILES:
+        fpath = os.path.join(weights_dir, fname)
+        if not os.path.isfile(fpath) or force:
+            missing.append(fname)
+
+    if missing:
+        for fname in missing:
+            url = f"{WEIGHTS_REPO}/{fname}"
+            fpath = os.path.join(weights_dir, fname)
+            os.makedirs(os.path.dirname(fpath), exist_ok=True)
+            print(f"Downloading {fname}...")
+            urllib.request.urlretrieve(url, fpath)
+        print("Weights downloaded successfully.")
+    else:
+        print("Weights already cached.")
+
+    return weights_dir
+
+
+def enhance_file(input_path, output_path, device="cuda", verbose=True):
+    """Enhance a single ULF NIfTI file.
+
+    Args:
+        input_path: Path to input .nii or .nii.gz file.
+        output_path: Path for the enhanced output file.
+        device: Device for inference ('cuda', 'cpu', 'mps').
+        verbose: Print progress information.
+    """
+    input_path = os.path.abspath(input_path)
+    output_path = os.path.abspath(output_path)
+    os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)
+
+    with tempfile.TemporaryDirectory(prefix="ulfsynth_") as tmpdir:
+        # nnUNet expects files named {case}_0000.nii.gz
+        basename = os.path.basename(input_path)
+        if basename.endswith(".nii.gz"):
+            stem = basename[:-7]
+        else:
+            stem = basename[:-4]
+        nnunet_input = os.path.join(tmpdir, "input")
+        nnunet_output = os.path.join(tmpdir, "output")
+        os.makedirs(nnunet_input, exist_ok=True)
+        os.makedirs(nnunet_output, exist_ok=True)
+
+        # Copy input with _0000 suffix
+        shutil.copy2(input_path, os.path.join(nnunet_input, f"{stem}_0000.nii.gz"))
+
+        # Load model
+        weights_dir = _download_weights()
+        model_folder = os.path.join(weights_dir, MODEL_DIR)
+        _ensure_nnunet()
+        from nnunetv2.inference.predict_from_raw_data import nnUNetPredictor
+        import torch
+
+        predictor = nnUNetPredictor(
+            tile_step_size=0.5,
+            use_gaussian=True,
+            use_mirroring=True,
+
+            perform_everything_on_device=True,
+            device=torch.device(device),
+            verbose=verbose,
+            allow_tqdm=verbose,
+            verbose_preprocessing=verbose,
+        )
+        predictor.initialize_from_trained_model_folder(
+            model_folder,
+            use_folds=["all"],
+            checkpoint_name="checkpoint_best.pth",
+        )
+
+        # Run inference
+        if verbose:
+            print(f"Enhancing {basename}...")
+        predictor.predict_from_files(
+            nnunet_input,
+            nnunet_output,
+            save_probabilities=False,
+            overwrite=True,
+            num_processes_preprocessing=1,
+            num_processes_segmentation_export=1,
+            reconstruction_mode="mean",
+        )
+
+        # Find the NIfTI output (filter out JSON summaries added by nnUNet)
+        out_candidates = [f for f in os.listdir(nnunet_output)
+                          if f.endswith('.nii.gz')]
+        if not out_candidates:
+            raise RuntimeError(
+                f"Enhancement produced no NIfTI output. Found: {os.listdir(nnunet_output)}"
+            )
+
+        out_file = os.path.join(nnunet_output, out_candidates[0])
+        shutil.move(out_file, output_path)
+
+    if verbose:
+        print(f"  -> {output_path}")
+
+
+def enhance_folder(input_dir, output_dir, device="cuda", verbose=True):
+    """Enhance all NIfTI files in a directory.
+
+    Args:
+        input_dir: Directory containing .nii/.nii.gz files.
+        output_dir: Directory for enhanced outputs.
+        device: Device for inference.
+        verbose: Print progress information.
+    """
+    input_dir = os.path.abspath(input_dir)
+    output_dir = os.path.abspath(output_dir)
+    os.makedirs(output_dir, exist_ok=True)
+
+    files = sorted(
+        f for f in os.listdir(input_dir)
+        if f.endswith(".nii") or f.endswith(".nii.gz")
+    )
+    if not files:
+        raise FileNotFoundError(f"No NIfTI files found in {input_dir}")
+
+    with tempfile.TemporaryDirectory(prefix="ulfsynth_") as tmpdir:
+        nnunet_input = os.path.join(tmpdir, "input")
+        nnunet_output = os.path.join(tmpdir, "output")
+        os.makedirs(nnunet_input, exist_ok=True)
+        os.makedirs(nnunet_output, exist_ok=True)
+
+        # Copy all inputs with _0000 suffix
+        name_map = {}
+        for fname in files:
+            if fname.endswith(".nii.gz"):
+                stem = fname[:-7]
+            else:
+                stem = fname[:-4]
+            src = os.path.join(input_dir, fname)
+            dst = os.path.join(nnunet_input, f"{stem}_0000.nii.gz")
+            shutil.copy2(src, dst)
+            name_map[stem] = fname
+
+        # Load model
+        weights_dir = _download_weights()
+        model_folder = os.path.join(weights_dir, MODEL_DIR)
+
+        _ensure_nnunet()
+        from nnunetv2.inference.predict_from_raw_data import nnUNetPredictor
+        import torch
+
+        predictor = nnUNetPredictor(
+            tile_step_size=0.5,
+            use_gaussian=True,
+            use_mirroring=True,
+            perform_everything_on_device=True,
+            device=torch.device(device),
+            verbose=verbose,
+            allow_tqdm=verbose,
+            verbose_preprocessing=verbose,
+        )
+        predictor.initialize_from_trained_model_folder(
+            model_folder,
+            use_folds=["all"],
+            checkpoint_name="checkpoint_best.pth",
+        )
+
+        if verbose:
+            print(f"Enhancing {len(files)} files...")
+        predictor.predict_from_files(
+            nnunet_input,
+            nnunet_output,
+            save_probabilities=False,
+            overwrite=True,
+            num_processes_preprocessing=1,
+            num_processes_segmentation_export=1,
+            reconstruction_mode="mean",
+        )
+
+        # Rename outputs back (skip JSON summaries)
+        for of in os.listdir(nnunet_output):
+            if not of.endswith(".nii.gz"):
+                continue
+            stem = of[:-7].replace("_0000", "")
+            original_name = name_map.get(stem, of)
+            shutil.move(
+                os.path.join(nnunet_output, of),
+                os.path.join(output_dir, original_name),
+            )
+
+    if verbose:
+        print(f"Done. {len(files)} files written to {output_dir}")

ulfsynth/simulate.py

@@ -0,0 +1,177 @@
+"""
+Physics-guided ULF MRI simulation from high-field volumes.
+
+Simulates signal loss, noise, k-space degradation, and B0
+inhomogeneity effects characteristic of ultra-low-field MRI.
+"""
+
+import numpy as np
+import nibabel as nib
+from scipy.ndimage import gaussian_filter
+from numpy.fft import fftn, ifftn, fftshift, ifftshift
+import os
+
+B_HF = 1.5
+B_ULF = 0.064
+POLAR_SCALE = (B_ULF / B_HF) ** 2
+
+
+def to_kspace(vol):
+    return fftshift(fftn(vol))
+
+
+def to_ispace(K):
+    return np.real(ifftn(ifftshift(K)))
+
+
+def to_complex_ispace(K):
+    return ifftn(ifftshift(K))
+
+
+def object_mask(vol, thresh=0.05):
+    normed = (vol - vol.min()) / (vol.max() - vol.min() + 1e-8)
+    return normed > thresh
+
+
+def apply_b0_t2star_decay(I_complex, T2, TE, b0_strength, smoothness, k, eps=1e-6):
+    H, W, D = I_complex.shape
+    B0_map = gaussian_filter(np.random.randn(H, W, D), sigma=smoothness) * b0_strength
+    gx, gy, gz = np.gradient(B0_map)
+    grad_B0 = np.sqrt(gx**2 + gy**2 + gz**2)
+    grad_B0 /= (np.percentile(grad_B0, 95) + eps)
+    T2star = 1.0 / ((1.0 / T2) + k * grad_B0 + eps)
+    decay = np.exp(-TE / T2star)
+    return I_complex * decay
+
+
+def noisy_kspace(K, I_ref, signal_target):
+    alpha = 0.05
+    K_scaled = alpha * K
+    mask = object_mask(I_ref)
+    I_scaled = np.abs(ifftn(ifftshift(K_scaled)))
+    signal_power = np.mean(I_scaled[mask] ** 2)
+    sigma = np.sqrt(signal_power / (signal_target + 1e-8))
+    noise_img = sigma * np.ones_like(mask, dtype=float) * (
+        np.random.randn(*I_scaled.shape) + 1j * np.random.randn(*I_scaled.shape)
+    )
+    K_noisy = K_scaled + fftshift(fftn(noise_img))
+    return K_noisy
+
+
+def kspace_crop(K, crop_ratio):
+    H, W, D = K.shape
+    ch, cw, cd = int(H * crop_ratio), int(W * crop_ratio), int(D * crop_ratio)
+    h0, w0, d0 = (H - ch) // 2, (W - cw) // 2, (D - cd) // 2
+    K_cropped = np.zeros_like(K, dtype=complex)
+    K_cropped[h0:h0+ch, w0:w0+cw, d0:d0+cd] = K[h0:h0+ch, w0:w0+cw, d0:d0+cd]
+    return K_cropped
+
+
+def undersample_kspace(K, acceleration, center_fraction):
+    H, W, D = K.shape
+    mask = np.zeros((H, W, D), dtype=bool)
+    ch, cw, cd = int(H * center_fraction), int(W * center_fraction), int(D * center_fraction)
+    h0, w0, d0 = (H - ch) // 2, (W - cw) // 2, (D - cd) // 2
+    mask[h0:h0+ch, w0:w0+cw, d0:d0+cd] = True
+    outer = ~mask
+    n_sample = int(np.sum(outer) / acceleration)
+    coords = np.where(outer)
+    idx = np.random.choice(len(coords[0]), n_sample, replace=False)
+    mask[coords[0][idx], coords[1][idx], coords[2][idx]] = True
+    K_us = K * mask
+    I_original = np.abs(ifftn(ifftshift(K)))
+    I_us = np.abs(ifftn(ifftshift(K_us))) * object_mask(I_original, thresh=0.05)
+    return fftshift(fftn(I_us))
+
+
+def apply_b0_inhomogeneity(K, distortion_strength, smoothness):
+    I_complex = ifftn(ifftshift(K))
+    H, W, D = I_complex.shape
+    field_map = gaussian_filter(np.random.randn(H, W, D), sigma=smoothness) * distortion_strength
+    I_distorted = I_complex * np.exp(2j * np.pi * field_map)
+    return fftshift(fftn(I_distorted))
+
+
+def sample_params(rng=None):
+    if rng is None:
+        rng = np.random
+    return {
+        "T2":               rng.uniform(0.070, 0.090),
+        "TE":               rng.uniform(0.100, 0.130),
+        "b0_strength":      rng.uniform(0.020, 0.040),
+        "smoothness":       rng.uniform(30, 45),
+        "k":                rng.uniform(10, 15),
+        "signal_target":    rng.uniform(15, 50),
+        "crop_ratio":       rng.uniform(0.45, 0.55),
+        "acceleration":     int(rng.choice([2, 3], p=[0.7, 0.3])),
+        "center_fraction":  rng.uniform(0.20, 0.30),
+    }
+
+
+def simulate_ulf(hf_path, seed=None, params=None):
+    if seed is not None:
+        np.random.seed(seed)
+    if params is None:
+        params = sample_params()
+
+    hf_img = nib.load(hf_path)
+    I_hf = hf_img.get_fdata()
+    affine = hf_img.affine
+    header = hf_img.header.copy()
+
+    I_scaled = POLAR_SCALE * I_hf
+    K_hf = to_kspace(I_scaled)
+    I_complex = to_complex_ispace(K_hf)
+
+    I_b0 = apply_b0_t2star_decay(
+        I_complex,
+        T2=params["T2"],
+        TE=params["TE"],
+        b0_strength=params["b0_strength"],
+        smoothness=params["smoothness"],
+        k=params["k"],
+    )
+
+    K_b0 = to_kspace(I_b0)
+    K_noisy = noisy_kspace(K_b0, I_scaled, signal_target=params["signal_target"])
+
+    K_crop = kspace_crop(K_noisy, crop_ratio=params["crop_ratio"])
+
+    K_under = undersample_kspace(
+        K_crop,
+        acceleration=params["acceleration"],
+        center_fraction=params["center_fraction"],
+    )
+
+    K_final = apply_b0_inhomogeneity(
+        K_under,
+        distortion_strength=params["b0_strength"],
+        smoothness=max(1, int(params["smoothness"] // 10)),
+    )
+
+    I_ulf = np.abs(to_ispace(K_final)).astype(np.float32)
+    return I_ulf, affine, header, params
+
+
+def simulate_file(hf_path, out_path, seed=None, verbose=True):
+    I_ulf, affine, header, params = simulate_ulf(hf_path, seed=seed)
+    os.makedirs(os.path.dirname(os.path.abspath(out_path)) or ".", exist_ok=True)
+    nib.save(nib.Nifti1Image(I_ulf, affine, header), out_path)
+    if verbose:
+        print(f"  {os.path.basename(hf_path)} -> {out_path}  shape={I_ulf.shape}  range=[{I_ulf.min():.3f}, {I_ulf.max():.3f}]")
+    return params
+
+
+def simulate_folder(in_dir, out_dir, seed=None, verbose=True):
+    os.makedirs(out_dir, exist_ok=True)
+    files = sorted(f for f in os.listdir(in_dir) if f.endswith(('.nii', '.nii.gz')))
+    if not files:
+        raise FileNotFoundError(f"No NIfTI files found in {in_dir}")
+    results = []
+    for fname in files:
+        hf_path = os.path.join(in_dir, fname)
+        out_path = os.path.join(out_dir, fname)
+        file_seed = None if seed is None else seed + abs(hash(fname)) % (2**31)
+        params = simulate_file(hf_path, out_path, seed=file_seed, verbose=verbose)
+        results.append(params)
+    return results

ulfsynth-0.1.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: ulfsynth
+Version: 0.1.0
+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
+Provides-Extra: enhance
+Requires-Dist: nnunetv2>=2.5; extra == "enhance"
+Dynamic: license-file
+Dynamic: provides-extra
+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.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ulfsynth/__init__.py,sha256=7TizWjaILVaKCkQLQohnE9eGFreZPBv4sDzX_o6A3pw,339
+ulfsynth/cli.py,sha256=TdJWiCegEJmvkYham5X3SUOpsoiPE2ucrebfUE_4_Eo,3044
+ulfsynth/enhance.py,sha256=jmagU42ZCYwH3EjmQt1lkhGILNKrZupEyaaY8vBIPkw,8553
+ulfsynth/simulate.py,sha256=E883-8CglBY5Spk-9sUHweEWemV4IfpQ02m9yIEg7GQ,5900
+ulfsynth-0.1.0.dist-info/licenses/LICENSE,sha256=CUoI62adLPW53edyqgN_E66KMIAORk5QWw4IoGTKvao,1069
+ulfsynth-0.1.0.dist-info/METADATA,sha256=AYL--4afR33iFA0HUiUumx6nH12DesB6z1ycXSFHaSE,8545
+ulfsynth-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ulfsynth-0.1.0.dist-info/entry_points.txt,sha256=24J4SOhUWyQMBq6Ru42FPmxK8QgWiaI_kXL2MadP_Qo,47
+ulfsynth-0.1.0.dist-info/top_level.txt,sha256=QWzvK5IuFg-8wm6GZVgLl4gIyLRNkaqxoo3ON45Smr0,9
+ulfsynth-0.1.0.dist-info/RECORD,,

ulfsynth-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ulfsynth-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ulfsynth = ulfsynth.cli:main

ulfsynth-0.1.0.dist-info/licenses/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.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ulfsynth