Pulseq Sequence Interpreter#

The pulseq sequence interpreter consists of two sub-components. The SequenceProvider reads all the events from a pulseq sequence and calculates RF and gradient waveform. The unrolled pulse sequence is provided as UnrolledSequence which contains the unrolled waveforms and some additional data.

See also

User guide on the sequence calculation.

Sequence Provider#

Sequence provider class.

class console.pulseq_interpreter.sequence_provider.SequenceProvider(gradient_efficiency: list[float], gpa_gain: list[float], high_impedance: list[bool], output_limits: list[int], system_limits: SystemLimits, spcm_dwell_time: float = 5e-08, rf_to_mvolt: float = 1.0)[source]#

Bases: Sequence

Sequence provider class.

This object is inherited from pulseq sequence object, so that all methods of the pypulseq Sequence object can be accessed.

The main functionality of the SequenceProvider is to unroll a given pulseq sequence. Usually the first step is to read a sequence file. The unrolling step can be achieved using the unroll_sequence() function.

Example

>>> seq_provider = SequenceProvider()
>>> seq_provider.read("./seq_file.seq")
>>> unrolled = seq_provider.unroll_sequence(acquisition_parameter)
dict() → dict[source]#

Abstract method which returns variables for logging in dictionary.

from_pypulseq(seq: Sequence) → None[source]#

Cast a pypulseq Sequence instance to this SequenceProvider.

If argument is a valid Sequence instance, all the attributes of Sequence are set in this SequenceProvider (inherits from Sequence).

Parameters:

seq – Pypulseq Sequence instance

Raises:

  • ValueError – seq is not a valid pypulseq Sequence instance

  • AttributeError – Key of Sequence instance not

get_adc_events() → list[source]#

Extract ADC ‘waveforms’ from the sequence.

TODO: Add error checks

Returns:

list

Return type:

List of with waveform ID, gate signal and reference signal for each unique ADC event.

get_rf_events() → list[source]#

Extract RF ‘waveforms’ from sequence file.

Returns:

list

Return type:

list of unique RF events.

plot_unrolled(time_range: tuple[float, float] = (0, -1)) → tuple[Figure, ndarray][source]#

Plot unrolled waveforms for replay.

Parameters:

  • time_range – Specify the time range of the plot in seconds. If the second value is smaller then the first or -1, the whole sequence is plotted.

  • (0 (default =) – Specify the time range of the plot in seconds. If the second value is smaller then the first or -1, the whole sequence is plotted.

  • -1) – Specify the time range of the plot in seconds. If the second value is smaller then the first or -1, the whole sequence is plotted.

Return type:

Matplotlib figure and axis

to_pypulseq() → Sequence | None[source]#

Slice sequence provider to return pypulseq sequence.

unroll_sequence(parameter: AcquisitionParameter) → UnrolledSequence[source]#

Unroll the pypulseq sequence description.

Parameters:

parameter – Instance of AcquisitionParameter containing all necessary parameters to calculate the sequence waveforms, i.e. larmor frequency, gradient offsets, etc.

Returns:

Instance of an unrolled sequence object which contains a list of numpy arrays with the block-wise calculated sample points in correct spectrum card order (Fortran).

The list of unrolled sequence arrays is returned as uint16 values which contain a digital signal encoded by 15th bit. Only the RF channel does not contain a digital signal. In addition, all receive events are described and returned in a list within the unrolled sequence object.

Return type:

UnrolledSequence

Examples

For channels ch0, ch1, ch2, ch3, data values n = 0, 1, …, N are ordered the following way.

>>> data = [ch0_0, ch1_0, ch2_0, ch3_0, ch0_1, ch1_1, ..., ch0_n, ..., ch3_N]

Per channel data can be extracted by the following code.

>>> rf = seq[0::4]
>>> gx = (seq[1::4] << 1).astype(np.int16)
>>> gy = (seq[2::4] << 1).astype(np.int16)
>>> gz = (seq[3::4] << 1).astype(np.int16)

All the gradient channels contain a digital signal encoded by the 15th bit. - gx: ADC gate signal - gy: Reference signal for phase correction - gz: RF unblanking signal The following example shows, how to extract the digital signals

>>> adc_gate = seq[1::4].astype(np.uint16) >> 15
>>> reference = seq[2::4].astype(np.uint16) >> 15
>>> unblanking = seq[3::4].astype(np.uint16) >> 15

As the 15th bit is not encoding the sign (as usual for int16), the values are casted to uint16 before shifting.

console.pulseq_interpreter.sequence_provider.profile(func: Callable[[...], Any]) → Callable[[...], Any][source]#

Define placeholder for profile decorator.

Unrolled Sequence#

Interface class for an unrolled sequence.

class console.interfaces.unrolled_sequence.UnrolledSequence(seq: ndarray, sample_count: int, rx_data: list[RxData], gpa_gain: list[float], gradient_efficiency: list[float], rf_to_mvolt: float, dwell_time: float, duration: float, adc_count: int, parameter: AcquisitionParameter)[source]#

Bases: object

Unrolled sequence interface.

This interface is used to share the unrolled sequence between the different components like TxEngine, SequenceProvider and AcquisitionControl. An unrolled sequence is generated by a SequenceProvider() instance using the unroll_sequence function.

adc_count: int#

Number of adc events in the sequence.

duration: float#

Total duration of the unrolled sequence in s.

dwell_time: float#

Dwell time of the spectrum card replay data (unrolled sequence). Defines the distance in time between to sample points. Note that this dwell time does not correlate to the larmor frequecy. Due to the sampling theorem dwell_time < 1/(2*larmor_frequency) must be satisfied. Usually a higher factor is chosen.

gpa_gain: list[float]#

The gradient waveforms in pulseq are defined in Hz/m. The translation to mV is calculated by 1e3 / (gyro * gpa_gain * grad_efficiency). The gpa gain is given in V/A and accounts for the voltage required to generate an output of 1A. The gyromagnetic ratio defined by 42.58e6 MHz/T.

gradient_efficiency: list[float]#

The gradient waveforms in pulseq are defined in Hz/m. The translation to mV is calculated by 1e3 / (gyro * gpa_gain * grad_efficiency). The gradient efficiency is given in mT/m/A and accounts for the gradient field which is generated per 1A. The gyromagnetic ratio defined by 42.58e6 MHz/T.

parameter: AcquisitionParameter#

Hash of acquisition parameters used to calculate the sequence.

rf_to_mvolt: float#

If sequence values are given as float values, they can be interpreted as output voltage [mV] directly. This conversion factor represents the scaling from original pulseq RF values [Hz] to card output voltage.

rx_data: list[RxData]#

List containing the data and metadata of all receive events

sample_count: int#

Total number of samples per channel.

seq: ndarray#

Replay data as int16 values in a list of numpy arrays. The sequence data already contains the digital adc and unblanking signals in the channels gx and gy.