Events and blocks

TL;DR

• A sequence is an ordered list of blocks played back to back without a gap. The file holds a flattened event schedule without loops, branches or nested blocks.

• A block has a duration and at most one event per channel, and its events are played concurrently, each with its own delay. A block whose duration exceeds the extent of its events is a delay, which is how an echo time or a repetition time is realized.

• Events are stored in libraries, one row per distinct event, and the block table refers to them by integer id; indices are 1-based and a zero means no event on that channel. A shape is stored normalized, and the amplitude that scales it belongs to the event.

• Amplitudes are in Hz for RF and Hz/m for gradients rather than in tesla and tesla per metre. The gyromagnetic ratio in Hz/T, gamma on Opts, enters only where a physical amplitude is required.

• Extensions carry information for which the block table has no column: labels (LABELSET, LABELINC), whose values remain in force until set or incremented again, rotations, triggers, RF shims and soft delays.

Pulseq is an open file format for MR pulse sequences. A .seq file specifies event timing and channel assignment for a complete, portable acquisition. pypulseqpp builds, analyses and writes that description, and its Python interface preserves the format’s conventions.

The authoritative definition is the Pulseq specification and the MATLAB reference implementation.

Blocks

A sequence is an ordered list of blocks. A block has a duration and at most one event per channel: one RF pulse, one gradient on each of x, y and z, one ADC window, and a chain of extensions.

Two rules fix the timing completely:

1. The events of a block are played concurrently, each with its own delay from the start of the block.

2. Blocks are played back to back, with no gap between them.

The file contains a flattened event schedule without loops, branches or nested blocks. Scan-loop control exists only in the authoring program.

A block whose duration exceeds the extent of its events is therefore a delay, and this is how a repetition time is realized. A two-dimensional gradient-echo repetition, for example, is six blocks: the pulse with its slice-selection gradient, an echo-time delay carrying the slice rephaser, the prewinders, the readout gradient with its ADC, the spoilers, and a delay that completes the repetition time. Which of the middle blocks carries the wait is a design choice; that the wait is a block duration rather than a field of its own is the format.

One repetition of a two-dimensional gradient echo, over its six blocks, numbered in the order just listed. Blocks 2 and 6 last longer than their events, and that difference is the echo time and the repetition time.

Event libraries

Events are stored in libraries and referenced from the block table by integer id, so an event played ten thousand times is stored once:

[BLOCKS]
# NUM  DUR  RF  GX  GY  GZ  ADC  EXT
    1  694   1   0   0   1    0    2
    2  356   0   2   3   4    0    0
    3  268   0   5   0   0    1    0

A zero means the block has no event on that channel. Block and library indices are 1-based.

The block table of a written eight-line gradient-echo file, the libraries its cells index, and the shape library the RF and gradient rows index in turn. Each library holds one row per distinct event, however many blocks play it, so the tables below the block table are far shorter than it is.

RF

An amplitude in Hz, ids into a magnitude, a phase and optionally a time shape, a delay, frequency and phase offsets, a centre time, and a use — excitation, refocusing, inversion, saturation or preparation. The use identifies which pulses begin a shot and which refocus one, which is why the pulse factories such as make_slr_pulse() accept it and why rf_times() can report the two separately.

Gradients

Two kinds share one column. A trapezoid is an amplitude with rise, flat and fall times. An arbitrary gradient is a shape id, with an optional time shape when the samples do not fall on the gradient raster, and endpoint amplitudes. The two occupy separate tables and share the file’s id space.

ADC

A sample count, a dwell time, a delay, frequency and phase offsets, and an optional per-sample phase modulation.

Shapes

Sample arrays, compressed by a run-length encoding of their derivative, so a linear ramp of a thousand samples is stored as three numbers. A shape is stored normalized; the amplitude that scales it belongs to the event, not to the samples.

Gyromagnetic-ratio-free units

Amplitudes are in Hz for RF and Hz/m for gradients rather than in tesla and tesla per metre. The same file therefore means the same thing on any nucleus a scanner is tuned to, and the gyromagnetic ratio enters only where a physical amplitude is required.

Converting a reported amplitude from Hz/m to mT/m means dividing by the gyromagnetic ratio in Hz/T, which Opts holds as gamma, and multiplying by 1000. The constraint checks in Gradient, PNS and SAR constraints report their values in the file’s units and convert with that constant.

Extensions

Extensions carry information for which the block table has no column. Each block’s EXT id refers to a linked list of typed rows.

LABELSET and LABELINC

Counters and flags. The counters (LIN, PAR, SLC, ECO, REP, AVG, SET, SEG, PHS, ACQ) are the encoding indices a reconstruction sorts the acquisition by; the flags (NAV, REV, IMA, NOISE, REF, …) state what an acquisition is for. Label values are sticky: a value set on one block remains in force until it is set or incremented again, so the file contains one row where a counter changes rather than one row per block. evaluate_labels() evaluates the block table in order and returns the running values.

ROTATIONS

A quaternion that rotates the block’s gradients into the physical frame. One row per orientation replaces a rotated copy of every waveform, so a radial or spiral acquisition references a single interleaf for every shot; see Storage, deduplication and file revisions.

TRIGGERS

Wait on, or emit, a hardware signal.

RF_SHIMS

Per-transmit-channel magnitude and phase, for parallel transmission.

SOFT_DELAY

A delay whose duration is adjusted at the console without rewriting the file.

See also

• Storage, deduplication and file revisions — how events are stored, deduplicated and written.

• Timing and rasterization — the rasters every event time is quantized to.

• Events and blocks — the event factories and block operations.