play

Contents

play#

pulserver.ir.play()[source]#

Walk the cache beside a sequence file as the scanner’s playout does.

The cache is loaded by the C library a scanner links, and its execution stream is walked with that library’s cursor: one entry per played block, in play order, across the subsequences of the chain. This build loads only vendor-neutral caches, and only when the size recorded in the cache matches the file.

Returns:

One entry per played block in each:

  • subsequence, segment: chain file and cache segment indices;

  • duration_us: block duration, in µs;

  • rf_amp_hz, rf_freq_hz, rf_phase_rad: RF amplitude (gamma B1) and frequency and phase offsets, with ppm offsets resolved at the field strength the cache was converted under; 0 without RF;

  • rf_use: the PULSEG_RF_USE_* code of the RF event, 1 for an excitation and 2 for a refocusing pulse; a pulse the file leaves unlabelled takes the use pypulseqpp detects when the chain is read, and an event a cache carries without one is a refocusing pulse at a flip angle of 162 to 198 degrees and an excitation otherwise; 0 without RF;

  • rf_delay_us: RF delay from the block’s start, in µs;

  • rf_channels: the transmit channels the RF waveform holds, one after another over one time base for a dynamic pTx pulse; 0 without RF;

  • rf_grad_constant, rf_grad_level: 1 where every instance of the block’s position plays its RF pulse under one gradient, steady from the pulse’s first sample to its last as pypulseqpp.Sequence.rf_gradients finds it, and the block carries no rotation, so the scanner may move the excitation by a carrier offset; and (blocks, 3), that gradient along x, y and z over the amplitude of the event playing it there;

  • gradient_hz_per_m: (blocks, 3), the amplitude along the logical x, y and z axes: the factor on the shape of the gradient event, or on the wave, the block plays there, each normalised to a largest magnitude of one;

  • wave: the wave the block plays, as indexed by the subsequence’s waves in summary(), or -1 for a block that plays its gradient events as they are. A block plays one at every segment position where an instance carries a rotation other than the identity, or plays a gradient definition or shape other than the one the position’s events are prepared with: its gradient events combined and turned by its rotation, so that the prescription’s rotation is the only one the scanner applies;

  • norot, nopos: the block’s NOROT and NOPOS flags;

  • adc, adc_freq_hz, adc_phase_rad: whether the block acquires, and its frequency and phase offsets;

  • adc_delay_us, adc_dwell_ns, adc_samples: the ADC delay from the block’s start, dwell time and sample count; 0 without ADC;

  • trid: the TRID group in force, 0 when ungrouped.

With waveforms, also:

  • rf_center_us: the time of the RF centre the design records, from the block’s start, in µs; NaN without RF;

  • rf_time_us, rf_waveform_hz: the samples of every played RF pulse, concatenated in play order: their times from the block’s start, in µs, and the instance’s amplitude times the magnitude shape and exp(i phase) of the phase shape its definition carries, complex, in Hz. The pulse plays each sample turned by the phase offset and advancing at the frequency offset from its start. The channels of a pTx pulse follow one another, each over the one time base;

  • rf_span: (blocks, 2), the start and stop of each block’s RF in those arrays; empty without RF;

  • gradient_time_us, gradient_waveform_hz_per_m: the corners of every played gradient, concatenated in play order: their times from the block’s start, in µs, and the gradient there, the amplitude times the shape or wave the instance plays. A waveform on the gradient raster holds its end values over the half raster intervals before its first sample and after its last. A rotated wave takes the corners of every gradient event it combines, or the raster centres across them when one is an arbitrary gradient on the raster;

  • gradient_span: (blocks, 3, 2), the start and stop of each block’s gradient along x, y and z in those arrays; empty without one;

  • adc_phase_modulation_rad: the phase modulation of every played readout, one phase per sample in radians, concatenated in play order; the receiver phase of a sample is the ADC phase offset, plus its frequency offset times the time since the ADC’s start, plus this. Empty for a cache converted here, which leaves the modulation to the reconstruction proxy;

  • adc_modulation_span: (blocks, 2), the start and stop of each block’s modulation in that array; empty without one.

Return type:

dict of str to ndarray

Raises:

  • ValueError – If the cache cannot be loaded.

  • RuntimeError – With waveforms, if a block’s gradient holds another number of samples than the segment position it plays at is prepared with, or its wave more points than that position reserves.

Contents