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..e22bc301 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,204 @@ 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; + } +}; + +// 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; + 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); + 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; + 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; + 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} + : 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[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); + 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) { + problem.d_achieved[problem.along.at(train, direction, echoes) + echo] = + slopes[direction].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); + 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; + 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; + advance(along, slopes, states, relaxing, e1, e2); + const double angle = problem.flip[row + echo]; + for (std::int64_t direction = 0; direction < directions; ++direction) { + slopes[direction].rotate_tangent( + along, angle, + problem.d_flip[problem.along.at(train, direction, echoes) + echo] + ); + } + along.rotate(angle); + advance(along, slopes, states, relaxing, e1, e2); + problem.echo[row + echo] = along.plus[0]; + for (std::int64_t direction = 0; direction < directions; ++direction) { + problem.d_echo[problem.along.at(train, direction, echoes) + echo] = + slopes[direction].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 +652,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)