GateImplementation

GateImplementation#

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

Module: iqm.pulse.gate_implementation

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.
`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_factorizable`	Construct an 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 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. Only meaningful if 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.

_timebox_cache: dict[tuple[Any, ...], TimeBox | list[TimeBox]]#: Cache for __call__() results.

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

classmethod needs_calibration()#

True iff the implementation needs calibration data.

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.

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

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

_call(*args, **kwargs)#

The GateImplementation-specific logic for implementing a quantum operation.

Inheriting classes may override this method if the default __call__() caching (based on the args & kwargs in the signature) is sufficient. Any additional caching may also be implemented inside this function if needed.

Return type:: TimeBox | list[TimeBox]

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

Construct an 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=())#

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.

Returns:

EXA setting node describing the required calibration data for each locus. All the Setting values are None.

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

GateImplementation

Contents

GateImplementation#