pypulseq package¶

Subpackages¶

Submodules¶

pypulseq.add_gradients module¶

pypulseq.add_gradients.add_gradients(grads: Iterable[types.SimpleNamespace], max_grad: int = 0, max_slew: int = 0, system=<pypulseq.opts.Opts object>) → types.SimpleNamespace¶

Returns the superposition of several gradients.

Parameters

grads ([SimpleNamespace, ..]) – Gradient events.
system (Opts, default=Opts()) – System limits.
max_grad (float, default=0) – Maximum gradient amplitude.
max_slew (float, default=0) – Maximum slew rate.

Returns

grad – Superimposition of gradient events from grads.

Return type

SimpleNamespace

pypulseq.add_ramps module¶

pypulseq.add_ramps.add_ramps(k: Union[list, numpy.ndarray, tuple], max_grad: int = 0, max_slew: int = 0, rf: Optional[types.SimpleNamespace] = None, system=<pypulseq.opts.Opts object>) → List[numpy.ndarray]¶

Add segments to the trajectory to ramp to and from the given trajectory.

Parameters

k (numpy.ndarray, or [numpy.ndarray, ..]) – If k is a single trajectory: Add a segment to k so k_out travels from 0 to k[0] and a segment so k_out goes from k[-1] back to 0 without violating the gradient and slew constraints. If k is multiple trajectoriess: add segments of the same length for each trajectory in the cell array.
system (Opts, default=Opts()) – System limits.
rf (SimpleNamespace, default=None) – Add a segment of zeros over the ramp times to an RF shape.
max_grad (int, default=0) – Maximum gradient amplitude.
max_slew (int, default=0) – Maximum slew rate.

Returns

result – List of ramped up and ramped down k-space trajectories from k.

Return type

[numpy.ndarray, ..]

Raises

ValueError – If k is not list, np.ndarray or tuple
RuntimeError – If gradient ramps fail to be calculated

pypulseq.align module¶

pypulseq.align.align(**kwargs: Union[types.SimpleNamespace, List[types.SimpleNamespace]]) → List[types.SimpleNamespace]¶

Sets delays of the objects within the block to achieve the desired alignment of the objects in the block. Aligns objects as per specified alignment options by setting delays of the pulse sequence events within the block. All previously configured delays within objects are taken into account during calculating of the block duration but then reset according to the selected alignment. Possible values for align_spec are ‘left’, ‘center’, ‘right’.

Parameters: args (dict{str, [SimpleNamespace, ..]}) – Dictionary mapping of alignment options and SimpleNamespace objects. Format: alignment_spec1=SimpleNamespace, alignment_spec2=[SimpleNamespace, …], … Alignment spec must be one of left, center or right.
Returns: objects – List of aligned SimpleNamespace objects.
Return type: [SimpleNamespace, ..]
Raises: ValueError – If first parameter is not of type str. If invalid alignment spec is passed. Must be one of left, center or right.

Examples

al_grad1, al_grad2, al_grad3 = align(right=[grad1, grad2, grad3])

pypulseq.block_to_events module¶

pypulseq.block_to_events.block_to_events(*args: types.SimpleNamespace) → Tuple[types.SimpleNamespace, …]¶

Converts args from a block to a list of events. If args is already a list of event(s), returns it unmodified.

Parameters: args (SimpleNamespace) – Block to be flattened into a list of events.
Returns: events – List of events comprising args if it was a block, otherwise args unmodified.
Return type: list[SimpleNamespace]

pypulseq.calc_duration module¶

pypulseq.calc_duration.calc_duration(*args: types.SimpleNamespace) → float¶

Calculate the duration of an event or block.

Parameters: args (SimpleNamespace) – Block or events.
Returns: duration – Cumulative duration of args.
Return type: float

pypulseq.calc_ramp module¶

pypulseq.calc_ramp.calc_ramp(k0: numpy.ndarray, k_end: numpy.ndarray, max_grad: numpy.ndarray = numpy.zeros, max_points: int = 500, max_slew: numpy.ndarray = numpy.zeros, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>) → Tuple[numpy.ndarray, bool]¶

Join the points k0 and k_end in three-dimensional k-space in minimal time, observing the gradient and slew limits (max_grad and max_slew respectively), and the gradient strength G0 before k0[:, 1] and Gend after k_end[:, 1]. In the context of a fixed gradient dwell time this is a discrete problem with an a priori unknown number of discretization steps. Therefore this method tries out the optimization with 0 steps, then 1 step, and so on, until all conditions can be fulfilled, thus yielding a short connection.

Parameters

k0 (numpy.ndarray) – Two preceding points in k-space. Shape is [3, 2]. From these points, the starting gradient will be calculated.
k_end (numpy.ndarray) – Two following points in k-space. Shape is [3, 2]. From these points, the target gradient will be calculated.
max_grad (float or array_like, default=0) – Maximum total gradient strength. Either a single value or one value for each coordinate, of shape [3, 1].
max_points (int, default=500) – Maximum number of k-space points to be used in connecting k0 and k_end.
max_slew (float or array_like, default=0) – Maximum total slew rate. Either a single value or one value for each coordinate, of shape [3, 1].
system (Opts, default=Opts()) – System limits.

Returns

k_out (numpy.ndarray) – Connected k-space trajectory.
success (bool) – Boolean flag indicating if k0 and k_end were successfully joined.

pypulseq.calc_rf_bandwidth module¶

pypulseq.calc_rf_bandwidth.calc_rf_bandwidth(rf: types.SimpleNamespace, cutoff: float = 0.5, return_axis: bool = False, return_spectrum: bool = False) → Union[float, Tuple[float, numpy.ndarray], Tuple[float, numpy.ndarray, float]]¶

Calculate the spectrum of the RF pulse. Returns the bandwidth of the pulse (calculated by a simple FFT, e.g. presuming a low-angle approximation) and optionally the spectrum and the frequency axis. The default for the optional parameter ‘cutoff’ is 0.5.

Parameters

rf (SimpleNamespace) – RF pulse event.
cutoff (float, default=0.5) –
return_axis (bool, default=False) – Boolean flag to indicate if frequency axis of RF pulse will be returned.
return_spectrum (bool, default=False) – Boolean flag to indicate if spectrum of RF pulse will be returned.

Returns

bw – Bandwidth of the RF pulse.

Return type

float

pypulseq.calc_rf_center module¶

pypulseq.calc_rf_center.calc_rf_center(rf: types.SimpleNamespace) → Tuple[float, float]¶

Calculate the time point of the effective rotation calculated as the peak of the radio-frequency amplitude for the shaped pulses and the center of the pulse for the block pulses. Zero padding in the radio-frequency pulse is considered as a part of the shape. Delay field of the radio-frequency object is not taken into account.

Parameters

rf (SimpleNamespace) – Radio-frequency pulse event.

Returns

time_center (float) – Time point of the center of the radio-frequency pulse.
id_center (float) – Corresponding position of time_center in the radio-frequency pulse’s envelope.

pypulseq.check_timing module¶

pypulseq.check_timing.check_timing(system: pypulseq.opts.Opts, *events: types.SimpleNamespace) → Tuple[bool, str, float]¶

Checks if timings of events are aligned with the corresponding raster time.

Parameters

system (Opts) – System limits object.
events (SimpleNamespace) – Events.

Returns

is_ok (bool) – Boolean flag indicating if timing of events events are aligned with gradient raster time system.grad_raster_time.
text_err (str) – Error string, if timings are not aligned.
total_duration (float) – Total duration of events.

Raises

ValueError – If incorrect data type is encountered in events.

pypulseq.compress_shape module¶

pypulseq.compress_shape.compress_shape(decompressed_shape: numpy.ndarray, force_compression: bool = False) → types.SimpleNamespace¶

Compress a gradient or pulse shape waveform using a run-length compression scheme on the derivative. This strategy encodes constant and linear waveforms with very few samples. A structure is returned with the fields: - num_samples - the number of samples in the uncompressed waveform - data - containing the compressed waveform

pypulseq.convert module¶

pypulseq.convert.convert(from_value: Union[float, Iterable], from_unit: str, gamma: float = 42576000.0, to_unit: str = '') → Union[float, Iterable]¶

Converts gradient amplitude or slew rate from unit from_unit to unit to_unit with gyromagnetic ratio gamma.

Parameters

from_value (float) – Gradient amplitude or slew rate to convert from.
from_unit (str) – Unit of gradient amplitude or slew rate to convert from.
to_unit (str, default='') – Unit of gradient amplitude or slew rate to convert to.
gamma (float, default=42.576e6) – Gyromagnetic ratio. Default is 42.576e6, for Hydrogen.

Returns

out – Converted gradient amplitude or slew rate.

Return type

float

Raises

ValueError – If an invalid from_unit is passed. Must be one of ‘Hz/m’, ‘mT/m’, or ‘rad/ms/mm’. If an invalid to_unit is passed. Must be one of ‘Hz/m/s’, ‘mT/m/ms’, ‘T/m/s’, ‘rad/ms/mm/ms’.

pypulseq.decompress_shape module¶

pypulseq.decompress_shape.decompress_shape(compressed_shape: types.SimpleNamespace, force_decompression: bool = False) → numpy.ndarray¶

Decompress a gradient or pulse shape compressed with a run-length compression scheme on the derivative. The given shape is structure with the following fields: - num_samples - the number of samples in the uncompressed waveform - data - containing the compressed waveform

pypulseq.event_lib module¶

class pypulseq.event_lib.EventLibrary¶

Bases: object

Defines an event library ot maintain a list of events. Provides methods to insert new data and find existing data.

Sequence Properties: - keys - A list of event IDs - data - A struct array with field ‘array’ to store data of varying lengths, remaining compatible with codegen. - lengths - Corresponding lengths of the data arrays - type - Type to distinguish events in the same class (e.g. trapezoids and arbitrary gradients)

Sequence Methods: - find - Find an event in the library - insert - Add a new event to the library

pypulseq.make_adc module¶

pypulseq.make_adc.make_adc(num_samples: int, delay: float = 0, duration: float = 0, dwell: float = 0, freq_offset: float = 0, phase_offset: float = 0, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>) → types.SimpleNamespace¶

Create an ADC readout event.

Parameters

num_samples (int) – Number of readout samples.
system (Opts, default=Opts()) – System limits. Default is a system limits object initialised to default values.
dwell (float, default=0) – ADC dead time in seconds (s) after sampling.
duration (float, default=0) – Duration in seconds (s) of ADC readout event with num_samples number of samples.
delay (float, default=0) – Delay in seconds (s) of ADC readout event.
freq_offset (float, default=0) – Frequency offset of ADC readout event.
phase_offset (float, default=0) – Phase offset of ADC readout event.

Returns

adc – ADC readout event.

Return type

SimpleNamespace

Raises

ValueError – If neither dwell nor duration are defined.

pypulseq.make_adiabatic_pulse module¶

pypulseq.make_adiabatic_pulse.make_adiabatic_pulse(pulse_type: str, adiabaticity: int = 4, bandwidth: int = 40000, beta: int = 800, delay: float = 0, duration: float = 0.01, dwell: float = 0, freq_offset: float = 0, max_grad: float = 0, max_slew: float = 0, n_fac: int = 40, mu: float = 4.9, phase_offset: float = 0, return_gz: bool = False, return_delay: bool = False, slice_thickness: float = 0, system=<pypulseq.opts.Opts object>, use: str = '') → Union[types.SimpleNamespace, Tuple[types.SimpleNamespace, types.SimpleNamespace, types.SimpleNamespace, types.SimpleNamespace], Tuple[types.SimpleNamespace, types.SimpleNamespace, types.SimpleNamespace]]¶

Make an adiabatic inversion pulse.

Note: some parameters only affect certain pulse types and are ignored for other; e.g. bandwidth is ignored if type=’hypsec’.

hypsec(n=512, beta=800, mu=4.9, dur=0.012)

Design a hyperbolic secant adiabatic pulse. mu * beta becomes the amplitude of the frequency sweep.

Args:

n (int): number of samples (should be a multiple of 4).
beta (float): AM waveform parameter.
mu (float): a constant, determines amplitude of frequency sweep.
dur (float): pulse time (s).

Returns:

2-element tuple containing - a (array): AM waveform. - om (array): FM waveform (radians/s).

References:

Baum, J., Tycko, R. and Pines, A. (1985). ‘Broadband and adiabatic inversion of a two-level system by phase-modulated pulses’. Phys. Rev. A., 32:3435-3447.

wurst(n=512, n_fac=40, bw=40000.0, dur=0.002)

Design a WURST (wideband, uniform rate, smooth truncation) adiabatic inversion pulse

Args:

n (int): number of samples (should be a multiple of 4).
n_fac (int): power to exponentiate to within AM term. ~20 or greater is typical.
bw (float): pulse bandwidth.
dur (float): pulse time (s).

Returns:

2-element tuple containing - a (array): AM waveform. - om (array): FM waveform (radians/s).

References:

Kupce, E. and Freeman, R. (1995). ‘Stretched Adiabatic Pulses for Broadband Spin Inversion’. J. Magn. Reson. Ser. A., 117:246-256.

Parameters

pulse_type (str) – One of ‘hypsec’ or ‘wurst’ pulse types.
adiabaticity (int, default=4) –
bandwidth (int, default=40000) – Pulse bandwidth.
beta (int, default=800) – AM waveform parameter.
delay (float, default=0) – Delay in seconds (s).
duration (float, default=10e-3) – Pulse time (s).
dwell (float, default=0) –
freq_offset (float, default=0) –
max_grad (float, default=0) – Maximum gradient strength.
max_slew (float, default=0) – Maximum slew rate.
mu (float, default=4.9) – Constant determining amplitude of frequency sweep.
n_fac (int, default=40) – Power to exponentiate to within AM term. ~20 or greater is typical.
phase_offset (float, default=0) – Phase offset.
return_delay (bool, default=False) – Boolean flag to indicate if the delay has to be returned.
return_gz (bool, default=False) – Boolean flag to indicate if the slice-selective gradient has to be returned.
slice_thickness (float, default=0) –
system (Opts, default=Opts()) – System limits.
use (str) – Whether it is a ‘refocusing’ pulse (for k-space calculation).

Returns

rf (SimpleNamespace) – Adiabatic RF pulse event.
gz (SimpleNamespace, optional) – Slice-selective trapezoid event.
gzr (SimpleNamespace, optional) – Slice-select rephasing trapezoid event.
delay (SimpleNamespace, optional) – Delay event.

Raises

ValueError – If invalid pulse type is encountered. If invalid pulse use is encountered. If slice thickness is not provided but slice-selective trapezoid event is expected.

pypulseq.make_arbitrary_grad module¶

pypulseq.make_arbitrary_grad.make_arbitrary_grad(channel: str, waveform: numpy.ndarray, delay: float = 0, max_grad: float = 0, max_slew: float = 0, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>) → types.SimpleNamespace¶

Creates a gradient event with arbitrary waveform.

See also pypulseq.Sequence.sequence.Sequence.add_block().

Parameters

channel (str) – Orientation of gradient event of arbitrary shape. Must be one of x, y or z.
waveform (numpy.ndarray) – Arbitrary waveform.
system (Opts, default=Opts()) – System limits.
max_grad (float, default=0) – Maximum gradient strength.
max_slew (float, default=0) – Maximum slew rate.
delay (float, default=0) – Delay in seconds (s).

Returns

grad – Gradient event with arbitrary waveform.

Return type

SimpleNamespace

Raises

ValueError – If invalid channel is passed. Must be one of x, y or z. If slew rate is violated. If gradient amplitude is violated.

pypulseq.make_arbitrary_rf module¶

pypulseq.make_arbitrary_rf.make_arbitrary_rf(signal: numpy.ndarray, flip_angle: float, bandwidth: float = 0, delay: float = 0, dwell: float = 0, freq_offset: float = 0, max_grad: float = 0, max_slew: float = 0, phase_offset: float = 0, return_delay: bool = False, return_gz: bool = False, slice_thickness: float = 0, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>, time_bw_product: float = 0, use: str = '') → Union[types.SimpleNamespace, Tuple[types.SimpleNamespace, types.SimpleNamespace]]¶

Create an RF pulse with the given pulse shape.

Parameters

signal (numpy.ndarray) – Arbitrary waveform.
flip_angle (float) – Flip angle in radians.
bandwidth (float, default=0) – Bandwidth in Hertz (Hz).
delay (float, default=0) – Delay in seconds (s) of accompanying slice select trapezoidal event.
freq_offset (float, default=0) – Frequency offset in Hertz (Hz).
max_grad (float, default=system.max_grad) – Maximum gradient strength of accompanying slice select trapezoidal event.
max_slew (float, default=system.max_slew) – Maximum slew rate of accompanying slice select trapezoidal event.
phase_offset (float, default=0) – Phase offset in Hertz (Hz).a
return_delay (bool, default=False) – Boolean flag to indicate if delay has to be returned.
return_gz (bool, default=False) – Boolean flag to indicate if slice-selective gradient has to be returned.
slice_thickness (float, default=0) – Slice thickness of accompanying slice select trapezoidal event. The slice thickness determines the area of the slice select event.
system (Opts, default=Opts()) – System limits.
time_bw_product (float, default=4) – Time-bandwidth product.
use (str, default=str()) – Use of arbitrary radio-frequency pulse event. Must be one of ‘excitation’, ‘refocusing’ or ‘inversion’.

Returns

rf (SimpleNamespace) – Radio-frequency pulse event with arbitrary pulse shape.
gz (SimpleNamespace, optional) – Slice select trapezoidal gradient event accompanying the arbitrary radio-frequency pulse event.

Raises

ValueError – If invalid use parameter is passed. Must be one of ‘excitation’, ‘refocusing’ or ‘inversion’. If signal with ndim > 1 is passed. If return_gz=True, and slice_thickness and bandwidth are not passed.

pypulseq.make_block_pulse module¶

pypulseq.make_block_pulse.make_block_pulse(flip_angle: float, bandwidth: float = 0, delay: float = 0, duration: float = 0.004, freq_offset: float = 0, phase_offset: float = 0, return_delay: bool = False, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>, time_bw_product: float = 0, use: str = '') → Union[types.SimpleNamespace, Tuple[types.SimpleNamespace, types.SimpleNamespace]]¶

Create a block pulse with optional slice selectiveness.

Parameters

flip_angle (float) – Flip angle in radians.
bandwidth (float, default=0) – Bandwidth in Hertz (hz).
delay (float, default=0) – Delay in seconds (s) of accompanying slice select trapezoidal event.
duration (float, default=4e-3) – Duration in seconds (s).
freq_offset (float, default=0) – Frequency offset in Hertz (Hz).
phase_offset (float, default=0) – Phase offset Hertz (Hz).
return_delay (bool, default=False) – Boolean flag to indicate if the delay event has to be returned.
system (Opts, default=Opts()) – System limits.
time_bw_product (float, default=0) – Time-bandwidth product.
use (str, default=str()) – Use of radio-frequency block pulse event. Must be one of ‘excitation’, ‘refocusing’ or ‘inversion’.

Returns

rf (SimpleNamespace) – Radio-frequency block pulse event.
delay (SimpleNamespace, optional) – Slice select trapezoidal gradient event accompanying the radio-frequency block pulse event.

Raises

ValueError – If invalid use parameter is passed. Must be one of ‘excitation’, ‘refocusing’ or ‘inversion’. If neither bandwidth nor duration are passed. If return_gz=True, and slice_thickness is not passed.

pypulseq.make_delay module¶

pypulseq.make_delay.make_delay(d: float) → types.SimpleNamespace¶

Creates a delay event.

Parameters: d (float) – Delay time in seconds (s).
Returns: delay – Delay event.
Return type: SimpleNamespace
Raises: ValueError – If delay is invalid (not finite or < 0).

pypulseq.make_digital_output_pulse module¶

pypulseq.make_digital_output_pulse.make_digital_output_pulse(channel: str, delay: float = 0, duration: float = 0.004, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>) → types.SimpleNamespace¶

Create a digital output pulse event a.k.a. trigger. Creates an output trigger event on a given channel with optional given delay and duration.

Parameters

channel (str) – Must be one of ‘osc0’,’osc1’, or ‘ext1’.
delay (float, default=0) – Delay in seconds (s).
duration (float, default=4e-3) – Duration of trigger event in seconds (s).
system (Opts, default=Opts()) – System limits.

Returns

trig – Trigger event.

Return type

SimpleNamespace

Raises

ValueError – If channel is invalid. Must be one of ‘osc0’,’osc1’, or ‘ext1’.

pypulseq.make_extended_trapezoid module¶

pypulseq.make_extended_trapezoid.make_extended_trapezoid(channel: str, amplitudes: numpy.ndarray = numpy.zeros, convert_to_arbitrary: bool = False, max_grad: float = 0, max_slew: float = 0, skip_check: bool = False, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>, times: numpy.ndarray = numpy.zeros) → types.SimpleNamespace¶

Create a gradient by specifying a set of points (amplitudes) at specified time points(times) at a given channel with given system limits. Returns an arbitrary gradient object.

See also: - pypulseq.Sequence.sequence.Sequence.add_block() - pypulseq.opts.Opts - pypulseq.make_trapezoid.make_trapezoid()

Parameters

channel (str) – Orientation of extended trapezoidal gradient event. Must be one of ‘x’, ‘y’ or ‘z’.
convert_to_arbitrary (bool, default=False) – Boolean flag to indicate if the extended trapezoid gradient has to be converted into an arbitrary gradient.
amplitudes (numpy.ndarray, default=09) – Values defined at times time indices.
max_grad (float, default=0) – Maximum gradient strength.
max_slew (float, default=0) – Maximum slew rate.
system (Opts, default=Opts()) – System limits.
skip_check (bool, default=False) – Boolean flag to indicate if amplitude check is to be skipped.
times (numpy.ndarray, default=np.zeros(1)) – Time points at which amplitudes defines amplitude values.

Returns

grad – Extended trapezoid gradient event.

Return type

SimpleNamespace

Raises

ValueError – If invalid channel is passed. Must be one of ‘x’, ‘y’ or ‘z’. If all elements in times are zero. If elements in times are not in ascending order or not distinct. If all elements in amplitudes are zero. If first amplitude of a gradient is non-ero and does not connect to a previous block.

pypulseq.make_extended_trapezoid_area module¶

pypulseq.make_extended_trapezoid_area.make_extended_trapezoid_area(area: float, channel: str, grad_end: float, grad_start: float, system: pypulseq.opts.Opts) → Tuple[types.SimpleNamespace, numpy.array, numpy.array]¶

Makes the shortest possible extended trapezoid with a given area which starts and ends (optionally) as non-zero gradient values.

Parameters

channel (str) – Orientation of extended trapezoidal gradient event. Must be one of ‘x’, ‘y’ or ‘z’.
grad_start (float) – Starting non-zero gradient value.
grad_end (float) – Ending non-zero gradient value.
area (float) – Area of extended trapezoid.
system (Opts) – System limits.

Returns

grad (SimpleNamespace) – Extended trapezoid event.
times (numpy.ndarray)
amplitude (numpy.ndarray)

pypulseq.make_gauss_pulse module¶

pypulseq.make_gauss_pulse.make_gauss_pulse(flip_angle: float, apodization: float = 0, bandwidth: float = 0, center_pos: float = 0.5, delay: float = 0, dwell: float = 0, duration: float = 0.004, freq_offset: float = 0, max_grad: float = 0, max_slew: float = 0, phase_offset: float = 0, return_gz: bool = False, return_delay: bool = False, slice_thickness: float = 0, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>, time_bw_product: float = 4, use: str = '') → Union[types.SimpleNamespace, Tuple[types.SimpleNamespace, types.SimpleNamespace, types.SimpleNamespace], Tuple[types.SimpleNamespace, types.SimpleNamespace, types.SimpleNamespace, types.SimpleNamespace]]¶

Create a [optionally slice selective] Gauss pulse.

See also pypulseq.Sequence.sequence.Sequence.add_block().

Parameters

flip_angle (float) – Flip angle in radians.
apodization (float, default=0) – Apodization.
bandwidth (float, default=0) – Bandwidth in Hertz (Hz).
center_pos (float, default=0.5) – Position of peak.
delay (float, default=0) – Delay in seconds (s).
dwell (float, default=0) –
duration (float, default=4e-3) – Duration in seconds (s).
freq_offset (float, default=0) – Frequency offset in Hertz (Hz).
max_grad (float, default=0) – Maximum gradient strength of accompanying slice select trapezoidal event.
max_slew (float, default=0) – Maximum slew rate of accompanying slice select trapezoidal event.
phase_offset (float, default=0) – Phase offset in Hertz (Hz).
return_delay (bool, default=False) – Boolean flag to indicate if the delay event has to be returned.
return_gz (bool, default=False) – Boolean flag to indicate if the slice-selective gradient has to be returned.
slice_thickness (float, default=0) – Slice thickness of accompanying slice select trapezoidal event. The slice thickness determines the area of the slice select event.
system (Opts, default=Opts()) – System limits.
time_bw_product (int, default=4) – Time-bandwidth product.
use (str, default=str()) – Use of radio-frequency gauss pulse event. Must be one of ‘excitation’, ‘refocusing’ or ‘inversion’.

Returns

rf (SimpleNamespace) – Radio-frequency gauss pulse event.
gz (SimpleNamespace, optional) – Accompanying slice select trapezoidal gradient event.
gzr (SimpleNamespace, optional) – Accompanying slice select rephasing trapezoidal gradient event.
delay (SimpleNamespace, optional) – Delay event.

Raises

ValueError – If invalid use is passed. Must be one of ‘excitation’, ‘refocusing’ or ‘inversion’. If return_gz=True and slice_thickness was not passed.

pypulseq.make_label module¶

pypulseq.make_label.make_label(label: str, type: str, value: Union[bool, float, int]) → types.SimpleNamespace¶

Create an ADC Label.

Parameters

type (str) – Label type. Must be one of ‘SET’ or ‘INC’.
label (str) – Must be one of ‘SLC’, ‘SEG’, ‘REP’, ‘AVG’, ‘SET’, ‘ECO’, ‘PHS’, ‘LIN’, ‘PAR’, ‘NAV’, ‘REV’, or ‘SMS’.
value (bool, float or int) – Label value.

Returns

out – Label object.

Return type

SimpleNamespace

Raises

ValueError – If a valid label was not passed. Must be one of ‘SLC’, ‘SEG’, ‘REP’, ‘AVG’, ‘SET’, ‘ECO’, ‘PHS’, ‘LIN’, ‘PAR’, NAV’, ‘REV’, or ‘SMS’. If a valid type was not passed. Must be one of ‘SET’ or ‘INC’. If value was not a valid numerical or logical value.

pypulseq.make_sigpy_pulse module¶

pypulseq.make_sigpy_pulse.make_slr(flip_angle: float, time_bw_product: float = 4, duration: float = 0, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>, pulse_cfg: pypulseq.sigpy_pulse_opts.SigpyPulseOpts = <pypulseq.sigpy_pulse_opts.SigpyPulseOpts object>, disp: bool = False)¶

pypulseq.make_sigpy_pulse.make_sms(flip_angle: float, time_bw_product: float = 4, duration: float = 0, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>, pulse_cfg: pypulseq.sigpy_pulse_opts.SigpyPulseOpts = <pypulseq.sigpy_pulse_opts.SigpyPulseOpts object>, disp: bool = False)¶

pypulseq.make_sigpy_pulse.sigpy_n_seq(flip_angle: float, delay: float = 0, duration: float = 0.004, freq_offset: float = 0, center_pos: float = 0.5, max_grad: float = 0, max_slew: float = 0, phase_offset: float = 0, return_gz: bool = True, slice_thickness: float = 0, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>, time_bw_product: float = 4, pulse_cfg: pypulseq.sigpy_pulse_opts.SigpyPulseOpts = <pypulseq.sigpy_pulse_opts.SigpyPulseOpts object>, use: str = '') → Union[types.SimpleNamespace, Tuple[types.SimpleNamespace, types.SimpleNamespace, types.SimpleNamespace]]¶

Creates a radio-frequency sinc pulse event using the sigpy rf pulse library and optionally accompanying slice select, slice select rephasing trapezoidal gradient events.

Parameters

flip_angle (float) – Flip angle in radians.
apodization (float, optional, default=0) – Apodization.
center_pos (float, optional, default=0.5) – Position of peak.5 (midway).
delay (float, optional, default=0) – Delay in seconds (s).
duration (float, optional, default=4e-3) – Duration in seconds (s).
freq_offset (float, optional, default=0) – Frequency offset in Hertz (Hz).
max_grad (float, optional, default=0) – Maximum gradient strength of accompanying slice select trapezoidal event.
max_slew (float, optional, default=0) – Maximum slew rate of accompanying slice select trapezoidal event.
phase_offset (float, optional, default=0) – Phase offset in Hertz (Hz).
return_gz (bool, default=False) – Boolean flag to indicate if slice-selective gradient has to be returned.
slice_thickness (float, optional, default=0) – Slice thickness of accompanying slice select trapezoidal event. The slice thickness determines the area of the slice select event.
system (Opts, optional) – System limits. Default is a system limits object initialised to default values.
time_bw_product (float, optional, default=4) – Time-bandwidth product.
use (str, optional, default=str()) – Use of radio-frequency sinc pulse. Must be one of ‘excitation’, ‘refocusing’ or ‘inversion’.

Returns

rf (SimpleNamespace) – Radio-frequency sinc pulse event.
gz (SimpleNamespace, optional) – Accompanying slice select trapezoidal gradient event. Returned only if slice_thickness is provided.
gzr (SimpleNamespace, optional) – Accompanying slice select rephasing trapezoidal gradient event. Returned only if slice_thickness is provided.

Raises

ValueError – If invalid use parameter was passed. Must be one of ‘excitation’, ‘refocusing’ or ‘inversion’. If return_gz=True and slice_thickness was not provided.

pypulseq.make_sinc_pulse module¶

pypulseq.make_sinc_pulse.make_sinc_pulse(flip_angle: float, apodization: float = 0, delay: float = 0, duration: float = 0.004, dwell: float = 0, center_pos: float = 0.5, freq_offset: float = 0, max_grad: float = 0, max_slew: float = 0, phase_offset: float = 0, return_delay: bool = False, return_gz: bool = False, slice_thickness: float = 0, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>, time_bw_product: float = 4, use: str = '') → Union[types.SimpleNamespace, Tuple[types.SimpleNamespace, types.SimpleNamespace, types.SimpleNamespace], Tuple[types.SimpleNamespace, types.SimpleNamespace, types.SimpleNamespace, types.SimpleNamespace]]¶

Creates a radio-frequency sinc pulse event and optionally accompanying slice select and slice select rephasing trapezoidal gradient events.

Parameters

flip_angle (float) – Flip angle in radians.
apodization (float, default=0) – Apodization.
center_pos (float, default=0.5) – Position of peak.5 (midway).
delay (float, default=0) – Delay in seconds (s).
duration (float, default=4e-3) – Duration in seconds (s).
dwell (float, default=0) –
freq_offset (float, default=0) – Frequency offset in Hertz (Hz).
max_grad (float, default=0) – Maximum gradient strength of accompanying slice select trapezoidal event.
max_slew (float, default=0) – Maximum slew rate of accompanying slice select trapezoidal event.
phase_offset (float, default=0) – Phase offset in Hertz (Hz).
return_delay (bool, default=False) – Boolean flag to indicate if the delay event has to be returned.
return_gz (bool, default=False) – Boolean flag to indicate if slice-selective gradient has to be returned.
slice_thickness (float, default=0) – Slice thickness of accompanying slice select trapezoidal event. The slice thickness determines the area of the slice select event.
system (Opts, default=Opts()) – System limits. Default is a system limits object initialised to default values.
time_bw_product (float, default=4) – Time-bandwidth product.
use (str, default=str()) – Use of radio-frequency sinc pulse. Must be one of ‘excitation’, ‘refocusing’ or ‘inversion’.
also pypulseq.Sequence.sequence.Sequence.add_block() (See) –

Returns

rf (SimpleNamespace) – Radio-frequency sinc pulse event.
gz (SimpleNamespace, optional) – Accompanying slice select trapezoidal gradient event. Returned only if slice_thickness is provided.
gzr (SimpleNamespace, optional) – Accompanying slice select rephasing trapezoidal gradient event. Returned only if slice_thickness is provided.

Raises

ValueError – If invalid use parameter was passed. Must be one of ‘excitation’, ‘refocusing’ or ‘inversion’. If return_gz=True and slice_thickness was not provided.

pypulseq.make_trapezoid module¶

pypulseq.make_trapezoid.make_trapezoid(channel: str, amplitude: float = 0, area: Optional[float] = None, delay: float = 0, duration: float = 0, fall_time: float = 0, flat_area: float = 0, flat_time: float = -1, max_grad: float = 0, max_slew: float = 0, rise_time: float = 0, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>) → types.SimpleNamespace¶

Create a trapezoidal gradient event.

See also: - pypulseq.Sequence.sequence.Sequence.add_block() - pypulseq.opts.Opts

Parameters

channel (str) – Orientation of trapezoidal gradient event. Must be one of x, y or z.
amplitude (float, default=0) – Amplitude.
area (float, default=None) – Area.
delay (float, default=0) – Delay in seconds (s).
duration (float, default=0) – Duration in seconds (s).
flat_area (float, default=0) – Flat area.
flat_time (float, default=-1) – Flat duration in seconds (s). Default is -1 to account for triangular pulses.
max_grad (float, default=0) – Maximum gradient strength.
max_slew (float, default=0) – Maximum slew rate.
rise_time (float, default=0) – Rise time in seconds (s).
system (Opts, default=Opts()) – System limits.

Returns

grad – Trapezoidal gradient event created based on the supplied parameters.

Return type

SimpleNamespace

Raises

ValueError – If none of area, flat_area and amplitude are passed If requested area is too large for this gradient If flat_time, duration and area are not supplied. Amplitude violation

pypulseq.make_trigger module¶

pypulseq.make_trigger.make_trigger(channel: str, delay: float = 0, duration: float = 0, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>) → types.SimpleNamespace¶

Create a trigger halt event for a synchronisation with an external signal from a given channel with an optional given delay prio to the sync and duration after the sync. Possible channel values: ‘physio1’,’physio2’ (Siemens specific).

See also pypulseq.Sequence.sequence.Sequence.add_block().

channelstr
Must be one of ‘physio1’ or ‘physio2’.

delayfloat, default=0
Delay in seconds

duration: float, default=0
Duration in seconds.

systemOpts, default=Opts()
System limits.

triggerSimpleNamespace
Trigger event.

ValueError
If invalid channel is passed. Must be one of ‘physio1’ or ‘physio2’.

pypulseq.opts module¶

class pypulseq.opts.Opts(adc_dead_time: float = 0, adc_raster_time: float = 1e-07, block_duration_raster: float = 1e-05, gamma: float = 42576000.0, grad_raster_time: float = 1e-05, grad_unit: str = 'Hz/m', max_grad: float = 0, max_slew: float = 0, rf_dead_time: float = 0, rf_raster_time: float = 1e-06, rf_ringdown_time: float = 0, rise_time: float = 0, slew_unit: str = 'Hz/m/s', B0: float = 1.5)¶

Bases: object

System limits of an MR scanner.

adc_dead_time¶

Dead time for ADC readout pulses.

Type: float, default=0

gamma¶

Gyromagnetic ratio. Default gamma is specified for Hydrogen.

Type: float, default=42.576e6

grad_raster_time¶

Raster time for gradient waveforms.

Type: float, default=10e-6

grad_unit¶

Unit of maximum gradient amplitude. Must be one of ‘Hz/m’, ‘mT/m’ or ‘rad/ms/mm’.

Type: str, default=’Hz/m’

max_grad¶

Maximum gradient amplitude.

Type: float, default=0

max_slew¶

Maximum slew rate.

Type: float, default=0

rf_dead_time¶

Dead time for radio-frequency pulses.

Type: float, default=0

rf_raster_time¶

Raster time for radio-frequency pulses.

Type: float, default=1e-6

rf_ringdown_time¶

Ringdown time for radio-frequency pulses.

Type: float, default=0

rise_time¶

Rise time for gradients.

Type: float, default=0

slew_unit¶

Unit of maximum slew rate. Must be one of ‘Hz/m/s’, ‘mT/m/ms’, ‘T/m/s’ or ‘rad/ms/mm/ms’.

Type: str, default=’Hz/m/s’

Raises: ValueError – If invalid grad_unit is passed. Must be one of ‘Hz/m’, ‘mT/m’ or ‘rad/ms/mm’. If invalid slew_unit is passed. Must be one of ‘Hz/m/s’, ‘mT/m/ms’, ‘T/m/s’ or ‘rad/ms/mm/ms’.

pypulseq.points_to_waveform module¶

pypulseq.points_to_waveform.points_to_waveform(amplitudes: numpy.ndarray, grad_raster_time: float, times: numpy.ndarray) → numpy.ndarray¶

1D interpolate amplitude values amplitudes at time indices times as per the gradient raster time grad_raster_time to generate a gradient waveform.

Parameters

amplitudes (numpy.ndarray) – Amplitude values at time indices times.
grad_raster_time (float) – Gradient raster time.
times (numpy.ndarray) – Time indices.

Returns

waveform – Gradient waveform.

Return type

numpy.ndarray

pypulseq.rotate module¶

pypulseq.rotate.rotate(*args: types.SimpleNamespace, angle: float, axis: str) → List[types.SimpleNamespace]¶

Rotates the corresponding gradient(s) about the given axis by the specified amount. Gradients parallel to the rotation axis and non-gradient(s) are not affected. Possible rotation axes are ‘x’, ‘y’ or ‘z’.

See also pypulseq.Sequence.sequence.add_block().

Parameters

axis (str) – Axis about which the gradient(s) will be rotated.
angle (float) – Angle by which the gradient(s) will be rotated.
args (SimpleNamespace) – Gradient(s).

Returns

rotated_grads – Rotated gradient(s).

Return type

[SimpleNamespace]

pypulseq.scale_grad module¶

pypulseq.scale_grad.scale_grad(grad: types.SimpleNamespace, scale: float) → types.SimpleNamespace¶

Scales the gradient with the scalar.

Parameters

grad (SimpleNamespace) – Gradient event to be scaled.
scale (float) – Scaling factor.

Returns

grad – Scaled gradient.

Return type

SimpleNamespace

pypulseq.sigpy_pulse_opts module¶

class pypulseq.sigpy_pulse_opts.SigpyPulseOpts(pulse_type: str = 'slr', ptype: str = 'st', ftype: str = 'ls', d1: float = 0.01, d2: float = 0.01, cancel_alpha_phs: bool = False, n_bands: int = 3, band_sep: int = 20, phs_0_pt: str = 'None')¶: Bases: object

pypulseq.split_gradient module¶

pypulseq.split_gradient.split_gradient(grad: types.SimpleNamespace, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>) → Tuple[types.SimpleNamespace, types.SimpleNamespace, types.SimpleNamespace]¶

Splits a trapezoidal gradient into slew up, flat top and slew down. Returns the individual gradient parts (slew up, flat top and slew down) as extended trapezoid gradient objects. The delays in the individual gradient events are adapted such that addGradients(…) produces an gradient equivalent to ‘grad’.

See also: - pypulseq.split_gradient() - pypulseq.make_extended_trapezoid() - pypulseq.make_trapezoid() - pypulseq.Sequence.sequence.Sequence.add_block() - pypulseq.opts.Opts

Parameters

grad (SimpleNamespace) – Gradient event to be split into two gradient waveforms.
system (Opts, default=Opts()) – System limits.

Returns

grad1, grad2 – Split gradient waveforms.

Return type

SimpleNamespace

Raises

ValueError – If arbitrary gradients are passed. If non-gradient event is passed.

pypulseq.split_gradient_at module¶

pypulseq.split_gradient_at.split_gradient_at(grad: types.SimpleNamespace, time_point: float, system: pypulseq.opts.Opts = <pypulseq.opts.Opts object>) → Union[types.SimpleNamespace, Tuple[types.SimpleNamespace, types.SimpleNamespace]]¶

Splits a trapezoidal gradient into two extended trapezoids defined by the cut line. Returns the two gradient parts by cutting the original ‘grad’ at ‘time_point’. For the input type ‘trapezoid’ the results are returned as extended trapezoids, for ‘arb’ as arbitrary gradient objects. The delays in the individual gradient events are adapted such that add_gradients(…) produces a gradient equivalent to ‘grad’.

See also: - pypulseq.split_gradient() - pypulseq.make_extended_trapezoid() - pypulseq.make_trapezoid() - pypulseq.Sequence.sequence.Sequence.add_block() - pypulseq.opts.Opts

Parameters

grad (SimpleNamespace) – Gradient event to be split into two gradient events.
time_point (float) – Time point at which grad will be split into two gradient waveforms.
system (Opts, default=Opts()) – System limits.

Returns

grad1, grad2 – Gradient waveforms after splitting.

Return type

SimpleNamespace

Raises

ValueError – If non-gradient event is passed.

pypulseq.supported_labels_rf_use module¶

pypulseq.supported_labels_rf_use.get_supported_labels() → Tuple[str, str, str, str, str, str, str, str, str, str, str, str, str]¶

Returns: Supported labels.
Return type: tuple

pypulseq.supported_labels_rf_use.get_supported_rf_uses() → Tuple[str, str, str, str, str]¶

Returns: Supported RF use labels.
Return type: tuple

pypulseq.traj_to_grad module¶

pypulseq.traj_to_grad.traj_to_grad(k: numpy.ndarray, raster_time: float = 1e-05) → Tuple[numpy.ndarray, numpy.ndarray]¶

Convert k-space trajectory k into gradient waveform in compliance with raster_time gradient raster time.

Parameters

k (numpy.ndarray) – K-space trajectory to be converted into gradient waveform.
raster_time (float, default=Opts()grad_raster_time) – Gradient raster time.

Returns

g (numpy.ndarray) – Gradient waveform.
sr (numpy.ndarray) – Slew rate.

Module contents¶

pypulseq.round_half_up(n, decimals=0)¶: Avoid banker’s rounding inconsistencies; from https://realpython.com/python-rounding/#rounding-half-up