Sequence

class pulserver.Sequence(system, platform)

Bases: object

Intermediate representation of a Pulseq sequence.

This class manages the creation and handling of Pulseq blocks, which consist of one or more PyPulseq events. A PulseqBlock allows for a maximum of one event for each board (rf, gx, gy, gz, adc, trig) to be executed at a time.

Parameters:

• system (SimpleNamespace) – The hardware system parameters for the sequence (e.g., gradient, RF limits).

• platform (str) – The target platform for the sequence. Acceptable values are ‘pulseq’ (alias for ‘siemens’) and ‘toppe’ (alias for ‘gehc’).

_system

Holds the system configuration (e.g., gradient and RF settings).

Type:

SimpleNamespace

_format

Indicates the platform type (‘siemens’ or ‘gehc’).

Type:

str

_sequence

PyPulseq sequence or Ceq structure depending on the format.

Type:

pp.Sequence or Ceq

_block_library

Stores all defined Pulseq blocks by name.

Type:

dict

_header

Holds the sequence metadata, including parameters like FOV and shape.

Type:

SequenceDefinition

_section_labels

List of section labels in the sequence.

Type:

list

_sections_edges

Sequence length markers for different sections.

Type:

list

Methods

__init__
add_block	Add a previously registered block to the sequence.
build	Build the final sequence.
initialize_header	Initialize the header with sequence metadata.
register_block	Register a Pulseq block with one or more events.
section	Define a new section within the sequence.
set_definition	Set a specific sequence parameter in the header.
set_label	Set the label for the current MRI acquisition by configuring encoding indices and trajectory data.

initialize_header(ndims)

Initialize the header with sequence metadata.

Parameters:

ndims (int) – The number of dimensions for the acquisition (e.g., 2D or 3D).

register_block(name, rf=None, gx=None, gy=None, gz=None, adc=None, trig=None, delay=None)

Register a Pulseq block with one or more events.

Parameters:

• name (str) – The block name to be registered.

• rf (SimpleNamespace or None) – Individual components of the Pulseq block. These may include RF, gradients (gx, gy, gz), ADC event, trigger, or delay. If None, the event is ignored.

• gx (SimpleNamespace or None) – Individual components of the Pulseq block. These may include RF, gradients (gx, gy, gz), ADC event, trigger, or delay. If None, the event is ignored.

• gy (SimpleNamespace or None) – Individual components of the Pulseq block. These may include RF, gradients (gx, gy, gz), ADC event, trigger, or delay. If None, the event is ignored.

• gz (SimpleNamespace or None) – Individual components of the Pulseq block. These may include RF, gradients (gx, gy, gz), ADC event, trigger, or delay. If None, the event is ignored.

• adc (SimpleNamespace or None) – Individual components of the Pulseq block. These may include RF, gradients (gx, gy, gz), ADC event, trigger, or delay. If None, the event is ignored.

• trig (SimpleNamespace or None) – Individual components of the Pulseq block. These may include RF, gradients (gx, gy, gz), ADC event, trigger, or delay. If None, the event is ignored.

• delay (SimpleNamespace or None) – Individual components of the Pulseq block. These may include RF, gradients (gx, gy, gz), ADC event, trigger, or delay. If None, the event is ignored.

Raises:

AssertionError – If the sequence format is already defined or if the block contains both RF and ADC events.

section(name)

Define a new section within the sequence.

Parameters:

name (str) – A unique name for the section.

Raises:

AssertionError – If the section name already exists.

add_block(name, gx_amp=1.0, gy_amp=1.0, gz_amp=1.0, rf_amp=1.0, rf_phase=0.0, rf_freq=0.0, adc_phase=0.0, delay=None, rotmat=None)

Add a previously registered block to the sequence.

Parameters:

• name (str) – The name of the block to be added.

• gx_amp (float, optional) – Scaling factors for the x, y, and z gradients, respectively.

• gy_amp (float, optional) – Scaling factors for the x, y, and z gradients, respectively.

• gz_amp (float, optional) – Scaling factors for the x, y, and z gradients, respectively.

• rf_amp (float, optional) – Scaling factor for the RF pulse amplitude.

• rf_phase (float, optional) – Phase and frequency modulation for the RF pulse.

• rf_freq (float, optional) – Phase and frequency modulation for the RF pulse.

• adc_phase (float, optional) – Phase modulation for the ADC event.

• delay (float, optional) – Delay for pure delay blocks.

• rotmat (np.ndarray, optional) – 3x3 rotation matrix to apply to gradients.

Raises:

• AssertionError – If the block is not registered or gradients have inconsistent lengths.

• ValueError – If delay is missing for a pure delay block.

set_definition(key, *args, **kwargs)

Set a specific sequence parameter in the header.

Parameters:

• key (str) – Parameter to be set, e.g., ‘fov’, ‘shape’, ‘limits’, or ‘trajectory’.

• *args – Positional arguments for the parameter.

• **kwargs – Keyword arguments for the parameter.

Raises:

KeyError – If ‘fov’ is set before ‘shape’ in 2D acquisitions.

set_label(iy=None, iz=0, islice=None, icontrast=0, iframe=0, ishot=None)

Set the label for the current MRI acquisition by configuring encoding indices and trajectory data.

Parameters:

• iy (int, optional) – Cartesian encoding step in the k-space (along the y-axis). Mutually exclusive with ishot. Default is None.

• iz (int, optional) – Cartesian encoding step in the k-space (along the z-axis, for 3D acquisitions). Mutually exclusive with islice. Default is 0.

• islice (int, optional) – Slice index for 2D multislice acquisitions. Mutually exclusive with iz. Default is None.

• icontrast (int, optional) – Contrast encoding index for multicontrast MRI acquisitions. Mutually exclusive with iframe. Default is 0.

• iframe (int, optional) – Repetition or dynamic frame index for dynamic MRI acquisitions. Mutually exclusive with icontrast. Default is 0.

• ishot (int, optional) – Non-Cartesian encoding step (shot number). Mutually exclusive with iy. Default is None.

Raises:

ValueError – If both iy and ishot are provided (Cartesian and Non-Cartesian are mutually exclusive). If both islice and iz are provided (2D and 3D encoding are mutually exclusive). If both iframe and icontrast are provided (dynamic and multicontrast MRI are mutually exclusive).

Notes

This function updates the MRI acquisition label by setting k-space encoding indices and, if applicable, the corresponding trajectory from the self._trajectory attribute. The indices for k-space encoding (kspace_encode_step_1 for the y-axis, kspace_encode_step_2 for the z-axis or slice) and contrast or repetition are updated based on the provided parameters.

The acquisition trajectory is updated if ishot is provided, and it fetches the corresponding trajectory point from the self._trajectory data. The function also appends the newly created acquisition to self._labels.

Examples

Set a Cartesian acquisition with y and z encoding steps:

>>> set_label(iy=10, iz=5)

Set a 2D multislice acquisition with slice index:

>>> set_label(islice=3)

Set a Non-Cartesian shot-based acquisition:

>>> set_label(ishot=7)

build(ngain=0)

Build the final sequence.

Returns:

• sequence (pp.Sequence or Ceq) – The finalized sequence object.

• header (dict or None) – Sequence metadata, if available.