Readout#

This modules contains compositions of building blocks commonly used for in defining actual signal acqusition and spatial encoding

Functions:

`balanced_gre_cartesian_line`(system_specs, ...)	Generates a gradient sequence to apply phase encoding (0, 1.,0.) direction and a readout including adc-events for a single line in gradient direction (1., 0., 0.).
`get_longest_adc_duration`(system_specs, ...)	Creates the readout-gradient and prephaser (and balancing rewinder) with maximum flat top duration of the readout gradient, for the specified flat top area (defined by the image resoultion) and a specified total duration.
`get_shortest_adc_duration`(system_specs, ...)	Computes the shortest possible single-line readout gradient (without prephaser) for the given resolution and matrix size in RO direction.
`gre_cartesian_line`(system_specs, ...[, ...])	Generates a gradient sequence to apply phase encoding (0, 1.,0.) direction and a readout including adc-events for a single line in gradient direction (1., 0., 0.).
`matrix_to_kspace_2d`(matrix_size, ...)	Calculates maximal k-space vector and phase encoding for each line for a bottom up filling.
`multi_line_cartesian`(system_specs, fnc, ...)	Creates a list of sequences, one for each k-space_line for a given single-line-definiton e.g.
`pipe_WHIRLED_PEAS`(system_specs, interleaves, ...)	Generates WHIRL trajectory from analytic equations from James Pipe.
`se_cartesian_line`(system_specs, num_samples, ...)	Generates a gradient sequence to apply phase encoding (0, 1.,0.) direction and a readout including adc-events for a single line in gradient direction (1., 0., 0.) for a spin-echo based readout.
`single_shot_epi`(system_specs, field_of_view, ...)	Defines a single shot EPI readout sequence according to the image configuration.
`spiral_pipezwart`(system_specs, interleaves, ...)	Generates spiral trajectory.

balanced_gre_cartesian_line(system_specs, num_samples, k_readout, k_phase, adc_duration, delay=<Quantity(0.0, 'millisecond')>, prephaser_duration=None)#

Generates a gradient sequence to apply phase encoding (0, 1.,0.) direction and a readout including adc-events for a single line in gradient direction (1., 0., 0.). After readout prephasers are rewound. Is designed to work for gradient-echo based readouts.

Parameters:

system_specs (SystemSpec) – SystemSpecification
num_samples (int) – Number of samples acquired during frequency encoding
k_readout (Quantity) – Quantity[1/Length] \(FOV_{kx}\) corresponds to \(1/\Delta x\) s
k_phase (Quantity) – Quantity[1/Length] \(n \Delta k_{y}\) phase encoding strength of current line
adc_duration (Quantity) – Quantity[time] Total duration of adc-sampling for a single TR
delay (Quantity) – Defaults to 0 ms
prephaser_duration (Optional[Quantity]) – Optional - if not specified the shortest possible duration for the RO/PE prephaser is calculates

Return type:

Sequence

Returns:

Sequence object containing RO- & PE-gradients plus rewinders as well as ADC events

get_longest_adc_duration(system_specs, total_duration, num_samples, resolution, balanced=False, additional_kspace_traverse=None)#

Creates the readout-gradient and prephaser (and balancing rewinder) with maximum flat top duration of the readout gradient, for the specified flat top area (defined by the image resoultion) and a specified total duration.

Parameters:

system_specs (SystemSpec) –
total_duration (Quantity) – Total duration to fit the gradients into.
num_samples (int) – Number of samples (used to compute the required k-space traverse)
resoultion – Resultion in RO direction (used to compute the required k-space traverse)
balanced (bool) – If true, the total duration includes the rewinder after the readout, otherwise not
additional_kspace_traverse (Optional[Quantity]) – k-space vector that needs to be traversed during the prephaser, while adhering to the norm of the combined gradient channels being smaller than system_specs.max_grad. If None, no additional traverse is assumed, potentially resulting in higher prephaser amplitudes.
resolution (Quantity) –

Return type:

(TrapezoidalGradient, TrapezoidalGradient)

Returns:

Two trapezoidal gradient objects, one for the prephaser and the other for the readout gradient

get_shortest_adc_duration(system_specs, num_samples, resolution)#

Computes the shortest possible single-line readout gradient (without prephaser) for the given resolution and matrix size in RO direction.

Assumes gradients are ramped with maximum slew-rate.

\[\Delta = 2 a / s_{max} + A / a\]

with

\[A = k_{max} / \gamma\]

Parameters:

system_specs (SystemSpec) –
num_samples (int) –
resolution (Quantity) –

Return type:

(Quantity, Quantity, Quantity)

Returns:

flat_duration, rise_time and amplitude of the trapezoidal_gradient

gre_cartesian_line(system_specs, num_samples, k_readout, k_phase, adc_duration, delay=<Quantity(0.0, 'millisecond')>, prephaser_duration=None)#

Generates a gradient sequence to apply phase encoding (0, 1.,0.) direction and a readout including adc-events for a single line in gradient direction (1., 0., 0.). Is designed to work for gradient-echo based readouts.

. ADC:                      ||||||     -> num_samples    .
.                           ______                       .
. RO:      ___________     /      \                      .
.                     \___/                              .
.                      ___                               .
. PE:      ___________/   \________                      .
.                                                        .
.         | delay    |     |     |                       .
.                        adc_duration                    .

Parameters:

system_specs (SystemSpec) – SystemSpecification
num_samples (int) – Number of samples acquired during frequency encoding
k_readout (Quantity) – Quantity[1/Length] \(FOV_{kx}\) corresponds to \(1/\Delta x\) s
k_phase (Quantity) – Quantity[1/Length] \(n \Delta k_{y}\) phase encoding strength of current line
adc_duration (Quantity) – Quantity[time] Total duration of adc-sampling for a single TR
delay (Quantity) –
prephaser_duration (Optional[Quantity]) – Optional - if not specified the shortest possible duration for the RO/PE prephaser is calculated

Return type:

Sequence

Returns:

Sequence object containing RO- & PE-gradients as well as ADC events

matrix_to_kspace_2d(matrix_size, inplane_resolution)#

Calculates maximal k-space vector and phase encoding for each line for a bottom up filling.

The k-space center will allway be covered by a line, therefore:

For an even number of k-space lines the first line at -kmax_pe and the last line is at +kmax_pe - delta_kpe

For and odd number the lines are symmetric around the center in pe direction

Parameters:

matrix_size (ndarray) – (2, ) Integer array providing the inplane matrix size
inplane_resolution (Quantity) – (2, ) Quantity with length-dimension providing the inplane resolution

Return type:

(ndarray, ndarray)

Returns:

k_max (2, ), k-phase positions in phase encoding direction

multi_line_cartesian(system_specs, fnc, matrix_size, inplane_resolution, dummy_shots=None, **kwargs)#

Creates a list of sequences, one for each k-space_line for a given single-line-definiton e.g. se_cartesian_line, gre_cartesian_line

Example: .. code-block: python

ro_blocks = cmrseq.seqdefs.readout.multi_line_cartesian(
system_specs=system_specs, fnc=cmrseq.seqdefs.readout.gre_cartesian_line, matrix_size=matrix_size, inplane_resolution=inplane_resolution, adc_duration=adc_duration, prephaser_duration=ss_refocus.duration, dummy_shots=dummy_shots)

Parameters:

system_specs (SystemSpec) – SystemSpecification
fnc (callable) – callable
matrix_size (ndarray) – array of shape (2, )
inplane_resolution (Quantity) – Quantity[Length] of shape (2, )
dummy_shots (Optional[int]) – number of shots without adc-events
kwargs – is forwared to call fnc. may not contain num_samples, k_readout, k_phase, prephaser_duration

Returns:

pipe_WHIRLED_PEAS(system_specs, interleaves, fov, kr_max, freq_max=<Quantity(0, 'hertz')>)#

Generates WHIRL trajectory from analytic equations from James Pipe.

Pipe JG. WHIRLED PEAS: Analytical Equations for Spiral Trajectories and Matching Gradient Waveforms. ISMRM Annual Meeting 2023 Original code can be found at jim-pipe/whirled-peas

Parameters:

system_specs (SystemSpec) – SystemSpecifications
interleaves (int) – number of interleaved spirals
fov (Quantity) – field of view
kr_max (Quantity) – \(FOV_{kr, max}\) corresponding to minimal radial resolution \(1/\Delta r\)
freq_max (Quantity) – maximum frequency of spiral rotation, optional

Returns:

se_cartesian_line(system_specs, num_samples, echo_time, pulse_duration, excitation_center_time, k_readout, k_phase, adc_duration, delay=<Quantity(0.0, 'millisecond')>, prephaser_duration=None)#

Generates a gradient sequence to apply phase encoding (0, 1.,0.) direction and a readout including adc-events for a single line in gradient direction (1., 0., 0.) for a spin-echo based readout.

.                excitation center                                  .
.                   |                                               .
.                   |   TE/2 |   TE/2 |                             .
.   ADC:                           ||||||     -> num_samples        .
.                      ___         ______                           .
.   RO:           ____/   \_______/      \                          .
.                      ___                                          .
.   PE:           ____/   \_____________                            .
.           |   |                 |     |                           .
.           delay              adc_duration                         .
.               |    |                                              .
.           pulse_duration                                          .

Raises:

ValueError – If phase/frequency encoding amplitude would exceed system limits

Parameters:

system_specs (SystemSpec) – SystemSpecification
num_samples (int) – Number of samples acquired during frequency encoding
echo_time (Quantity) –
pulse_duration (Quantity) – total time of ss-gradient (including ramps)
excitation_center_time (Quantity) – Quantity[Time] Reference time-point to calculate TE from
k_readout (Quantity) – Quantity[1/Length] \(FOV_{kx}\) corresponds to \(1/\Delta x\)
k_phase (Quantity) – Quantity[1/Length] \(n \Delta k_{y}\) phase encoding strength of current line
adc_duration (Quantity) – Quantity[time] Total duration of adc-sampling for a single TR
prephaser_duration (Optional[Quantity]) – Optional - if not specified the shortest possible duration for the RO/PE prephaser is calculates
delay (Quantity) –

Return type:

Sequence

Returns:

Sequence containing the RO/PE prephaser, RO and adc events for a spin-echo read-out

single_shot_epi(system_specs, field_of_view, matrix_size, blip_direction='up', partial_fourier_lines=0, slope_sampling=False, water_fat_shift='minimum', max_total_duration=None, delay=<Quantity(0, 'millisecond')>)#

Defines a single shot EPI readout sequence according to the image configuration. Assumes the prephaser to be as short as possible.

Raises:

ValueError if shortest possible duration is longer than max_total_duration
ValueError if water-fat-shift==”maximum” but max_total_duration==None

Parameters:

system_specs (SystemSpec) –
field_of_view (Quantity) –
matrix_size (ndarray) –
blip_direction (str) –
partial_fourier_lines (int) –
slope_sampling (bool) –
water_fat_shift (str | float) –
max_total_duration (Quantity | None) –
delay (Quantity) –

Return type:

Sequence

.                                                                     .
.           ADC:     |||  |||  |||  |||  |||  |||                     .
.                         ___       ___       ___                     .
.           RO:          /   \     /   \     /   \                    .
.                   \___/     \___/     \___/     \___/               .
.                                                                     .
.           PE:          ____/\___/\___/\___/\___/\_______            .
.                   \___/                                             .
.                                  |  |                               .
.                                adc_duration                         .

Parameters:

system_specs (SystemSpec) – cmrseq.SystemSpecs
field_of_view (Quantity) – Quantity[Length] - Defines the spatial extend in readout and phase-encoding direction
matrix_size (ndarray) – np.ndarray (2, ) - number of samples in readout/phase-encoding direction if partial fourier is enabled the lines are subtracted from this parameter
blip_direction (str) – (str) from [‘up’, ‘down’] specifies the direction of phase encoding steps
partial_fourier_lines (int) – (int) number of lines to be skipped before k-space center
slope_sampling (bool) – if True the unbound method (epi_ramp_sampling) is used, otherwise the unbound method (epi_flat_sampling) is used.
max_total_duration (Optional[Quantity]) – Quantity needs to be specified if water-fat-shift is set to maximum.
water_fat_shift (Union[str, float]) – one of [‘minimum’, ‘maximum’, #pixels(float)]. Determines the echo-spacing therefore the duration of all according to the formula \(P/(C * (N+1)) = T\) with (P)ixels, (C)hemical shift frequency, (N)umber of k-space lines and (T) Echo spacing
delay (Quantity) – Time gap added before the sequence

Return type:

Sequence

spiral_pipezwart(system_specs, interleaves, kr_max, kr_delta, spiral_type='archimedean', gradient_rewind_type='ramp down', undersampling_type='none', undersampling_start=1.0, undersampling_end=1.0, undersampling_factor=1.0, kz_max=<Quantity(1.0, '1 / meter')>, kz_delta=<Quantity(1.0, '1 / meter')>)#

Generates spiral trajectory. Ported from C code provided along with: Pipe JG, Zwart NR. Spiral trajectory design: A flexible numerical algorithm and base analytical equations. Magn. Reson. Med. 2014;71:278–285 doi: 10.1002/mrm.24675.

Original C code can be found at https://www.ismrm.org/mri_unbound/sequence.htm

Some small changes to indexing when defining rewinder gradients and to address slew rate: violations

Warning:

If not rewound, gradient waveform does not end on 0 magnitude, therefore it is likely to violate subsequent sequence validation.

Parameters:

system_specs (SystemSpec) – SystemSpecifications
interleaves (int) – number of interleaved spirals
kr_max (Quantity) – \(FOV_{kr, max}\) corresponding to minimal radial resolution \(1/\Delta r\)
kr_delta (Quantity) – k-space radial step-length
spiral_type (str) – str from [‘Archimedean’, ‘spherical dst’] denoting the type of spiral
gradient_rewind_type (str) – From [None, ‘ramp down’, ‘rewind to center’] denoting the type of gradient rewind. If None is specified, the gradient waveform will not end on 0 magnitude, potentially violating subsequent sequence-validation
undersampling_type (str) – str from [‘linear’, ‘quadratic’, ‘hanning’] defining the type of undersampling during acquisition
undersampling_start (float) –
undersampling_end (float) –
undersampling_factor (float) –
kz_max (Quantity) –
kz_delta (Quantity) –

Return type:

ArbitraryGradient

Returns:

Gradient block containing the spiral waveform