blochtwin 0.3.1__tar.gz

blochtwin-0.3.1/.gitignore

@@ -0,0 +1,34 @@
+.DS_Store
+**/.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage / cache
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# Generated artifacts (phantoms, sequences, raw data) — never commit data
+*.npz
+*.seq
+*.h5
+*.nii
+*.nii.gz
+!references/**
+
+# Local datasets (third-party, never commit)
+data/

blochtwin-0.3.1/CHANGELOG.md

@@ -0,0 +1,164 @@
+# Changelog
+
+이 프로젝트는 [Semantic Versioning](https://semver.org)을 따릅니다(pre-1.0에서는 minor = 마일스톤).
+릴리스 노트는 "무엇이 새로운가 · 연구자가 할 수 있는 것 · 구현한 물리와 논문" 순서로 씁니다.
+
+## [0.3.1] — 2026-10-29 · BlochTwin으로 이름 변경 · PyPI 첫 배포
+
+### 이름 변경: PhantomMRI → **BlochTwin** · PyPI 첫 배포
+- 패키지와 import 이름은 `blochtwin`(`pip install blochtwin`, `import blochtwin as bt`), CLI는 `blochtwin`.
+- 이름을 바꾼 이유: MRI에서 "phantom"은 QA용 실물 팬텀을 가리켜 검색 결과와 의미가 겹친다. 새 이름은
+  Bloch 방정식으로 스캐너를 재현하는 디지털 트윈이라는 정체성을 드러낸다.
+
+### 시퀀스 패밀리 추가: FLAIR / Inversion Recovery
+- **`InversionRecovery`** (180° invert → TI → 90°–180° SE readout) + **`FLAIR`** preset:
+  반전회복으로 특정 조직을 null하고 SE로 T2 가중을 얹음. STIR(지방 null)·T1-FLAIR·FLAIR(CSF
+  null)가 모두 같은 물리(TI/TE만 다름).
+- **`FLAIR`** 기본값(3T): TI 2500 ms로 **CSF를 null**(T1≈4300ms, TR 9000ms), TE 90 ms T2 가중.
+  결과: CSF가 어둡게, 뇌조직은 T2 가중(병변 강조) — 임상 FLAIR 대비와 일치. 검증: CSF 신호
+  < WM의 10%, IR-SE 엔진 vs 닫힌 해 0.000%(null 근처 제외).
+- **`null_ti_ms(t1, tr)`** 헬퍼: 임의 조직/필드의 null TI 계산(유한 TR 보정 포함).
+- CLI: `blochtwin simulate --seq flair`(또는 `--seq ir --ti …`).
+
+### 팬텀 소스 선택 (실제 사람 머리 해부 경로)
+- **절차적 팬텀에 공기강 추가**(`build_brain_phantom(sinuses=True)` 기본): 비강·상악/전두/
+  접형 부비동·이도(ear canal) 공기 주머니를 carve → 공기/조직 경계 생성(M3 susceptibility 대비).
+- **팬텀 소스 registry + 통합 API**(`bt.load_phantom(source=...)`, `bt.list_phantom_sources()`):
+  `procedural`(내장) / `brainweb`(실제 뇌) / `nyhead`(실제 머리: scalp/skull/CSF/GM/WM/공기) 중
+  선택. 외부 소스는 **번들 금지**·라이선스 게이트.
+- **New York Head 로더**(`load_nyhead`) + 일반 분할 머리 로더(`load_segmented_head`):
+  6구획 분할(부비동·콧구멍 공기 포함)을 9조직으로 매핑 — 정확히 "skin+bone+skull(공기강)" 충족.
+  실데이터는 사용자가 다운로드(`nyhead_license_notice()`), 로딩/매핑 로직은 합성 fixture로 검증.
+- CLI: `blochtwin phantom --source {procedural,brainweb,nyhead} [--path …] [--list-sources]`.
+- 테스트 89개 통과. ROADMAP M1의 "New York Head 흡수 검토" → 로더 구현 완료.
+
+## [0.3.0] — 2026-06-10 · MVP: Bloch 시뮬 + k-space + recon (M2) ⭐
+
+**시뮬레이터의 심장 완성.** 파라미터 → **물리적으로 올바른 복소 k-space → 영상**이 한 바퀴
+돕니다. 외부 연구자에게 처음으로 쓸모 있어지는 MVP 라인입니다. 대비(T1/T2/T2* weighting)는
+하드코딩이 아니라 Bloch 물리에서 자연히 나옵니다.
+
+### 무엇이 새로운가
+- **Forward 시뮬레이터**(`simulate`): 팬텀 + GRE/SE 시퀀스 → 복소 k-space → iFFT recon 영상,
+  결정론적 스캔타임. 코일 1개·full-Cartesian.
+- **operator-splitting Bloch 엔진**(`blochtwin.bloch`): 회전(Rodrigues) ∘ 이완으로 분해,
+  PyTorch **미분 가능**. GRE/SE 정상상태 신호의 **해석적 닫힌 해와 기계정밀도로 일치**.
+- **T2\* = 가역 vs 비가역 디페이징**: 비가역 T2 위에 가역 R2'=1/T2*−1/T2를 얹고, 180° 펄스가
+  R2'를 refocus. GRE(refocus 없음)는 T2\*, SE는 T2 — **대비가 refocusing 구조에서 emergent**.
+  (literal isochromat 앙상블 경로도 `mode="isochromat"`로 제공.)
+- **시퀀스 패밀리 GRE·SE**(`GradientEcho`/`SpinEcho`): Bloch 이벤트 타임라인 + Pulseq `.seq` +
+  해석적 닫힌 해 + 스캔타임을 한 파라미터셋에서 모두 도출.
+- **교체 가능 RF shape**(`RFPulse`): apodized sinc + slice-rephasing, TBW 파라미터화.
+- **k-space + recon**: image→k-space FFT + 매트릭스 크롭(유한 해상도·Gibbs 자연 발생),
+  Cartesian iFFT recon, 선택적 복소 가우시안 k-space 노이즈(→ Rician).
+- **시퀀스 뷰어 + 결과 표시**(`blochtwin.viz`, lazy matplotlib), CLI `simulate` 명령.
+
+### 연구자가 할 수 있는 것
+- TR/TE/flip/FOV/matrix/필드세기를 바꿔 GRE(T2\*/T1 가중)·SE(T2 가중) 영상을 직접 생성.
+- 복소 k-space·영상·조직별 정상상태 신호·정확한 스캔타임을 한 번에 획득(기초 합성 데이터).
+- `blochtwin simulate --seq se --te 90` 한 줄로 T2 가중 영상 + 스캔타임 확인.
+- diff-MRI: 신호가 flip 등에 미분 가능(autograd 그래프 보존).
+
+### 구현한 물리·논문
+- **Bloch 방정식** — *Bloch 1946.* **연산자 분리** — *Lauzon 2020 · SIMRI (Benoit-Cattin 2005).*
+- **k-space = gradient 적분, 신호 = Fourier 샘플** — *Twieg 1983 · Ljunggren 1983.*
+- **GRE/SE 정상상태 신호식** — 표준 공학 텍스트(Nishimura; Bernstein-King-Zhou).
+- **영상 노이즈 = k-space 복소 가우시안 → Rician** — *Gudbjartsson-Patz 1995.*
+- 미분 가능 코어 정신 — *MRzero (Loktyushin 2021) · PDG (Endres 2024).*
+
+### 검증 결과 (`pytest`, 79 passed)
+- **충실도 게이트 (KomaMRI 수치 대조 완료):** KomaMRI.jl(Castillo-Passi 2023)을 실제로 설치해
+  동일 단일-voxel 실험(spin echo=T2, inversion recovery=T1, flip angle=excitation; WM/GM/CSF)을
+  대조 → **BlochTwin vs KomaMRI mean-abs-diff = 0.0023% (worst 0.011%), 게이트 <0.1% 통과.**
+  BlochTwin은 해석적 Bloch 식과 기계정밀도(0.000%)로 일치. 재현: `benchmarks/compare.py`.
+  (정상상태 spoiled GRE는 spoiling 모델 차이 — 우리는 ideal spoiling=Ernst 정확, Koma는 유한
+  isochromat gradient spoiling이라 잔류 coherence 수% — 물리 불일치 아님. T2\*는 양쪽 모두
+  isochromat 필요. `benchmarks/README.md` 참조.) isochromat 모드는 T2\* 닫힌 해에 <1% 수렴.
+- **대비가 emergent:** SE T2 가중에서 CSF가 가장 밝고, 단TR GRE에서 WM>CSF로 **순서가 시퀀스에
+  따라 뒤집힘**(하드코딩 아님). 필드세기 토글이 WM 신호를 바꿈.
+- **수치:** encode/recon round-trip 기계정밀도, 스캔타임 = TR×N_PE×N_avg 단위테스트, 노이즈
+  재현성(seed), `.seq` timing 유효, 미분 가능성(∂|Mxy|/∂flip = cos α).
+
+### 알려진 한계 / 근사
+- 단일 코일·full-Cartesian·2D 단일 슬라이스. 멀티코일/병렬영상은 M4(v0.5.0).
+- 음향 노이즈·모션/Gibbs/chemical-shift/susceptibility 아티팩트는 M3(v0.4.0).
+- in-plane FOV는 팬텀 슬라이스를 따르고 매트릭스가 해상도를 정함(FOV zoom은 후속).
+- T2\* 기본 경로는 가역/비가역 분리 해석 모델(정확). isochromat 경로는 이산화 오차(개수 의존).
+- KomaMRI **수치** 대조 완료(0.0023%, `benchmarks/`). JEMRIS 대조는 후속.
+
+### 설치·예제
+```bash
+pip install blochtwin
+python examples/simulate_mvp.py        # 파라미터→k-space→영상, 대비 demo
+blochtwin simulate --seq se --te 90   # CLI 한 줄
+```
+
+### 인용
+[CITATION.cff](CITATION.cff) (v0.3.0). Zenodo version DOI와 arXiv preprint는 이 릴리스 라인에 맞춰
+발행할 예정입니다.
+
+## [0.2.0] — 2026-06-10 · 기반 + 팬텀 (M0 + M1) · 조용한 공개
+
+**코드 첫 버전.** 외부 표준과 배포
+구조를 못 박고, 시뮬레이터가 먹을 "디지털 객체"인 3D fuzzy 뇌 팬텀을 만들었습니다.
+**아직 신호(Bloch) 시뮬레이션은 없습니다** — 그건 v0.3.0 MVP입니다.
+
+### 무엇이 새로운가
+- `blochtwin` headless 수치 코어 패키지(라이브러리 + `blochtwin` CLI). 코어는 **GUI를
+  import하지 않습니다**(클러스터 headless 실행 보장, 테스트로 강제).
+- **PyTorch 백엔드 추상화**(`get_backend`): CPU/CUDA/MPS 디바이스 + dtype 해석. 데이터 생성
+  기본값은 **CPU/CUDA float64**, MPS는 교육용 float32 경로로만 — 정밀도 정책을 코드로 강제
+  (MPS+float64 / MPS+데이터 생성은 에러).
+- **3D fuzzy 뇌 팬텀**(`build_brain_phantom`): ICBM152-유사 격자 위 9개 조직 클래스
+  (WM/GM/CSF/skull/skin/fat/glial/connective/background)의 분율 맵. 절차적·결정론적 생성이라
+  외부 데이터 없이 바로 돌아갑니다. 부드러운 경계 = partial-volume(경계 voxel이 혼합값).
+- **필드세기별 조직 파라미터 테이블**(`tissue_parameters`, `tissue_table`): 1.5/3/7T의
+  T1/T2/T2*/PD/χ를 **출처 태깅과 함께** 제공. Rooney power-law T1(B0), Peters T2*, 화학적
+  이동(`chemical_shift_hz`). 7T·glial/connective/skin 값은 정직하게 플래그.
+- **Pulseq `.seq` I/O**(`read_seq`/`write_seq`): PyPulseq 1.5 재사용(직접 재발명 안 함).
+  데모 GRE 빌더 포함(round-trip·뷰어용).
+- **ISMRMRD 출력 스텁**(`write_ismrmrd_skeleton`): 유효한 XML 헤더 + HDF5, 표준 리더로 다시
+  열림.
+- **BrainWeb/ICBM 다운로더·로더**(`blochtwin.io.download`): 외부 팬텀은 **번들하지 않고**
+  사용자가 라이선스 동의 후 받아 같은 `Phantom`으로 적재.
+- **napari 3D 인스펙터**(선택, `blochtwin[viz]`, lazy import).
+- pip extras 골격(`[cuda]/[viz]/[ml]/[app]/[dev]`) + 재현용 Docker 스텁.
+
+### 연구자가 할 수 있는 것
+- `pip install blochtwin` 후 fuzzy 조직 분율 팬텀을 만들고 검사(napari).
+- 1.5/3/7T 조직 파라미터 테이블을 인용 출처와 함께 조회(`blochtwin tables --field 7.0`).
+- Pulseq `.seq`를 읽고/쓰고 round-trip 검증, 빈 ISMRMRD 파일을 표준 리더로 열기.
+
+### 구현한 물리·논문
+- **부분 체적(partial volume):** voxel 신호 = 조직별 분율 가중합, Σ f_k = 1 —
+  *BrainWeb (Collins 1998; Kwan 1999; Aubert-Broche 2006).*
+- **필드 의존 T1 power-law:** WM ≈ 0.583·B0^0.382 s, GM ≈ 0.857·B0^0.376 s, CSF ≈ 4.3 s
+  (≈ B0-무관) — *Rooney 2007.*
+- **멀티필드 T2\*** — *Peters 2007.* 3T 이완 앵커 — *Stanisz 2005, Wansapura 1999.*
+  자화율 χ — *Schenck 1996.* 화학적 이동 Δf = ppm·γ̄·B0.
+
+### 검증 결과 (`pytest`, 48 passed)
+- 팬텀: 분율 합이 voxel당 1에서 최대 ~1e-16 이내, 분율 ∈ [0,1], WM/GM 경계 혼합 voxel 존재.
+- 물리 테이블: 3T WM T1 ≈ 832 ms, GM ≈ 1331 ms, CSF ≈ 4300 ms(인용 범위 내), T1은 필드와
+  함께 증가·T2\*는 감소, 모든 값이 출처를 가짐.
+- Pulseq round-trip: 써놓은 `.seq`를 다시 읽어 쓰면 body·서명·duration·k-space 샘플 수 일치.
+- ISMRMRD: 스켈레톤이 표준 `ismrmrd` 리더로 다시 열림, ¹H 공명주파수가 필드에 비례.
+- 표준 호환·재현성: 코어 import가 GUI를 끌어오지 않음(headless), 동일 입력 → 동일 출력.
+
+### 알려진 한계 / 근사
+- **신호 시뮬레이션 없음.** 팬텀은 기하·파라미터까지만. parameter→영상은 v0.3.0(Bloch 엔진).
+- **절차적 팬텀은 근사 해부.** 실제 BrainWeb 해부가 필요하면 다운로더로 받아 적재(번들 금지).
+  ICBM152 affine은 중심 정렬 근사이며 실제 템플릿에 등록(registration)되지 않음.
+- **7T 조직값은 less-standardized**로 플래그(Rooney 외삽 + Peters). glial/connective/skin은
+  표준 brain-MR relaxometry가 없어 인접 조직값을 차용(`approximate` 플래그).
+- 음향 노이즈·아티팩트·멀티코일·CS는 이후 마일스톤(M3~M5).
+
+### 설치·예제
+```bash
+pip install blochtwin
+python examples/quickstart.py     # 전체 파이프라인 데모
+blochtwin info                   # 버전·디바이스·상태
+```
+
+### 인용
+[CITATION.cff](CITATION.cff) 참조. v0.2.0 첫 태그에서 Zenodo DOI 자동 발행 예정.

blochtwin-0.3.1/CITATION.cff

@@ -0,0 +1,44 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+title: "BlochTwin: a physics-faithful open MRI scanner simulator for synthetic data and teaching"
+type: software
+authors:
+  - family-names: "Lee"
+    given-names: "Hoonjae"
+    alias: "이훈재"
+    affiliation: "newmean.ai (Newmean AI)"
+    email: "dev@newmean.ai"
+    # orcid: "https://orcid.org/0000-0000-0000-0000"  # ORCID 발급 후 채울 것
+repository-code: "https://github.com/newmean-ai/blochtwin"
+url: "https://github.com/newmean-ai/blochtwin"
+abstract: >-
+  An open, GPU-accelerated, physics-faithful MRI scanner simulator (digital twin)
+  for generating realistic synthetic MRI training data and for teaching scanner
+  operation (parameter to image and scan-time intuition). Models a high-resolution
+  3D brain phantom with partial-volume effects, 1.5T/3T/7T field strengths,
+  viewable RF pulse sequences, gradient-coil acoustic noise tied to gradient
+  switching, k-space acquisition and reconstruction (with SENSE/GRAPPA/CS on the
+  roadmap).
+keywords:
+  - MRI
+  - simulation
+  - digital twin
+  - synthetic data
+  - Bloch equations
+  - k-space
+  - deep learning
+  - medical imaging
+  - acoustic noise
+license: "Apache-2.0"
+version: "0.3.1"
+date-released: "2026-06-10"
+# 동반 논문(MRM 또는 ISMRM abstract) 출간 후 preferred-citation 블록 추가:
+# preferred-citation:
+#   type: article
+#   title: "..."
+#   authors:
+#     - family-names: "Lee"
+#       given-names: "Hoonjae"
+#   journal: "Magnetic Resonance in Medicine"
+#   year: 2026
+#   doi: "10.1002/mrm.XXXXX"

blochtwin-0.3.1/LICENSE

@@ -0,0 +1,24 @@
+                                 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.

blochtwin-0.3.1/NOTICE

@@ -0,0 +1,11 @@
+BlochTwin
+Copyright 2026 Hoonjae Lee (이훈재), newmean.ai
+
+This product includes software developed by Hoonjae Lee / newmean.ai.
+
+"BlochTwin" and the project name and logo are trademarks of newmean.ai.
+Use of the source code is governed by the Apache License 2.0 (see LICENSE).
+The Apache-2.0 license does NOT grant trademark rights: forks and derivatives
+may not use the "BlochTwin" name, logo, or "BlochTwin-validated" mark without
+permission. Commercial offerings (hosted generation, validated presets,
+validation reports, enterprise support): dev@newmean.ai

blochtwin-0.3.1/PKG-INFO

@@ -0,0 +1,197 @@
+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.

blochtwin-0.3.1/README.md

@@ -0,0 +1,123 @@
+# 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.