Fit mobafit's water/fat, diffusion and Z-spectrum models with TorchSim

[mcencini]

Requested by Matteo · project thread

What changed

Before: bartorch mobafit went through the app only for -T, -I and -L. Water/fat (-G), diffusion (-D) and Lorentzian Z-spectra (-M) ran as the BART command.

After: those three are also fitted by apps.mobafit, using TorchSim's closed forms. They come out in BART's coefficient layout and units:

• For -G (models 0, 1, 3 and 4), a complex amplitude with a fat fraction and a fat phase is mapped back to W, F, R2* and fB0.
• For -D, the model is TorchSim's diffusion decay.
• For -M, the model is TorchSim's Lorentzian lines; -M goes through the app when --init is given.

The following still run as the command:

• -G -m 2, whose separate water and fat decays do not converge in the bounded fit.
• -P.
• -M without a start.
• --fB0-init.

TorchSim's floor is raised to 0.0.7, the first release with these simulators (FiRMLAB-Pisa/torchsim#20).

A failed BART command no longer hangs the process

Before: on Windows the suite hung partway through. BART's Windows vdprintf opened a stdio stream per call and never closed it, so after a few dozen CFL files create_cfl failed. On every platform, an error raised inside an OpenMP critical section left that section locked, so the next command waited on it forever. This happened after a bad option or -R term, or a missing input.

After:

• BART is pinned to the downstream merge of pulserver/bart#5, which writes through _write.
• src/csrc/substitute/critical.c defines the runtime's critical-section entry points (__kmpc_critical for clang, GOMP_critical_* for GCC) hidden inside the library. Each forwards to the runtime the library is bound to and records per thread which sections are held.
• bartorch_command and guarded leave whatever is still held once BART's error catcher returns.
• tests/test_core.py runs each of those three failures followed by two good commands in a child process with a timeout. Without the change it times out.

Why

Signal simulation belongs to TorchSim rather than to BART. tests/test_signal_models.py pins every closed-form model BART ships, from signal and mobasig, to its TorchSim simulator within single-precision round-off. The models covered are Look-Locker (three variants), MOLLI, IR-bSSFP, spin echo and IR spin echo, the TSE generating function, water/fat, ASL (continuous and pulsed), the five multi-echo models, the Middleton fat spectrum at 1.5 T, diffusion, and Lorentzian Z-spectra.

Validation

• ./scripts/lint.sh: all checks passed, codespell included.
• Full suite against a clang build of libbartorch.so: 2304 passed, 132 skipped, 2 failed.
  • The 2 failures are tests/test_openmp.py, which fails locally only because the clang build loads LLVM's libomp next to torch's libgomp. CI builds with GCC 14.
• The interposer was also exercised in a standalone harness against GCC 13's libgomp and clang 18's libomp. The harness jumps out of a named and an unnamed section and re-enters on the same thread, then enters from four threads. It hangs without the interposer and passes with it.
• The new mobafit routes are held against the command in tests/test_cli.py, to the tolerance the existing -T/-I/-L routes use.
• No CUDA was available.

Public API and documentation

There are no new public names. docs/api/cli.md and AGENTS.md now list the new routes and what still goes to BART, and docs/guides/user/prerequisites.md names TorchSim 0.0.7. AGENTS.md also describes the critical-section release under Errors.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FavM1ptGCKq51oher8tVd9

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!