Metadata-Version: 2.5
Name: blochtwin
Version: 0.3.1
Summary: Physics-faithful, GPU-accelerated open-source MRI scanner simulator (digital twin) for synthetic ML training data and scanner-operation teaching.
Project-URL: Homepage, https://github.com/newmean-ai/blochtwin
Project-URL: Repository, https://github.com/newmean-ai/blochtwin
Project-URL: Issues, https://github.com/newmean-ai/blochtwin/issues
Author-email: Hoonjae Lee <dev@newmean.ai>
License:                                  Apache License
                                   Version 2.0, January 2004
                                http://www.apache.org/licenses/
        
        Copyright 2026 Hoonjae Lee (이훈재), newmean.ai
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at
        
            http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
        
        SPDX-License-Identifier: Apache-2.0
        
        NOTE: Before the first public release, replace this file with the FULL verbatim
        text of the Apache License 2.0 (the ~11KB canonical text from the URL above).
        Trademark note: see the NOTICE file. "BlochTwin" is a trademark of newmean.ai
        and is not licensed under Apache-2.0.
License-File: LICENSE
License-File: NOTICE
Keywords: Bloch,ISMRMRD,MRI,Pulseq,digital-twin,k-space,medical-imaging,phantom,simulation,synthetic-data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.14,>=3.10
Requires-Dist: h5py>=3.8
Requires-Dist: ismrmrd>=1.14
Requires-Dist: nibabel>=5.0
Requires-Dist: numpy>=1.24
Requires-Dist: pypulseq>=1.5
Requires-Dist: scipy>=1.10
Requires-Dist: torch>=2.2
Provides-Extra: all
Requires-Dist: monai>=1.3; extra == 'all'
Requires-Dist: napari>=0.4.18; extra == 'all'
Requires-Dist: pytest-cov>=4.1; extra == 'all'
Requires-Dist: pytest>=7.4; extra == 'all'
Requires-Dist: ruff>=0.4; extra == 'all'
Requires-Dist: streamlit>=1.30; extra == 'all'
Provides-Extra: app
Requires-Dist: streamlit>=1.30; extra == 'app'
Provides-Extra: cuda
Requires-Dist: cupy-cuda12x>=12.0; extra == 'cuda'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: ml
Requires-Dist: monai>=1.3; extra == 'ml'
Provides-Extra: viz
Requires-Dist: napari>=0.4.18; extra == 'viz'
Description-Content-Type: text/markdown

# BlochTwin

**A physics-faithful, open-source MRI scanner simulator (digital twin)** for generating
synthetic MRI training data with perfect ground truth and for learning how scan parameters
shape the image, the scan time and the artifacts.

[![PyPI](https://img.shields.io/pypi/v/blochtwin.svg)](https://pypi.org/project/blochtwin/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)

> **Status: alpha (v0.3).** The core loop works end to end: tissue phantom → Bloch
> simulation → complex k-space → reconstructed image. Multi-coil acquisition, artifacts and
> gradient acoustic noise are on the roadmap below.

## Why

MRI deep-learning work needs paired data that real scanners cannot provide. That means
fully sampled complex k-space, noise-free references, voxel-wise tissue maps and exact
sequence parameters. Physics simulators (JEMRIS, MRiLab, KomaMRI) produce faithful signals,
but they are not built as ML data pipelines. ML toolkits (TorchIO, MONAI) are easy to use,
but they fake k-space as the FFT of a magnitude image. BlochTwin aims at the gap between
them: real acquisition physics, packaged as a headless Python/PyTorch library.

- **Contrast comes from physics, not lookup tables.** Each tissue's signal is computed by an
  operator-splitting Bloch engine. T1, T2 and T2\* weighting follow from TR/TE/TI/flip and
  from the refocusing structure of the sequence.
- **Every tissue parameter is cited.** Tables for T1, T2, T2\*, PD and χ at 1.5, 3 and 7 T
  carry their literature sources (`blochtwin references`). Less-standardized values, such as
  7 T extrapolations, are flagged.
- **Differentiable.** The engine is written in PyTorch, so signals keep their autograd graph
  for diff-MRI experiments.
- **Headless by design.** The core never imports a GUI, so it runs on clusters. Viewers are
  optional.

## Install

```bash
pip install blochtwin          # Python 3.10–3.13, CPU/CUDA, Apple MPS for convenience
pip install 'blochtwin[viz]'   # optional napari 3D inspector (add a Qt backend)
```

## Quick start

```python
import blochtwin as bt

phantom = bt.build_brain_phantom(voxel_mm=2.0)   # built-in procedural head (incl. air sinuses)

# T2-weighted spin echo: CSF bright
se = bt.simulate(phantom, bt.SpinEcho(matrix=(128, 128), tr_ms=3000, te_ms=100), field_t=3.0)
print(se.magnitude.shape, se.scan_time_s)          # (128, 128) 384.0

# T1-weighted spoiled gradient echo: same phantom, different physics, WM bright
gre = bt.simulate(phantom, bt.GradientEcho(tr_ms=15, te_ms=4, flip_deg=25), field_t=3.0)

# FLAIR: inversion recovery that nulls CSF (TI chosen from CSF T1 at 3 T)
flair = bt.simulate(phantom, bt.FLAIR(), field_t=3.0)

kspace, image = gre.kspace, gre.image              # complex k-space + reconstruction
```

The same from the command line:

```bash
blochtwin simulate --seq se --te 90        # image + k-space + scan time
blochtwin simulate --seq flair
blochtwin tables --field 7.0               # cited tissue parameters at 7 T
blochtwin info
```

Real anatomy can be loaded from sources you download yourself. Their data is never bundled
because it is under third-party licenses:

```python
bt.list_phantom_sources()                                 # sources + licenses
bt.load_phantom("brainweb", directory="brainweb/")        # BrainWeb fuzzy tissue maps
bt.load_phantom("nyhead", path="nyhead_seg.nii")          # New York Head (scalp/skull/air)
```

## What works today (v0.3)

| Area | Status |
|---|---|
| Bloch engine | Operator splitting (rotation ∘ relaxation), differentiable; T2\* via reversible/irreversible split (analytic) or an explicit isochromat ensemble |
| Sequences | Spin echo, spoiled gradient echo, inversion recovery, FLAIR; apodized-sinc RF with slice rephasing; Pulseq `.seq` export |
| Phantoms | Fuzzy tissue-fraction model (partial volume built in); procedural head; BrainWeb and New York Head loaders |
| Physics tables | 1.5 / 3 / 7 T, field-dependent T1 (Rooney power law), cited sources |
| k-space & recon | Cartesian encoding with matrix crop (Gibbs and resolution emerge naturally), complex Gaussian noise (→ Rician), iFFT recon, deterministic scan time |
| I/O | Pulseq read/write, ISMRMRD header/skeleton output (full raw export comes with the dataset generator), NIfTI |

### Validation

- Steady-state GRE and SE signals match closed-form solutions to machine precision. IR
  matches too, except right at the null point.
- Single-voxel cross-check against **KomaMRI.jl 0.10.4** (SE, IR, flip sweeps over WM, GM and
  CSF): **0.0023 % mean absolute difference** (worst 0.011 %). Reproduce with
  `benchmarks/compare.py`.

## Roadmap

1. **Artifacts, field strength and acoustics.** Sampling patterns, motion, chemical shift,
   susceptibility, EPI ghosts, and **gradient acoustic noise**, which no open simulator
   models today.
2. **Multi-coil.** Coil sensitivities, SENSE and GRAPPA.
3. **Compressed sensing.**
4. **Dataset generator.** Paired, fastMRI-compatible tuples with domain randomization, plus
   an interactive teaching UI.
5. **v1.0.** Validation against real data (fastMRI) and a companion paper.

## How to cite

If you use BlochTwin in academic work, please cite it (see [CITATION.cff](CITATION.cff); a
Zenodo DOI will be added with the first tagged release). Citation is a community norm we ask
you to honor, not a license restriction.

## License

Apache License 2.0. You are free to use, modify and distribute BlochTwin, including
commercially. "BlochTwin" and its logo are trademarks of newmean.ai. Forks may use the code
but not the name or logo (see [NOTICE](NOTICE)).

Questions and physics-fidelity reports are welcome on
[GitHub Issues](https://github.com/newmean-ai/blochtwin/issues) or at dev@newmean.ai.
