From dd4ffc09e29588d5fd840874401e46bbeee2de78 Mon Sep 17 00:00:00 2001 From: mcencini Date: Tue, 10 Nov 2026 21:04:06 +0100 Subject: [PATCH 1/5] trains: prescribed-signal inverse EPG and Busse train design in a C++ kernel blochsim.trains designs refocusing trains from the echo signal they are to give: prescribed_flips inverts the phase graph of a CPMG train echo by echo, busse_flips builds the Busse variable-flip-angle trains on it, effective_te gives the contrast-equivalent echo time, and busse_centre_echo places the centre echo for one by trying every centre in a batch. The kernel (_trains_cpu) is double precision, host only, threaded over the trains of a batch, and takes NumPy arrays. It shares the real-subspace shift and rotation with the float simulation kernel through _real_subspace.hpp. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/build-and-test/SKILL.md | 2 +- .claude/skills/cut-a-release/SKILL.md | 2 +- AGENTS.md | 1 + CHANGELOG.md | 50 ++ CMakeLists.txt | 1 + docs/api/index.md | 2 + docs/api/trains.md | 25 + docs/developer-guide/installation.md | 3 +- docs/developer-guide/internals/kernels.md | 6 + scripts/check_wheel.py | 4 +- src/blochsim/_epg_cpu.cpp | 44 +- src/blochsim/_real_subspace.hpp | 94 ++++ src/blochsim/_trains_cpu.cpp | 393 ++++++++++++++ src/blochsim/trains/__init__.py | 17 + src/blochsim/trains/_busse.py | 628 ++++++++++++++++++++++ src/blochsim/trains/_prescribed.py | 296 ++++++++++ tests/trains/busse_figure1.json | 229 ++++++++ tests/trains/test_busse_centre_echo.py | 83 +++ tests/trains/test_busse_flips.py | 142 +++++ tests/trains/test_effective_te.py | 68 +++ tests/trains/test_prescribed_flips.py | 111 ++++ tests/utils/isochromats.py | 35 ++ 22 files changed, 2196 insertions(+), 40 deletions(-) create mode 100644 docs/api/trains.md create mode 100644 src/blochsim/_real_subspace.hpp create mode 100644 src/blochsim/_trains_cpu.cpp create mode 100644 src/blochsim/trains/__init__.py create mode 100644 src/blochsim/trains/_busse.py create mode 100644 src/blochsim/trains/_prescribed.py create mode 100644 tests/trains/busse_figure1.json create mode 100644 tests/trains/test_busse_centre_echo.py create mode 100644 tests/trains/test_busse_flips.py create mode 100644 tests/trains/test_effective_te.py create mode 100644 tests/trains/test_prescribed_flips.py create mode 100644 tests/utils/isochromats.py diff --git a/.claude/skills/build-and-test/SKILL.md b/.claude/skills/build-and-test/SKILL.md index 1f6a43b3..7e4c8ba1 100644 --- a/.claude/skills/build-and-test/SKILL.md +++ b/.claude/skills/build-and-test/SKILL.md @@ -15,7 +15,7 @@ pip install -e ".[dev]" ; echo "exit: $?" run alone, `pip install -e ".[test]"` is enough and much smaller. An editable install puts the Python sources on the path, so an edit under -`src/blochsim` takes effect on the next import. The two C++ extensions are +`src/blochsim` takes effect on the next import. The C++ extensions are compiled artifacts and do not: re-run the install after editing any `.cpp`, `.hpp` or `.cu`. diff --git a/.claude/skills/cut-a-release/SKILL.md b/.claude/skills/cut-a-release/SKILL.md index 7b80ec58..8b07624a 100644 --- a/.claude/skills/cut-a-release/SKILL.md +++ b/.claude/skills/cut-a-release/SKILL.md @@ -23,7 +23,7 @@ touches `pyproject.toml`, `CMakeLists.txt`, the `.cpp` sources, or the workflow. ## What gets built, and why there is so little of it -Both kernels are plain CPython extensions against the **stable ABI** from 3.10 +The CPU kernels are plain CPython extensions against the **stable ABI** from 3.10 on. They call no PyTorch API and link no PyTorch library. So: - one `cp310-abi3` wheel per platform serves every supported interpreter — diff --git a/AGENTS.md b/AGENTS.md index efead178..4fa1b6b7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,7 @@ carried out under them. | `src/blochsim/sequence/` | The description an acquisition is assembled from — events, operators, builders — and the dispatch that turns one into a kernel launch. | | `src/blochsim/_model/` | What a signal model *is*: the physics, the simulator that orders its events, and the binding that resolves a protocol's structure once and rebinds its values per call. | | `src/blochsim/_epg_cpu.cpp`, `_perk_cpu.cpp` | The CPU kernels. Every path the GPU has exists here too, and the two agree to float32 round-off. | +| `src/blochsim/_trains_cpu.cpp`, `trains/` | Refocusing-train design: the prescribed-signal inverse of a CPMG train, in double precision on the host only, over NumPy with no PyTorch import. It shares the real-subspace operators of `_real_subspace.hpp` with `_epg_cpu.cpp`. | | `src/blochsim/_epg_kernels.hpp`, `_pools_kernels.hpp`, `_perk_kernels.hpp` | The GPU kernels, written over the tiles of `_tile.hpp`. `_kernels.hpp` is the table a launch reads: each kernel's parameters, and which of them size the block. | | `src/blochsim/_gpu.cu`, `_gpu_kernel.cu.in`, `_gpu_host.cpp`, `_gpu_launch.py` | The same kernels compiled ahead of time for the card (`_gpu`), and for the host (`_gpu_host`), which is how the suite checks them without one; and the launcher both answer to. | | `src/blochsim/sequence/_epg_gpu.py`, `_pools_gpu.py`, `estimators/_perk_gpu.py` | What a GPU launch is given: the tiling and the arguments. | diff --git a/CHANGELOG.md b/CHANGELOG.md index ed296ef8..d35d577a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,16 @@ ### Added +- **Refocusing trains from a prescribed echo signal.** `blochsim.trains` is + new: `prescribed_flips` inverts the phase graph of a CPMG train one echo at + a time, with or without relaxation; `busse_flips` designs the + variable-flip-angle trains of long 3D fast spin echo readouts (Busse 2006, + 2008) from a lowest, a centre and a highest angle; `busse_centre_echo` + places the centre echo for a contrast-equivalent echo time, trying every + centre in one batch; `effective_te` gives that echo time for any train. + They run in a new double-precision C++ extension (`_trains_cpu`) on the + host, take and return NumPy arrays, and solve a batch of trains across + threads. - **Coarse-to-fine dictionary search.** `DictionaryMatcher(coarse=k)` places the atoms on the lattice their parameters were simulated on, scores every k-th value along each parameter, then the `2k + 1` values around the winner @@ -28,6 +38,14 @@ ### Changed +- **`import blochsim` no longer imports PyTorch.** It imports + `blochsim.trains` alone; the simulators, estimators and design tools are + imported the first time any of them is asked for, by attribute, by + `from blochsim import ...` or by submodule. `import blochsim.trains` costs + what NumPy costs. +- **A forked child starts its own worker pool.** The CPU kernels' pool is + tied to the process that created it, so a process forked after a threaded + call no longer waits on workers it does not have. - **Every GPU, a bounded share of it, by default.** `execution="auto"` is the default of a simulator, an estimator's `map` and a `ModelOperator`. A call too small to repay a launch, or a simulator call carrying a gradient, runs @@ -124,6 +142,14 @@ ### Changed +- **`import blochsim` no longer imports PyTorch.** It imports + `blochsim.trains` alone; the simulators, estimators and design tools are + imported the first time any of them is asked for, by attribute, by + `from blochsim import ...` or by submodule. `import blochsim.trains` costs + what NumPy costs. +- **A forked child starts its own worker pool.** The CPU kernels' pool is + tied to the process that created it, so a process forked after a threaded + call no longer waits on workers it does not have. - **Both adjoint kernels compile one sweep at a time.** A reverse pass records a trajectory through the events and then walks it back, and the walk back is where the kernel's mass is: in the forward-over-reverse kernel at three @@ -352,6 +378,14 @@ ### Changed +- **`import blochsim` no longer imports PyTorch.** It imports + `blochsim.trains` alone; the simulators, estimators and design tools are + imported the first time any of them is asked for, by attribute, by + `from blochsim import ...` or by submodule. `import blochsim.trains` costs + what NumPy costs. +- **A forked child starts its own worker pool.** The CPU kernels' pool is + tied to the process that created it, so a process forked after a threaded + call no longer waits on workers it does not have. - **The PERK example says how sure it is.** The regression maps a slice in hundredths of a second, so the estimator's noise sensitivity is answered by running it: two dozen noise realizations of the same measurement, mapped @@ -589,6 +623,14 @@ ### Changed +- **`import blochsim` no longer imports PyTorch.** It imports + `blochsim.trains` alone; the simulators, estimators and design tools are + imported the first time any of them is asked for, by attribute, by + `from blochsim import ...` or by submodule. `import blochsim.trains` costs + what NumPy costs. +- **A forked child starts its own worker pool.** The CPU kernels' pool is + tied to the process that created it, so a process forked after a threaded + call no longer waits on workers it does not have. - **A property whose term the run leaves out is not laid out per voxel, and neither is one given as a single value.** Every tissue property was broadcast to the voxel count and materialized, so a model naming two relaxation times @@ -1125,6 +1167,14 @@ ### Changed +- **`import blochsim` no longer imports PyTorch.** It imports + `blochsim.trains` alone; the simulators, estimators and design tools are + imported the first time any of them is asked for, by attribute, by + `from blochsim import ...` or by submodule. `import blochsim.trains` costs + what NumPy costs. +- **A forked child starts its own worker pool.** The CPU kernels' pool is + tied to the process that created it, so a process forked after a threaded + call no longer waits on workers it does not have. - **The documentation has a User Guide and a Developer Guide** in place of *Getting Started* and *Miscellaneous*. The user guide installs PyTorch first -- the build depends on hardware pip cannot see -- with tabs for the isolated diff --git a/CMakeLists.txt b/CMakeLists.txt index 1dd989aa..57099ac7 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -64,6 +64,7 @@ set(BLOCHSIM_CUDA_PACKAGE "" CACHE STRING if(NOT BLOCHSIM_CUDA_PACKAGE) blochsim_add_kernel(_epg_cpu src/blochsim/_epg_cpu.cpp) blochsim_add_kernel(_perk_cpu src/blochsim/_perk_cpu.cpp) + blochsim_add_kernel(_trains_cpu src/blochsim/_trains_cpu.cpp) endif() # The GPU kernels compiled for the host, one program at a time. Nothing in the diff --git a/docs/api/index.md b/docs/api/index.md index 2e68c35e..8f726da1 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -12,6 +12,7 @@ the per-voxel nonlinear least-squares fit, are bartorch's. | {doc}`sequence` | `blochsim` | Operators, sequence descriptions, RF definitions | | {doc}`estimators` | `blochsim.estimators` | Dictionary matching, lookup tables, PERK | | {doc}`optim` | `blochsim.optim` | Sequence parameter optimization | +| {doc}`trains` | `blochsim.trains` | Refocusing trains from a prescribed echo signal | ```{toctree} :hidden: @@ -22,4 +23,5 @@ simulators sequence estimators optim +trains ``` diff --git a/docs/api/trains.md b/docs/api/trains.md new file mode 100644 index 00000000..0edd5a64 --- /dev/null +++ b/docs/api/trains.md @@ -0,0 +1,25 @@ +# Refocusing trains + +```{eval-rst} +.. currentmodule:: blochsim.trains +``` + +Refocusing flip angles designed from the echo signal they are to give. The +functions take and return NumPy arrays in degrees and ms, run on the host in +double precision, and do not import PyTorch: `import blochsim.trains` costs +what NumPy costs. + +{func}`prescribed_flips` inverts the extended phase graph of a CPMG train one +echo at a time: the flip angle of each pulse is the smallest whose echo has the +prescribed amplitude, with or without relaxation. {func}`busse_flips` builds +on it the variable-flip-angle trains of long 3D fast spin echo readouts, and +{func}`busse_centre_echo` places their centre echo for a contrast-equivalent +echo time, which {func}`effective_te` computes for any train. A batch of +trains is solved in one call, across threads. + +| Object | Description | +| --- | --- | +| {obj}`~blochsim.trains.prescribed_flips` | Flip angles whose echoes take prescribed amplitudes, and the echoes they give. | +| {obj}`~blochsim.trains.effective_te` | Contrast-equivalent echo time of every echo of a train. | +| {obj}`~blochsim.trains.busse_flips` | Variable flip angles with a prescribed lowest, centre and highest angle. | +| {obj}`~blochsim.trains.busse_centre_echo` | Centre echo whose contrast-equivalent echo time is nearest a target. | diff --git a/docs/developer-guide/installation.md b/docs/developer-guide/installation.md index ecdc6c34..07ae7341 100644 --- a/docs/developer-guide/installation.md +++ b/docs/developer-guide/installation.md @@ -14,7 +14,7 @@ Besides the environment and PyTorch build of the {doc}`user guide <../user-guide/index>`, you need: - **A C++17 compiler and CMake.** The CPU kernels (`src/blochsim/_epg_cpu.cpp`, - `_perk_cpu.cpp`) are compiled at install, and there is no Python fallback. + `_perk_cpu.cpp`, `_trains_cpu.cpp`) are compiled at install, and there is no Python fallback. ::::{tab-set} @@ -76,6 +76,7 @@ python -c "import blochsim._epg_cpu as k; print(k.__file__)" | `src/blochsim/sequence/` | Events, operators and builders, and the dispatch to the kernels. `_parameters.py` is the parameter ABI the Python dispatch, the C++ extension and the GPU kernels share. | | `src/blochsim/_model/` | The signal model: physics, the simulator that orders events, and the binding that resolves a protocol's structure once. | | `src/blochsim/_epg_cpu.cpp`, `_perk_cpu.cpp` | The CPU kernels. Every GPU path exists here too; the two agree to float32 round-off. | +| `src/blochsim/_trains_cpu.cpp`, `trains/` | The train-design kernels, in double precision on the host only, and their NumPy interface. | | `src/blochsim/_epg_kernels.hpp`, `_pools_kernels.hpp` | The GPU kernels. | | `src/blochsim/_operator.py`, `_subspace.py` | The model operator and the temporal basis a reconstruction composes with. | | `src/blochsim/simulators/`, `estimators/`, `optim/` | Shipped sequences, and what is built on them. | diff --git a/docs/developer-guide/internals/kernels.md b/docs/developer-guide/internals/kernels.md index 03b19221..3d9b9cc6 100644 --- a/docs/developer-guide/internals/kernels.md +++ b/docs/developer-guide/internals/kernels.md @@ -119,6 +119,12 @@ specialization and the pool models -- and the two agree to float32 round-off. On Linux the same CUDA kernels are also compiled for the host (`_gpu_host`), which is how the suite checks them without a card. +The train-design kernels (`_trains_cpu.cpp`, behind `blochsim.trains`) are a +third extension on the same worker pool. They invert a CPMG train for a +prescribed echo signal in double precision, on the host only, and share the +real-subspace shift and rotation with the simulation kernels +(`_real_subspace.hpp`), which use them at float. + ### Layouts and compiles The EPG kernels on a card are written for their layouts (`_layout.hpp`). A diff --git a/scripts/check_wheel.py b/scripts/check_wheel.py index ef4f8d1e..c39c4763 100644 --- a/scripts/check_wheel.py +++ b/scripts/check_wheel.py @@ -77,8 +77,8 @@ def main() -> int: if root is None: raise SystemExit("blochsim is not installed") kernels = extensions(root, "_*_cpu.*") - if len(kernels) != 2: - raise SystemExit(f"expected two kernels in {root}, found {kernels}") + if len(kernels) != 3: + raise SystemExit(f"expected three kernels in {root}, found {kernels}") for path in kernels: load(path, "blochsim", LARGEST_REASONABLE_BYTES) # A build from source keeps the card's module beside the package. diff --git a/src/blochsim/_epg_cpu.cpp b/src/blochsim/_epg_cpu.cpp index da2fe903..37425215 100644 --- a/src/blochsim/_epg_cpu.cpp +++ b/src/blochsim/_epg_cpu.cpp @@ -19,18 +19,9 @@ #endif #include "_ifunc.hpp" +#include "_real_subspace.hpp" #include "_threads.hpp" -// MSVC rejects the GNU spelling of both of these outright, and the kernel is -// built by whichever compiler the platform ships. -#if defined(_MSC_VER) -#define BLOCHSIM_ALWAYS_INLINE __forceinline -#define BLOCHSIM_RESTRICT __restrict -#else -#define BLOCHSIM_ALWAYS_INLINE __attribute__((always_inline)) inline -#define BLOCHSIM_RESTRICT __restrict__ -#endif - namespace { constexpr std::uint8_t PRE_SHIFT = 1; @@ -3010,20 +3001,10 @@ __attribute__((target_clones("default", "sse4.2", "avx2", "avx512f"))) inline void shift_real( std::vector& plus, std::vector& minus, const std::size_t states ) { - // No states is impossible -- every entry point rejects a state count - // below one -- but not provable here, and the loops below count down - // from ``states - 1``. - if (states == 0) { - return; - } - for (std::size_t state = 0; state + 1 < states; ++state) { - minus[state] = minus[state + 1]; - } - minus[states - 1] = 0.0F; - for (std::size_t state = states - 1; state > 0; --state) { - plus[state] = plus[state - 1]; - } - plus[0] = -minus[0]; + blochsim::real_subspace::shift( + plus.data(), minus.data(), states, + blochsim::real_subspace::ACROSS_AXIS + ); } // --------------------------------------------------------------------------- @@ -3096,17 +3077,10 @@ void simulate_real_range( const float alpha = view.flip[event] * b1; const float cosine = std::cos(alpha); const float sine = std::sin(alpha); - const float cosine_half_sq = 0.5F * (1.0F + cosine); - const float sine_half_sq = 0.5F * (1.0F - cosine); - const float half_sine = 0.5F * sine; - for (std::size_t state = 0; state < states; ++state) { - const float p = plus[state]; - const float m = minus[state]; - const float z = longitudinal[state]; - plus[state] = cosine_half_sq * p + sine_half_sq * m - sine * z; - minus[state] = sine_half_sq * p + cosine_half_sq * m + sine * z; - longitudinal[state] = half_sine * p - half_sine * m + cosine * z; - } + blochsim::real_subspace::rotate( + plus.data(), minus.data(), longitudinal.data(), states, + cosine, sine + ); } } else if (buffers.kind[event] == 2 && (action & RECORD) != 0) { const std::int64_t index = diff --git a/src/blochsim/_real_subspace.hpp b/src/blochsim/_real_subspace.hpp new file mode 100644 index 00000000..eb820799 --- /dev/null +++ b/src/blochsim/_real_subspace.hpp @@ -0,0 +1,94 @@ +// The EPG operators of the real subspaces, over a number type: at float they +// are the forward simulation's (_epg_cpu.cpp), at double the train design's +// (_trains_cpu.cpp). +// +// When every pulse of a train turns about one axis and nothing carries a +// state off it -- no off-resonance, no transmit phase -- the complex states +// split into two sets of real ones that never mix: +// +// across the axis: F+ = e^{i phi} i a, F- = e^{-i phi} i b, Z = c +// along the axis: F+ = e^{i phi} a, F- = e^{-i phi} b, Z = -i c +// +// with phi the pulses' phase. The first holds what a pulse of the train +// excites out of the longitudinal magnetization, recovery included; the +// second holds the magnetization an excitation a quarter turn from the train +// leaves along its axis, which is the CPMG arrangement. A pulse turns either +// set through the same real 3x3 in its flip angle, relaxation scales both, +// and the shift's conjugate coupling F+0 = conj(F-0) is a0 = -b0 across the +// axis and a0 = b0 along it. +#ifndef BLOCHSIM_REAL_SUBSPACE_HPP +#define BLOCHSIM_REAL_SUBSPACE_HPP + +#include + +// MSVC rejects the GNU spelling of both of these outright, and the kernel is +// built by whichever compiler the platform ships. +#if defined(_MSC_VER) +#define BLOCHSIM_ALWAYS_INLINE __forceinline +#define BLOCHSIM_RESTRICT __restrict +#else +#define BLOCHSIM_ALWAYS_INLINE __attribute__((always_inline)) inline +#define BLOCHSIM_RESTRICT __restrict__ +#endif + +namespace blochsim { +namespace real_subspace { + +// The sign the shift couples the two zeroth orders with. +template +constexpr Real ACROSS_AXIS = Real(-1); +template +constexpr Real ALONG_AXIS = Real(1); + +// One dephasing order: F+ moves up, F- moves down, and the zeroth F+ is the +// conjugate of the zeroth F-, which is ``coupling`` times it. +// +// No states is impossible -- every entry point rejects a state count below +// one -- but not provable here, and the loops below count from ``states - 1``. +template +BLOCHSIM_ALWAYS_INLINE void shift( + Real* const BLOCHSIM_RESTRICT plus, + Real* const BLOCHSIM_RESTRICT minus, + const std::size_t states, + const Real coupling +) { + if (states == 0) { + return; + } + for (std::size_t state = 0; state + 1 < states; ++state) { + minus[state] = minus[state + 1]; + } + minus[states - 1] = Real(0); + for (std::size_t state = states - 1; state > 0; --state) { + plus[state] = plus[state - 1]; + } + plus[0] = coupling * minus[0]; +} + +// A pulse of flip angle alpha, given as its cosine and sine. +template +BLOCHSIM_ALWAYS_INLINE void rotate( + Real* const BLOCHSIM_RESTRICT plus, + Real* const BLOCHSIM_RESTRICT minus, + Real* const BLOCHSIM_RESTRICT longitudinal, + const std::size_t states, + const Real cosine, + const Real sine +) { + const Real cosine_half_sq = Real(0.5) * (Real(1) + cosine); + const Real sine_half_sq = Real(0.5) * (Real(1) - cosine); + const Real half_sine = Real(0.5) * sine; + for (std::size_t state = 0; state < states; ++state) { + const Real p = plus[state]; + const Real m = minus[state]; + const Real z = longitudinal[state]; + plus[state] = cosine_half_sq * p + sine_half_sq * m - sine * z; + minus[state] = sine_half_sq * p + cosine_half_sq * m + sine * z; + longitudinal[state] = half_sine * p - half_sine * m + cosine * z; + } +} + +} // namespace real_subspace +} // namespace blochsim + +#endif // BLOCHSIM_REAL_SUBSPACE_HPP diff --git a/src/blochsim/_trains_cpu.cpp b/src/blochsim/_trains_cpu.cpp new file mode 100644 index 00000000..b7ab4311 --- /dev/null +++ b/src/blochsim/_trains_cpu.cpp @@ -0,0 +1,393 @@ +#define PY_SSIZE_T_CLEAN +#include + +#include +#include +#include +#include + +#include "_ifunc.hpp" +#include "_real_subspace.hpp" +#include "_threads.hpp" + +// Refocusing trains whose echoes follow a prescription, and the echoes a +// train gives, for a batch of trains at once. +// +// A train is an ideal excitation a quarter turn from its refocusing pulses, +// then one pulse per echo, each midway between two echoes: the CPMG +// arrangement. The excited magnetization lies along the pulses' axis, so its +// states are the real subspace along it (_real_subspace.hpp). What recovers +// during the train is excited by the pulses across the axis, into the other +// subspace. It is not carried: a pathway born at a pulse is back at the +// zeroth order an even number of half intervals later, which is at a pulse +// again and never at an echo. +// +// These are design kernels: a schedule is solved once, on the host, and the +// solve is a shooting problem whose residual has to resolve a change of a +// billionth of a degree. They are in double precision for that reason, and +// there is no counterpart of them on a card. + +#if BLOCHSIM_MULTIVERSIONED +#define BLOCHSIM_TRAIN_CLONES \ + __attribute__((target_clones("default", "avx2", "avx512f"))) +#else +#define BLOCHSIM_TRAIN_CLONES +#endif + +namespace { + +using blochsim::WorkerPool; +using blochsim::worker_count; +namespace subspace = blochsim::real_subspace; + +constexpr double PI = 3.14159265358979323846; + +// A train is tens of microseconds of work, so a worker is worth waking only +// for a few of them. +constexpr std::int64_t TRAINS_PER_WORKER = 8; + +// What every train of a batch shares: the batch's shape, and the relaxation +// over half an echo interval -- the first interval's, and every later one's. +struct Batch { + std::int64_t count; + std::int64_t echoes; + const std::int64_t* lengths; + double e1_first; + double e2_first; + double e1; + double e2; + + bool relaxing() const { + return e1_first != 1.0 || e2_first != 1.0 || e1 != 1.0 || e2 != 1.0; + } +}; + +// The states of one real subspace, and how many of its orders a train has +// reached: an order beyond that is still empty, so nothing is spent on it. +struct States { + std::vector plus; + std::vector minus; + std::vector longitudinal; + std::size_t occupied = 0; + + explicit States(const std::size_t capacity) + : plus(capacity), minus(capacity), longitudinal(capacity) {} + + void clear(const std::size_t states) { + std::fill(plus.begin(), plus.begin() + states, 0.0); + std::fill(minus.begin(), minus.begin() + states, 0.0); + std::fill(longitudinal.begin(), longitudinal.begin() + states, 0.0); + occupied = 1; + } + + BLOCHSIM_ALWAYS_INLINE void relax(const double e1, const double e2) { + for (std::size_t state = 0; state < occupied; ++state) { + plus[state] *= e2; + minus[state] *= e2; + longitudinal[state] *= e1; + } + } + + BLOCHSIM_ALWAYS_INLINE void shift(const std::size_t states, const double coupling) { + occupied = std::min(occupied + 1, states); + subspace::shift(plus.data(), minus.data(), occupied, coupling); + } + + BLOCHSIM_ALWAYS_INLINE void rotate(const double angle) { + subspace::rotate( + plus.data(), minus.data(), longitudinal.data(), occupied, + std::cos(angle), std::sin(angle) + ); + } +}; + +// The flip angle in [0, pi] whose echo is ``target``, from the first-order +// states the pulse is about to turn. +// +// The echo is the zeroth F- the pulse leaves, a + b cos(alpha) + c sin(alpha) +// = a + r cos(alpha - delta), scaled by the transverse relaxation ``e2`` of +// the half interval after the pulse. A target within reach has two solutions, +// delta -/+ turn, and the smaller rotation is taken. One out of reach has +// none, and the angle whose echo comes nearest is taken instead: an end of +// the interval, or the extremum at delta. The candidates are scored by their +// distance from the target plus a term that orders equal scores by angle. +inline double refocusing_angle( + const double plus, const double minus, const double longitudinal, + const double target, const double e2 +) { + if (std::isnan(target)) { + return target; + } + const double a = 0.5 * (plus + minus); + const double b = 0.5 * (minus - plus); + const double c = longitudinal; + const double delta = std::atan2(c, b); + const double radius = std::hypot(b, c); + const double reach = std::min( + 1.0, std::max(-1.0, (target / e2 - a) / std::max(radius, 1e-16)) + ); + const double turn = std::acos(reach); + const double met = a + radius * reach; + const double angles[8] = { + 0.0, PI, delta, delta + PI, delta - turn, delta + turn, + delta - turn + 2.0 * PI, delta + turn + 2.0 * PI, + }; + const double echoes[8] = { + a + b, a - b, a + radius, a - radius, met, met, met, met, + }; + double best = 0.0; + double best_score = INFINITY; + for (int candidate = 0; candidate < 8; ++candidate) { + const double angle = angles[candidate]; + if (!(angle >= 0.0 && angle <= PI)) { + continue; + } + const double score = + std::fabs(echoes[candidate] * e2 - target) + 1e-12 * angle; + if (score < best_score) { + best_score = score; + best = angle; + } + } + return best; +} + +struct Inverse { + Batch batch; + const double* target; + // The first pulse's flip angle per train, or null for it to be solved + // like the others. + const double* first_flip; + double* flip; + double* achieved; +}; + +// Trains ``begin`` to ``end``: the flip angles that give the prescribed +// echoes, and the echoes they do give. Echoes past a train's length are left +// at zero. +BLOCHSIM_TRAIN_CLONES +void inverse_range( + const Inverse& problem, const std::int64_t begin, const std::int64_t end +) { + const Batch& batch = problem.batch; + const std::size_t echoes = static_cast(batch.echoes); + const bool relaxing = batch.relaxing(); + States along(echoes + 1); + for (std::int64_t train = begin; train < end; ++train) { + const std::size_t row = static_cast(train) * echoes; + const std::size_t length = static_cast(batch.lengths[train]); + // An order is reached one shift at a time and has as many shifts to + // come back by, so none past the train's length reaches an echo. + const std::size_t states = length + 1; + along.clear(states); + along.plus[0] = 1.0; + along.minus[0] = 1.0; + for (std::size_t echo = 0; echo < length; ++echo) { + const double e1 = echo == 0 ? batch.e1_first : batch.e1; + const double e2 = echo == 0 ? batch.e2_first : batch.e2; + if (relaxing) { + along.relax(e1, e2); + } + along.shift(states, subspace::ALONG_AXIS); + const double angle = (echo == 0 && problem.first_flip != nullptr) + ? problem.first_flip[train] + : refocusing_angle( + along.plus[1], along.minus[1], along.longitudinal[1], + problem.target[row + echo], e2 + ); + along.rotate(angle); + if (relaxing) { + along.relax(e1, e2); + } + along.shift(states, subspace::ALONG_AXIS); + problem.flip[row + echo] = angle; + problem.achieved[row + echo] = along.plus[0]; + } + for (std::size_t echo = length; echo < echoes; ++echo) { + problem.flip[row + echo] = 0.0; + problem.achieved[row + echo] = 0.0; + } + } +} + +struct Forward { + Batch batch; + const double* flip; + double* echo; +}; + +// Trains ``begin`` to ``end``: the echoes of given flip angles. +BLOCHSIM_TRAIN_CLONES +void forward_range( + const Forward& problem, const std::int64_t begin, const std::int64_t end +) { + const Batch& batch = problem.batch; + const std::size_t echoes = static_cast(batch.echoes); + const bool relaxing = batch.relaxing(); + States along(echoes + 1); + for (std::int64_t train = begin; train < end; ++train) { + const std::size_t row = static_cast(train) * echoes; + const std::size_t length = static_cast(batch.lengths[train]); + const std::size_t states = length + 1; + along.clear(states); + along.plus[0] = 1.0; + along.minus[0] = 1.0; + for (std::size_t echo = 0; echo < length; ++echo) { + const double e1 = echo == 0 ? batch.e1_first : batch.e1; + const double e2 = echo == 0 ? batch.e2_first : batch.e2; + if (relaxing) { + along.relax(e1, e2); + } + along.shift(states, subspace::ALONG_AXIS); + along.rotate(problem.flip[row + echo]); + if (relaxing) { + along.relax(e1, e2); + } + along.shift(states, subspace::ALONG_AXIS); + problem.echo[row + echo] = along.plus[0]; + } + for (std::size_t echo = length; echo < echoes; ++echo) { + problem.echo[row + echo] = 0.0; + } + } +} + +// Deal the trains to the pool in contiguous shares. +template +void run(const Problem& problem, const int requested_threads, const Kernel kernel) { + const std::int64_t count = problem.batch.count; + // ``worker_count`` gives a slot to every MIN_WORK_PER_THREAD items of an + // unrequested count, so the trains are counted in the units that makes + // TRAINS_PER_WORKER of them. + const unsigned int slots = worker_count( + requested_threads, + requested_threads > 0 + ? count + : count * blochsim::MIN_WORK_PER_THREAD / TRAINS_PER_WORKER + ); + const std::int64_t share = (count + slots - 1) / slots; + WorkerPool::instance().run(slots, [&](const unsigned int slot) { + const std::int64_t begin = static_cast(slot) * share; + const std::int64_t end = std::min(count, begin + share); + if (begin < end) { + kernel(problem, begin, end); + } + }); +} + +bool parse_pointer(PyObject* sequence, const Py_ssize_t index, void** pointer) { + PyObject* value = PySequence_GetItem(sequence, index); + if (value == nullptr) { + return false; + } + *pointer = PyLong_AsVoidPtr(value); + Py_DECREF(value); + return *pointer != nullptr || !PyErr_Occurred(); +} + +bool unpack(PyObject* pointers, const Py_ssize_t expected, std::vector& raw) { + if (PySequence_Size(pointers) != expected) { + PyErr_SetString(PyExc_ValueError, "wrong number of buffers"); + return false; + } + raw.resize(static_cast(expected)); + for (Py_ssize_t index = 0; index < expected; ++index) { + if (!parse_pointer(pointers, index, &raw[static_cast(index)])) { + return false; + } + } + return true; +} + +// A batch with nothing in it has nothing to compute; one whose shape does not +// describe its buffers must not be walked. +bool describe( + Batch& batch, const long long count, const long long echoes, + const void* lengths +) { + if (count < 0 || echoes < 1 || lengths == nullptr) { + PyErr_SetString(PyExc_ValueError, "a batch needs its lengths and an echo"); + return false; + } + batch.count = count; + batch.echoes = echoes; + batch.lengths = static_cast(lengths); + for (long long train = 0; train < count; ++train) { + if (batch.lengths[train] < 1 || batch.lengths[train] > echoes) { + PyErr_SetString( + PyExc_ValueError, "a train's length is outside its batch's echoes" + ); + return false; + } + } + return true; +} + +PyObject* inverse(PyObject*, PyObject* arguments) { + PyObject* pointers = nullptr; + long long count = 0; + long long echoes = 0; + Inverse problem{}; + Batch& batch = problem.batch; + int threads = 0; + if (!PyArg_ParseTuple( + arguments, "OLLddddi", &pointers, &count, &echoes, &batch.e1_first, + &batch.e2_first, &batch.e1, &batch.e2, &threads + )) { + return nullptr; + } + std::vector raw; + if (!unpack(pointers, 5, raw) || !describe(batch, count, echoes, raw[0])) { + return nullptr; + } + problem.target = static_cast(raw[1]); + problem.first_flip = static_cast(raw[2]); + problem.flip = static_cast(raw[3]); + problem.achieved = static_cast(raw[4]); + Py_BEGIN_ALLOW_THREADS + run(problem, threads, inverse_range); + Py_END_ALLOW_THREADS + Py_RETURN_NONE; +} + +PyObject* forward(PyObject*, PyObject* arguments) { + PyObject* pointers = nullptr; + long long count = 0; + long long echoes = 0; + Forward problem{}; + Batch& batch = problem.batch; + int threads = 0; + if (!PyArg_ParseTuple( + arguments, "OLLddddi", &pointers, &count, &echoes, &batch.e1_first, + &batch.e2_first, &batch.e1, &batch.e2, &threads + )) { + return nullptr; + } + std::vector raw; + if (!unpack(pointers, 3, raw) || !describe(batch, count, echoes, raw[0])) { + return nullptr; + } + problem.flip = static_cast(raw[1]); + problem.echo = static_cast(raw[2]); + Py_BEGIN_ALLOW_THREADS + run(problem, threads, forward_range); + Py_END_ALLOW_THREADS + Py_RETURN_NONE; +} + +PyMethodDef methods[] = { + {"inverse", inverse, METH_VARARGS, + "Flip angles whose CPMG echoes follow a prescription."}, + {"forward", forward, METH_VARARGS, "CPMG echoes of given flip angles."}, + {nullptr, nullptr, 0, nullptr}, +}; + +PyModuleDef module = { + PyModuleDef_HEAD_INIT, "blochsim._trains_cpu", + "Torch-free refocusing-train design kernels.", -1, methods, + nullptr, nullptr, nullptr, nullptr, +}; + +} // namespace + +PyMODINIT_FUNC PyInit__trains_cpu() { return PyModule_Create(&module); } diff --git a/src/blochsim/trains/__init__.py b/src/blochsim/trains/__init__.py new file mode 100644 index 00000000..b4035d24 --- /dev/null +++ b/src/blochsim/trains/__init__.py @@ -0,0 +1,17 @@ +"""Refocusing trains whose echoes follow a prescription. + +Everything here runs on the host in double precision and takes and returns +NumPy arrays; importing it does not import PyTorch. +""" + +from __future__ import annotations + +__all__ = [ + "busse_centre_echo", + "busse_flips", + "effective_te", + "prescribed_flips", +] + +from ._busse import busse_centre_echo, busse_flips +from ._prescribed import effective_te, prescribed_flips diff --git a/src/blochsim/trains/_busse.py b/src/blochsim/trains/_busse.py new file mode 100644 index 00000000..3a6ad01e --- /dev/null +++ b/src/blochsim/trains/_busse.py @@ -0,0 +1,628 @@ +"""Busse refocusing trains: a prescribed pseudo-steady-state signal, inverted.""" + +from __future__ import annotations + +__all__ = ["busse_centre_echo", "busse_flips"] + +from operator import index + +import numpy as np +import numpy.typing as npt + +from ._prescribed import AUTO_THREADS, equivalent_te, inverse_rows, relaxation + +#: No relaxation: the prescription is of coherence, not of a tissue's signal. +_FREE = (1.0, 1.0, 1.0, 1.0) +#: Echoes the opening transient is given before the ramp to the centre starts. +_RAMP_START = 5 +#: The step the shooting Jacobian is differenced over, in degrees. +_STEP_DEG = 1e-3 +#: Newton steps a train is given, the halvings a step is, the steps a +#: bracket is closed in, and the residual a train stops at, in degrees. +_NEWTON_STEPS = 40 +_HALVINGS = 8 +_BRACKET_STEPS = 80 +_CONVERGED_DEG = 1e-10 +#: What a solved train is held to: its three angles, in degrees, and the +#: echoes it gives against the ones prescribed. +_ANGLE_TOLERANCE_DEG = 1e-6 +_SIGNAL_TOLERANCE = 1e-10 +#: Degrees of residual a unit of echo out of reach counts for. +_SHORTFALL_DEG = 360.0 + + +def _pss(flip_deg: np.ndarray) -> np.ndarray: + """Pseudo-steady-state echo amplitude of a constant train of one flip angle. + + ``sqrt(s) * P(s * (1 + sin(alpha)**2 / (8 * s**4)))`` with ``s`` the sine of + half the angle and ``P`` the Legendre function of degree -1/2, which is + the reciprocal of an arithmetic-geometric mean. + """ + angle = np.deg2rad(flip_deg) + sine = np.sin(angle / 2) + with np.errstate(invalid="ignore", divide="ignore"): + argument = sine * (1 + np.sin(angle) ** 2 / (8 * sine**4)) + arithmetic = np.ones_like(argument) + geometric = np.sqrt((1 + argument) / 2) + for _ in range(10): + arithmetic, geometric = ( + (arithmetic + geometric) / 2, + np.sqrt(arithmetic * geometric), + ) + return np.sqrt(sine) / arithmetic + + +def _target( + controls: np.ndarray, + lengths: np.ndarray, + centres: np.ndarray, + max_flip: np.ndarray, + decay: np.ndarray, + echoes: int, +) -> np.ndarray: + """The prescribed echoes of ``(trains, 3)`` pseudo-steady-state controls. + + The controls are flip angles whose pseudo-steady-state amplitudes the + signal passes through: the first at the end of the opening transient, the + second at the centre echo, the third at the last echo. + """ + low, middle, final = _pss(controls.T)[:, :, None] + echo = np.arange(echoes)[None, :] + centre = centres[:, None] + with np.errstate(invalid="ignore", divide="ignore"): + ramp = np.clip((echo - _RAMP_START) / (centre - _RAMP_START), 0, 1) ** 1.5 + signal = low + (middle - low) * ramp + signal = np.where( + echo > centre, + middle + + (final - middle) * (echo - centre) / (lengths[:, None] - 1 - centre), + signal, + ) + first = np.sin(np.deg2rad(max_flip[:, None] / 2)) ** 2 + return signal + (first - low) * np.exp(-echo / decay[:, None]) + + +class _Trains: + """A batch of trains to solve: what each is asked for, and how to try it. + + The inversion is causal: the angles up to an echo answer to the echoes + prescribed up to it and to nothing after. So the first two controls, which + shape the prescription up to the centre echo, are solved against the + lowest angle before the centre and the angle at it, on the trains cut at + their centres; the third, which only sets the rise past the centre, is + then solved against the last angle alone. + """ + + def __init__( + self, + lengths: np.ndarray, + centres: np.ndarray, + wanted: np.ndarray, + decay: np.ndarray, + threads: int, + ) -> None: + self.lengths = lengths + self.centres = centres + self.wanted = wanted + self.decay = decay + self.threads = threads + + def evaluate( + self, controls: np.ndarray, rows: np.ndarray, opening: bool = False + ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]: + """Try ``controls`` on the trains ``rows``, which may repeat. + + Returns the three angles each trial plays less the ones it is asked + for, with what its echoes fall short by added in; its flip angles in + degrees; its echoes; and the echoes prescribed. With ``opening`` the + trains are cut after their centre echoes, which is all the first two + controls reach, and the third residual is not formed. + + An echo out of reach gets the nearest angle whatever the controls + are, so the angles alone stop answering to them. What the echoes + fall short by does not, and it is added where the level it answers + to is: before the centre, at it, and past it. A train that meets its + prescription falls short of nothing, so the roots are the same. + """ + centres = self.centres[rows] + lengths = centres + 1 if opening else self.lengths[rows] + wanted = self.wanted[rows] + echoes = int(lengths.max()) + target = _target( + controls, + self.lengths[rows], + centres, + wanted[:, 2], + self.decay[rows], + echoes, + ) + flip, achieved = inverse_rows( + target, lengths, np.deg2rad(wanted[:, 2]), _FREE, self.threads + ) + flip = np.rad2deg(flip) + echo = np.arange(echoes)[None, :] + centre = centres[:, None] + each = np.arange(len(rows)) + short = _SHORTFALL_DEG * np.where( + echo < lengths[:, None], target - achieved, 0.0 + ) + residual = np.column_stack( + ( + np.where((echo >= 1) & (echo < centre), flip, np.inf).min(axis=1) + + np.where(echo < centre, short, 0.0).sum(axis=1), + flip[each, centres] + short[each, centres], + flip[each, lengths - 1] + + np.where(echo > centre, short, 0.0).sum(axis=1), + ) + ) + return residual - wanted, flip, achieved, target + + def accepted( + self, controls: np.ndarray, rows: np.ndarray + ) -> tuple[np.ndarray, np.ndarray]: + """Whether each trial is a train that meets its prescription, and its flips.""" + residual, flip, achieved, target = self.evaluate(controls, rows) + wanted = self.wanted[rows] + played = np.arange(flip.shape[1])[None, :] < self.lengths[rows, None] + with np.errstate(invalid="ignore"): + valid = ( + np.all(np.isfinite(np.where(played, flip, 0.0)), axis=1) + & (np.abs(residual).max(axis=1) < _ANGLE_TOLERANCE_DEG) + & np.all( + np.where(played, np.abs(achieved - target), 0.0) + < _SIGNAL_TOLERANCE, + axis=1, + ) + & np.all( + np.where( + played, flip >= wanted[:, :1] - _ANGLE_TOLERANCE_DEG, True + ), + axis=1, + ) + & np.all( + np.where( + played, flip <= wanted[:, 2:] + _ANGLE_TOLERANCE_DEG, True + ), + axis=1, + ) + & (controls[:, 0] > 0) + & np.all(np.diff(controls, axis=1) > 0, axis=1) + & (controls[:, 2] < 180) + ) + return valid, np.where(played, flip, 0.0) + + def _opening(self, controls: np.ndarray, rows: np.ndarray) -> np.ndarray: + """The two residuals the first two controls answer to.""" + return self.evaluate(controls, rows, opening=True)[0][:, :2] + + def newton(self, controls: np.ndarray, rows: np.ndarray) -> np.ndarray: + """The first two controls of ``rows`` by damped Newton steps, in place. + + The Jacobian is differenced, and a step is halved until it brings + the residual down: the residual has kinks, where the lowest angle + moves to another echo or an echo comes within reach. A train stops + at its own residual and takes no further part, so what it converges + to does not depend on the batch it was solved in. Returns which + trains converged. + """ + active = np.arange(len(rows)) + base = self._opening(controls, rows) + converged = np.zeros(len(rows), dtype=bool) + offsets = _STEP_DEG * np.eye(3)[:2] + for _ in range(_NEWTON_STEPS): + with np.errstate(invalid="ignore"): + done = np.abs(base).max(axis=1) < _CONVERGED_DEG + converged[active[done]] = True + active, base = active[~done], base[~done] + if not active.size: + break + count = active.size + probes = np.concatenate([controls[active] + offset for offset in offsets]) + probed = self._opening(probes, np.tile(rows[active], 2)) + jacobian = np.stack( + [ + (probed[:count] - base) / _STEP_DEG, + (probed[count:] - base) / _STEP_DEG, + ], + axis=-1, + ) + with np.errstate(invalid="ignore"): + determinant = np.linalg.det(jacobian) + solvable = ( + np.isfinite(determinant) + & (np.abs(determinant) > 1e-300) + & np.all(np.isfinite(base), axis=1) + ) + active, base = active[solvable], base[solvable] + correction = np.clip( + np.linalg.solve(jacobian[solvable], base[..., None])[..., 0], -10, 10 + ) + size = np.linalg.norm(base, axis=1) + pending = np.arange(active.size) + taken = np.zeros(active.size, dtype=bool) + for halving in range(_HALVINGS + 1): + if not pending.size: + break + trial = controls[active[pending]].copy() + trial[:, :2] -= correction[pending] / 2**halving + tried = self._opening(trial, rows[active[pending]]) + with np.errstate(invalid="ignore"): + better = np.linalg.norm(tried, axis=1) < size[pending] + controls[active[pending[better]]] = trial[better] + base[pending[better]] = tried[better] + taken[pending[better]] = True + pending = pending[~better] + # A train no step improves has stalled, and is left where it is. + active, base = active[taken], base[taken] + return converged + + def hybrid(self, row: int) -> np.ndarray: + """The first two controls of one train from MINPACK's hybrid method. + + It follows a root across kinks a damped Newton step can stall at. + """ + from scipy.optimize import root + + rows = np.array([row]) + trial = self.wanted[row : row + 1].copy() + + def residual(controls: np.ndarray) -> np.ndarray: + trial[0, :2] = controls + return self._opening(trial, rows)[0] + + trial[0, :2] = root(residual, self.wanted[row, :2], tol=1e-9).x + return trial + + def closing(self, controls: np.ndarray, rows: np.ndarray) -> None: + """The third control of ``rows``, in place, bracketed and closed in on. + + Between the second control, where the prescription is flat past the + centre, and 180 degrees, where it rises to the whole echo, the last + angle crosses the one asked for. The bracket is closed by false + position with the Illinois correction, which cannot leave it. + """ + + def last(third: np.ndarray, which: np.ndarray) -> np.ndarray: + trial = controls[which].copy() + trial[:, 2] = third + return self.evaluate(trial, rows[which])[0][:, 2] + + every = np.arange(len(rows)) + low = controls[:, 1].copy() + high = np.full(len(rows), 180.0 - 1e-9) + at_low, at_high = last(low, every), last(high, every) + # Which end the last step left in place: -1 the low one, 1 the high. + kept = np.zeros(len(rows), dtype=np.int8) + with np.errstate(invalid="ignore"): + active = np.flatnonzero((at_low < 0) & (at_high > 0)) + controls[:, 2] = np.nan + for _ in range(_BRACKET_STEPS): + if not active.size: + break + a, b = low[active], high[active] + fa, fb = at_low[active], at_high[active] + third = b - fb * (b - a) / (fb - fa) + value = last(third, active) + controls[active, 2] = third + below = value < 0 + # An end left in place twice running has its value halved, or + # it would hold the bracket open while the other end crept up. + again = kept[active] == np.where(below, 1, -1) + at_high[active] = np.where(below, np.where(again, fb / 2, fb), value) + at_low[active] = np.where(below, value, np.where(again, fa / 2, fa)) + high[active] = np.where(below, b, third) + low[active] = np.where(below, third, a) + kept[active] = np.where(below, 1, -1) + with np.errstate(invalid="ignore"): + active = active[ + np.isfinite(value) + & (np.abs(value) >= _CONVERGED_DEG) + & (high[active] - low[active] > 1e-13) + ] + + def solve(self) -> tuple[np.ndarray, np.ndarray]: + """Flip angles in degrees, zero past each train, and which trains exist.""" + rows = np.arange(len(self.lengths)) + controls = self.wanted.copy() + converged = self.newton(controls, rows) + for row in np.flatnonzero(~converged): + one = rows[row : row + 1] + trial = self.hybrid(int(row)) + if self.newton(trial, one)[0]: + controls[one] = trial + self.closing(controls, rows) + return self.accepted(controls, rows)[::-1] + + +def _integers(values: npt.ArrayLike, name: str) -> np.ndarray: + """``values`` as integers, refusing what only rounds to one.""" + array = np.asarray(values) + if array.dtype == bool or not ( + np.issubdtype(array.dtype, np.integer) + or (array.dtype == object and all(_is_index(v) for v in array.ravel())) + ): + raise ValueError(f"{name} must be an integer") + return array.astype(np.int64) + + +def _is_index(value: object) -> bool: + if isinstance(value, (bool, np.bool_)): + return False + try: + index(value) # type: ignore[arg-type] + except TypeError: + return False + return True + + +def _prescription( + length: npt.ArrayLike, + min_flip: npt.ArrayLike, + centre_flip: npt.ArrayLike, + max_flip: npt.ArrayLike, + initial_decay: npt.ArrayLike, +) -> tuple[tuple[int, ...], np.ndarray, np.ndarray, np.ndarray]: + """The batch shape, and each train's length, three angles and decay.""" + lengths = _integers(length, "length") + arrays = np.broadcast_arrays( + lengths, + np.asarray(min_flip, dtype=float), + np.asarray(centre_flip, dtype=float), + np.asarray(max_flip, dtype=float), + np.asarray(initial_decay, dtype=float), + ) + shape = arrays[0].shape + lengths = arrays[0].reshape(-1) + wanted = np.stack([array.reshape(-1) for array in arrays[1:4]], axis=1) + decay = arrays[4].reshape(-1) + if np.any(lengths < 1): + raise ValueError("length must be positive") + with np.errstate(invalid="ignore"): + ordered = ( + np.all(np.isfinite(wanted), axis=1) + & (wanted[:, 0] > 0) + & (wanted[:, 0] < wanted[:, 1]) + & (wanted[:, 1] < wanted[:, 2]) + & (wanted[:, 2] < 180) + ) + if not np.all(ordered): + raise ValueError( + "flip angles must satisfy 0 < min_flip < centre_flip < max_flip < 180" + ) + if not np.all(np.isfinite(decay)) or np.any(decay <= 0): + raise ValueError("initial_decay must be positive and finite") + return shape, lengths, wanted, decay + + +def busse_flips( + length: npt.ArrayLike, + *, + min_flip: npt.ArrayLike = 25.0, + centre_flip: npt.ArrayLike = 70.0, + max_flip: npt.ArrayLike = 120.0, + centre_echo: npt.ArrayLike | None = None, + startup_echoes: npt.ArrayLike = 6, + initial_decay: npt.ArrayLike = 1.3, + threads: int = AUTO_THREADS, +) -> np.ndarray: + """Variable refocusing flip angles of a long echo train, after Busse. + + The echo signal is prescribed without relaxation: an opening transient + from the first echo, a rise through the centre echo, and a linear rise to + the last one, each level the pseudo-steady-state amplitude of a flip + angle [1]_ [2]_. :func:`prescribed_flips` inverts it, and the three levels + are found by shooting so that the angles played are the ones asked for: + the lowest before the centre is ``min_flip``, the centre echo's is + ``centre_flip``, and the first and the last are ``max_flip``. + + Every argument may be an array; they broadcast, and each element is a + train of its own. The trains are solved together. + + Parameters + ---------- + length : int or array-like + Refocusing pulses of the train, startup pulses included. + min_flip : float or array-like, default=25.0 + Lowest flip angle before the centre echo, in degrees. + centre_flip : float or array-like, default=70.0 + Flip angle at the centre echo, in degrees. + max_flip : float or array-like, default=120.0 + Flip angle of the first and the last pulse, in degrees. + centre_echo : int or array-like, default=None + Zero-based index of the pulse whose echo samples the centre of + k-space, startup pulses included. By default the middle of what + follows the startup pulses, + ``startup_echoes + (length - startup_echoes - 1) // 2``. + startup_echoes : int or array-like, default=6 + Leading pulses whose echoes are not acquired; they only place the + default centre echo. + initial_decay : float or array-like, default=1.3 + Time constant of the opening transient, in echoes. + threads : int, default=0 + Threads to spread the trains over; 0 sizes the pool to the batch. + + Returns + ------- + numpy.ndarray + Flip angles in degrees: shape ``(length,)`` for one train, and + ``(..., max(length))`` for a batch, zero past each train's last pulse. + + Raises + ------ + ValueError + If a count or an angle is not valid, a centre echo is not after the + sixth pulse and before the last, or no train meets a prescription. + + Notes + ----- + The rise to the centre follows a power of 1.5 and the one after it is + linear [2]_. The flip angles do not depend on the echo spacing; what + relaxation makes of them is :func:`effective_te`'s and the simulators'. + + References + ---------- + .. [1] Busse RF, Hariharan H, Vu A, Brittain JH. Fast spin echo sequences + with very long echo trains: design of variable refocusing flip angle + schedules and generation of clinical T2 contrast. Magn Reson Med. + 2006;55:1030-1037. + .. [2] Busse RF, Brau ACS, Vu A, et al. Effects of refocusing flip angle + modulation and view ordering in 3D fast spin echo. Magn Reson Med. + 2008;60:640-649. + + Examples + -------- + >>> import numpy as np + >>> from blochsim.trains import busse_flips + >>> flip = busse_flips(106) + >>> bool(np.allclose([flip[1:55].min(), flip[55], flip[-1]], [25, 70, 120])) + True + + """ + shape, lengths, wanted, decay = _prescription( + length, min_flip, centre_flip, max_flip, initial_decay + ) + startup = np.broadcast_to(_integers(startup_echoes, "startup_echoes"), shape) + startup = startup.reshape(-1) + if np.any(startup < 0) or np.any(startup >= lengths): + raise ValueError("startup_echoes must lie in [0, length)") + if centre_echo is None: + centres = startup + (lengths - startup - 1) // 2 + else: + centres = np.broadcast_to(_integers(centre_echo, "centre_echo"), shape) + centres = centres.reshape(-1) + if np.any(centres <= _RAMP_START) or np.any(centres >= lengths - 1): + raise ValueError( + "centre_echo must be after the sixth pulse and before the last" + ) + flip, feasible = _Trains(lengths, centres, wanted, decay, threads).solve() + if not np.all(feasible): + missing = np.flatnonzero(~feasible) + raise ValueError( + "no Busse train meets the prescription of " + + ( + "the train" + if len(lengths) == 1 + else f"trains {', '.join(map(str, missing[:8]))}" + ) + ) + return flip.reshape(*shape, flip.shape[-1]) + + +def busse_centre_echo( + TE: float, + length: npt.ArrayLike, + ESP: float, + *, + first_ESP: float | None = None, + min_flip: npt.ArrayLike = 25.0, + centre_flip: npt.ArrayLike = 70.0, + max_flip: npt.ArrayLike = 120.0, + startup_echoes: int = 6, + initial_decay: float = 1.3, + T1: float = 1000.0, + T2: float = 100.0, + threads: int = AUTO_THREADS, +) -> tuple[int, float]: + """The centre echo whose contrast-equivalent echo time is nearest ``TE``. + + A Busse train is designed around its centre echo, so moving the centre + changes the train and with it the contrast the centre is acquired at. + Every centre the trains allow is tried at once: the train is designed for + it, and :func:`effective_te` of its centre echo is compared with ``TE``. + + ``length`` and the three angles broadcast to several trains that share + the centre echo -- the trains of a shot-dependent schedule. A centre is + kept only when every one of them can be designed for it, and the echo + time is that of the first. + + Parameters + ---------- + TE : float + Contrast-equivalent echo time asked for, in ms. + length : int or array-like + Refocusing pulses of each train, startup pulses included. + ESP : float + Echo spacing, in ms. + first_ESP : float, default=None + Time from the excitation to the first echo, in ms; ``ESP`` by default. + min_flip : float or array-like, default=25.0 + Lowest flip angle before the centre echo, in degrees. + centre_flip : float or array-like, default=70.0 + Flip angle at the centre echo, in degrees. + max_flip : float or array-like, default=120.0 + Flip angle of the first and the last pulse, in degrees. + startup_echoes : int, default=6 + Leading pulses whose echoes are not acquired. The centre is an + acquired echo. + initial_decay : float, default=1.3 + Time constant of the opening transient, in echoes. + T1 : float, default=1000.0 + Longitudinal relaxation time of the reference tissue, in ms. + T2 : float, default=100.0 + Transverse relaxation time of the reference tissue, in ms. + threads : int, default=0 + Threads to spread the trains over; 0 sizes the pool to the batch. + + Returns + ------- + centre_echo : int + Zero-based index of the centre pulse, startup pulses included. Of two + centres equally near, the earlier. + TE : float + Its contrast-equivalent echo time, in ms. + + Raises + ------ + ValueError + If ``TE``, the timing or a prescription is not valid, or no centre + gives every train a design. + + Examples + -------- + >>> from blochsim.trains import busse_centre_echo + >>> centre, te = busse_centre_echo(60.0, 66, 3.672, max_flip=100.0) + >>> centre + 38 + + """ + if not np.isfinite(TE) or TE <= 0: + raise ValueError("TE must be positive and finite") + if not np.all(np.isfinite([T1, T2])): + raise ValueError("the reference T1 and T2 must be finite") + relax = relaxation(ESP, first_ESP, T1, T2) + _, lengths, wanted, _ = _prescription( + length, min_flip, centre_flip, max_flip, initial_decay + ) + startup = int(_integers(startup_echoes, "startup_echoes")) + if startup < 0: + raise ValueError("startup_echoes must not be negative") + # Trains asked for twice are designed once; the first stays first. + trains = np.column_stack((lengths, wanted)) + _, first = np.unique(trains, axis=0, return_index=True) + keep = np.sort(first) + lengths, wanted = lengths[keep], wanted[keep] + candidates = np.arange( + max(startup, _RAMP_START + 1), int(lengths.min()) - 1, dtype=np.int64 + ) + if not candidates.size: + raise ValueError("the trains are too short to have a centre echo") + trials, shared = len(candidates), len(lengths) + flip, feasible = _Trains( + np.tile(lengths, trials), + np.repeat(candidates, shared), + np.tile(wanted, (trials, 1)), + np.full(trials * shared, float(initial_decay)), + threads, + ).solve() + feasible = feasible.reshape(trials, shared).all(axis=1) + equivalent = equivalent_te( + np.deg2rad(flip[::shared]), candidates + 1, relax, T2, threads + )[np.arange(trials), candidates] + usable = feasible & np.isfinite(equivalent) + if not np.any(usable): + raise ValueError( + "no centre echo gives every train a Busse design at these angles" + ) + miss = np.where(usable, np.abs(equivalent - TE), np.inf) + best = int(np.argmin(miss)) + return int(candidates[best]), float(equivalent[best]) diff --git a/src/blochsim/trains/_prescribed.py b/src/blochsim/trains/_prescribed.py new file mode 100644 index 00000000..987e20b2 --- /dev/null +++ b/src/blochsim/trains/_prescribed.py @@ -0,0 +1,296 @@ +"""The train kernels of the C++ extension, over NumPy arrays. + +The extension takes data pointers, so what it is given has to be contiguous, +of the type it reads, and alive for the call. That is what the private +functions here are for; the public ones are those two with units. +""" + +from __future__ import annotations + +__all__ = ["effective_te", "prescribed_flips"] + +import numpy as np +import numpy.typing as npt + +from .._trains_cpu import forward, inverse + +#: Let the extension's pool size itself against the work. +AUTO_THREADS = 0 + + +def relaxation( + ESP: float | None, first_ESP: float | None, T1: float, T2: float +) -> tuple[float, float, float, float]: + """Relaxation over half an echo interval: ``(e1_first, e2_first, e1, e2)``. + + The first pair is the interval from the excitation to the first echo, the + second every later one. Times are in ms; an infinite relaxation time is no + relaxation, and without any the spacing is not needed. + """ + times = np.asarray([T1, T2], dtype=float) + if np.any(np.isnan(times)) or np.any(times <= 0): + raise ValueError("T1 and T2 must be positive") + if ESP is None: + if np.all(np.isinf(times)) and first_ESP is None: + return 1.0, 1.0, 1.0, 1.0 + raise ValueError("relaxation and first_ESP need the echo spacing ESP") + first = ESP if first_ESP is None else first_ESP + spacing = np.asarray([first, ESP], dtype=float) + if not np.all(np.isfinite(spacing)) or np.any(spacing <= 0): + raise ValueError("ESP and first_ESP must be positive and finite") + e1_first, e1 = np.exp(-spacing / 2 / T1) + e2_first, e2 = np.exp(-spacing / 2 / T2) + return float(e1_first), float(e2_first), float(e1), float(e2) + + +def _rows(values: npt.ArrayLike, name: str) -> tuple[np.ndarray, tuple[int, ...]]: + """``values`` as contiguous float64 ``(trains, echoes)``, and its batch shape.""" + array = np.asarray(values, dtype=np.float64) + if array.ndim < 1 or array.shape[-1] < 1: + raise ValueError(f"{name} needs its echoes on the last axis") + return np.ascontiguousarray(array.reshape(-1, array.shape[-1])), array.shape[:-1] + + +def _lengths( + lengths: npt.ArrayLike | None, shape: tuple[int, ...], echoes: int +) -> np.ndarray: + """The echoes each train of a batch of ``shape`` plays, one per train.""" + if lengths is None: + return np.full(int(np.prod(shape)), echoes, dtype=np.int64) + played = np.ascontiguousarray(np.broadcast_to(lengths, shape), dtype=np.int64) + played = played.reshape(-1) + if np.any(played < 1) or np.any(played > echoes): + raise ValueError("lengths must lie in [1, echoes]") + return played + + +def inverse_rows( + target: np.ndarray, + lengths: np.ndarray, + first_rad: np.ndarray | None, + relax: tuple[float, float, float, float], + threads: int = AUTO_THREADS, +) -> tuple[np.ndarray, np.ndarray]: + """Flip angles (rad) and achieved echoes of ``(trains, echoes)`` targets.""" + target = np.ascontiguousarray(target, dtype=np.float64) + lengths = np.ascontiguousarray(lengths, dtype=np.int64) + count, echoes = target.shape + flip = np.empty_like(target) + achieved = np.empty_like(target) + if first_rad is not None: + first_rad = np.ascontiguousarray(first_rad, dtype=np.float64) + inverse( + ( + lengths.ctypes.data, + target.ctypes.data, + 0 if first_rad is None else first_rad.ctypes.data, + flip.ctypes.data, + achieved.ctypes.data, + ), + count, + echoes, + *relax, + threads, + ) + return flip, achieved + + +def forward_rows( + flip_rad: np.ndarray, + lengths: np.ndarray, + relax: tuple[float, float, float, float], + threads: int = AUTO_THREADS, +) -> np.ndarray: + """Echoes of ``(trains, echoes)`` flip angles, in radians.""" + flip_rad = np.ascontiguousarray(flip_rad, dtype=np.float64) + lengths = np.ascontiguousarray(lengths, dtype=np.int64) + count, echoes = flip_rad.shape + echo = np.empty_like(flip_rad) + forward( + (lengths.ctypes.data, flip_rad.ctypes.data, echo.ctypes.data), + count, + echoes, + *relax, + threads, + ) + return echo + + +def equivalent_te( + flip_rad: np.ndarray, + lengths: np.ndarray, + relax: tuple[float, float, float, float], + T2: float, + threads: int = AUTO_THREADS, +) -> np.ndarray: + """Contrast-equivalent echo times (ms) of ``(trains, echoes)`` flip angles.""" + relaxed = np.abs(forward_rows(flip_rad, lengths, relax, threads)) + free = np.abs(forward_rows(flip_rad, lengths, (1.0, 1.0, 1.0, 1.0), threads)) + with np.errstate(invalid="ignore", divide="ignore"): + equivalent = -T2 * np.log(relaxed / free) + return np.where(free > 1e-12, equivalent, np.nan) + + +def prescribed_flips( + signal: npt.ArrayLike, + *, + first_flip: npt.ArrayLike | None = None, + ESP: float | None = None, + first_ESP: float | None = None, + T1: float = np.inf, + T2: float = np.inf, + lengths: npt.ArrayLike | None = None, + threads: int = AUTO_THREADS, +) -> tuple[np.ndarray, np.ndarray]: + """Refocusing flip angles whose echoes take prescribed amplitudes. + + The train is the CPMG arrangement: an ideal 90 degree excitation a quarter + turn from the refocusing pulses, each pulse midway between two echoes. The + extended phase graph is inverted one echo at a time: the states before a + pulse fix the echo after it as a function of its flip angle alone, and the + smallest angle in [0, 180] degrees giving the prescribed amplitude is + taken. An amplitude no angle reaches gets the angle that comes nearest, + so the returned echoes are the test of a prescription: they equal it + exactly where it can be met. + + Parameters + ---------- + signal : array-like + Prescribed echo amplitudes, as fractions of the excited magnetization, + shape ``(..., echoes)``. + first_flip : float or array-like, default=None + Flip angle of the first pulse, in degrees, one per train. The first + echo is then what that pulse gives and its prescription is not read. + ESP : float, default=None + Echo spacing, in ms. Needed only with relaxation. + first_ESP : float, default=None + Time from the excitation to the first echo, in ms; ``ESP`` by default. + T1 : float, default=np.inf + Longitudinal relaxation time the amplitudes are prescribed under, in + ms. The default is no relaxation. + T2 : float, default=np.inf + Transverse relaxation time the amplitudes are prescribed under, in ms. + The default is no relaxation. + lengths : int or array-like, default=None + Echoes each train plays, when the trains of a batch differ in length; + what follows a train's last echo is returned as zero. + threads : int, default=0 + Threads to spread the trains over; 0 sizes the pool to the batch. + + Returns + ------- + flip : numpy.ndarray + Refocusing flip angles, in degrees, shaped like ``signal``. + achieved : numpy.ndarray + The echo amplitudes those angles give, shaped like ``signal``. + + Raises + ------ + ValueError + If the timing, the relaxation times or the lengths are not valid. + + Notes + ----- + The magnetization that recovers during the train is excited across the + refocusing axis and refocuses at the pulses, not at the echoes, so an + echo holds none of it: T1 enters only through the decay of what the + train stores along z. + + Examples + -------- + A constant train of 180 degree pulses is what unit echoes ask for: + + >>> import numpy as np + >>> from blochsim.trains import prescribed_flips + >>> flip, achieved = prescribed_flips(np.ones(8)) + >>> bool(np.allclose(flip, 180.0)) + True + + """ + target, shape = _rows(signal, "signal") + count, echoes = target.shape + relax = relaxation(ESP, first_ESP, T1, T2) + first = None + if first_flip is not None: + first = np.deg2rad(np.broadcast_to(first_flip, shape).reshape(count)) + flip, achieved = inverse_rows( + target, _lengths(lengths, shape, echoes), first, relax, threads + ) + return ( + np.rad2deg(flip).reshape(*shape, echoes), + achieved.reshape(*shape, echoes), + ) + + +def effective_te( + flip: npt.ArrayLike, + ESP: float, + *, + first_ESP: float | None = None, + T1: float = 1000.0, + T2: float = 100.0, + threads: int = AUTO_THREADS, +) -> np.ndarray: + """Contrast-equivalent echo time of every echo of a refocusing train. + + The echo of a train of reduced flip angles has decayed less than its echo + time says, because part of its history was spent stored along z. Its + contrast-equivalent echo time is the time a spin echo would need for the + same T2 decay: ``-T2 * log(S / S0)``, with ``S`` the echo of a reference + tissue and ``S0`` the same echo without relaxation. + + Parameters + ---------- + flip : array-like + Refocusing flip angles, in degrees, shape ``(..., echoes)``, each in + [0, 180]. + ESP : float + Echo spacing, in ms. + first_ESP : float, default=None + Time from the excitation to the first echo, in ms; ``ESP`` by default. + T1 : float, default=1000.0 + Longitudinal relaxation time of the reference tissue, in ms. + T2 : float, default=100.0 + Transverse relaxation time of the reference tissue, in ms. + threads : int, default=0 + Threads to spread the trains over; 0 sizes the pool to the batch. + + Returns + ------- + numpy.ndarray + Contrast-equivalent echo times, in ms, shaped like ``flip``. An echo + with no signal has none, and is ``nan``. + + Raises + ------ + ValueError + If an angle is outside [0, 180] degrees, or the timing or the + relaxation times are not positive and finite. + + Notes + ----- + The train is the one :func:`prescribed_flips` designs: an ideal 90 degree + excitation of fully relaxed magnetization and instantaneous CPMG + refocusing, with no slice profile, off-resonance or transmit variation. + The value depends on the reference tissue; at 180 degrees it is the echo + time itself. + + Examples + -------- + >>> import numpy as np + >>> from blochsim.trains import effective_te + >>> bool(np.allclose(effective_te([180.0] * 3, 4.0), [4.0, 8.0, 12.0])) + True + + """ + angles, shape = _rows(flip, "flip") + if not np.all(np.isfinite(angles)) or np.any((angles < 0) | (angles > 180 + 1e-6)): + raise ValueError("flip must be finite degrees in [0, 180]") + if not np.all(np.isfinite([T1, T2])): + raise ValueError("the reference T1 and T2 must be finite") + relax = relaxation(ESP, first_ESP, T1, T2) + echoes = angles.shape[-1] + equivalent = equivalent_te( + np.deg2rad(angles), _lengths(None, shape, echoes), relax, T2, threads + ) + return equivalent.reshape(*shape, echoes) diff --git a/tests/trains/busse_figure1.json b/tests/trains/busse_figure1.json new file mode 100644 index 00000000..ceaeff8e --- /dev/null +++ b/tests/trains/busse_figure1.json @@ -0,0 +1,229 @@ +{ + "provenance": "The 106-pulse train of Busse et al. 2008, Figure 1, as reconstructed by the NumPy implementation this package's kernel replaced: its flip angles and the echoes they give without relaxation. A reconstruction, not the authors' numerical data.", + "doi": "10.1002/mrm.21680", + "length": 106, + "startup_echoes": 6, + "centre_echo": 55, + "initial_decay": 1.3, + "controls_deg": [ + 25, + 70, + 120 + ], + "angles_deg": [ + 119.99999999999999, + 59.74785588155771, + 40.338263517017154, + 32.55236664834607, + 28.838016222799716, + 26.835505074617615, + 25.763790206506545, + 25.218361324172403, + 25.000000000000785, + 25.012181515364517, + 25.194320636327017, + 25.50249366148105, + 25.9012566991802, + 26.36045189165538, + 26.854502190221073, + 27.36299402602149, + 27.871771679322997, + 28.373891895738936, + 28.869888139932357, + 29.366983248434153, + 29.877174414102058, + 30.4144310742626, + 30.99150724129947, + 31.61701415081407, + 32.293409810891866, + 33.016445408471256, + 33.77636228738025, + 34.56074468819377, + 35.35842663918309, + 36.163351872096804, + 36.97702943133871, + 37.8084572919199, + 38.6711734852652, + 39.57822630818169, + 40.536893774372246, + 41.54544703562358, + 42.593792236156496, + 43.66834995784153, + 44.75939320680691, + 45.86722197332578, + 47.00333101195878, + 48.184940818611835, + 49.42522852910512, + 50.72506829909595, + 52.07240730588443, + 53.451227457012315, + 54.85495833952996, + 56.294112071994526, + 57.790343036437825, + 59.35971258127762, + 60.999084578279536, + 62.68996654845289, + 64.41928230363762, + 66.1974308438414, + 68.05199524101646, + 70.00000000000055, + 71.16058608736941, + 72.10918525318732, + 72.83081584447164, + 73.4915535431081, + 74.21328134419798, + 74.99280585054441, + 75.76257140288553, + 76.49854063079877, + 77.24265710312265, + 78.03005411414908, + 78.83758739548573, + 79.62637462249145, + 80.40512984919697, + 81.21319242418271, + 82.0542023067877, + 82.89184470368556, + 83.71392479566786, + 84.5534874872563, + 85.42963326556105, + 86.31374437701466, + 87.18321977465904, + 88.06419395176212, + 88.98215871220461, + 89.91346339470822, + 90.83261654457061, + 91.76381022681214, + 92.7326368226612, + 93.71435876148553, + 94.6866014892195, + 95.67781214157773, + 96.70698099111095, + 97.74328768085395, + 98.77595962898447, + 99.8399139577236, + 100.93712088030126, + 102.03375728477555, + 103.14202371371401, + 104.29260428399665, + 105.4619730248558, + 106.63321823917754, + 107.84096966115052, + 109.0855832386969, + 110.33568110179645, + 111.61423994813015, + 112.94056692754565, + 114.28251844639985, + 115.65017386765, + 117.07240347493583, + 118.52122942523762, + 120.00000000000216 + ], + "static_signal": [ + 0.7499999999999999, + 0.560116218942646, + 0.4721298910868694, + 0.43135972184737076, + 0.412468074243416, + 0.40371426340943395, + 0.40063174899158455, + 0.4005326085414065, + 0.40196721999305973, + 0.4042938615414796, + 0.4072036680470473, + 0.4105412489737359, + 0.4142239937431248, + 0.4182046660345976, + 0.4224537753793023, + 0.42695113272233676, + 0.43168171958690243, + 0.4366336074934215, + 0.4417968668067652, + 0.4471629632135979, + 0.45272440167005795, + 0.4584745010238197, + 0.4644072412306894, + 0.4705171533901483, + 0.47679923671027036, + 0.48324889349112954, + 0.4898618768377687, + 0.49663424777226317, + 0.5035623395265449, + 0.5106427274642673, + 0.5178722035020418, + 0.525247754181533, + 0.532766541739588, + 0.540425887664761, + 0.5482232583333566, + 0.5561562523975889, + 0.5642225896597888, + 0.5724201012145907, + 0.5807467206790198, + 0.5892004763607508, + 0.5977794842392877, + 0.606481941654665, + 0.6153061216145248, + 0.6242503676437768, + 0.633313089112103, + 0.6424927569837722, + 0.6517878999419183, + 0.6611971008458993, + 0.6707189934858109, + 0.6803522596028551, + 0.6900956261482007, + 0.6999478627563407, + 0.7099077794118331, + 0.7199742242908028, + 0.7301460817607273, + 0.7404222705238823, + 0.7440480386976545, + 0.7476738068714267, + 0.7512995750451991, + 0.7549253432189711, + 0.7585511113927437, + 0.7621768795665158, + 0.7658026477402882, + 0.7694284159140603, + 0.7730541840878326, + 0.7766799522616048, + 0.7803057204353769, + 0.7839314886091494, + 0.7875572567829217, + 0.7911830249566939, + 0.7948087931304662, + 0.7984345613042384, + 0.8020603294780106, + 0.8056860976517828, + 0.8093118658255551, + 0.8129376339993275, + 0.8165634021730998, + 0.820189170346872, + 0.8238149385206442, + 0.8274407066944165, + 0.8310664748681887, + 0.8346922430419608, + 0.8383180112157332, + 0.8419437793895055, + 0.8455695475632778, + 0.84919531573705, + 0.8528210839108223, + 0.8564468520845945, + 0.8600726202583668, + 0.8636983884321392, + 0.8673241566059113, + 0.8709499247796836, + 0.8745756929534556, + 0.8782014611272282, + 0.8818272293010004, + 0.8854529974747727, + 0.8890787656485448, + 0.8927045338223172, + 0.8963303019960893, + 0.8999560701698617, + 0.9035818383436338, + 0.9072076065174062, + 0.9108333746911786, + 0.9144591428649508, + 0.9180849110387229, + 0.9217106792124952 + ] +} \ No newline at end of file diff --git a/tests/trains/test_busse_centre_echo.py b/tests/trains/test_busse_centre_echo.py new file mode 100644 index 00000000..c5dad69e --- /dev/null +++ b/tests/trains/test_busse_centre_echo.py @@ -0,0 +1,83 @@ +"""The centre echo chosen is the nearest one in contrast-equivalent echo time. + +Held to the definition: design the train for every centre, one at a time, +take :func:`effective_te` of each centre echo, and pick the nearest by hand. +""" + +import numpy as np +import pytest + +from blochsim.trains import busse_centre_echo, busse_flips, effective_te + +TIMING = {"ESP": 3.416, "first_ESP": 4.162} + + +def one_at_a_time(length, startup=6, **prescription): + """Equivalent echo time of every centre a train can be designed for.""" + equivalent = {} + for centre in range(max(startup, 6), length - 1): + try: + flip = busse_flips(length, centre_echo=centre, **prescription) + except ValueError: + continue + equivalent[centre] = effective_te(flip[: centre + 1], **TIMING)[-1] + return equivalent + + +@pytest.mark.parametrize("TE", [20.0, 54.0, 80.0, 400.0]) +def test_the_centre_is_the_nearest_of_every_feasible_one(TE): + equivalent = one_at_a_time(46) + expected = min( + equivalent, key=lambda centre: (abs(equivalent[centre] - TE), centre) + ) + centre, achieved = busse_centre_echo(TE, 46, **TIMING) + assert centre == expected + assert achieved == pytest.approx(equivalent[expected], abs=1e-12) + + +def test_the_equivalent_echo_time_grows_with_the_centre(): + equivalent = one_at_a_time(66, max_flip=100.0) + assert np.all(np.diff([equivalent[centre] for centre in sorted(equivalent)]) > 0) + + +def test_a_centre_is_kept_only_when_every_train_has_a_design(): + # Centred on its first acquired echo, the 120 degree train has a design + # and the 100 degree one has none. + alone, _ = busse_centre_echo(1.0, 66, **TIMING) + assert alone == 6 + shared, _ = busse_centre_echo(1.0, 66, max_flip=[120.0, 100.0], **TIMING) + assert shared == 7 + with pytest.raises(ValueError): + busse_flips(66, max_flip=100.0, centre_echo=6) + + +def test_the_echo_time_is_the_first_train_s(): + centre, achieved = busse_centre_echo( + 60.0, [66, 46], centre_flip=[70.0, 60.0], **TIMING + ) + flip = busse_flips(66, centre_echo=centre) + assert achieved == pytest.approx(effective_te(flip[: centre + 1], **TIMING)[-1]) + assert centre < 45 + + +def test_startup_echoes_are_not_centres(): + centre, _ = busse_centre_echo(1.0, 66, startup_echoes=12, **TIMING) + assert centre == 12 + + +@pytest.mark.parametrize( + "arguments", + [ + {"TE": 0.0}, + {"TE": np.nan}, + {"ESP": 0.0}, + {"T2": np.inf}, + {"length": 7}, + {"startup_echoes": -1}, + {"max_flip": 180.0}, + {"length": 46, "startup_echoes": 45}, + ], +) +def test_an_invalid_request_is_refused(arguments): + with pytest.raises(ValueError): + busse_centre_echo(**({"TE": 60.0, "length": 46, "ESP": 3.4} | arguments)) diff --git a/tests/trains/test_busse_flips.py b/tests/trains/test_busse_flips.py new file mode 100644 index 00000000..b1f58939 --- /dev/null +++ b/tests/trains/test_busse_flips.py @@ -0,0 +1,142 @@ +"""A Busse train plays the angles it is asked for and gives the signal it prescribes. + +Pinned from outside the phase graph: the pseudo-steady-state amplitude +against SciPy's Legendre function, the 106-pulse train of Busse et al. 2008, +Figure 1, against a frozen reconstruction of it, and the echoes of any train +by isochromat summation (``utils.isochromats``), which must rise as the +prescription says they do. +""" + +import json +from pathlib import Path + +import numpy as np +import pytest +from scipy.special import eval_legendre + +from blochsim.trains import busse_flips +from blochsim.trains._busse import _pss +from utils.isochromats import cpmg_echoes + + +@pytest.fixture(scope="module") +def figure1(): + return json.loads((Path(__file__).parent / "busse_figure1.json").read_text()) + + +def test_pseudo_steady_state_is_the_legendre_form(): + angle = np.linspace(1.0, 180.0, 359) + sine = np.sin(np.deg2rad(angle) / 2) + argument = sine * (1 + np.sin(np.deg2rad(angle)) ** 2 / (8 * sine**4)) + np.testing.assert_allclose( + _pss(angle), np.sqrt(sine) * eval_legendre(-0.5, argument), rtol=1e-13 + ) + assert _pss(np.array(180.0)) == pytest.approx(1.0) + + +def test_the_default_train_is_figure_1(figure1): + flip = busse_flips(figure1["length"]) + np.testing.assert_allclose(flip, figure1["angles_deg"], atol=1e-8, rtol=0) + np.testing.assert_allclose( + cpmg_echoes(flip, count=2048), figure1["static_signal"], atol=1e-11, rtol=0 + ) + + +@pytest.mark.parametrize("acquired", [40, 80, 100, 120, 160]) +def test_a_train_plays_the_angles_asked_for(acquired): + flip = busse_flips(acquired + 6) + centre = 6 + (acquired - 1) // 2 + assert flip.shape == (acquired + 6,) + np.testing.assert_allclose( + [flip[1:centre].min(), flip[centre], flip[-1]], [25, 70, 120], atol=1e-8 + ) + assert flip[0] == pytest.approx(120.0, abs=1e-12) + assert flip.max() <= 120.0 + 1e-8 + assert flip.min() >= 25.0 - 1e-8 + + +def test_the_echoes_rise_linearly_past_the_centre(): + flip = busse_flips(126, centre_echo=50) + echoes = cpmg_echoes(flip).real + past = echoes[50:] + np.testing.assert_allclose(np.diff(past, 2), 0.0, atol=1e-11) + assert np.all(np.diff(past) > 0) + # Before it they rise faster than linearly: a power above one. + assert np.all(np.diff(echoes[20:51], 2) > 0) + + +def test_trains_of_a_batch_are_designed_as_they_are_alone(): + lengths = np.array([46, 51, 66, 86, 106]) + controls = np.array( + [[25, 70, 120], [27, 68, 118], [30, 65, 115], [22, 74, 125], [20, 75, 130]], + dtype=float, + ) + together = busse_flips( + lengths, + min_flip=controls[:, 0], + centre_flip=controls[:, 1], + max_flip=controls[:, 2], + centre_echo=25, + threads=3, + ) + assert together.shape == (5, 106) + for row, (length, wanted) in enumerate(zip(lengths, controls, strict=True)): + alone = busse_flips( + int(length), + min_flip=wanted[0], + centre_flip=wanted[1], + max_flip=wanted[2], + centre_echo=25, + threads=1, + ) + np.testing.assert_array_equal(together[row, :length], alone) + assert not together[row, length:].any() + + +def test_arguments_broadcast_to_the_batch_shape(): + flip = busse_flips([[60], [66]], centre_flip=[60.0, 70.0, 80.0], centre_echo=30) + assert flip.shape == (2, 3, 66) + np.testing.assert_allclose(flip[..., 30], [[60, 70, 80]] * 2, atol=1e-8) + + +def test_a_train_centred_on_its_first_acquired_echo_is_found(): + # Newton steps leave the reachable echoes here; the hybrid solver does not. + flip = busse_flips(66, centre_echo=6) + np.testing.assert_allclose( + [flip[1:6].min(), flip[6], flip[-1]], [25, 70, 120], atol=1e-6 + ) + echoes = cpmg_echoes(flip).real + # The opening transient is below the tolerance from the fortieth echo. + np.testing.assert_allclose(np.diff(echoes[40:], 2), 0.0, atol=1e-11) + + +def test_a_prescription_no_train_meets_is_refused(): + with pytest.raises(ValueError, match="no Busse train"): + busse_flips(66, max_flip=100.0, centre_echo=6) + with pytest.raises(ValueError, match="trains 1"): + busse_flips(66, max_flip=[120.0, 100.0], centre_echo=6) + + +@pytest.mark.parametrize( + "arguments", + [ + {"length": 0}, + {"length": 106.5}, + {"length": True}, + {"startup_echoes": -1}, + {"startup_echoes": 106}, + {"startup_echoes": 6.5}, + {"centre_echo": 5}, + {"centre_echo": 105}, + {"centre_echo": 55.5}, + {"min_flip": 0.0}, + {"min_flip": np.nan}, + {"centre_flip": 20.0}, + {"max_flip": 180.0}, + {"initial_decay": 0.0}, + {"initial_decay": np.inf}, + ], +) +def test_an_invalid_prescription_is_refused(arguments): + with pytest.raises(ValueError): + busse_flips(**({"length": 106} | arguments)) diff --git a/tests/trains/test_effective_te.py b/tests/trains/test_effective_te.py new file mode 100644 index 00000000..5535b742 --- /dev/null +++ b/tests/trains/test_effective_te.py @@ -0,0 +1,68 @@ +"""The contrast-equivalent echo time is the T2 decay an echo actually took. + +Two things pin it from outside the phase graph: a train of 180 degree pulses +decays with the echo time itself, and for any other train the echo and its +relaxation-free twin can both be summed over isochromats +(``utils.isochromats``). +""" + +import numpy as np +import pytest + +from blochsim.trains import effective_te +from utils.isochromats import cpmg_echoes + + +def test_180_degree_pulses_give_the_echo_time(): + equivalent = effective_te(np.full(6, 180.0), 4.0, first_ESP=6.0) + np.testing.assert_allclose(equivalent, 6.0 + 4.0 * np.arange(6), atol=1e-12) + + +@pytest.mark.parametrize("seed", [0, 1]) +def test_isochromats_give_the_same_decay(seed): + flip = np.random.default_rng(seed).uniform(30.0, 170.0, 40) + timing = {"ESP": 3.6, "first_ESP": 4.2, "T1": 1200.0, "T2": 85.0} + relaxed = np.abs(cpmg_echoes(flip, **timing)) + free = np.abs(cpmg_echoes(flip)) + np.testing.assert_allclose( + effective_te(flip, **timing), -85.0 * np.log(relaxed / free), atol=1e-9 + ) + + +def test_reduced_angles_shorten_the_equivalent_echo_time(): + equivalent = effective_te(np.full(30, 60.0), 4.0) + echo_time = 4.0 * np.arange(1, 31) + assert equivalent[0] == pytest.approx(4.0) + assert np.all(equivalent[1:] < echo_time[1:]) + assert np.all(np.diff(equivalent) > 0) + + +def test_a_batch_keeps_its_shape_and_its_trains(): + flip = np.random.default_rng(2).uniform(20.0, 180.0, (2, 3, 16)) + together = effective_te(flip, 5.0, threads=3) + assert together.shape == flip.shape + for where in np.ndindex(2, 3): + np.testing.assert_array_equal(together[where], effective_te(flip[where], 5.0)) + + +def test_an_echo_without_signal_has_no_echo_time(): + assert np.isnan(effective_te([0.0, 90.0], 4.0)[0]) + + +@pytest.mark.parametrize( + "arguments", + [ + {"flip": []}, + {"flip": [181.0]}, + {"flip": [-1.0]}, + {"flip": [np.nan]}, + {"ESP": 0.0}, + {"ESP": np.inf}, + {"first_ESP": -1.0}, + {"T1": np.inf}, + {"T2": 0.0}, + ], +) +def test_an_invalid_train_is_refused(arguments): + with pytest.raises(ValueError): + effective_te(**({"flip": [120.0, 90.0], "ESP": 4.0} | arguments)) diff --git a/tests/trains/test_prescribed_flips.py b/tests/trains/test_prescribed_flips.py new file mode 100644 index 00000000..3e2086e5 --- /dev/null +++ b/tests/trains/test_prescribed_flips.py @@ -0,0 +1,111 @@ +"""The flips an inversion returns give the echoes it was asked for. + +The echoes are checked by isochromat summation (``utils.isochromats``), which +shares nothing with the phase graph the inversion walks, and against the two +closed forms a CPMG train has: a 180 degree pulse returns the whole echo, and +the first echo of any train is the squared sine of half its first angle. +""" + +import numpy as np +import pytest + +from blochsim.trains import prescribed_flips +from utils.isochromats import cpmg_echoes + + +def test_unit_echoes_are_a_train_of_180_degree_pulses(): + flip, achieved = prescribed_flips(np.ones(12)) + np.testing.assert_allclose(flip, 180.0, atol=1e-12) + np.testing.assert_allclose(achieved, 1.0, atol=1e-14) + + +@pytest.mark.parametrize("amplitude", [0.05, 0.25, 0.5, 0.9]) +def test_first_echo_is_the_squared_sine_of_half_the_first_angle(amplitude): + flip, achieved = prescribed_flips([amplitude]) + assert flip[0] == pytest.approx(2 * np.rad2deg(np.arcsin(np.sqrt(amplitude)))) + assert achieved[0] == pytest.approx(amplitude, abs=1e-15) + + +@pytest.mark.parametrize("amplitude", [0.3, 0.5, 0.8]) +def test_isochromats_give_a_constant_prescription(amplitude): + target = np.full(40, amplitude) + flip, achieved = prescribed_flips(target) + np.testing.assert_allclose(achieved, target, atol=1e-13) + echoes = cpmg_echoes(flip) + np.testing.assert_allclose(echoes.real, target, atol=1e-12) + np.testing.assert_allclose(echoes.imag, 0.0, atol=1e-12) + + +def test_isochromats_give_a_prescription_under_relaxation(): + timing = {"ESP": 4.0, "first_ESP": 5.0, "T1": 900.0, "T2": 70.0} + echo_time = 5.0 + 4.0 * np.arange(48) + target = 0.45 * np.exp(-echo_time / 250.0) + flip, achieved = prescribed_flips(target, **timing) + np.testing.assert_allclose(achieved, target, atol=1e-13) + # What recovers during the train is excited across the axis and + # refocuses at the pulses: no echo holds any of it. + echoes = cpmg_echoes(flip, **timing) + np.testing.assert_allclose(echoes.real, target, atol=1e-12) + np.testing.assert_allclose(echoes.imag, 0.0, atol=1e-12) + + +def test_the_first_angle_can_be_given_and_its_echo_follows(): + flip, achieved = prescribed_flips([0.0, 0.5, 0.5, 0.5], first_flip=120.0) + assert flip[0] == pytest.approx(120.0) + assert achieved[0] == pytest.approx(np.sin(np.deg2rad(60.0)) ** 2) + np.testing.assert_allclose(achieved[1:], 0.5, atol=1e-14) + np.testing.assert_allclose(cpmg_echoes(flip).real, achieved, atol=1e-12) + + +def test_of_two_angles_that_meet_an_echo_the_smaller_is_taken(): + target = [0.0, 0.7] + flip, _ = prescribed_flips(target, first_flip=100.0) + scan = np.linspace(0.0, 180.0, 3601) + second = np.array([cpmg_echoes([100.0, angle]).real[1] for angle in scan]) + crossings = np.flatnonzero(np.diff(np.sign(second - target[1]))) + assert len(crossings) == 2 + assert scan[crossings[0]] <= flip[1] <= scan[crossings[0] + 1] + + +@pytest.mark.parametrize( + ("amplitude", "angle", "echo"), [(1.5, 180.0, 1.0), (-0.5, 0.0, 0.0)] +) +def test_an_echo_out_of_reach_gets_the_nearest_angle(amplitude, angle, echo): + flip, achieved = prescribed_flips([amplitude]) + assert flip[0] == pytest.approx(angle, abs=1e-12) + assert achieved[0] == pytest.approx(echo, abs=1e-15) + + +def test_trains_of_a_batch_are_solved_as_they_are_alone(): + rng = np.random.default_rng(0) + target = rng.uniform(0.2, 0.7, (3, 5, 24)) + lengths = rng.integers(4, 25, (3, 5)) + flip, achieved = prescribed_flips(target, lengths=lengths, threads=4) + assert flip.shape == achieved.shape == target.shape + for where in np.ndindex(3, 5): + length = lengths[where] + alone, echoes = prescribed_flips(target[where][:length], threads=1) + np.testing.assert_array_equal(flip[where][:length], alone) + np.testing.assert_array_equal(achieved[where][:length], echoes) + assert not flip[where][length:].any() + assert not achieved[where][length:].any() + + +@pytest.mark.parametrize( + "arguments", + [ + {"signal": []}, + {"signal": 0.5}, + {"T2": 80.0}, + {"first_ESP": 5.0}, + {"ESP": 0.0}, + {"ESP": 4.0, "T1": -1.0}, + {"ESP": 4.0, "T2": np.nan}, + {"ESP": 4.0, "first_ESP": np.inf}, + {"lengths": 0}, + {"lengths": 9}, + ], +) +def test_an_invalid_prescription_is_refused(arguments): + with pytest.raises(ValueError): + prescribed_flips(**({"signal": np.full(8, 0.5)} | arguments)) diff --git a/tests/utils/isochromats.py b/tests/utils/isochromats.py new file mode 100644 index 00000000..881c1c41 --- /dev/null +++ b/tests/utils/isochromats.py @@ -0,0 +1,35 @@ +"""A CPMG train by isochromat summation, which shares nothing with a phase graph. + +Every isochromat precesses through its own fixed angle in each half echo +interval -- a whole number of turns across the ensemble, as a crusher pair +leaves it -- and is turned by every refocusing pulse about the axis the +excitation left it along. The echo is the mean transverse magnetization: its +real part lies along the refocusing axis and its imaginary part across it. +""" + +import numpy as np + + +def cpmg_echoes(flip_deg, ESP=None, first_ESP=None, T1=np.inf, T2=np.inf, count=4096): + """Complex echoes of one train of refocusing flip angles, in degrees.""" + precession = np.exp(2j * np.pi * np.arange(count) / count) + transverse = np.ones(count, dtype=complex) + longitudinal = np.zeros(count) + echoes = [] + for echo, angle in enumerate(np.deg2rad(flip_deg)): + half = ( + 0.0 if ESP is None else (first_ESP if echo == 0 and first_ESP else ESP) / 2 + ) + e1, e2 = np.exp(-half / T1), np.exp(-half / T2) + for after_pulse in (False, True): + if after_pulse: + across = transverse.imag.copy() + transverse = transverse.real + 1j * ( + np.cos(angle) * across - np.sin(angle) * longitudinal + ) + longitudinal = np.sin(angle) * across + np.cos(angle) * longitudinal + transverse = transverse * e2 + longitudinal = longitudinal * e1 + (1 - e1) + transverse = transverse * precession + echoes.append(transverse.mean()) + return np.array(echoes) From 8ffd9e3602c4924a46078ab31746936e91d7204d Mon Sep 17 00:00:00 2001 From: mcencini Date: Tue, 10 Nov 2026 21:04:06 +0100 Subject: [PATCH 2/5] Import PyTorch on first use; a forked child starts its own worker pool import blochsim imports blochsim.trains alone, so a train is designed at NumPy's import cost; everything built on PyTorch is imported the first time it is asked for. The CPU kernels' worker pool is tied to the process that created it, so a child forked after a threaded call does not wait on workers it does not have. Co-Authored-By: Claude Opus 5.5 --- src/blochsim/__init__.py | 102 +++++++++++++++++++++++++++++++----- src/blochsim/_threads.hpp | 35 ++++++++++++- tests/trains/test_import.py | 91 ++++++++++++++++++++++++++++++++ 3 files changed, 212 insertions(+), 16 deletions(-) create mode 100644 tests/trains/test_import.py diff --git a/src/blochsim/__init__.py b/src/blochsim/__init__.py index 64cc33c3..27f224ba 100644 --- a/src/blochsim/__init__.py +++ b/src/blochsim/__init__.py @@ -1,20 +1,94 @@ -"""Main BlochSim API.""" +"""Main BlochSim API. -__all__ = ["ModelOperator", "Simulator", "Subspace"] +The simulators, the estimators and the design tools are built on PyTorch, +and importing it takes far longer than anything :mod:`blochsim.trains` does. +So ``import blochsim`` imports :mod:`blochsim.trains` alone, and the rest of +the package the first time anything else is asked of it. +""" -from . import estimators # noqa -from . import optim # noqa -from . import sequence # noqa -from . import simulators # noqa +from __future__ import annotations -from ._model import Simulator # noqa -from ._operator import ModelOperator # noqa -from ._subspace import Subspace # noqa -from .sequence import * # noqa +import threading +from importlib import import_module +from importlib.util import find_spec +from typing import TYPE_CHECKING, Any -__all__.extend(sequence.__all__) +from . import trains # noqa: F401 -from . import _functional # noqa -from ._functional import * # noqa +if TYPE_CHECKING: + from . import ( # noqa: F401 + _functional, + estimators, + optim, + sequence, + simulators, + ) + from ._functional import * # noqa: F403 + from ._model import Simulator # noqa: F401 + from ._operator import ModelOperator # noqa: F401 + from ._subspace import Subspace # noqa: F401 + from .sequence import * # noqa: F403 -__all__.extend(_functional.__all__) +_lock = threading.RLock() +#: The thread importing the rest of the package, while it does. +_loader: int | None = None +_loaded = False + + +def _load() -> None: + """Import everything built on PyTorch, and name it here.""" + global _loader, _loaded + with _lock: + if _loaded: + return + _loader = threading.get_ident() + try: + from . import _functional, estimators, optim, sequence, simulators + from ._model import Simulator + from ._operator import ModelOperator + from ._subspace import Subspace + + namespace = globals() + namespace.update( + estimators=estimators, + optim=optim, + sequence=sequence, + simulators=simulators, + _functional=_functional, + Simulator=Simulator, + ModelOperator=ModelOperator, + Subspace=Subspace, + ) + names = ["ModelOperator", "Simulator", "Subspace"] + for module in (sequence, _functional): + for name in module.__all__: + namespace[name] = getattr(module, name) + names.extend(module.__all__) + namespace["__all__"] = names + _loaded = True + finally: + _loader = None + + +def __getattr__(name: str) -> Any: + missing = AttributeError(f"module {__name__!r} has no attribute {name!r}") + if name.startswith("__") and name != "__all__": + raise missing + # A submodule that imports a sibling while the package loads is asking + # the import system, and an AttributeError is what sends it there. + if _loaded or _loader == threading.get_ident(): + raise missing + # A submodule is the import system's to import, under its own locks; + # only a name the package defines needs the whole of it. + if name != "__all__" and find_spec(f"{__name__}.{name}") is not None: + return import_module(f"{__name__}.{name}") + _load() + try: + return globals()[name] + except KeyError: + raise missing from None + + +def __dir__() -> list[str]: + _load() + return sorted(globals()) diff --git a/src/blochsim/_threads.hpp b/src/blochsim/_threads.hpp index 6dce0df6..11aee291 100644 --- a/src/blochsim/_threads.hpp +++ b/src/blochsim/_threads.hpp @@ -5,6 +5,7 @@ #define BLOCHSIM_THREADS_HPP #include +#include #include #include #include @@ -16,6 +17,15 @@ #include #endif +// Whether a process can be forked, and so find itself holding a pool whose +// workers it does not have. +#if defined(__unix__) || defined(__APPLE__) +#include +#define BLOCHSIM_HAS_FORK 1 +#else +#define BLOCHSIM_HAS_FORK 0 +#endif + namespace blochsim { // Leave the vector registers in the state a legacy-encoded caller expects. @@ -59,8 +69,26 @@ class WorkerPool { // Deliberately never destroyed. An extension can be torn down with // threads still parked, and joining them there risks a deadlock at // interpreter exit for no benefit. - static WorkerPool* const pool = new WorkerPool(); - return *pool; + static std::atomic pool{new WorkerPool()}; + WorkerPool* current = pool.load(std::memory_order_acquire); +#if BLOCHSIM_HAS_FORK + // A fork copies the pool's bookkeeping and none of its threads: the + // child would hand slots to workers that are not there and wait on + // them for good. It starts a pool of its own instead, and the one it + // inherited is left alone -- its locks may have been held across the + // fork by threads that will never release them here. + if (current->owner_ != ::getpid()) { + WorkerPool* const fresh = new WorkerPool(); + if (pool.compare_exchange_strong( + current, fresh, std::memory_order_acq_rel + )) { + current = fresh; + } else { + delete fresh; + } + } +#endif + return *current; } void run(const unsigned int slots, const std::function& task) { @@ -116,6 +144,9 @@ class WorkerPool { } } +#if BLOCHSIM_HAS_FORK + const pid_t owner_ = ::getpid(); +#endif std::mutex submission_mutex_; std::mutex mutex_; std::condition_variable ready_; diff --git a/tests/trains/test_import.py b/tests/trains/test_import.py new file mode 100644 index 00000000..c8476e0d --- /dev/null +++ b/tests/trains/test_import.py @@ -0,0 +1,91 @@ +"""Designing a train does not import PyTorch, and the package is whole on first use. + +``import blochsim`` brings :mod:`blochsim.trains` alone; everything built on +PyTorch arrives the first time it is asked for, by any of the routes an eager +import served. +""" + +import os +import subprocess +import sys + +import pytest + +import blochsim + + +def run(code): + return subprocess.run( + [sys.executable, "-c", code], capture_output=True, text=True, check=True + ).stdout.split() + + +def test_a_train_is_designed_without_pytorch(): + out = run( + "import sys, blochsim\n" + "from blochsim.trains import busse_centre_echo, busse_flips\n" + "busse_flips(66); busse_centre_echo(60.0, 66, 3.6)\n" + "print('torch' in sys.modules)" + ) + assert out == ["False"] + + +@pytest.mark.parametrize( + "use", + [ + "blochsim.fse_sim", + "blochsim.Simulator", + "blochsim.simulators.FSESimulator", + "blochsim.optim.Bounded", + "blochsim._execution", + "getattr(__import__('blochsim.simulators').simulators, 'FSESimulator')", + "dir(blochsim)", + "blochsim.__all__", + ], +) +def test_the_package_loads_on_first_use(use): + assert run(f"import sys, blochsim\n{use}\nprint('torch' in sys.modules)") == [ + "True" + ] + + +def test_a_star_import_names_what_the_package_exports(): + names = run( + "from blochsim import *\nprint(*sorted(k for k in dir() if k[0] != '_'))" + ) + exported = { + *blochsim.sequence.__all__, + *blochsim._functional.__all__, + "ModelOperator", + "Simulator", + "Subspace", + } + assert set(names) == exported + for name in exported: + assert getattr(blochsim, name) is not None + + +def test_what_the_package_lacks_is_an_attribute_error(): + with pytest.raises(AttributeError): + _ = blochsim.no_such_thing + with pytest.raises(ImportError): + from blochsim import no_such_thing # noqa: F401 + + +@pytest.mark.skipif(not hasattr(os, "fork"), reason="the platform does not fork") +def test_a_forked_child_runs_its_own_workers(): + code = """ +import os, signal +import numpy as np +from blochsim.trains import prescribed_flips +target = np.full((256, 32), 0.5) +before, _ = prescribed_flips(target, threads=4) +pid = os.fork() +if pid == 0: + signal.alarm(20) + after, _ = prescribed_flips(target, threads=4) + os._exit(0 if np.array_equal(before, after) else 3) +_, status = os.waitpid(pid, 0) +print(os.WIFEXITED(status) and os.WEXITSTATUS(status)) +""" + assert run(code) == ["0"] From ddbcace0eb5f499bdbe89196babbad6b9133f0ee Mon Sep 17 00:00:00 2001 From: mcencini Date: Tue, 10 Nov 2026 21:08:14 +0100 Subject: [PATCH 3/5] trains: wake a worker for a millisecond of trains, not for eight Co-Authored-By: Claude Opus 5.5 --- src/blochsim/_trains_cpu.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/blochsim/_trains_cpu.cpp b/src/blochsim/_trains_cpu.cpp index b7ab4311..fdaf88ef 100644 --- a/src/blochsim/_trains_cpu.cpp +++ b/src/blochsim/_trains_cpu.cpp @@ -43,8 +43,8 @@ namespace subspace = blochsim::real_subspace; constexpr double PI = 3.14159265358979323846; // A train is tens of microseconds of work, so a worker is worth waking only -// for a few of them. -constexpr std::int64_t TRAINS_PER_WORKER = 8; +// for the best part of a millisecond of them. +constexpr std::int64_t TRAINS_PER_WORKER = 64; // What every train of a batch shares: the batch's shape, and the relaxation // over half an echo interval -- the first interval's, and every later one's. From 0283d2a5e7812f198c7cc37303b73c89c7998b6c Mon Sep 17 00:00:00 2001 From: mcencini Date: Tue, 10 Nov 2026 21:11:33 +0100 Subject: [PATCH 4/5] tests: end the Figure 1 fixture with a newline Co-Authored-By: Claude Opus 5.5 --- tests/trains/busse_figure1.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/trains/busse_figure1.json b/tests/trains/busse_figure1.json index ceaeff8e..74d60d45 100644 --- a/tests/trains/busse_figure1.json +++ b/tests/trains/busse_figure1.json @@ -226,4 +226,4 @@ 0.9180849110387229, 0.9217106792124952 ] -} \ No newline at end of file +} From facb5a7e5b99a038e7d7ac1e2beeac4432500ea1 Mon Sep 17 00:00:00 2001 From: mcencini Date: Wed, 11 Nov 2026 01:49:13 +0100 Subject: [PATCH 5/5] Review fixes: no lock in the lazy import, NaN stays NaN, fallback tested The lazy import held a lock of its own while importing subpackages, and a missing optional module asked for by 'from blochsim import _gpu' took it too: one thread using blochsim.Simulator and another importing blochsim.estimators waited on each other. The lock is gone, so the import system sees every cycle, and a private name that is no submodule is an AttributeError without loading anything. prescribed_flips refuses amplitudes and first angles that are not finite, and in the kernel an echo that is not a number leaves every later angle not a number, where it left zeros. busse_flips broadcasts centre_echo and startup_echoes into the batch shape. The MINPACK fallback and the no-centre error are tested. The changelog entries are once. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 32 ---------- src/blochsim/__init__.py | 86 ++++++++++++++------------ src/blochsim/_trains_cpu.cpp | 8 ++- src/blochsim/trains/_busse.py | 11 +++- src/blochsim/trains/_prescribed.py | 7 ++- tests/trains/test_busse_centre_echo.py | 5 ++ tests/trains/test_busse_flips.py | 42 +++++++++++++ tests/trains/test_import.py | 43 +++++++++++++ tests/trains/test_prescribed_flips.py | 16 +++++ 9 files changed, 174 insertions(+), 76 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d35d577a..54ac3fa3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -142,14 +142,6 @@ ### Changed -- **`import blochsim` no longer imports PyTorch.** It imports - `blochsim.trains` alone; the simulators, estimators and design tools are - imported the first time any of them is asked for, by attribute, by - `from blochsim import ...` or by submodule. `import blochsim.trains` costs - what NumPy costs. -- **A forked child starts its own worker pool.** The CPU kernels' pool is - tied to the process that created it, so a process forked after a threaded - call no longer waits on workers it does not have. - **Both adjoint kernels compile one sweep at a time.** A reverse pass records a trajectory through the events and then walks it back, and the walk back is where the kernel's mass is: in the forward-over-reverse kernel at three @@ -378,14 +370,6 @@ ### Changed -- **`import blochsim` no longer imports PyTorch.** It imports - `blochsim.trains` alone; the simulators, estimators and design tools are - imported the first time any of them is asked for, by attribute, by - `from blochsim import ...` or by submodule. `import blochsim.trains` costs - what NumPy costs. -- **A forked child starts its own worker pool.** The CPU kernels' pool is - tied to the process that created it, so a process forked after a threaded - call no longer waits on workers it does not have. - **The PERK example says how sure it is.** The regression maps a slice in hundredths of a second, so the estimator's noise sensitivity is answered by running it: two dozen noise realizations of the same measurement, mapped @@ -623,14 +607,6 @@ ### Changed -- **`import blochsim` no longer imports PyTorch.** It imports - `blochsim.trains` alone; the simulators, estimators and design tools are - imported the first time any of them is asked for, by attribute, by - `from blochsim import ...` or by submodule. `import blochsim.trains` costs - what NumPy costs. -- **A forked child starts its own worker pool.** The CPU kernels' pool is - tied to the process that created it, so a process forked after a threaded - call no longer waits on workers it does not have. - **A property whose term the run leaves out is not laid out per voxel, and neither is one given as a single value.** Every tissue property was broadcast to the voxel count and materialized, so a model naming two relaxation times @@ -1167,14 +1143,6 @@ ### Changed -- **`import blochsim` no longer imports PyTorch.** It imports - `blochsim.trains` alone; the simulators, estimators and design tools are - imported the first time any of them is asked for, by attribute, by - `from blochsim import ...` or by submodule. `import blochsim.trains` costs - what NumPy costs. -- **A forked child starts its own worker pool.** The CPU kernels' pool is - tied to the process that created it, so a process forked after a threaded - call no longer waits on workers it does not have. - **The documentation has a User Guide and a Developer Guide** in place of *Getting Started* and *Miscellaneous*. The user guide installs PyTorch first -- the build depends on hardware pip cannot see -- with tabs for the isolated diff --git a/src/blochsim/__init__.py b/src/blochsim/__init__.py index 27f224ba..e66ddc3c 100644 --- a/src/blochsim/__init__.py +++ b/src/blochsim/__init__.py @@ -29,45 +29,47 @@ from ._subspace import Subspace # noqa: F401 from .sequence import * # noqa: F403 -_lock = threading.RLock() -#: The thread importing the rest of the package, while it does. -_loader: int | None = None +#: Set on the thread that is importing the rest of the package, while it does. +_loading = threading.local() _loaded = False def _load() -> None: - """Import everything built on PyTorch, and name it here.""" - global _loader, _loaded - with _lock: - if _loaded: - return - _loader = threading.get_ident() - try: - from . import _functional, estimators, optim, sequence, simulators - from ._model import Simulator - from ._operator import ModelOperator - from ._subspace import Subspace + """Import everything built on PyTorch, and name it here. - namespace = globals() - namespace.update( - estimators=estimators, - optim=optim, - sequence=sequence, - simulators=simulators, - _functional=_functional, - Simulator=Simulator, - ModelOperator=ModelOperator, - Subspace=Subspace, - ) - names = ["ModelOperator", "Simulator", "Subspace"] - for module in (sequence, _functional): - for name in module.__all__: - namespace[name] = getattr(module, name) - names.extend(module.__all__) - namespace["__all__"] = names - _loaded = True - finally: - _loader = None + No lock is held: the import system serializes each module's import and + detects a cycle between threads, which a lock of this module's own would + hide from it. Two threads arriving together both run this, to the same + end. + """ + global _loaded + _loading.here = True + try: + from . import _functional, estimators, optim, sequence, simulators + from ._model import Simulator + from ._operator import ModelOperator + from ._subspace import Subspace + + namespace = globals() + namespace.update( + estimators=estimators, + optim=optim, + sequence=sequence, + simulators=simulators, + _functional=_functional, + Simulator=Simulator, + ModelOperator=ModelOperator, + Subspace=Subspace, + ) + names = ["ModelOperator", "Simulator", "Subspace"] + for module in (sequence, _functional): + for name in module.__all__: + namespace[name] = getattr(module, name) + names.extend(module.__all__) + namespace["__all__"] = names + _loaded = True + finally: + _loading.here = False def __getattr__(name: str) -> Any: @@ -76,12 +78,18 @@ def __getattr__(name: str) -> Any: raise missing # A submodule that imports a sibling while the package loads is asking # the import system, and an AttributeError is what sends it there. - if _loaded or _loader == threading.get_ident(): + if _loaded or getattr(_loading, "here", False): raise missing - # A submodule is the import system's to import, under its own locks; - # only a name the package defines needs the whole of it. - if name != "__all__" and find_spec(f"{__name__}.{name}") is not None: - return import_module(f"{__name__}.{name}") + if name != "__all__": + # A submodule is the import system's to import. + if find_spec(f"{__name__}.{name}") is not None: + return import_module(f"{__name__}.{name}") + # Everything the package exports is public. A private name that is + # no submodule is an optional module that was not built, asked for + # by ``from blochsim import``: it is missing, and loading the + # package from inside another module's import would not find it. + if name.startswith("_"): + raise missing _load() try: return globals()[name] diff --git a/src/blochsim/_trains_cpu.cpp b/src/blochsim/_trains_cpu.cpp index fdaf88ef..bee0398d 100644 --- a/src/blochsim/_trains_cpu.cpp +++ b/src/blochsim/_trains_cpu.cpp @@ -115,8 +115,10 @@ inline double refocusing_angle( const double plus, const double minus, const double longitudinal, const double target, const double e2 ) { - if (std::isnan(target)) { - return target; + // A prescription that is not a number has no angle, and neither has + // any echo after it: the states it leaves are not numbers either. + if (!std::isfinite(target)) { + return NAN; } const double a = 0.5 * (plus + minus); const double b = 0.5 * (minus - plus); @@ -135,7 +137,7 @@ inline double refocusing_angle( const double echoes[8] = { a + b, a - b, a + radius, a - radius, met, met, met, met, }; - double best = 0.0; + double best = NAN; double best_score = INFINITY; for (int candidate = 0; candidate < 8; ++candidate) { const double angle = angles[candidate]; diff --git a/src/blochsim/trains/_busse.py b/src/blochsim/trains/_busse.py index 3a6ad01e..b8f00802 100644 --- a/src/blochsim/trains/_busse.py +++ b/src/blochsim/trains/_busse.py @@ -478,8 +478,17 @@ def busse_flips( True """ + # The centre and the startup echoes shape the batch like the rest. + every = [length, min_flip, centre_flip, max_flip, initial_decay, startup_echoes] + if centre_echo is not None: + every.append(centre_echo) + shape = np.broadcast_shapes(*(np.shape(value) for value in every)) shape, lengths, wanted, decay = _prescription( - length, min_flip, centre_flip, max_flip, initial_decay + np.broadcast_to(_integers(length, "length"), shape), + min_flip, + centre_flip, + max_flip, + initial_decay, ) startup = np.broadcast_to(_integers(startup_echoes, "startup_echoes"), shape) startup = startup.reshape(-1) diff --git a/src/blochsim/trains/_prescribed.py b/src/blochsim/trains/_prescribed.py index 987e20b2..8f4c125a 100644 --- a/src/blochsim/trains/_prescribed.py +++ b/src/blochsim/trains/_prescribed.py @@ -187,7 +187,8 @@ def prescribed_flips( Raises ------ ValueError - If the timing, the relaxation times or the lengths are not valid. + If an amplitude or a first angle is not finite, or the timing, the + relaxation times or the lengths are not valid. Notes ----- @@ -209,10 +210,14 @@ def prescribed_flips( """ target, shape = _rows(signal, "signal") count, echoes = target.shape + if not np.all(np.isfinite(target)): + raise ValueError("signal must be finite") relax = relaxation(ESP, first_ESP, T1, T2) first = None if first_flip is not None: first = np.deg2rad(np.broadcast_to(first_flip, shape).reshape(count)) + if not np.all(np.isfinite(first)): + raise ValueError("first_flip must be finite") flip, achieved = inverse_rows( target, _lengths(lengths, shape, echoes), first, relax, threads ) diff --git a/tests/trains/test_busse_centre_echo.py b/tests/trains/test_busse_centre_echo.py index c5dad69e..4dcb46d3 100644 --- a/tests/trains/test_busse_centre_echo.py +++ b/tests/trains/test_busse_centre_echo.py @@ -60,6 +60,11 @@ def test_the_echo_time_is_the_first_train_s(): assert centre < 45 +def test_trains_no_centre_suits_are_refused(): + with pytest.raises(ValueError, match="no centre echo"): + busse_centre_echo(20.0, 8, 3.4, min_flip=60.0, centre_flip=65.0, max_flip=70.0) + + def test_startup_echoes_are_not_centres(): centre, _ = busse_centre_echo(1.0, 66, startup_echoes=12, **TIMING) assert centre == 12 diff --git a/tests/trains/test_busse_flips.py b/tests/trains/test_busse_flips.py index b1f58939..7378180c 100644 --- a/tests/trains/test_busse_flips.py +++ b/tests/trains/test_busse_flips.py @@ -110,6 +110,48 @@ def test_a_train_centred_on_its_first_acquired_echo_is_found(): np.testing.assert_allclose(np.diff(echoes[40:], 2), 0.0, atol=1e-11) +@pytest.fixture +def hybrid_calls(monkeypatch): + """Count the trains handed to the MINPACK fallback.""" + from blochsim.trains._busse import _Trains + + calls = [] + hybrid = _Trains.hybrid + + def counted(self, row): + calls.append(row) + return hybrid(self, row) + + monkeypatch.setattr(_Trains, "hybrid", counted) + return calls + + +def test_a_train_the_newton_steps_stall_on_is_found_by_the_fallback(hybrid_calls): + prescription = {"min_flip": 15.0, "centre_flip": 80.0, "max_flip": 170.0} + flip = busse_flips(66, centre_echo=6, **prescription) + assert hybrid_calls == [0] + np.testing.assert_allclose( + [flip[1:6].min(), flip[6], flip[-1]], [15, 80, 170], atol=1e-8 + ) + assert flip.min() >= 15.0 - 1e-8 + assert flip.max() <= 170.0 + 1e-8 + # The echoes are the prescription's: linear past the centre. + echoes = cpmg_echoes(flip).real + np.testing.assert_allclose(np.diff(echoes[40:], 2), 0.0, atol=1e-11) + # In a batch only the stalled train goes to the fallback, and it comes + # back as it does alone. + del hybrid_calls[:] + both = busse_flips(66, centre_echo=[30, 6], **prescription) + assert hybrid_calls == [1] + np.testing.assert_array_equal(both[1], flip) + + +def test_a_train_the_fallback_cannot_find_either_is_refused(hybrid_calls): + with pytest.raises(ValueError, match="no Busse train"): + busse_flips(30, min_flip=15.0, centre_flip=100.0, max_flip=150.0, centre_echo=6) + assert hybrid_calls == [0] + + def test_a_prescription_no_train_meets_is_refused(): with pytest.raises(ValueError, match="no Busse train"): busse_flips(66, max_flip=100.0, centre_echo=6) diff --git a/tests/trains/test_import.py b/tests/trains/test_import.py index c8476e0d..8c280690 100644 --- a/tests/trains/test_import.py +++ b/tests/trains/test_import.py @@ -65,6 +65,49 @@ def test_a_star_import_names_what_the_package_exports(): assert getattr(blochsim, name) is not None +@pytest.mark.parametrize( + ("first_use", "meanwhile"), + [ + ("blochsim.Simulator", "blochsim.estimators"), + ("blochsim.fse_sim", "blochsim.simulators"), + ("blochsim.__all__", "blochsim.optim"), + ], +) +def test_two_threads_load_the_package_without_waiting_on_each_other( + first_use, meanwhile +): + # One thread asks the package for a name while another imports one of + # its subpackages, which asks it for an optional module in turn. + code = f""" +import threading +import blochsim +threads = [ + threading.Thread(target=lambda: {first_use}), + threading.Thread(target=lambda: __import__({meanwhile!r})), +] +for thread in threads: + thread.start() +for thread in threads: + thread.join() +print(blochsim.Simulator.__name__, blochsim.estimators.__name__) +""" + done = subprocess.run( + [sys.executable, "-c", code], capture_output=True, text=True, timeout=120 + ) + assert done.returncode == 0, done.stderr + assert done.stdout.split() == ["Simulator", "blochsim.estimators"] + + +def test_an_optional_module_that_was_not_built_does_not_load_the_package(): + out = run( + "import sys, blochsim\n" + "try:\n from blochsim import _no_such_module\n" + "except ImportError:\n pass\n" + "print('torch' in sys.modules)" + ) + assert out == ["False"] + + def test_what_the_package_lacks_is_an_attribute_error(): with pytest.raises(AttributeError): _ = blochsim.no_such_thing diff --git a/tests/trains/test_prescribed_flips.py b/tests/trains/test_prescribed_flips.py index 3e2086e5..e8a1b6b5 100644 --- a/tests/trains/test_prescribed_flips.py +++ b/tests/trains/test_prescribed_flips.py @@ -96,6 +96,9 @@ def test_trains_of_a_batch_are_solved_as_they_are_alone(): [ {"signal": []}, {"signal": 0.5}, + {"signal": [0.5, np.nan, 0.5]}, + {"signal": [0.5, np.inf]}, + {"first_flip": np.nan}, {"T2": 80.0}, {"first_ESP": 5.0}, {"ESP": 0.0}, @@ -109,3 +112,16 @@ def test_trains_of_a_batch_are_solved_as_they_are_alone(): def test_an_invalid_prescription_is_refused(arguments): with pytest.raises(ValueError): prescribed_flips(**({"signal": np.full(8, 0.5)} | arguments)) + + +def test_what_is_not_a_number_stays_one_in_the_kernel(): + # The Busse solver hands the kernel trial prescriptions that may not be + # numbers; no angle after one may pass for a solution. + from blochsim.trains._prescribed import inverse_rows + + target = np.full((1, 6), 0.5) + target[0, 2] = np.nan + flip, achieved = inverse_rows(target, np.array([6]), None, (1.0, 1.0, 1.0, 1.0)) + assert np.all(np.isfinite(flip[0, :2])) + assert np.all(np.isnan(flip[0, 2:])) + assert np.all(np.isnan(achieved[0, 2:]))