Sequence

class pulser.sequence.Sequence(register, device)

Bases: Generic[DeviceType]

A sequence of operations on a device.

A sequence is composed by

The device constraints it must respect

The register of qubits on which to act

The device’s channels that are used

The schedule of operations on each channel

A Sequence also supports variable parameters, which have to be obtained through Sequence.declare_variable(). From the moment a variable is declared, a Sequence becomes parametrized and stops being built on the fly, instead storing the sequence building calls for later execution. This forgoes some specific functionalities of a “regular” Sequence, like the ability to validate a Pulse or to draw the sequence as it is being built. Instead, all validation happens upon building (through Sequence.build()), where values for all declared variables have to be specified and a “regular” Sequence is created and returned. By changing the values given to the variables, multiple sequences can be generated from a single “parametrized” Sequence.

Parameters:

register (BaseRegister | MappableRegister) – The atom register on which to apply the pulses. If given as a MappableRegister instance, the traps corrresponding to each qubit ID must be given when building the sequence.
device (TypeVar(DeviceType, bound= BaseDevice)) – A valid device in which to execute the Sequence.

Note

The register and device do not support variable parameters. As such, they are the same for all Sequences built from a parametrized Sequence.

Attributes

`available_channels`	Channels still available for declaration.
`declared_channels`	Channels declared in this Sequence.
`declared_variables`	Variables declared in this Sequence.
`device`	Device that the sequence is using.
`magnetic_field`	The magnetic field acting on the array of atoms.
`qubit_info`	Dictionary with the qubit's IDs and positions.
`register`	Register with the qubit's IDs and positions.

Methods

`add`	Adds a pulse to a channel.
`add_dmm_detuning`	Add a waveform to the detuning of a DMM.
`add_eom_pulse`	Adds a square pulse to a channel in EOM mode.
`align`	Aligns multiple channels in time.
`build`	Builds a sequence from the programmed instructions.
`config_detuning_map`	Declares a new DMM channel to the Sequence.
`config_slm_mask`	Setup an SLM mask by specifying the qubits it targets.
`current_phase_ref`	Current phase reference of a specific qubit for a given basis.
`declare_channel`	Declares a new channel in the Sequence.
`declare_variable`	Declare a new variable within this Sequence.
`delay`	Idles a given channel for a specific duration.
`disable_eom_mode`	Takes a channel out of EOM mode operation.
`draw`	Draws the sequence in its current state.
`enable_eom_mode`	Puts a channel in EOM mode operation.
`estimate_added_delay`	Delay that will be added before the pulse when added to a channel.
`from_abstract_repr`	Deserialize a sequence from an abstract JSON object.
`get_addressed_bases`	Returns the bases addressed by the declared channels.
`get_addressed_states`	Returns the states addressed by the declared channels.
`get_duration`	Returns the current duration of a channel or the whole sequence.
`get_measurement_basis`	Gets the sequence's measurement basis.
`get_register`	The atom register on which to apply the pulses.
`is_in_eom_mode`	States whether a channel is currently in EOM mode.
`is_measured`	States whether the sequence has been measured.
`is_parametrized`	States whether the sequence is parametrized.
`is_register_mappable`	States whether the sequence's register is mappable.
`measure`	Measures in a valid basis.
`modify_eom_setpoint`	Modifies the setpoint of an ongoing EOM mode operation.
`phase_shift`	Shifts the phase of a qubit's reference by 'phi', on a given basis.
`phase_shift_index`	Shifts the phase of a qubit's reference by 'phi', on a given basis.
`set_magnetic_field`	Sets the magnetic field acting on the entire array.
`switch_device`	Replicate the sequence with a different device.
`switch_register`	Replicate the sequence with a different register.
`target`	Changes the target qubit of a 'Local' channel.
`target_index`	Changes the target qubit of a 'Local' channel.
`to_abstract_repr`	Serializes the Sequence into an abstract JSON object.

Signatures

add(pulse, channel, protocol='min-delay')

Adds a pulse to a channel.

Parameters:

pulse (Pulse | Parametrized) – The pulse object to add to the channel.
channel (str) – The channel’s name provided when declared.
protocol (Literal['min-delay', 'no-delay', 'wait-for-all'], default: 'min-delay') –
Stipulates how to deal with eventual conflicts with other channels, specifically in terms of having multiple channels act on the same target simultaneously.
- 'min-delay': Before adding the pulse, introduces the smallest possible delay that avoids all exisiting conflicts.
- 'no-delay': Adds the pulse to the channel, regardless of existing conflicts.
- 'wait-for-all': Before adding the pulse, adds a delay that idles the channel until the end of the other channels’ latest pulse.

Return type:

None

Note

When the phase of the pulse to add is different than the phase of the previous pulse on the channel, a delay between the two pulses might be automatically added to ensure the channel’s phase_jump_time is respected. To override this behaviour, use the 'no-delay' protocol.

add_dmm_detuning(waveform, dmm_name, protocol='no-delay')

Add a waveform to the detuning of a DMM.

Parameters:

waveform (Waveform | Parametrized) – The waveform to add to the detuning of the DMM.
dmm_name (str) – The name of the DMM channel to modulate.
protocol (Literal['min-delay', 'no-delay', 'wait-for-all'], default: 'no-delay') –
Stipulates how to deal with eventual conflicts with other channels, specifically in terms of having multiple channels act on the same target simultaneously (defaults to “no-delay”).
- 'min-delay': Before adding the pulse, introduces the smallest possible delay that avoids all exisiting conflicts.
- 'no-delay': Adds the pulse to the channel, regardless of existing conflicts.
- 'wait-for-all': Before adding the pulse, adds a delay that idles the channel until the end of the other channels’ latest pulse.

Return type:

None

add_eom_pulse(channel, duration, phase, post_phase_shift=0.0, protocol='min-delay', correct_phase_drift=False)

Adds a square pulse to a channel in EOM mode.

For channels with a finite modulation bandwidth and an EOM, operation in EOM mode allows for the execution of square pulses with a higher bandwidth than that which is tipically available. It can be turned on and off through the Sequence.enable_eom_mode() and Sequence.disable_eom_mode() methods. A channel in EOM mode can only execute square pulses with a given amplitude (amp_on) and detuning (detuning_on), which are chosen at the moment the EOM mode is enabled. Furthermore, the detuning when there is no pulse being played (detuning_off) is restricted to a set of values that depends on amp_on and detuning_on. While in EOM mode, one can only add pulses of variable duration (through Sequence.add_eom_pulse()) or delays.

Note

When the phase between pulses is changed, the necessary buffer time for a phase jump will still be enforced (unless protocol='no-delay').

Parameters:

channel (str) – The name of the channel to add the pulse to.
duration (int | Parametrized) – The duration of the pulse (in ns).
phase (float | TensorLike | Parametrized) – The pulse phase (in radians).
post_phase_shift (float | Parametrized, default: 0.0) – Optionally lets you add a phase shift (in rad) immediately after the end of the pulse.
protocol (Literal['min-delay', 'no-delay', 'wait-for-all'], default: 'min-delay') – Stipulates how to deal with eventual conflicts with other channels (see Sequence.add() for more details).
correct_phase_drift (bool, default: False) – Adjusts the phase to correct for the phase drift that occured since the last pulse (or the start of the EOM mode, if adding the first pulse). This effectively changes the phase of the EOM pulse, so an extra delay might be added to enforce the phase jump time.

Return type:

None

align(*channels, at_rest=True)

Aligns multiple channels in time.

Introduces delays that align the provided channels with the one that finished the latest, such that the next action added to any of them will start right after the latest channel has finished.

Parameters:

channels (str) – The names of the channels to align, as given upon declaration.
at_rest (bool, default: True) – Whether to consider the output modulation of a channel’s contents when determining that it has finished.

Return type:

None

build(*, qubits=None, **vars)

Builds a sequence from the programmed instructions.

Parameters:

qubits (Mapping[str, int] | None, default: None) – A mapping between qubit IDs and trap IDs used to define the register. Must only be provided when the sequence is initialized with a MappableRegister.
vars (ArrayLike | TensorLike | float | int) – The values for all the variables declared in this Sequence instance, indexed by the name given upon declaration. Check Sequence.declared_variables to see all the variables.

Return type:

Sequence

Returns:

The Sequence built with the given variable values.

Example

# Check which variables are declared
>>> print(seq.declared_variables)
{'x': Variable(name='x', dtype=<class 'float'>, size=1),
 'y': Variable(name='y', dtype=<class 'int'>, size=3)}
# Build a sequence with specific values for both variables
>>> seq1 = seq.build(x=0.5, y=[1, 2, 3])

config_detuning_map(detuning_map, dmm_id)

Declares a new DMM channel to the Sequence.

Associates a DetuningMap to a DMM channel of the Device.

Note

Regular devices only allow a DMM to be declared once, but MockDevice DMM can be repeatedly declared if needed.

Parameters:

detuning_map (DetuningMap) – A DetuningMap defining the amount of detuning each atom receives.
dmm_id (str) – How the channel is identified in the device. See in Sequence.available_channels which DMM IDs are still available (start by “dmm” ) and the associated description.

Return type:

None

config_slm_mask(qubits, dmm_id='dmm_0')

Setup an SLM mask by specifying the qubits it targets.

If the sequence is in XY mode, masked qubits don’t interact with the incoming pulses until the end of the first pulse of the global channel starting the earliest in the schedule.

If the sequence is in Ising, the SLM Mask is a DetuningMap where the detuning of each masked qubit is 1.0. DMM “dmm_id” is configured using this Detuning Map, and modulated by a pulse having a large negative detuning and either a duration defined from pulses already present in the sequence (same as in XY mode) or by the first pulse added after this operation.

Parameters:

qubits (Collection[str]) – Collection of qubit ID’s to mask during the first global pulse of the sequence.
dmm_id (str, default: 'dmm_0') – Id of the DMM channel to use in the device.

Return type:

None

current_phase_ref(qubit, basis='digital')

Current phase reference of a specific qubit for a given basis.

Parameters:

qubit (str) – The id of the qubit whose phase shift is desired.
basis (str, default: 'digital') – The basis (i.e. electronic transition) the phase reference is associated with. Must correspond to the basis of a declared channel.

Return type:

float

Returns:

Current phase reference of ‘qubit’ in ‘basis’.

declare_channel(name, channel_id, initial_target=None)

Declares a new channel in the Sequence.

The first declared channel implicitly defines the sequence’s mode of operation (i.e. the underlying Hamiltonian). In particular, if the first declared channel is of type Microwave, the sequence will work in “XY Mode” and will not allow declaration of channels that do not address the ‘XY’ basis. Inversely, declaration of a channel of another type will block the declaration of Microwave channels.

Note

Regular devices only allow a channel to be declared once, but channels in VirtualDevice with reusable_channels=True can be repeatedly declared if needed.

Parameters:

name (str) – Unique name for the channel in the sequence.
channel_id (str) – How the channel is identified in the device. Consult Sequence.available_channels to see which channel ID’s are still available and the associated channel’s description.
initial_target (str | Collection[str] | None, default: None) – For ‘Local’ addressing channels only. Declares the initial target of the channel. If left as None, the initial target will have to be set manually as the first addition to this channel.

Return type:

None

declare_variable(name, size=None, dtype=<class 'float'>)

Declare a new variable within this Sequence.

The declared variables can be used to create parametrized versions of Waveform and Pulse objects, which in turn can be added to the Sequence. Additionally, simple arithmetic operations involving variables are also supported and will return parametrized objects that are dependent on the involved variables.

Parameters:

name (str) – The name for the variable. Must be unique within a Sequence.
size (int | None, default: None) – The number of entries stored in the variable. If defined, returns an array of variables with the given size. If left as None, returns a single variable.
dtype (type[int] | type[float], default: <class 'float'>) – The type of the data that will be assigned to the variable. Must be float or int.

Return type:

Variable | VariableItem

Returns:

The declared Variable instance.

Note

To avoid confusion, it is recommended to store the returned Variable instance in a Python variable with the same name.

delay(duration, channel, at_rest=False)

Idles a given channel for a specific duration.

Parameters:

duration (int | Parametrized) – Time to delay (in ns).
channel (str) – The channel’s name provided when declared.
at_rest (bool, default: False) – Whether to wait until the previous pulse on the channel has finished (including output modulation) before starting the delay.

Return type:

None

Note

Delays added automatically by other instructions will generally take into account the output modulation.

disable_eom_mode(channel, correct_phase_drift=False)

Takes a channel out of EOM mode operation.

Note

Disabling the EOM mode will automatically enforce a buffer time from the moment it is turned off.

Parameters:

channel (str) – The name of the channel to take out of EOM mode.
correct_phase_drift (bool, default: False) – Performs a phase shift to correct for the phase drift that occured since the last pulse (or the start of the EOM mode, if no pulse was added).

Return type:

None

draw(mode='input+output', as_phase_modulated=False, draw_phase_area=False, draw_interp_pts=True, draw_phase_shifts=False, draw_register=False, draw_phase_curve=True, draw_detuning_maps=False, draw_qubit_amp=False, draw_qubit_det=False, fig_name=None, kwargs_savefig={}, show=True)

Draws the sequence in its current state.

Parameters:

mode (str, default: 'input+output') – The curves to draw. ‘input’ draws only the programmed curves, ‘output’ the expected curves after modulation. ‘input+output’ will draw both curves except for channels without a defined modulation bandwidth, in which case only the input is drawn.
as_phase_modulated (bool, default: False) – Instead of displaying the detuning and phase offsets, displays the equivalent phase modulation.
draw_phase_area (bool, default: False) – Whether phase and area values need to be shown as text on the plot, defaults to False. Doesn’t work in ‘output’ mode.
draw_interp_pts (bool, default: True) – When the sequence has pulses with waveforms of type InterpolatedWaveform, draws the points of interpolation on top of the respective input waveforms (defaults to True). Doesn’t work in ‘output’ mode.
draw_phase_shifts (bool, default: False) – Whether phase shift and reference information should be added to the plot, defaults to False.
draw_register (bool, default: False) – Whether to draw the register before the pulse sequence, with a visual indication (square halo) around the qubits masked by the SLM, defaults to False. Can’t be set to True if the sequence is defined with a mappable register.
draw_phase_curve (bool, default: True) – Draws the changes in phase in its own curve (ignored if the phase doesn’t change throughout the channel).
draw_detuning_maps (bool, default: False) – Whether to draw the detuning maps applied on the qubits of the register of the sequence. Shown before the pulse sequence, defaults to False.
draw_qubit_amp (bool, default: False) – Draws the amplitude seen by the qubits locally after the drawing of the sequence.
draw_qubit_det (bool, default: False) – Draws the detuning seen by the qubits locally after the drawing of the sequence.
fig_name (str | None, default: None) – The name on which to save the figures. Figures are saved if fig_name is not None. If draw_register, draw_qubit_amp and draw_qubit_det are False, only the pulses are saved, with no suffix. If one of them is True, the pulses will be saved with a suffix _pulses. If draw_register is True, the register is saved in another figure, with a suffix _register in the file name. If draw_qubit_amp or draw_qubit_det is True, the evolution of the quantities along time for group of qubits is saved in another figure with the prefix ‘_per_qubit’, and the group of qubits having same evolution of quantities along time are saved in a figure with suffix ‘_per_qubit_legend’.
kwargs_savefig (dict, default: {}) – Keywords arguments for matplotlib.pyplot.savefig. Not applicable if fig_name is None.
show (bool, default: True) – Whether or not to call plt.show() before returning. When combining this plot with other ones in a single figure, one may need to set this flag to False.

Return type:

None