GateImplementation

GateImplementation#

Module: iqm.pulse.gate_implementation

class iqm.pulse.gate_implementation.GateImplementation(parent, name, locus, calibration_data, builder)#

Bases: ABC

ABC for implementing quantum gates and other quantum operations using instruction schedules.

Every implementation of every operation type can have its own GateImplementation subclass. Each GateImplementation instance represents a particular locus for that implementation, and encapsulates the calibration data it requires.

All GateImplementation subclasses __init__() must have exactly the below arguments in order to be usable via ScheduleBuilder.get_implementation().

GateImplementation also has the __call__() method, which takes the operation parameters (e.g. rotation angles) as input, and builds, caches and then returns a TimeBox instance which implements an instance of the operation at that locus. __call__() normally should not be reimplemented by the subclasses, instead they should define _call() which contains the actual implementation without the caching logic.

Even though it is possible, GateImplementations should not use other gates to implement themselves, unless they are subclasses of CompositeGate. This is to encapsulate the calibration data better, and avoid unpredictable dependencies between gates.

Parameters:

parent (QuantumOp) – Quantum operation this instance implements.
name (str) – Name of the implementation provided by this instance.
locus (Locus) – Locus the operation acts on.
calibration_data (OILCalibrationData) – (Raw) calibration data for the (operation, implementation, locus) represented by this instance.
builder (ScheduleBuilder) – Schedule builder instance that can be used to access system properties (and in the case of CompositeGate, other gates).

Attributes

`parameters`	Required calibration data, may be nested
`qualified_name`	Qualified name of the implementation.
`symmetric`	True iff the implementation is symmetric in its locus components, meaning a permuted `locus` produces the same Schedule/TimeBox.
`id`	Unique str identifier, needed for certain caching properties.
`sub_implementations`	Single-component sub-implementations for factorizable gates with len(locus) > 1, otherwise empty.

Methods

`build_setting_node`	Build the gate calibration settings tree node.
`construct_aggregator`	Construct an aggregator implementation for a factorizable operation.
`convert_calibration_data`	Convert time- and frequency-like items in the calibration data to fractions of the time duration of the gate.
`duration_in_seconds`	Duration of the Schedule of the gate implementation (in seconds).
`get_locus_mapping`	Get the locus mapping for this GateImplementation.
`get_parameters`	Default calibration data tree the GateImplementation subclass expects for each locus.
`locus_mapping_function`	One-qubit loci.
`may_have_calibration`	True iff the implementation may have calibration data.
`needs_calibration`	True iff the implementation class needs calibration parameter data.
`optional_calibration_keys`	Optional calibration data keys for this class, in addition to the required items in `parameters`.
`to_timebox`	Wraps the given instruction schedule into an atomic/resolved timebox.

symmetric: bool = False#: True iff the implementation is symmetric in its locus components, meaning a permuted locus produces the same Schedule/TimeBox. Only meaningful if self.parent.arity != 1, and the locus components are of the same type.

parameters: dict[str, Parameter | Setting | dict] = {}#: Required calibration data, may be nested

locus_mapping_function()#

Locus mapping function get_locus_mapping() uses.

For convenience the default is “all one-qubit loci”.

Parameters:: sp (StationProperties)
Return type:: dict[tuple[str, …], tuple[str, …]]

id#: Unique str identifier, needed for certain caching properties.

sub_implementations: dict[str, GateImplementation]#: Single-component sub-implementations for factorizable gates with len(locus) > 1, otherwise empty. At least one of self.sub_implementations and self.calibration_data is always empty.

property qualified_name: str#: Qualified name of the implementation.

classmethod needs_calibration()#

True iff the implementation class needs calibration parameter data.

Does not include the calibration data of CompositeGate member gates.

Returns:: True iff OpCalibrationDataTree must contain a node f"{self.parent.name}.{self.name}.{self.locus} for the calibration data this instance needs.
Return type:: bool

classmethod optional_calibration_keys()#

Optional calibration data keys for this class, in addition to the required items in parameters.

These keys are not required to be present in OILCalibrationData when validating it. E.g. custom calibration keys for CompositeGate member gates.

Returns:: Optional top-level calibration data keys.
Return type:: tuple[str, …]

final classmethod may_have_calibration()#

True iff the implementation may have calibration data.

Returns:: True iff OpCalibrationDataTree may contain a node "{self.parent.name}.{self.name}.{self.locus} for the calibration data of this instance.
Return type:: bool

final classmethod construct_aggregator(parent, name, locus, builder, sub_implementations)#

Construct an aggregator implementation for a factorizable operation.

Instead of calibration data this method is given sub_implementations, which contains single-qubit implementations for all the components in locus.

Parameters:

parent (QuantumOp)
name (str)
locus (Locus)
builder (ScheduleBuilder)
sub_implementations (dict[str, GateImplementation])

Return type:

GateImplementation

final to_timebox(schedule)#

Wraps the given instruction schedule into an atomic/resolved timebox.

Parameters:: schedule (Schedule)
Return type:: TimeBox

duration_in_seconds()#

Duration of the Schedule of the gate implementation (in seconds).

Can be left unimplemented if the duration e.g. depends on the gate arguments. Subclasses can reimplement this method in case it makes sense in their context.

Return type:: float

final classmethod convert_calibration_data(calibration_data, params, channel_props, *, duration=None, _top_level=True)#

Convert time- and frequency-like items in the calibration data to fractions of the time duration of the gate.

This is a convenience method for converting calibration data items involving time durations measured in seconds and frequencies measured in Hz into fractions of the duration of the gate, e.g. to be used to parameterize Waveform classes.

Values of items that are not measured in seconds or Hz are returned as is.
Items named duration get special treatment for convenience. They are not included in the converted data. If the duration parameter is None, there must be a "duration" item at the top level in calibration_data whose value will be used instead.
The duration parameter is converted to channel samples and included in the converted data under the top-level key "n_samples".

Parameters:

calibration_data (OILCalibrationData) – (subset of) calibration data for the gate/implementation/locus
params (NestedParams) – (subset of) cls.parameters specifying the calibration_data items to convert and return
channel_props (ChannelProperties) – used to convert "duration" from seconds into channel samples
duration (float | None) – Time duration of the gate, in seconds. If None, calibration_data must have an item named "duration", measured in seconds, which will be used instead.
_top_level (bool)

Returns:

converted calibration_data items

Return type:

OILCalibrationData

final classmethod get_parameters(locus, path=(), *, use_defaults=True)#

Default calibration data tree the GateImplementation subclass expects for each locus.

Formats the parameters class attribute into a tree of SettingNode objects, replacing any wildcard characters.

Parameters:

locus (tuple[str, ...]) – Locus component names to replace the wildcard character "*" in the calibration parameter names. One Setting will be generated for each component name in locus. If there are no wildcard characters in cls.parameters, this argument has no effect.
path (Iterable[str]) – parts of the dotted name for the root node, if any.
use_defaults (bool) – Iff True, return default values for calibration data items that have one.

Returns:

EXA setting node describing the required calibration data for each locus. The setting values are None, unless the corresponding gate parameter has a default value.

Return type:

SettingNode

classmethod build_setting_node(locus, station_properties, path=(), *, use_defaults=True)#

Build the gate calibration settings tree node.

By default, uses get_parameters() to build the node, but can be overridden by subclasses if needed (e.g. if the node structure needs to be aware of the station_properties).

Parameters:

locus (tuple[str, ...]) – Locus component names to replace the wildcard character "*" in the calibration parameter names. One Setting will be generated for each component name in locus. If there are no wildcard characters in cls.parameters, this argument has no effect.
station_properties (StationProperties) – The station properties. By default, not used, but subclasses may override this method in order to implement topology or control channel specific node structures.
path (Iterable[str]) – parts of the dotted name for the root node, if any.
use_defaults (bool) – Iff True, return default values for calibration data items that have one.

Returns:

EXA setting node describing the required calibration data for each locus.

Return type:

SettingNode

final classmethod get_locus_mapping(station)#

Get the locus mapping for this GateImplementation.

The locus mapping defines all the possible loci where this GateImplementation can be applied. It takes into account the symmetry of the gate and the implementation, and should not include unnecessary duplicate nodes for symmetric implementations, only the one sorted in the canonical (numerical) order.

For arity-0 gates the locus mapping should only have single-component loci.

Parameters:

station (StationProperties) – Static properties of the station for which to create the locus mapping.

Returns:

Mapping from the possible loci for this GateImplementation to the QPU components used: by the implementation on that locus.

Return type:

dict[tuple[str, …], tuple[str, …]]

Inheritance

GateImplementation

Contents

GateImplementation#