From 365b9c5a397871b207989125f86e44957445ff12 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Nov 2026 16:04:23 +0000 Subject: [PATCH 1/2] trains: exact forward-mode derivatives of designed refocusing trains The C++ train kernels carry one extra set of EPG states per direction through the echo-by-echo recursion, so prescribed_flips, effective_te and busse_flips return exact derivatives (signal_tangents, flip_tangents, jacobian=True). The Busse shooting takes its Newton and MINPACK Jacobians from them instead of differencing the residual. Forward mode also silences the torch.jit.script deprecation whatever warning class PyTorch raises it as. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MFB6QKxkFL4hC7MC4RCb2V --- CHANGELOG.md | 11 + docs/api/trains.md | 7 + src/blochsim/_derivative.py | 4 +- src/blochsim/_trains_cpu.cpp | 359 +++++++++++++++++++++++++- src/blochsim/trains/_busse.py | 239 ++++++++++++----- src/blochsim/trains/_prescribed.py | 201 +++++++++++++- tests/trains/test_busse_flips.py | 51 +++- tests/trains/test_effective_te.py | 23 ++ tests/trains/test_prescribed_flips.py | 60 +++++ 9 files changed, 870 insertions(+), 85 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 54ac3fa3..7cdec8a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,14 @@ 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. +- **Exact derivatives of designed trains.** `prescribed_flips` takes + `signal_tangents` (and `first_flip_tangents`) and returns the derivatives of + the flip angles and echoes along them; `effective_te` takes `flip_tangents`; + `busse_flips(jacobian=True)` returns the derivatives of the train with + respect to its lowest, centre and highest angle. They are carried through + the kernel's echo-by-echo recursion in forward mode, at the cost of one more + state vector per direction, and the shooting that pins a Busse train's three + angles takes its Newton Jacobian from them. - **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 +36,9 @@ ### Fixed +- **Forward mode is quiet on every PyTorch.** The `torch.jit.script` + deprecation PyTorch prints when forward mode first loads is silenced + whatever warning class it is raised as (a `FutureWarning` on PyTorch 2.15). - **`Subspace` round-trips complex signals.** `project` is `signals @ basis.conj()` and `expand` is `coefficients @ basis.mT`, so a signal in the span comes back unchanged; `modes` is `basis.mH`, which mri-nufft's `MRISubspace` expands diff --git a/docs/api/trains.md b/docs/api/trains.md index 0edd5a64..f69c3ccf 100644 --- a/docs/api/trains.md +++ b/docs/api/trains.md @@ -17,6 +17,13 @@ on it the variable-flip-angle trains of long 3D fast spin echo readouts, and echo time, which {func}`effective_te` computes for any train. A batch of trains is solved in one call, across threads. +Each of them also gives exact derivatives, for designing a train against a +cost: {func}`prescribed_flips` along changes of the prescribed signal and of +the first angle, {func}`effective_te` along changes of the flip angles, and +{func}`busse_flips` with respect to its three angles. They are carried through +the same echo-by-echo recursion in forward mode, one extra set of states per +direction, so a few directions cost a few inversions. + | Object | Description | | --- | --- | | {obj}`~blochsim.trains.prescribed_flips` | Flip angles whose echoes take prescribed amplitudes, and the echoes they give. | diff --git a/src/blochsim/_derivative.py b/src/blochsim/_derivative.py index 51ea16c2..ebadc28b 100644 --- a/src/blochsim/_derivative.py +++ b/src/blochsim/_derivative.py @@ -36,9 +36,7 @@ def forward_mode() -> None: if os.environ.get("PYTORCH_JIT", "1") != "1" or not __debug__: return with warnings.catch_warnings(): - warnings.filterwarnings( - "ignore", message=r"`torch\.jit\.script`", category=DeprecationWarning - ) + warnings.filterwarnings("ignore", message=r"`torch\.jit\.script`") try: importlib.import_module("torch._decomp.decompositions_for_jvp") except ImportError: diff --git a/src/blochsim/_trains_cpu.cpp b/src/blochsim/_trains_cpu.cpp index bee0398d..6e8137b0 100644 --- a/src/blochsim/_trains_cpu.cpp +++ b/src/blochsim/_trains_cpu.cpp @@ -93,6 +93,33 @@ struct States { subspace::shift(plus.data(), minus.data(), occupied, coupling); } + // The derivative of a pulse along one direction: this tangent turned by + // the pulse, plus the derivative of the turn itself applied to ``primal`` + // before it, times the angle's own derivative. Call it before the primal + // is turned. + BLOCHSIM_ALWAYS_INLINE void rotate_tangent( + const States& primal, const double angle, const double slope + ) { + subspace::rotate( + plus.data(), minus.data(), longitudinal.data(), occupied, + std::cos(angle), std::sin(angle) + ); + if (slope == 0.0) { + return; + } + const double half_sine = 0.5 * std::sin(angle) * slope; + const double cosine = std::cos(angle) * slope; + const double sine = std::sin(angle) * slope; + for (std::size_t state = 0; state < occupied; ++state) { + const double p = primal.plus[state]; + const double m = primal.minus[state]; + const double z = primal.longitudinal[state]; + plus[state] += -half_sine * p + half_sine * m - cosine * z; + minus[state] += half_sine * p - half_sine * m + cosine * z; + longitudinal[state] += 0.5 * cosine * (p - m) - sine * z; + } + } + BLOCHSIM_ALWAYS_INLINE void rotate(const double angle) { subspace::rotate( plus.data(), minus.data(), longitudinal.data(), occupied, @@ -101,6 +128,22 @@ struct States { } }; +// How a solved angle moves with what it was solved from. +enum class Reached { + // An end of [0, pi]: it stays there under a small change. + END, + // The angle whose echo comes nearest an unreachable target: it follows + // the extremum of the echo, delta or delta + pi. + EXTREMUM, + // The echo meets the target, and the angle follows the target. + MET, +}; + +struct Solved { + double angle; + Reached reached; +}; + // The flip angle in [0, pi] whose echo is ``target``, from the first-order // states the pulse is about to turn. // @@ -111,25 +154,25 @@ struct States { // 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( +inline Solved refocusing_angle( const double plus, const double minus, const double longitudinal, const double target, const double e2 ) { // 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; + return {NAN, Reached::END}; } 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 wanted = (target / e2 - a) / std::max(radius, 1e-16); + const double reach = std::min(1.0, std::max(-1.0, wanted)); const double turn = std::acos(reach); const double met = a + radius * reach; + const bool within = wanted > -1.0 && wanted < 1.0; const double angles[8] = { 0.0, PI, delta, delta + PI, delta - turn, delta + turn, delta - turn + 2.0 * PI, delta + turn + 2.0 * PI, @@ -137,7 +180,7 @@ inline double refocusing_angle( const double echoes[8] = { a + b, a - b, a + radius, a - radius, met, met, met, met, }; - double best = NAN; + Solved best{NAN, Reached::END}; double best_score = INFINITY; for (int candidate = 0; candidate < 8; ++candidate) { const double angle = angles[candidate]; @@ -148,12 +191,46 @@ inline double refocusing_angle( std::fabs(echoes[candidate] * e2 - target) + 1e-12 * angle; if (score < best_score) { best_score = score; - best = angle; + best.angle = angle; + best.reached = candidate < 2 ? Reached::END + : candidate < 4 || !within ? Reached::EXTREMUM + : Reached::MET; } } return best; } +// The derivative of a solved angle along one direction, from the derivatives +// of the states it was solved from and of its target. +// +// A met target holds a + b cos(alpha) + c sin(alpha) = target / e2, so the +// angle moves by the implicit function theorem; an extremum moves with +// delta = atan2(c, b); an end of the interval does not move. +inline double refocusing_slope( + const Solved& solved, const double plus, const double minus, + const double longitudinal, const double d_plus, const double d_minus, + const double d_longitudinal, const double d_target, const double e2 +) { + if (solved.reached == Reached::END || !std::isfinite(solved.angle)) { + return 0.0; + } + const double b = 0.5 * (minus - plus); + const double c = longitudinal; + const double d_a = 0.5 * (d_plus + d_minus); + const double d_b = 0.5 * (d_minus - d_plus); + const double d_c = d_longitudinal; + if (solved.reached == Reached::MET) { + const double cosine = std::cos(solved.angle); + const double sine = std::sin(solved.angle); + const double steepness = c * cosine - b * sine; + if (steepness != 0.0) { + return (d_target / e2 - d_a - d_b * cosine - d_c * sine) / steepness; + } + } + const double radius_sq = b * b + c * c; + return radius_sq > 0.0 ? (b * d_c - c * d_b) / radius_sq : 0.0; +} + struct Inverse { Batch batch; const double* target; @@ -196,7 +273,7 @@ void inverse_range( : refocusing_angle( along.plus[1], along.minus[1], along.longitudinal[1], problem.target[row + echo], e2 - ); + ).angle; along.rotate(angle); if (relaxing) { along.relax(e1, e2); @@ -254,6 +331,198 @@ void forward_range( } } +// Derivatives ride along a train as one copy of its states per direction, +// laid out ``(trains, directions, echoes)`` like the echoes they belong to. +struct Tangents { + std::int64_t directions; + + std::size_t at( + const std::int64_t train, const std::int64_t direction, + const std::size_t echoes + ) const { + return (static_cast(train * directions + direction)) * echoes; + } +}; + +struct InverseTangents { + Batch batch; + Tangents along; + const double* target; + const double* first_flip; + const double* d_target; + // ``(trains, directions)``, or null when the first angle is solved too. + const double* d_first_flip; + double* flip; + double* achieved; + double* d_flip; + double* d_achieved; +}; + +// What ``inverse_range`` computes, and its derivative along each direction of +// the targets and the first angles. +BLOCHSIM_TRAIN_CLONES +void inverse_tangents_range( + const InverseTangents& 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 std::int64_t directions = problem.along.directions; + const bool relaxing = batch.relaxing(); + States along(echoes + 1); + std::vector slopes( + static_cast(directions), States(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 (States& slope : slopes) { + slope.clear(states); + } + 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); + for (States& slope : slopes) { + slope.relax(e1, e2); + } + } + along.shift(states, subspace::ALONG_AXIS); + for (States& slope : slopes) { + slope.shift(states, subspace::ALONG_AXIS); + } + const bool given = echo == 0 && problem.first_flip != nullptr; + const Solved solved = given + ? Solved{problem.first_flip[train], Reached::END} + : refocusing_angle( + along.plus[1], along.minus[1], along.longitudinal[1], + problem.target[row + echo], e2 + ); + for (std::int64_t direction = 0; direction < directions; ++direction) { + States& slope = slopes[static_cast(direction)]; + const std::size_t at = problem.along.at(train, direction, echoes); + const double d_angle = given + ? (problem.d_first_flip == nullptr + ? 0.0 + : problem.d_first_flip[train * directions + direction]) + : refocusing_slope( + solved, along.plus[1], along.minus[1], + along.longitudinal[1], slope.plus[1], slope.minus[1], + slope.longitudinal[1], problem.d_target[at + echo], e2 + ); + slope.rotate_tangent(along, solved.angle, d_angle); + problem.d_flip[at + echo] = d_angle; + } + along.rotate(solved.angle); + if (relaxing) { + along.relax(e1, e2); + for (States& slope : slopes) { + slope.relax(e1, e2); + } + } + along.shift(states, subspace::ALONG_AXIS); + problem.flip[row + echo] = solved.angle; + problem.achieved[row + echo] = along.plus[0]; + for (std::int64_t direction = 0; direction < directions; ++direction) { + States& slope = slopes[static_cast(direction)]; + slope.shift(states, subspace::ALONG_AXIS); + problem.d_achieved[problem.along.at(train, direction, echoes) + echo] = + slope.plus[0]; + } + } + for (std::size_t echo = length; echo < echoes; ++echo) { + problem.flip[row + echo] = 0.0; + problem.achieved[row + echo] = 0.0; + for (std::int64_t direction = 0; direction < directions; ++direction) { + const std::size_t at = problem.along.at(train, direction, echoes); + problem.d_flip[at + echo] = 0.0; + problem.d_achieved[at + echo] = 0.0; + } + } + } +} + +struct ForwardTangents { + Batch batch; + Tangents along; + const double* flip; + const double* d_flip; + double* echo; + double* d_echo; +}; + +// What ``forward_range`` computes, and its derivative along each direction of +// the flip angles. +BLOCHSIM_TRAIN_CLONES +void forward_tangents_range( + const ForwardTangents& 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 std::int64_t directions = problem.along.directions; + const bool relaxing = batch.relaxing(); + States along(echoes + 1); + std::vector slopes( + static_cast(directions), States(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 (States& slope : slopes) { + slope.clear(states); + } + 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); + for (States& slope : slopes) { + slope.relax(e1, e2); + } + } + along.shift(states, subspace::ALONG_AXIS); + const double angle = problem.flip[row + echo]; + for (std::int64_t direction = 0; direction < directions; ++direction) { + States& slope = slopes[static_cast(direction)]; + slope.shift(states, subspace::ALONG_AXIS); + slope.rotate_tangent( + along, angle, + problem.d_flip[problem.along.at(train, direction, echoes) + echo] + ); + } + along.rotate(angle); + if (relaxing) { + along.relax(e1, e2); + for (States& slope : slopes) { + slope.relax(e1, e2); + } + } + along.shift(states, subspace::ALONG_AXIS); + problem.echo[row + echo] = along.plus[0]; + for (std::int64_t direction = 0; direction < directions; ++direction) { + States& slope = slopes[static_cast(direction)]; + slope.shift(states, subspace::ALONG_AXIS); + problem.d_echo[problem.along.at(train, direction, echoes) + echo] = + slope.plus[0]; + } + } + for (std::size_t echo = length; echo < echoes; ++echo) { + problem.echo[row + echo] = 0.0; + for (std::int64_t direction = 0; direction < directions; ++direction) { + problem.d_echo[problem.along.at(train, direction, echoes) + 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) { @@ -377,10 +646,84 @@ PyObject* forward(PyObject*, PyObject* arguments) { Py_RETURN_NONE; } +PyObject* inverse_tangents(PyObject*, PyObject* arguments) { + PyObject* pointers = nullptr; + long long count = 0; + long long echoes = 0; + long long directions = 0; + InverseTangents problem{}; + Batch& batch = problem.batch; + int threads = 0; + if (!PyArg_ParseTuple( + arguments, "OLLLddddi", &pointers, &count, &echoes, &directions, + &batch.e1_first, &batch.e2_first, &batch.e1, &batch.e2, &threads + )) { + return nullptr; + } + if (directions < 1) { + PyErr_SetString(PyExc_ValueError, "tangents need a direction"); + return nullptr; + } + std::vector raw; + if (!unpack(pointers, 9, raw) || !describe(batch, count, echoes, raw[0])) { + return nullptr; + } + problem.along.directions = directions; + problem.target = static_cast(raw[1]); + problem.first_flip = static_cast(raw[2]); + problem.d_target = static_cast(raw[3]); + problem.d_first_flip = static_cast(raw[4]); + problem.flip = static_cast(raw[5]); + problem.achieved = static_cast(raw[6]); + problem.d_flip = static_cast(raw[7]); + problem.d_achieved = static_cast(raw[8]); + Py_BEGIN_ALLOW_THREADS + run(problem, threads, inverse_tangents_range); + Py_END_ALLOW_THREADS + Py_RETURN_NONE; +} + +PyObject* forward_tangents(PyObject*, PyObject* arguments) { + PyObject* pointers = nullptr; + long long count = 0; + long long echoes = 0; + long long directions = 0; + ForwardTangents problem{}; + Batch& batch = problem.batch; + int threads = 0; + if (!PyArg_ParseTuple( + arguments, "OLLLddddi", &pointers, &count, &echoes, &directions, + &batch.e1_first, &batch.e2_first, &batch.e1, &batch.e2, &threads + )) { + return nullptr; + } + if (directions < 1) { + PyErr_SetString(PyExc_ValueError, "tangents need a direction"); + return nullptr; + } + std::vector raw; + if (!unpack(pointers, 5, raw) || !describe(batch, count, echoes, raw[0])) { + return nullptr; + } + problem.along.directions = directions; + problem.flip = static_cast(raw[1]); + problem.d_flip = static_cast(raw[2]); + problem.echo = static_cast(raw[3]); + problem.d_echo = static_cast(raw[4]); + Py_BEGIN_ALLOW_THREADS + run(problem, threads, forward_tangents_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."}, + {"inverse_tangents", inverse_tangents, METH_VARARGS, + "Prescribed flip angles and their derivatives along given directions."}, + {"forward_tangents", forward_tangents, METH_VARARGS, + "CPMG echoes and their derivatives along given directions."}, {nullptr, nullptr, 0, nullptr}, }; diff --git a/src/blochsim/trains/_busse.py b/src/blochsim/trains/_busse.py index b8f00802..bbdc3f28 100644 --- a/src/blochsim/trains/_busse.py +++ b/src/blochsim/trains/_busse.py @@ -9,14 +9,18 @@ import numpy as np import numpy.typing as npt -from ._prescribed import AUTO_THREADS, equivalent_te, inverse_rows, relaxation +from ._prescribed import ( + AUTO_THREADS, + equivalent_te, + inverse_rows, + inverse_rows_tangents, + 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 @@ -31,25 +35,42 @@ _SHORTFALL_DEG = 360.0 -def _pss(flip_deg: np.ndarray) -> np.ndarray: +def _pss(flip_deg: np.ndarray) -> tuple[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. + the reciprocal of an arithmetic-geometric mean. Returns the amplitude and + its derivative with respect to the angle, per degree, carried through the + same iteration. """ angle = np.deg2rad(flip_deg) sine = np.sin(angle / 2) + d_sine = 0.5 * np.cos(angle / 2) with np.errstate(invalid="ignore", divide="ignore"): - argument = sine * (1 + np.sin(angle) ** 2 / (8 * sine**4)) + excess = np.sin(angle) ** 2 / (8 * sine**4) + d_excess = ( + 2 * np.sin(angle) * np.cos(angle) / (8 * sine**4) + - 4 * excess * d_sine / sine + ) + argument = sine * (1 + excess) + d_argument = d_sine * (1 + excess) + sine * d_excess arithmetic = np.ones_like(argument) + d_arithmetic = np.zeros_like(argument) geometric = np.sqrt((1 + argument) / 2) + d_geometric = d_argument / (4 * geometric) for _ in range(10): - arithmetic, geometric = ( + mean = np.sqrt(arithmetic * geometric) + d_mean = (d_arithmetic * geometric + arithmetic * d_geometric) / (2 * mean) + arithmetic, d_arithmetic = ( (arithmetic + geometric) / 2, - np.sqrt(arithmetic * geometric), + (d_arithmetic + d_geometric) / 2, ) - return np.sqrt(sine) / arithmetic + geometric, d_geometric = mean, d_mean + root = np.sqrt(sine) + value = root / arithmetic + slope = (d_sine / (2 * root) - value * d_arithmetic) / arithmetic + return value, np.deg2rad(1.0) * slope def _target( @@ -59,27 +80,40 @@ def _target( max_flip: np.ndarray, decay: np.ndarray, echoes: int, -) -> np.ndarray: +) -> tuple[np.ndarray, 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. + second at the centre echo, the third at the last echo. Returns the echoes, + ``(trains, echoes)``, and their derivatives, ``(trains, 4, echoes)``, per + degree of each control and of ``max_flip``. """ - low, middle, final = _pss(controls.T)[:, :, None] + levels, slopes = _pss(controls.T) + low, middle, final = levels[:, :, 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 + rise = (echo - centre) / (lengths[:, None] - 1 - centre) + past = echo > centre signal = np.where( - echo > centre, - middle - + (final - middle) * (echo - centre) / (lengths[:, None] - 1 - centre), - signal, + past, middle + (final - middle) * rise, low + (middle - low) * ramp + ) + half = np.deg2rad(max_flip[:, None] / 2) + first = np.sin(half) ** 2 + transient = np.exp(-echo / decay[:, None]) + target = signal + (first - low) * transient + derivatives = np.stack( + ( + slopes[0][:, None] * (np.where(past, 0.0, 1 - ramp) - transient), + slopes[1][:, None] * np.where(past, 1 - rise, ramp), + slopes[2][:, None] * np.where(past, rise, 0.0), + np.deg2rad(0.5) * np.sin(2 * half) * transient, + ), + axis=1, ) - first = np.sin(np.deg2rad(max_flip[:, None] / 2)) ** 2 - return signal + (first - low) * np.exp(-echo / decay[:, None]) + return target, derivatives class _Trains: @@ -124,11 +158,41 @@ def evaluate( 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. """ + return self._trial(controls, rows, opening, None)[:4] + + def slopes( + self, + controls: np.ndarray, + rows: np.ndarray, + directions: np.ndarray, + opening: bool = False, + ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]: + """What :meth:`evaluate` returns first, with derivatives along ``directions``. + + ``directions`` is ``(k, 4)``: each row a change of the three controls + and of the maximum angle, in degrees. Returns the residuals + ``(trains, 3)``, their derivatives ``(trains, 3, k)``, the flip angles + ``(trains, echoes)`` and their derivatives ``(trains, k, echoes)``, + all in degrees. The derivative of the residuals leaves out the angles + asked for, which they are taken less. + """ + residual, flip, _, _, d_residual, d_flip = self._trial( + controls, rows, opening, directions + ) + return residual, d_residual, flip, d_flip + + def _trial( + self, + controls: np.ndarray, + rows: np.ndarray, + opening: bool, + directions: np.ndarray | None, + ) -> tuple: centres = self.centres[rows] lengths = centres + 1 if opening else self.lengths[rows] wanted = self.wanted[rows] echoes = int(lengths.max()) - target = _target( + target, d_target = _target( controls, self.lengths[rows], centres, @@ -136,26 +200,50 @@ def evaluate( self.decay[rows], echoes, ) - flip, achieved = inverse_rows( - target, lengths, np.deg2rad(wanted[:, 2]), _FREE, self.threads - ) + first = np.deg2rad(wanted[:, 2]) + if directions is None: + flip, achieved = inverse_rows(target, lengths, first, _FREE, self.threads) + else: + d_target = np.einsum("kj,tje->tke", directions, d_target) + d_first = np.broadcast_to( + np.deg2rad(directions[:, 3]), (len(rows), len(directions)) + ) + flip, achieved, d_flip, d_achieved = inverse_rows_tangents( + target, d_target, lengths, first, d_first, _FREE, self.threads + ) + d_flip = np.rad2deg(d_flip) 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 - ) + played = echo < lengths[:, None] + short = _SHORTFALL_DEG * np.where(played, target - achieved, 0.0) + opened = np.where((echo >= 1) & (echo < centre), flip, np.inf) + lowest = opened.argmin(axis=1) 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), + opened[each, lowest] + 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 + if directions is None: + return residual - wanted, flip, achieved, target + d_short = _SHORTFALL_DEG * np.where( + played[:, None, :], d_target - d_achieved, 0.0 + ) + d_residual = np.stack( + ( + d_flip[each, :, lowest] + + np.where(echo[:, None] < centre[:, None], d_short, 0.0).sum(axis=2), + d_flip[each, :, centres] + d_short[each, :, centres], + d_flip[each, :, lengths - 1] + + np.where(echo[:, None] > centre[:, None], d_short, 0.0).sum(axis=2), + ), + axis=1, + ) + return residual - wanted, flip, achieved, target, d_residual, d_flip def accepted( self, controls: np.ndarray, rows: np.ndarray @@ -198,34 +286,23 @@ def _opening(self, controls: np.ndarray, rows: np.ndarray) -> np.ndarray: 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. + The Jacobian is carried through the inversion with the residual, 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): + if not active.size: + break + base, jacobian = self._opening_slopes(controls[active], rows[active]) 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, - ) + active, base, jacobian = active[~done], base[~done], jacobian[~done] with np.errstate(invalid="ignore"): determinant = np.linalg.det(jacobian) solvable = ( @@ -249,13 +326,21 @@ def newton(self, controls: np.ndarray, rows: np.ndarray) -> np.ndarray: 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] + active = active[taken] return converged + def _opening_slopes( + self, controls: np.ndarray, rows: np.ndarray + ) -> tuple[np.ndarray, np.ndarray]: + """The two residuals of :meth:`_opening`, and their 2 x 2 Jacobian.""" + residual, d_residual, _, _ = self.slopes( + controls, rows, np.eye(4)[:2], opening=True + ) + return residual[:, :2], d_residual[:, :2, :] + def hybrid(self, row: int) -> np.ndarray: """The first two controls of one train from MINPACK's hybrid method. @@ -266,11 +351,12 @@ def hybrid(self, row: int) -> np.ndarray: rows = np.array([row]) trial = self.wanted[row : row + 1].copy() - def residual(controls: np.ndarray) -> np.ndarray: + def residual(controls: np.ndarray) -> tuple[np.ndarray, np.ndarray]: trial[0, :2] = controls - return self._opening(trial, rows)[0] + value, jacobian = self._opening_slopes(trial, rows) + return value[0], jacobian[0] - trial[0, :2] = root(residual, self.wanted[row, :2], tol=1e-9).x + trial[0, :2] = root(residual, self.wanted[row, :2], jac=True, tol=1e-9).x return trial def closing(self, controls: np.ndarray, rows: np.ndarray) -> None: @@ -331,8 +417,30 @@ def solve(self) -> tuple[np.ndarray, np.ndarray]: if self.newton(trial, one)[0]: controls[one] = trial self.closing(controls, rows) + self.controls = controls return self.accepted(controls, rows)[::-1] + def jacobian(self) -> np.ndarray: + """Derivatives of the solved flip angles with respect to the three asked for. + + The controls solve ``g(c, w) = w``, with ``g`` the three angles the + train plays; the maximum angle ``w[2]`` also enters ``g`` directly, as + the first pulse and through the opening transient. By the implicit + function theorem the controls move by ``G_c^-1 (I - G_w)`` and the + angles by ``F_c`` of that plus ``F_w``. Returns ``(trains, echoes, + 3)``, in degrees per degree of the minimum, centre and maximum angle. + """ + rows = np.arange(len(self.lengths)) + _, d_residual, _, d_flip = self.slopes(self.controls, rows, np.eye(4)) + moved = np.broadcast_to(np.eye(3), (len(rows), 3, 3)).copy() + moved[:, :, 2] -= d_residual[:, :, 3] + with np.errstate(invalid="ignore"): + controls = np.linalg.solve(d_residual[:, :, :3], moved) + slopes = np.einsum("tke,tkw->tew", d_flip[:, :3], controls) + slopes[..., 2] += d_flip[:, 3] + played = np.arange(d_flip.shape[2])[None, :] < self.lengths[:, None] + return np.where(played[..., None], slopes, 0.0) + def _integers(values: npt.ArrayLike, name: str) -> np.ndarray: """``values`` as integers, refusing what only rounds to one.""" @@ -404,7 +512,8 @@ def busse_flips( startup_echoes: npt.ArrayLike = 6, initial_decay: npt.ArrayLike = 1.3, threads: int = AUTO_THREADS, -) -> np.ndarray: + jacobian: bool = False, +) -> np.ndarray | tuple[np.ndarray, np.ndarray]: """Variable refocusing flip angles of a long echo train, after Busse. The echo signal is prescribed without relaxation: an opening transient @@ -440,12 +549,20 @@ def busse_flips( 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. + jacobian : bool, default=False + Also return the derivatives of the flip angles with respect to + ``min_flip``, ``centre_flip`` and ``max_flip``. Returns ------- - numpy.ndarray + flip : numpy.ndarray Flip angles in degrees: shape ``(length,)`` for one train, and ``(..., max(length))`` for a batch, zero past each train's last pulse. + jacobian : numpy.ndarray + Only with ``jacobian``: shape ``(..., max(length), 3)``, in degrees per + degree of ``min_flip``, ``centre_flip`` and ``max_flip``. It is exact, + carried through the inversion with the angles, and holds where the + lowest angle stays at the same echo. Raises ------ @@ -503,7 +620,8 @@ def busse_flips( raise ValueError( "centre_echo must be after the sixth pulse and before the last" ) - flip, feasible = _Trains(lengths, centres, wanted, decay, threads).solve() + trains = _Trains(lengths, centres, wanted, decay, threads) + flip, feasible = trains.solve() if not np.all(feasible): missing = np.flatnonzero(~feasible) raise ValueError( @@ -514,7 +632,10 @@ def busse_flips( else f"trains {', '.join(map(str, missing[:8]))}" ) ) - return flip.reshape(*shape, flip.shape[-1]) + flip = flip.reshape(*shape, flip.shape[-1]) + if jacobian: + return flip, trains.jacobian().reshape(*flip.shape, 3) + return flip def busse_centre_echo( diff --git a/src/blochsim/trains/_prescribed.py b/src/blochsim/trains/_prescribed.py index 8f4c125a..25460cc4 100644 --- a/src/blochsim/trains/_prescribed.py +++ b/src/blochsim/trains/_prescribed.py @@ -12,7 +12,7 @@ import numpy as np import numpy.typing as npt -from .._trains_cpu import forward, inverse +from .._trains_cpu import forward, forward_tangents, inverse, inverse_tangents #: Let the extension's pool size itself against the work. AUTO_THREADS = 0 @@ -95,6 +95,97 @@ def inverse_rows( return flip, achieved +def inverse_rows_tangents( + target: np.ndarray, + d_target: np.ndarray, + lengths: np.ndarray, + first_rad: np.ndarray | None, + d_first_rad: np.ndarray | None, + relax: tuple[float, float, float, float], + threads: int = AUTO_THREADS, +) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]: + """What :func:`inverse_rows` returns, and its derivatives along directions. + + ``d_target`` is ``(trains, directions, echoes)`` and ``d_first_rad`` + ``(trains, directions)``; the derivatives of the flip angles (rad) and of + the achieved echoes come back shaped like ``d_target``. + """ + target = np.ascontiguousarray(target, dtype=np.float64) + d_target = np.ascontiguousarray(d_target, dtype=np.float64) + lengths = np.ascontiguousarray(lengths, dtype=np.int64) + count, echoes = target.shape + directions = d_target.shape[1] + if d_target.shape != (count, directions, echoes) or directions < 1: + raise ValueError("target tangents must be (trains, directions, echoes)") + flip = np.empty_like(target) + achieved = np.empty_like(target) + d_flip = np.empty_like(d_target) + d_achieved = np.empty_like(d_target) + if first_rad is not None: + first_rad = np.ascontiguousarray(first_rad, dtype=np.float64) + if d_first_rad is not None: + d_first_rad = np.ascontiguousarray(d_first_rad, dtype=np.float64) + if d_first_rad.shape != (count, directions): + raise ValueError("first-angle tangents must be (trains, directions)") + inverse_tangents( + ( + lengths.ctypes.data, + target.ctypes.data, + 0 if first_rad is None else first_rad.ctypes.data, + d_target.ctypes.data, + 0 if d_first_rad is None else d_first_rad.ctypes.data, + flip.ctypes.data, + achieved.ctypes.data, + d_flip.ctypes.data, + d_achieved.ctypes.data, + ), + count, + echoes, + directions, + *relax, + threads, + ) + return flip, achieved, d_flip, d_achieved + + +def forward_rows_tangents( + flip_rad: np.ndarray, + d_flip_rad: np.ndarray, + lengths: np.ndarray, + relax: tuple[float, float, float, float], + threads: int = AUTO_THREADS, +) -> tuple[np.ndarray, np.ndarray]: + """Echoes of ``(trains, echoes)`` flip angles, and their derivatives. + + ``d_flip_rad`` is ``(trains, directions, echoes)``, in radians; the + derivatives of the echoes come back in the same shape. + """ + flip_rad = np.ascontiguousarray(flip_rad, dtype=np.float64) + d_flip_rad = np.ascontiguousarray(d_flip_rad, dtype=np.float64) + lengths = np.ascontiguousarray(lengths, dtype=np.int64) + count, echoes = flip_rad.shape + directions = d_flip_rad.shape[1] + if d_flip_rad.shape != (count, directions, echoes) or directions < 1: + raise ValueError("flip tangents must be (trains, directions, echoes)") + echo = np.empty_like(flip_rad) + d_echo = np.empty_like(d_flip_rad) + forward_tangents( + ( + lengths.ctypes.data, + flip_rad.ctypes.data, + d_flip_rad.ctypes.data, + echo.ctypes.data, + d_echo.ctypes.data, + ), + count, + echoes, + directions, + *relax, + threads, + ) + return echo, d_echo + + def forward_rows( flip_rad: np.ndarray, lengths: np.ndarray, @@ -141,7 +232,9 @@ def prescribed_flips( T2: float = np.inf, lengths: npt.ArrayLike | None = None, threads: int = AUTO_THREADS, -) -> tuple[np.ndarray, np.ndarray]: + signal_tangents: npt.ArrayLike | None = None, + first_flip_tangents: npt.ArrayLike | None = None, +) -> tuple[np.ndarray, ...]: """Refocusing flip angles whose echoes take prescribed amplitudes. The train is the CPMG arrangement: an ideal 90 degree excitation a quarter @@ -176,6 +269,12 @@ def prescribed_flips( 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. + signal_tangents : array-like, default=None + Directions to differentiate along, shape ``(directions, ..., echoes)``: + each a change of ``signal``. Asks for the derivatives as well. + first_flip_tangents : array-like, default=None + The change of ``first_flip`` along each direction, in degrees, shape + ``(directions, ...)``; none by default. Needs ``signal_tangents``. Returns ------- @@ -183,12 +282,19 @@ def prescribed_flips( Refocusing flip angles, in degrees, shaped like ``signal``. achieved : numpy.ndarray The echo amplitudes those angles give, shaped like ``signal``. + flip_tangents : numpy.ndarray + Only with ``signal_tangents``: the derivative of ``flip`` along each + direction, in degrees, shaped like ``signal_tangents``. + achieved_tangents : numpy.ndarray + Only with ``signal_tangents``: the derivative of ``achieved`` along + each direction, shaped like ``signal_tangents``. Raises ------ ValueError - If an amplitude or a first angle is not finite, or the timing, the - relaxation times or the lengths are not valid. + If an amplitude or a first angle is not finite, the timing, the + relaxation times or the lengths are not valid, or the tangents are + not shaped as described. Notes ----- @@ -197,6 +303,11 @@ def prescribed_flips( echo holds none of it: T1 enters only through the decay of what the train stores along z. + The derivatives are exact: each angle is solved in closed form from the + states before its pulse, and the derivatives of those states are carried + through the train alongside them. An echo out of reach takes the angle of + the nearest one, which moves with the states and not with the target. + Examples -------- A constant train of 180 degree pulses is what unit echoes ask for: @@ -218,12 +329,45 @@ def prescribed_flips( 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 + played = _lengths(lengths, shape, echoes) + if signal_tangents is None: + if first_flip_tangents is not None: + raise ValueError("first_flip_tangents needs signal_tangents") + flip, achieved = inverse_rows(target, played, first, relax, threads) + return ( + np.rad2deg(flip).reshape(*shape, echoes), + achieved.reshape(*shape, echoes), + ) + tangents = np.asarray(signal_tangents, dtype=np.float64) + if tangents.ndim < 2 or tangents.shape[1:] != (*shape, echoes): + raise ValueError("signal_tangents must be shaped (directions, *signal.shape)") + directions = tangents.shape[0] + d_target = np.moveaxis(tangents.reshape(directions, count, echoes), 0, 1) + d_first = None + if first_flip_tangents is not None: + if first is None: + raise ValueError("first_flip_tangents needs first_flip") + d_first = np.deg2rad( + np.broadcast_to(first_flip_tangents, (directions, *shape)) + .reshape(directions, count) + .T + ) + if not np.all(np.isfinite(d_target)) or ( + d_first is not None and not np.all(np.isfinite(d_first)) + ): + raise ValueError("tangents must be finite") + flip, achieved, d_flip, d_achieved = inverse_rows_tangents( + target, d_target, played, first, d_first, relax, threads ) + + def back(values: np.ndarray) -> np.ndarray: + return np.moveaxis(values, 1, 0).reshape(directions, *shape, echoes) + return ( np.rad2deg(flip).reshape(*shape, echoes), achieved.reshape(*shape, echoes), + np.rad2deg(back(d_flip)), + back(d_achieved), ) @@ -235,7 +379,8 @@ def effective_te( T1: float = 1000.0, T2: float = 100.0, threads: int = AUTO_THREADS, -) -> np.ndarray: + flip_tangents: npt.ArrayLike | None = None, +) -> np.ndarray | tuple[np.ndarray, 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 @@ -259,18 +404,26 @@ def effective_te( 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. + flip_tangents : array-like, default=None + Directions to differentiate along, in degrees, shape + ``(directions, ..., echoes)``: each a change of ``flip``. Asks for the + exact derivatives as well. Returns ------- - numpy.ndarray + TE : numpy.ndarray Contrast-equivalent echo times, in ms, shaped like ``flip``. An echo with no signal has none, and is ``nan``. + TE_tangents : numpy.ndarray + Only with ``flip_tangents``: the derivative of ``TE`` along each + direction, in ms per degree, shaped like ``flip_tangents``. Raises ------ ValueError - If an angle is outside [0, 180] degrees, or the timing or the - relaxation times are not positive and finite. + If an angle is outside [0, 180] degrees, the timing or the relaxation + times are not positive and finite, or the tangents are not shaped as + described. Notes ----- @@ -295,7 +448,29 @@ def effective_te( 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 + lengths = _lengths(None, shape, echoes) + if flip_tangents is None: + equivalent = equivalent_te(np.deg2rad(angles), lengths, relax, T2, threads) + return equivalent.reshape(*shape, echoes) + tangents = np.asarray(flip_tangents, dtype=np.float64) + if tangents.ndim < 2 or tangents.shape[1:] != (*shape, echoes): + raise ValueError("flip_tangents must be shaped (directions, *flip.shape)") + if not np.all(np.isfinite(tangents)): + raise ValueError("flip_tangents must be finite") + directions = tangents.shape[0] + d_flip = np.deg2rad(np.moveaxis(tangents.reshape(directions, -1, echoes), 0, 1)) + rad = np.deg2rad(angles) + relaxed, d_relaxed = forward_rows_tangents(rad, d_flip, lengths, relax, threads) + free, d_free = forward_rows_tangents( + rad, d_flip, lengths, (1.0, 1.0, 1.0, 1.0), threads + ) + with np.errstate(invalid="ignore", divide="ignore"): + equivalent = -T2 * np.log(np.abs(relaxed) / np.abs(free)) + slope = -T2 * (d_relaxed / relaxed[:, None] - d_free / free[:, None]) + valid = np.abs(free) > 1e-12 + equivalent = np.where(valid, equivalent, np.nan) + slope = np.where(valid[:, None], slope, np.nan) + return ( + equivalent.reshape(*shape, echoes), + np.moveaxis(slope, 1, 0).reshape(directions, *shape, echoes), ) - return equivalent.reshape(*shape, echoes) diff --git a/tests/trains/test_busse_flips.py b/tests/trains/test_busse_flips.py index 7378180c..244dba00 100644 --- a/tests/trains/test_busse_flips.py +++ b/tests/trains/test_busse_flips.py @@ -29,9 +29,16 @@ def test_pseudo_steady_state_is_the_legendre_form(): 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 + _pss(angle)[0], np.sqrt(sine) * eval_legendre(-0.5, argument), rtol=1e-13 ) - assert _pss(np.array(180.0)) == pytest.approx(1.0) + assert _pss(np.array(180.0))[0] == pytest.approx(1.0) + + +def test_pseudo_steady_state_slope_is_its_derivative_per_degree(): + angle = np.linspace(5.0, 175.0, 69) + step = 1e-6 + central = (_pss(angle + step)[0] - _pss(angle - step)[0]) / (2 * step) + np.testing.assert_allclose(_pss(angle)[1], central, rtol=1e-7, atol=1e-10) def test_the_default_train_is_figure_1(figure1): @@ -182,3 +189,43 @@ def test_a_prescription_no_train_meets_is_refused(): def test_an_invalid_prescription_is_refused(arguments): with pytest.raises(ValueError): busse_flips(**({"length": 106} | arguments)) + + +@pytest.mark.parametrize( + "prescription", + [ + {}, + {"min_flip": 35.0, "centre_flip": 60.0, "max_flip": 140.0, "centre_echo": 30}, + ], +) +def test_jacobian_is_the_derivative_of_the_design(prescription): + flip, jacobian = busse_flips(106, jacobian=True, **prescription) + np.testing.assert_array_equal(flip, busse_flips(106, **prescription)) + angles = {"min_flip": 25.0, "centre_flip": 70.0, "max_flip": 120.0} + angles |= {name: prescription[name] for name in angles if name in prescription} + rest = {name: value for name, value in prescription.items() if name not in angles} + step = 1e-5 + for column, name in enumerate(angles): + moved = [ + busse_flips(106, **rest, **(angles | {name: angles[name] + sign * step})) + for sign in (1, -1) + ] + np.testing.assert_allclose( + jacobian[:, column], (moved[0] - moved[1]) / (2 * step), atol=1e-6 + ) + + +def test_jacobian_plays_each_angle_asked_for_one_to_one(): + flip, jacobian = busse_flips(106, jacobian=True) + lowest = 1 + int(np.argmin(flip[1:55])) + np.testing.assert_allclose(jacobian[lowest], [1.0, 0.0, 0.0], atol=1e-9) + np.testing.assert_allclose(jacobian[55], [0.0, 1.0, 0.0], atol=1e-9) + np.testing.assert_allclose(jacobian[[0, -1]], [[0, 0, 1], [0, 0, 1]], atol=1e-9) + + +def test_jacobian_of_a_batch_is_zero_past_each_train(): + flip, jacobian = busse_flips([66, 106], jacobian=True) + assert jacobian.shape == (2, 106, 3) + np.testing.assert_array_equal(jacobian[0, 66:], 0.0) + _, alone = busse_flips(66, jacobian=True) + np.testing.assert_allclose(jacobian[0, :66], alone, atol=1e-12) diff --git a/tests/trains/test_effective_te.py b/tests/trains/test_effective_te.py index 5535b742..30294526 100644 --- a/tests/trains/test_effective_te.py +++ b/tests/trains/test_effective_te.py @@ -66,3 +66,26 @@ def test_an_echo_without_signal_has_no_echo_time(): def test_an_invalid_train_is_refused(arguments): with pytest.raises(ValueError): effective_te(**({"flip": [120.0, 90.0], "ESP": 4.0} | arguments)) + + +def test_tangents_are_the_derivative_of_the_echo_time(): + rng = np.random.default_rng(4) + flip = 60.0 + 100.0 * rng.random((2, 30)) + directions = rng.standard_normal((3, 2, 30)) + timing = {"first_ESP": 5.0, "T1": 900.0, "T2": 70.0} + equivalent, slopes = effective_te(flip, 4.0, flip_tangents=directions, **timing) + np.testing.assert_array_equal(equivalent, effective_te(flip, 4.0, **timing)) + step = 1e-6 + for direction in range(3): + moved = [ + effective_te(flip + sign * step * directions[direction], 4.0, **timing) + for sign in (1, -1) + ] + np.testing.assert_allclose( + slopes[direction], (moved[0] - moved[1]) / (2 * step), atol=1e-6 + ) + + +def test_tangents_not_shaped_as_the_train_are_refused(): + with pytest.raises(ValueError, match="flip_tangents"): + effective_te(np.full(4, 120.0), 4.0, flip_tangents=np.zeros((1, 5))) diff --git a/tests/trains/test_prescribed_flips.py b/tests/trains/test_prescribed_flips.py index e8a1b6b5..f50b27a5 100644 --- a/tests/trains/test_prescribed_flips.py +++ b/tests/trains/test_prescribed_flips.py @@ -125,3 +125,63 @@ def test_what_is_not_a_number_stays_one_in_the_kernel(): assert np.all(np.isfinite(flip[0, :2])) assert np.all(np.isnan(flip[0, 2:])) assert np.all(np.isnan(achieved[0, 2:])) + + +@pytest.mark.parametrize( + "timing", [{}, {"ESP": 4.0, "first_ESP": 5.0, "T1": 900.0, "T2": 70.0}] +) +def test_flip_tangents_are_the_derivative_of_the_inversion(timing): + rng = np.random.default_rng(3) + target = np.stack([np.linspace(0.6, 0.35, 48), np.full(48, 0.5)]) + first = np.array([150.0, 130.0]) + signal_tangents = 0.01 * rng.standard_normal((3, *target.shape)) + first_tangents = rng.standard_normal((3, 2)) + flip, achieved, d_flip, d_achieved = prescribed_flips( + target, + first_flip=first, + signal_tangents=signal_tangents, + first_flip_tangents=first_tangents, + **timing, + ) + np.testing.assert_array_equal( + (flip, achieved), prescribed_flips(target, first_flip=first, **timing) + ) + for direction in range(3): + moved = [ + prescribed_flips( + target + sign * 1e-6 * signal_tangents[direction], + first_flip=first + sign * 1e-6 * first_tangents[direction], + **timing, + ) + for sign in (1, -1) + ] + np.testing.assert_allclose( + d_flip[direction], (moved[0][0] - moved[1][0]) / 2e-6, atol=1e-6 + ) + np.testing.assert_allclose( + d_achieved[direction], (moved[0][1] - moved[1][1]) / 2e-6, atol=1e-8 + ) + + +def test_an_echo_out_of_reach_has_an_angle_that_ignores_its_target(): + # The third echo asks for more than any angle gives, so it takes the + # nearest angle, which a change of that target does not move. + target = np.array([0.5, 0.5, 2.0, 0.5]) + tangent = np.zeros((1, 4)) + tangent[0, 2] = 1.0 + _, _, d_flip, _ = prescribed_flips(target, signal_tangents=tangent) + np.testing.assert_array_equal(d_flip[0, :3], 0.0) + + +@pytest.mark.parametrize( + "arguments", + [ + {"signal_tangents": np.zeros((2, 5))}, + {"signal_tangents": np.zeros((1, 4)), "first_flip_tangents": [1.0]}, + {"first_flip_tangents": [1.0], "first_flip": 120.0}, + {"signal_tangents": np.full((1, 4), np.nan)}, + ], +) +def test_tangents_not_shaped_as_the_signal_are_refused(arguments): + with pytest.raises(ValueError): + prescribed_flips(np.full(4, 0.5), **arguments) From 1124dbf4b4182f198ae8af4fe66f1f0e68fa8dd1 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Nov 2026 17:01:53 +0000 Subject: [PATCH 2/2] trains: share the derivative states' relax and shift between the tangent kernels Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MFB6QKxkFL4hC7MC4RCb2V --- src/blochsim/_trains_cpu.cpp | 124 ++++++++++++++++++----------------- 1 file changed, 65 insertions(+), 59 deletions(-) diff --git a/src/blochsim/_trains_cpu.cpp b/src/blochsim/_trains_cpu.cpp index 6e8137b0..e22bc301 100644 --- a/src/blochsim/_trains_cpu.cpp +++ b/src/blochsim/_trains_cpu.cpp @@ -344,6 +344,59 @@ struct Tangents { } }; +// The derivative states of one train, one copy per direction. What is linear +// in the states -- relaxation and the shift -- moves them as it moves the +// states themselves. +struct Slopes { + std::vector along; + + Slopes(const std::int64_t directions, const std::size_t capacity) + : along(static_cast(directions), States(capacity)) {} + + void clear(const std::size_t states) { + for (States& slope : along) { + slope.clear(states); + } + } + + void relax(const double e1, const double e2) { + for (States& slope : along) { + slope.relax(e1, e2); + } + } + + void shift(const std::size_t states) { + for (States& slope : along) { + slope.shift(states, subspace::ALONG_AXIS); + } + } + + States& operator[](const std::int64_t direction) { + return along[static_cast(direction)]; + } +}; + +// A train's states and their derivatives, back at the excitation. +inline void start(States& states, Slopes& slopes, const std::size_t count) { + states.clear(count); + states.plus[0] = 1.0; + states.minus[0] = 1.0; + slopes.clear(count); +} + +// Relaxation over half an interval, then the shift, for states and slopes. +inline void advance( + States& states, Slopes& slopes, const std::size_t count, const bool relaxing, + const double e1, const double e2 +) { + if (relaxing) { + states.relax(e1, e2); + slopes.relax(e1, e2); + } + states.shift(count, subspace::ALONG_AXIS); + slopes.shift(count); +} + struct InverseTangents { Batch batch; Tangents along; @@ -369,32 +422,16 @@ void inverse_tangents_range( const std::int64_t directions = problem.along.directions; const bool relaxing = batch.relaxing(); States along(echoes + 1); - std::vector slopes( - static_cast(directions), States(echoes + 1) - ); + Slopes slopes(directions, 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 (States& slope : slopes) { - slope.clear(states); - } + start(along, slopes, states); 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); - for (States& slope : slopes) { - slope.relax(e1, e2); - } - } - along.shift(states, subspace::ALONG_AXIS); - for (States& slope : slopes) { - slope.shift(states, subspace::ALONG_AXIS); - } + advance(along, slopes, states, relaxing, e1, e2); const bool given = echo == 0 && problem.first_flip != nullptr; const Solved solved = given ? Solved{problem.first_flip[train], Reached::END} @@ -403,7 +440,7 @@ void inverse_tangents_range( problem.target[row + echo], e2 ); for (std::int64_t direction = 0; direction < directions; ++direction) { - States& slope = slopes[static_cast(direction)]; + States& slope = slopes[direction]; const std::size_t at = problem.along.at(train, direction, echoes); const double d_angle = given ? (problem.d_first_flip == nullptr @@ -418,20 +455,12 @@ void inverse_tangents_range( problem.d_flip[at + echo] = d_angle; } along.rotate(solved.angle); - if (relaxing) { - along.relax(e1, e2); - for (States& slope : slopes) { - slope.relax(e1, e2); - } - } - along.shift(states, subspace::ALONG_AXIS); + advance(along, slopes, states, relaxing, e1, e2); problem.flip[row + echo] = solved.angle; problem.achieved[row + echo] = along.plus[0]; for (std::int64_t direction = 0; direction < directions; ++direction) { - States& slope = slopes[static_cast(direction)]; - slope.shift(states, subspace::ALONG_AXIS); problem.d_achieved[problem.along.at(train, direction, echoes) + echo] = - slope.plus[0]; + slopes[direction].plus[0]; } } for (std::size_t echo = length; echo < echoes; ++echo) { @@ -466,52 +495,29 @@ void forward_tangents_range( const std::int64_t directions = problem.along.directions; const bool relaxing = batch.relaxing(); States along(echoes + 1); - std::vector slopes( - static_cast(directions), States(echoes + 1) - ); + Slopes slopes(directions, 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 (States& slope : slopes) { - slope.clear(states); - } + start(along, slopes, states); 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); - for (States& slope : slopes) { - slope.relax(e1, e2); - } - } - along.shift(states, subspace::ALONG_AXIS); + advance(along, slopes, states, relaxing, e1, e2); const double angle = problem.flip[row + echo]; for (std::int64_t direction = 0; direction < directions; ++direction) { - States& slope = slopes[static_cast(direction)]; - slope.shift(states, subspace::ALONG_AXIS); - slope.rotate_tangent( + slopes[direction].rotate_tangent( along, angle, problem.d_flip[problem.along.at(train, direction, echoes) + echo] ); } along.rotate(angle); - if (relaxing) { - along.relax(e1, e2); - for (States& slope : slopes) { - slope.relax(e1, e2); - } - } - along.shift(states, subspace::ALONG_AXIS); + advance(along, slopes, states, relaxing, e1, e2); problem.echo[row + echo] = along.plus[0]; for (std::int64_t direction = 0; direction < directions; ++direction) { - States& slope = slopes[static_cast(direction)]; - slope.shift(states, subspace::ALONG_AXIS); problem.d_echo[problem.along.at(train, direction, echoes) + echo] = - slope.plus[0]; + slopes[direction].plus[0]; } } for (std::size_t echo = length; echo < echoes; ++echo) {