qfabric.planner¶

planner¶

class qfabric.planner.planner.Planner(segmenters, start_step, stop_step)¶

Bases: object

Sequence planner and AWG data generator.

Parameters:

segmenters (list[Segmenter]) – List of AWG segmenters. Each device corresponds to a segmenter.
start_step (dict[str, Any]) – Start step config.
stop_step (dict[str, Any]) – Stop step config.

_sequences¶

Sequence objects that are currently scheduled.

Type:: dict[int, Sequence]

_scheduled_sequences¶

Sequence indices in the scheduled order.

Type:: deque[int]

_prepared_sequences¶

Sequence indices where their segments are programmed on each of the AWG device. The dict keys are AWG device indices.

Type:: dict[int, list[int]]

_steps¶

list of nonduplicate steps in all scheduled sequences.

Type:: list[Step]

_sequence_to_steps_map¶

Mapping from sequence indices to step indices in _steps.

Type:: dict[int, list[int]]

_step_to_segment_maps¶

Mapping from steps to segments for each AWG device. The first dict layer represents different AWG devices, and the second dict layer is mapping from step indices in _steps to segment indices sent to the AWG programmer device.

Type:: dict[int, dict[int, int]]

register_program_single_device(function_program_memory_single_device, function_program_segment_step_single_device)¶

Registers callback functions for programming the AWG memory and segment steps.

Parameters:

function_program_memory_single_device (Callable[[int, Any], None]) – Function (device_index, awg_data) -> None.
function_program_segment_step_single_device (Callable[[int, list[tuple[int, int]]], None]) – Function (device_index, list_of_segment_indices_and_repeats) -> None.

schedule(sequences, repeats=1)¶

Schedules sequences with repeats.

Parameters:

sequences (Sequence | list[Sequence]) – A single sequence or a list of sequences.
repeats (int) – Number of repeats for sequences. Default 1.

Returns:

List of sequence indices scheduled.

Return type:

list[int]

property scheduled_sequence_indices: deque[int]¶: Gets indices of all scheduled sequences.

setup(program_single_sequence_only=False)¶

Prepares execution of the sequences.

This must be called before calling get_next_sequence_info. It sends steps in all scheduled sequences to segmenters to produce AWG segments.

Parameters:: program_single_sequence_only (bool) – Whether to only program the next sequence. If True, attempts to program as many sequences as possible to fit in the AWG memory.

program_next_sequence()¶

Programs the AWG memory and segment orders and repeats for the next scheduled sequence.

Returns:: next scheduled sequence object.
Return type:: Sequence

segmenter¶

class qfabric.planner.segmenter.Segment(device_step)¶

Bases: object

Base class representing AWG data of a DeviceStep.

Parameters:: device_step (DeviceStep) – device step containing AWG functions on a single device.

class qfabric.planner.segmenter.Segmenter(analog_channels, digital_channels)¶

Bases: object

Base class for converting from Step to Segment on a AWG device.

It converts from pulse sequence steps (analog and digital functions) to AWG-specific data. Data stored in the Segment objects should be compatible with the AWG used, respecting all specifications and constraints of the AWG.

Each different AWG model (or even the same AWG model with very different usage) generally needs a subclass of Segmenter converting Step objects to Segment objects. See MockSegmenter and M4i6622Segmenter for examples.

Each subclass of Segmenter needs to override set_steps() and get_awg_memory_data().

Parameters:

analog_channel (list[int]) – Analog channel indices.
digital_channels (list[int]) – Digital channel indices.

trigger_device¶

Whether this AWG is used to trigger other AWGs.

Type:: bool

_device_steps¶

See set_steps(), device steps scheduled on this device. All unique device_steps are saved in it.

Type:: list[DeviceStep]

_sequence_to_device_steps_map¶

See set_steps(), mapping from sequence indices to device step indices.

Type:: dict[int, list[int]]

abstractmethod set_steps(steps, sequence_to_steps_map)¶

Gets a list of device steps and a list of segments from a list of steps.

This function converts steps to _device_steps, which is a list of DeviceStep with the same length and order as steps. It also stores the map from sequence indices to lists of steps indices, sequence_to_steps_map, in _sequence_to_device_steps_map.

Parameters:

steps (list[Step]) – All steps in sequences that are scheduled.
sequence_to_steps_map (dict[int, list[int]]) – Mapping from sequence indices to lists to step indices in steps. Keys should be in the order of sequence scheduling. Values should be in the order of step executation in each sequence.

abstractmethod get_awg_memory_data(sequence_indices)¶

Gets AWG programming information given sequences that need to be programmed.

Parameters:

sequence_indices (list[int]) – Sequence indices to be programmed. The indices must match the indices from _sequence_to_device_steps_map.

Returns:

(awg_data, step_to_segment_map, sequence_indices_programmed)

awg_data: Data sent to the programming device (Device) to program the segments. The data usually contains a list of Segment objects, representing the segments to be programmed.

step_to_segment_map: Mapping from step indices to segment indices. Steps are indexed with _device_steps and segments are indexed with the list of segments returned in awg_data.

sequence_indices_programmed: List of sequence indexed programmed.

Return type:

(Any, dict[int, int], list[int])

segmenter.virtual¶

class qfabric.planner.segmenter.virtual.VirtualSegmenter(analog_channels, digital_channels)¶

Bases: Segmenter

A virtual segmenter that accepts any number of digital and analog channels.

It works with VirtualDevice. It does not interface with any AWG device. However, it can be defined as an AWG in the config TOML file as a virtual AWG. It allows additional virtual channels to be visualized.

set_steps(steps, sequence_to_steps_map)¶

Gets a list of device steps and a list of segments from a list of steps.

Parameters:

steps (list[Step]) – All steps in sequences that are scheduled.
sequence_to_steps_map (dict[int, list[int]]) – Mapping from sequence indices to lists to step indices in steps. Keys should be in the order of sequence scheduling. Values should be in the order of step executation in each sequence.

get_awg_memory_data(sequence_indices)¶

Gets AWG programming information given sequences that need to be programmed.

Parameters:

sequence_indices (list[int]) – Sequence indices to be programmed. The indices must match the indices from _sequence_to_device_steps_map.

Returns:

(awg_data, step_to_segment_map, sequence_indices_programmed)

awg_data: Data sent to the programming device (Device) to program the segments. The data usually contains a list of Segment objects, representing the segments to be programmed.

step_to_segment_map: Mapping from step indices to segment indices. Steps are indexed with _device_steps and segments are indexed with the list of segments returned in awg_data.

sequence_indices_programmed: List of sequence indexed programmed.

Return type:

(Any, dict[int, int], list[int])

segmenter.m4i6622¶

qfabric.planner.segmenter.m4i6622.get_segment_sample_size_from_time(nominal_segment_time)¶

Gets the minimum allowed sample size given the segment duration.

Parameters:: nominal_segment_time (float) – Desired duration of a segment.
Returns:: Minimum number of samples of a segment longer or equal to the desired duration.
Return type:: int

qfabric.planner.segmenter.m4i6622.get_segment_sample_size(nominal_sample_size)¶

Gets the minimum allowed sample size given desired sample size.

Parameters:: nominal_sample_size (int) – Desired number of samples.
Returns:: Minimum number of samples of a segment longer or equal to the desired size.
Return type:: int

qfabric.planner.segmenter.m4i6622.get_max_segment_size_and_count(segment_count)¶

Gets the maximum segment size and maximum number of segments.

Parameters:: segment_count (int) – Number of segments needed.
Returns:: Maximum size of each segment, aximum number of segments without reducing the segment size.
Return type:: tuple[int, int]

qfabric.planner.segmenter.m4i6622.voltages_to_awg_data(analog_voltages)¶

Converts voltages in V to AWG data of a channel.

Parameters:: analog_voltages (npt.NDArray[np.float64]) – AWG output in V.
Returns:: AWG raw data.
Return type:: npt.NDArray[np.int16]

qfabric.planner.segmenter.m4i6622.add_digital_to_awg_data(awg_data, digital)¶

Adds digital output information to AWG analog data.

Digital data of a channel uses the most significant bit of the AWG data of a channel.

Parameters:

awg_data (npt.NDArray[np.int16]) – AWG raw data.
digital (npt.NDArray[np.bool]) – Digital data.

Returns:

AWG raw data with digital data in it.

Return type:

awg_data (npt.NDArray[np.int16])

class qfabric.planner.segmenter.m4i6622.SegmentBlock(segment, start_index, stop_index)¶

Bases: object

A block of a segment that corresponds to a AWG memory block

As the M4i6622 device has uniform sized memory blocks, it is often helpful to divide M4i6622Segment into smaller units to ensure efficient use of the AWG memory.

Parameters:

segment (M4i6622Segment) – Segment to divide into blocks.
start_index (int) – Start sample (time) index.
stop_index (int) – Stop sample (time) index.

awg_data¶

AWG data compatible with its memory format.

Type:: npt.NDArray[np.int16]

class qfabric.planner.segmenter.m4i6622.EmptySegmentBlock(num_samples)¶

Bases: SegmentBlock

Empty segment block.

Parameters:: num_samples (int) – Number of samples for each channel.

class qfabric.planner.segmenter.m4i6622.M4i6622Segment(device_step, analog_channels, digital_analog_map)¶

Bases: Segment

Performs segmentation of a device step data for the M4i6622 AWG.

Parameters:

device_step (DeviceStep) – Device step containing AWG functions on a device.
analog_channels (list[int]) – (list[int]): Analog channels of the device.
digital_analog_map (dict[int, int]) – (dict[int, int]): Maps digital channels to analog channels storing the digital data.

max_segment_block_size¶

Last maximum block size used to divide the segment into blocks.

Type:: int

segment_size¶

Number of samples in this segment.

Type:: int

is_empty¶

If this segment has no nonzero analog or digital data.

Type:: bool

awg_data¶

AWG data in 2D array. Axis 0 is sample indices, axis 1 is channel indices.

Type:: npt.NDArray[np.int16]

_constant_sample_region_indices¶

Start and stop indices for regions with constant AWG data. Here constant AWG data means that for each digital or analog channel, the output value does not change in this region. Such regions may be replaced by a shorter block repeated a few times.

Type:: list[tuple[int, int]]

segment_blocks¶

Distinct blocks for this segment.

Type:: list[SegmentBlock]

segment_block_indices_and_repeats¶

Block indices and repeats for this segment. Index -1 refers to a maximum length EmptySegmentBlock.

Type:: list[tuple[int, int]]

estimate_segment_blocks_needed(max_segment_block_size)¶

Conservatively estimates the number of segment blocks needed for this segment.

Parameters:: max_segment_block_size (int) – Maximum length of a segment block to be saved in the AWG.
Returns:: Maximum number of segment blocks needed.
Return type:: int

create_segment_blocks(max_segment_block_size)¶

Creates the segment_blocks.

Defines segment_blocks as distinct segment_blocks of this segment.

Defines segment_block_indices_and_repeats as segment_block indices and repeats to execute this segment. Index -1 refers to an empty segment block of maximum length.

Parameters:: max_segment_block_size (int) – Maximum length of a segment_block to be saved in the AWG.

class qfabric.planner.segmenter.m4i6622.M4i6622Segmenter(analog_channels, digital_channels, analog_channels_to_store_digital_data)¶

Bases: Segmenter

Converts steps to M4i6622Segment objects.

Supports the Spectrum M4i6622 AWG.

Assumptions:

The AWG sample rate is fixed at 625 Msps.
All four AWG channels of the device is used.

Parameters:

device_step (DeviceStep) – Device step containing AWG functions on a device.
analog_channels (list[int]) – (list[int]): Analog channels of the device.
digital_analog_map – (dict[int, int]): Maps digital channels to analog channels storing the digital data.

_device_steps¶

See set_steps(), device steps scheduled on this device. All unique device_steps are saved in it.

Type:: list[DeviceStep]

_sequence_to_device_steps_map¶

See set_steps(), mapping from sequence indices to device step indices.

Type:: dict[int, list[int]]

_segments¶

Unique segments from _device_steps.

Type:: list[M4i6622Segment]

_device_step_to_segment_map¶

Mapping from device step indices to segment indices.

Type:: dict[int, int]

_sequence_to_segments_map¶

Mapping from sequence indices to segment indices. The keys are the segment indices in the scheduled order. The values are segment indices in the execution order of a sequence.

Type:: dict[int, list[int]]

set_steps(steps, sequence_to_steps_map)¶

Gets a list of device steps and a list of segments from a list of steps.

Parameters:

steps (list[Step]) – All steps in sequences that are scheduled.
sequence_to_steps_map (dict[int, list[int]]) – Mapping from sequence indices to lists to step indices in steps. Keys should be in the order of sequence scheduling. Values should be in the order of step executation in each sequence.

get_awg_memory_data(sequence_indices)¶

Gets AWG programming information given sequences that need to be programmed.

Parameters:

sequence_indices (list[int]) – Sequence indices to be programmed. The indices must match the indices from _sequence_to_device_steps_map.

Returns:

(awg_data, step_to_segment_map, sequence_indices_programmed)

awg_data: Data sent to the programming device (Device) to program the segments. The data usually contains a list of Segment objects, representing the segments to be programmed.

step_to_segment_map: Mapping from step indices to segment indices. Steps are indexed with _device_steps and segments are indexed with the list of segments returned in awg_data.

sequence_indices_programmed: List of sequence indexed programmed.

Return type:

(Any, dict[int, int], list[int])

segmenter.awg710¶

qfabric.planner.segmenter.awg710.get_segment_sample_size_from_time(nominal_segment_time, sample_rate)¶

Gets the minimum allowed sample size given the segment duration.

Parameters:

nominal_segment_time (float) – Desired duration of a segment.
sample_rate (int) – Sample rate.

Returns:

Minimum number of samples of a segment longer or equal to the desired duration.

Return type:

int

qfabric.planner.segmenter.awg710.get_segment_sample_size(nominal_sample_size)¶

Gets the minimum allowed sample size given desired sample size.

Parameters:: nominal_sample_size (int) – Desired number of samples.
Returns:: Minimum number of samples of a segment longer or equal to the desired size.
Return type:: int

class qfabric.planner.segmenter.awg710.AWG710Segment(device_step, analog_channel, digital_channels, sample_rate)¶

Bases: Segment

Represents a device step for the Tektronix AWG710 AWG.

Parameters:

device_step (DeviceStep) – Device step containing AWG functions on a device.
analog_channel (int) – Analog channel of the device.
digital_channels (list[int]) – Digital channels of the device.
sample_rate (int) – Sample rate.

class qfabric.planner.segmenter.awg710.AWG710Segmenter(analog_channels, digital_channels, sample_rate=4000000000)¶

Bases: Segmenter

Converts steps to AWG710Segment objects.

Supports the Tektronix AWG710 AWG.

Parameters:

analog_channels (list[int]) – Analog channels of the device.
digital_chnanels (list[int]) – Digital channels of the device.
sample_rate (int) – Sample rate of the AWG. Minimum 50e3 (50 kS/s), maximum 4e9 (4 GS/s).

_device_steps¶

See set_steps(), device steps scheduled on this device. All unique device_steps are saved in it.

Type:: list[DeviceStep]

_sequence_to_device_steps_map¶

See set_steps(), mapping from sequence indices to device step indices.

Type:: dict[int, list[int]]

_segments¶

Unique segments from _device_steps.

Type:: list[AWG710Segment]

_device_step_to_segment_map¶

Mapping from device step indices to segment indices.

Type:: dict[int, int]

_sequence_to_segments_map¶

Mapping from sequence indices to segment indices. The keys are the segment indices in the scheduled order. The values are segment indices in the execution order of a sequence.

Type:: dict[int, list[int]]

set_steps(steps, sequence_to_steps_map)¶

Gets a list of device steps and a list of segments from a list of steps.

Parameters:

steps (list[Step]) – All steps in sequences that are scheduled.
sequence_to_steps_map (dict[int, list[int]]) – Mapping from sequence indices to lists to step indices in steps. Keys should be in the order of sequence scheduling. Values should be in the order of step executation in each sequence.

get_awg_memory_data(sequence_indices)¶

Gets AWG programming information given sequences that need to be programmed.

Parameters:

sequence_indices (list[int]) – Sequence indices to be programmed. The indices must match the indices from _sequence_to_device_steps_map.

Returns:

(awg_data, step_to_segment_map, sequence_indices_programmed)

awg_data: Data sent to the programming device (Device) to program the segments. The data usually contains a list of Segment objects, representing the segments to be programmed.

step_to_segment_map: Mapping from step indices to segment indices. Steps are indexed with _device_steps and segments are indexed with the list of segments returned in awg_data.

sequence_indices_programmed: List of sequence indexed programmed.

Return type:

(Any, dict[int, int], list[int])

segmenter.mock¶

class qfabric.planner.segmenter.mock.MockSegment(device_step, sample_rate, analog_channels, digital_channels)¶

Bases: Segment

Segment for a mock AWG device.

class qfabric.planner.segmenter.mock.MockSegmenter(sample_rate, analog_channels, digital_channels)¶

Bases: Segmenter

A mock segmenter.

It does not do anything other than checking for segment duplicates.

set_steps(steps, sequence_to_steps_map)¶

Gets a list of device steps and a list of segments from a list of steps.

Parameters:

steps (list[Step]) – All steps in sequences that are scheduled.
sequence_to_steps_map (dict[int, list[int]]) – Mapping from sequence indices to lists to step indices in steps. Keys should be in the order of sequence scheduling. Values should be in the order of step executation in each sequence.

get_awg_memory_data(sequence_indices)¶

Gets AWG programming information given sequences that need to be programmed.

Parameters:

sequence_indices (list[int]) – Sequence indices to be programmed. The indices must match the indices from _sequence_to_device_steps_map.

Returns:

(awg_data, step_to_segment_map, sequence_indices_programmed)

awg_data: Data sent to the programming device (Device) to program the segments. The data usually contains a list of Segment objects, representing the segments to be programmed.

step_to_segment_map: Mapping from step indices to segment indices. Steps are indexed with _device_steps and segments are indexed with the list of segments returned in awg_data.

sequence_indices_programmed: List of sequence indexed programmed.

Return type:

(Any, dict[int, int], list[int])