Isochromats.repetitions

Isochromats.repetitions#

Isochromats.repetitions()[source]#

Repetitions of a sequence of blocks, from the magnetisation where it stands.

Repetition n plays blocks with every RF event’s phase offset larger by phases[n], every ADC event’s by adc_phases[n], and gradients that differ from the blocks’ by a waveform zero during every RF pulse and held through every ADC window, at readouts[n, w] through the repetition’s w-th window, whose area at that window’s first sample is areas[n, w], by the start of any RF pulse zero, and over the repetition nets[n]: a phase encoding, or a readout turned with its prephaser, rewound or not.

One repetition applies an affine map to each isochromat’s magnetisation, and another to its transverse magnetisation at each window’s first sample. Four plays of blocks, from no magnetisation and from a unit magnetisation along each axis, give both; every repetition then follows from them, a pulse turned by a phase offset turning the maps alike. The windows are read as play() reads a window under a gradient held throughout it.

Parameters:

  • blocks (sequence of dict) – One repetition, each block as play()’s keyword arguments: duration and, where it plays them, gradients, rotation, rf and adc. Every window must be read under a gradient held throughout it, its samples on one side of any RF pulse in its block.

  • phases (array_like) – (repetitions,) increase of every RF event’s phase offset, in rad.

  • areas (array_like, default=None) – (repetitions, windows, 3) phase-encoding area at each window’s first sample, in 1/m, along the axes the positions are given along; none by default.

  • adc_phases (array_like, default=None) – (repetitions,) increase of every ADC event’s phase offset, in rad; phases by default.

  • readouts (array_like, default=None) – (repetitions, windows, 3) gradient the difference holds through each window, in Hz/m, along the axes the positions are given along; none by default. A window with any is read along each repetition’s own gradient, and the magnetisation is not split.

  • nets (array_like, default=None) – (repetitions, 3) area the difference leaves over each repetition, in 1/m, along the same axes; none by default. With any, each isochromat’s transverse magnetisation is turned by its own phase at the end of each repetition, and the magnetisation is not split.

  • pulse_gradients (array_like, default=None) – (repetitions, 3) gradient, in Hz/m along the same axes, by which the gradient held through the first block, under its RF pulse, exceeds that block’s own; none by default. With any, each isochromat’s map of the first block is read off the pulse’s tables at the field it sees under each repetition’s gradient, with the block’s free precession at that field; the four plays play the blocks after it, areas and nets are what the difference leaves over those blocks, and the magnetisation is not split. The first block must hold its gradient through it and read no ADC window.

  • system (Opts, default=None) – As play() takes it.

  • tolerance (float, default=0.0) – Accuracy of the samples, relative to the sum of the magnitudes of the terms each sums; exact to rounding at zero. Above zero, the windows are read by a kernel just wide enough for it, and from 1e-4 on the magnetisation is carried in single precision. Where, besides, the phases step by one increment, to within 1e-4 rad, and the phase encodings run along at most two axes along which the isochromats take few coordinates, as on a lattice, each isochromat’s magnetisation is split into its fixed point under the mean increment and a transient about it: the fixed points’ samples are summed over the columns of isochromats that share their coordinates along those axes, and an isochromat whose transient falls below tolerance times its proton density stands at its fixed point from then on.

  • split (bool, default=True) – Whether the magnetisation may be split so; repetitions that Repetitions.resume() after blocks played between them are not.

Returns:

The repetitions, which play in turn; the isochromats hold the magnetisation at the start of the next to be played.

Return type:

Repetitions

Raises:

ValueError – If the phases, ADC phases and areas do not describe one set of repetitions, a window is not read under a held gradient, a block is one play() would refuse, the isochromats move or diffuse, or, with pulse_gradients, the first block holds no gradient through it, reads a window, or plays a pulse whose channels play more than one waveform or whose tables would take more points than the isochromats over every repetition.

Examples

Balanced steady-state free precession, the RF phase alternating:

>>> import numpy as np
>>> import pypulseqpp as pp
>>> from pulserver.virtual import Isochromats
>>> spins = Isochromats([[0.0, 0.0, 0.0]], t1=1.0, t2=0.1)
>>> tr = [
...     dict(duration=1e-3, rf=pp.make_block_pulse(np.pi / 4, duration=0.5e-3)),
...     dict(duration=4e-3, adc=pp.make_adc(1, dwell=10e-6, delay=1.5e-3)),
... ]
>>> scan = spins.repetitions(tr, np.pi * np.arange(4))
>>> scan.play().shape
(4, 1, 1)