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.
`special_implementation`	Set to `True` if the implementation is a special purpose implementation that should never get called in `ScheduleBuilder.get_implementation` unless explicitly requested via the `impl_name` argument.
`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

`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_custom_locus_mapping`	Get custom locus mapping for this GateImplementation.
`get_locus_mapping_name`	Get the name of the locus mapping stored in `ScheduleBuilder.ChipTopology` for this implementation.
`get_parameters`	Calibration data tree the GateImplementation subclass expects for each locus.
`may_have_calibration`	True iff the implementation may have calibration data.
`needs_calibration`	True iff the implementation class needs calibration 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

special_implementation: bool = False#: Set to True if the implementation is a special purpose implementation that should never get called in ScheduleBuilder.get_implementation unless explicitly requested via the impl_name argument.

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 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)#

Calibration data tree the GateImplementation subclass expects for each locus.

Helper method for EXA use.

Parameters:

locus (Iterable[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 get_locus_mapping_name(operation_name, implementation_name)#

Get the name of the locus mapping stored in ScheduleBuilder.ChipTopology for this implementation.

By default, it is "<operation_name>.<implementation_name>". Inheriting classes may override this for different behaviour.

Parameters:

operation_name (str) – name of the quantum operation.
implementation_name (str) – name of the implementation

Returns:

name of the locus mapping

Return type:

str

classmethod get_custom_locus_mapping(chip_topology, component_to_channels)#

Get custom locus mapping for this GateImplementation.

This method can be used to return the locus mapping (wrt. to the given ChipTopology) for this GateImplementation. Overriding this method allows a GateImplementation to be “self-sufficient” in the sense that it knows its own locus mapping.

Parameters:

chip_topology (ChipTopology) – ChipTopology instance in which context to create the custom locus mapping.
component_to_channels (Mapping[str, Iterable[str]]) – dict mapping QPU component names to an Iterable of channel operation names available for this component (i.e. “readout”, “drive”, “flux”). This info is often needed in building a locus mapping.

Returns:

Custom locus mapping for this GateImplementation or None if the gate implementation has no need for a: custom locus mapping, otherwise the returned mapping should be like in ChipTopology.set_locus_mapping()

Return type:

dict[tuple[str, …] | frozenset[str], tuple[str, …]] | None

Inheritance

GateImplementation

Contents

GateImplementation#