qat.experimental.dialect.pulse.ir.attributes module

class AmplitudeAttr(value)

Bases: PulseNumericTypedAttr[AmplitudeType]

An attribute that represents a compile-time constant amplitude.

Variables:

real – The real part of the amplitude, which is expected to be a float representing the amplitude in arbitrary units.
imag – The imaginary part of the amplitude, which is expected to be a float representing the amplitude in arbitrary units, and defaults to 0.0 if not provided.

Parameters:

value¶ (complex | float) – The amplitude value, which can be a complex number or a float. If a float is provided, the imaginary part is set to 0.0.

property associated_type: type[AmplitudeType]: Returns the associated dialect type.

classmethod get_irdl_definition(): Get the IRDL attribute definition.

imag: FloatData

property literal_value: complex: Returns the amplitude value as a complex number.

name: ClassVar[str] = 'pulse.amplitude_attr': The attribute name should be a static field in the attribute classes.

real: FloatData

class ComplexData(data)

Bases: Data[complex]

Store a Pythonic complex data type.

Comparatively to the complex.ComplexNumberAttr type, this data object can store a Pythonic complex number without having to specify bitwidth (with its counterpart also breaking it up into two real components). This is analogous to the FloatData, which allows us to specify floats without specifying bitwidth. For the high level of abstraction targeted by the pulse dialect, we do not need to specify details like bitwidth, as this is specified when lowering to lower levels, be it a classical CPU, or quantum control system.

Note

This data type is specified in the absence of an existing one in xDSL. If that changes in the future, this type would be marked for deprecation.

data: DataElement

name: ClassVar[str] = 'pulse.complex_data': The attribute name should be a static field in the attribute classes.

classmethod parse_parameter(parser)

Parses the parameter represented as a string into a complex number.

Return type:: complex

print_parameter(printer): Prints the complex parameter, representing the real and imaginary components as a two-element tuple.

class DiscriminatorPolicyAttr(*parameters)

Bases: ParametrizedAttribute, ABC

Parent class for all discriminator policies, which are used to determine how to process IQ values.

State labels are non-negative integers, with the exception of -1, which is reserved for representing an unmapped state, such as IQ values which cannot be confidently mapped to any state.

POLICY_NAME: ClassVar[str]

name: ClassVar[str] = 'pulse.discriminator_policy': The attribute name should be a static field in the attribute classes.

abstract property state_range: tuple[int, int]: Returns the range of state labels that the discriminator policy can discriminate between.

class EqualiseAttr(linear_coefficient, conjugate_coefficient, translation)

Bases: EqualiseAttr

An attribute that represents an affine transformation, used as part of the post- processing pipeline for acquired signals.

In a complex space, an affine transformation of a complex number z can be represented as:

\[z' = a * z + b * conj(z) + c\]

where:

\(a\) is the (complex) linear coefficient,
\(b\) is the (complex) conjugate coefficient,
\(c\) is the (complex) translation.

If we consider this from a two-dimensional real space perspective, we can represent the affine transformation as

\[z' = A * z + C\]

where A is an arbitrary 2x2 real matrix representing the linear transformation, and C is an arbitrary 2D real vector representing the translation.

This attribute stores the transformation using the three complex numbers to be consistent with the complex representation of the IQ space. However, it offers utilities to expose the transformation in a real space representation, and also build from it. This allows a compact representation that is consistent with legacy PuRR linear_map_complex_to_real, and also the more generalised affine transformations defined in pydantic pipelines.

Parameters:

linear_coefficient¶ (ComplexData | complex) – The (complex) linear coefficient.
conjugate_coefficient¶ (ComplexData | complex) – The (complex) conjugate coefficient.
translation¶ (ComplexData | complex) – The (complex) translation.

conjugate_coefficient: ComplexData

classmethod from_real_space(linear_matrix, translation_vector)

Creates an EqualiseAttr from a real space representation.

Parameters:

linear_matrix¶ (ndarray[float64]) – A 2x2 real matrix representing the linear transformation.
translation_vector¶ (ndarray[float64]) – A 2D real vector representing the translation.

Return type:

EqualiseAttr

Returns:

An instance of EqualiseAttr.

classmethod get_irdl_definition(): Get the IRDL attribute definition.

linear_coefficient: ComplexData

property linear_matrix: ndarray[float64]: Returns the linear transformation matrix in real space representation.

name: ClassVar[str] = 'pulse.affine_transform': The attribute name should be a static field in the attribute classes.

translation: ComplexData

property translation_vector: ndarray[float64]: Returns the translation vector in real space representation.

class ExternalPolicyAttr(*parameters)

Bases: DiscriminatorPolicyAttr

Stub for a future extension that will allow custom (off-chip) state discrimination to be hooked into the runtime post-processing facilities.

class FrequencyAttr(value, unit=FrequencyUnits.HERTZ)

Bases: PulseNumericTypedAttr[FrequencyType]

An attribute that represents a compile-time constant frequency.

Variables:

value – The frequency value, which can be a float or an integer.
unit – The frequency units, which is an instance of the FrequencyUnits enum.

Parameters:

value¶ (float | int) – The frequency value in Hz, which can be a float or an integer.
unit¶ (FrequencyUnits) – The frequency units, which is an instance of the FrequencyUnits, enum and defaults to hertz if not provided.

property associated_type: type[FrequencyType]: Returns the associated dialect type.

classmethod from_literal_value(value, unit=FrequencyUnits.HERTZ)

Creates a frequency attribute from a canonical value in Hertz.

Parameters:

value¶ (float | int) – The frequency value in Hertz.
unit¶ (FrequencyUnits) – The unit used to store the value.

Return type:

FrequencyAttr

Returns:

A frequency attribute storing value in the requested unit.

classmethod get_irdl_definition(): Get the IRDL attribute definition.

property literal_value: float | int: Returns the frequency value in Hertz.

name: ClassVar[str] = 'pulse.frequency_attr': The attribute name should be a static field in the attribute classes.

unit: FrequencyUnitsData

value: FloatData | IntAttr

class FrequencyUnitsData(data)

Bases: Data[FrequencyUnits]

Data attribute for representing frequency units in the pulse dialect.

data: DataElement

name: ClassVar[str] = 'pulse.frequency_units': The attribute name should be a static field in the attribute classes.

classmethod parse_parameter(parser)

Parses the parameters of the attribute, which are expected to be a string representing the frequency units.

Return type:: FrequencyUnits

print_parameter(printer)

Prints the parameters of the attribute, which are expected to be a string representing the frequency units.

Return type:: None

class MaximumLikelihoodPolicyAttr(state_centers, noise_estimate=1.0, p_min=0.0)

Bases: MaximumLikelihoodPolicyAttr

A discriminator policy that discriminates between multiple states based on a maximum likelihood approach.

State labels are non-negative integers, each mapping to a center represented by a complex number. Every IQ point can be assigned to the state label k with the highest normalised likelihood:

\[\tilde{p}_k(z) = \frac{L_k(z)}{\sum_j L_j(z)}, \quad L_k(z) = \exp\!\left(-\frac{|z - \mathrm{loc}_k|^2}{2\,\nu}\right)\]

where \(\nu\) is the noise power (variance) noise_est.

If the maximum likelihood is below a threshold p_min, the IQ point is assigned to the state -1 (unmapped).

Variables:

state_centers – A list of the different state centers which map respectively to their state labels, which are ordered from 0 to len(state_centers) - 1. Each center is represented by a complex number.
noise_estimate – The noise power (variance) of the IQ values.
p_min – The minimum normalised likelihood required to assign an IQ point to a state label. If the maximum normalised likelihood is below this threshold, the IQ point is assigned to the state -1 (unmapped).

Parameters:

state_centers¶ (Iterable[complex | ComplexData]) – A list of the different state centers which map respectively to their state labels, which are ordered from 0 to len(state_centers) - 1. Each center is represented by a complex number.
noise_estimate¶ (float) – The noise power (variance) of the IQ values. Defaults to 1.0 if not provided. Noise estimate is only important if p_min is set to a value greater than 0.0, as it is used to calculate the normalised likelihoods of the IQ points. If p_min is set to 0.0, the noise estimate is ignored.
p_min¶ (float) – The minimum normalised likelihood required to assign an IQ point to a state label. If the maximum normalised likelihood is below this threshold, the IQ point is assigned to the state -1 (unmapped).

POLICY_NAME: ClassVar[str] = 'maximum_likelihood'

classmethod get_irdl_definition(): Get the IRDL attribute definition.

name: ClassVar[str] = 'pulse.maximum_likelihood_policy': The attribute name should be a static field in the attribute classes.

noise_estimate: FloatData

p_min: FloatData

state_centers: ArrayAttr[ComplexData]

property state_range: tuple[int, int]: The range of state labels that the discriminator policy can discriminate between.

verify(): Validates the properties of the maximum likelihood policy attribute.

class NumericArrayData(data)

Bases: Data[ndarray[complexfloating]]

Stores numeric arrays for use in attributes.

Manipulations of sampled waveforms and weight vectors are processed using numpy due to its performance, and for this reason, we store this data as a numpy array.

To be future thinking, and compatible with integrations with MLIR in the future, we print and parse the data as a list of builtin attributes, with the conversion handled in the interface.

data: DataElement

name: ClassVar[str] = 'pulse.numeric_array_data': The attribute name should be a static field in the attribute classes.

classmethod parse_parameter(parser)

Parses the parameters of the attribute, which are expected to be a list of builtin complex attributes representing elements within the array.

Return type:: ndarray[complex128]

print_parameter(printer)

Prints the parameters as textual MLIR, which are provided as complex attributes in a list.

Return type:: None

class PhaseAttr(value)

Bases: PulseNumericTypedAttr[PhaseType]

An attribute that represents a compile-time constant phase. Phases are represented by radians.

Variables:: value – The phase value, which is expected to be a float representing the phase in radians.
Parameters:: value¶ (float) – The phase value in radians, represented as a float.

property associated_type: type[PhaseType]: Returns the associated dialect type.

classmethod get_irdl_definition(): Get the IRDL attribute definition.

property literal_value: float: Returns the phase value.

name: ClassVar[str] = 'pulse.phase_attr': The attribute name should be a static field in the attribute classes.

value: FloatData

class PulseNumericTypedAttr(*parameters)

Bases: ParametrizedAttribute, Generic[PULSE_VAR_TYPE], ABC

Base class for attributes in the pulse dialect that have a type associated with them.

This is used to group together attributes that represent typed values, such as frequencies, phases, times and amplitudes.

abstract property associated_type: type[PULSE_VAR_TYPE]: Returns the type that is associated with this attribute, which is specified by the concrete subclass.

abstract property literal_value: Number: Converts the attribute to a literal value, which is returned as a numeric value, and specified by the concrete subclass.

class RealThresholdPolicyAttr(threshold=0.0)

Bases: RealThresholdPolicyAttr

A discriminator policy that discriminates between two states based on a real threshold.

The discriminator works by mapping the IQ values to states {0, 1} according to the classifier

\[\begin{split}\text{state}(z) = \begin{cases} 0 & \text{if } \Re(z) < \text{threshold} \\ 1 & \text{if } \Re(z) \geq \text{threshold} \end{cases}\end{split}\]

Variables:: threshold – The threshold value, which is used to determine the state of the IQ value.
Parameters:: threshold¶ (float) – The threshold value, which is used to determine the state of the IQ value.

POLICY_NAME: ClassVar[str] = 'real_threshold'

classmethod get_irdl_definition(): Get the IRDL attribute definition.

name: ClassVar[str] = 'pulse.real_threshold_policy': The attribute name should be a static field in the attribute classes.

property state_range: tuple[int, int]: The range of state labels that the discriminator policy can discriminate between.

threshold: FloatData

class SampledWaveformAttr(samples, width, sample_time)

Bases: PulseNumericTypedAttr[WaveformType]

An attribute that represents a sampled waveform, which is represented by a real or complex numpy array.

Parameters:

samples¶ (ndarray[complex] | list[complex]) – The samples of the waveform, represented as a numpy array or a list of floats or complex numbers.
width¶ (TimeAttr) – The total width of the waveform, represented as a TimeAttr.
sample_time¶ (TimeAttr) – The time between samples, represented as a TimeAttr.

property associated_type: type[WaveformType]: Returns the associated dialect type.

classmethod get_irdl_definition(): Get the IRDL attribute definition.

property literal_value: ndarray: Returns the samples of the waveform as a numpy array.

name: ClassVar[str] = 'pulse.sampled_waveform': The attribute name should be a static field in the attribute classes.

sample_time: TimeAttr

samples: NumericArrayData

verify()

Check that the attribute parameters satisfy the expected invariants. Raise a VerifyException otherwise.

Return type:: None

width: TimeAttr

class StateMapDictAttr(data)

Bases: Data[immutabledict[int, IntAttr]]

An attribute that represents a mapping from integer state labels to integer data, which for example, could be another state label, or a binary value.

The expected use cases are for mapping state labels from state discrimination onto binary outputs.

Initializes the state map dictionary attribute.

Parameters:: data¶ (Mapping[int, IntAttr | int]) – A mapping from integer state labels to integer attributes associated with those states.

data: DataElement

name: ClassVar[str] = 'pulse.state_map_dict': The attribute name should be a static field in the attribute classes.

classmethod parse_parameter(parser)

Parses the parameters of the attribute, which are expected to be a dictionary representing the state mapping.

Return type:: immutabledict[int, IntAttr]

print_parameter(printer): Prints the parameters of the attribute, which are expected to be a dictionary representing the state mapping.

class TimeAttr(value, unit=TimeUnits.SECOND)

Bases: PulseNumericTypedAttr[TimeType]

An attribute that represents a compile-time constant time.

This attribute intentionally does not specify the precision of the time value, and uses the standard Python precision for its respective type. The representation of the value will be set by the target.

Variables:

value – The time value, which can be a float or an integer.
unit – The time units, which is an instance of the TimeUnits enum.

Parameters:

value¶ (float | int) – The time value in seconds, which can be a float or an integer.
unit¶ (TimeUnits) – The time units, which is an instance of the TimeUnits enum and defaults to seconds if not provided.

property associated_type: type[TimeType]: Returns the associated dialect type.

classmethod from_literal_value(value, unit=TimeUnits.SECOND)

Creates a time attribute from a canonical value in seconds.

Parameters:

value¶ (float | int) – The time value in seconds.
unit¶ (TimeUnits) – The unit used to store the value.

Return type:

TimeAttr

Returns:

A time attribute storing value in the requested unit.

classmethod get_irdl_definition(): Get the IRDL attribute definition.

property literal_value: float | int: Returns the time value in seconds.

name: ClassVar[str] = 'pulse.time_attr': The attribute name should be a static field in the attribute classes.

unit: TimeUnitsData

value: FloatData | IntAttr

value_in_unit(unit)

Returns the time value in the specified units.

Parameters:: unit¶ (TimeUnits) – The units to convert the time value to.
Return type:: float | int
Returns:: The time value in the specified units.

class TimeUnitsData(data)

Bases: Data[TimeUnits]

Data attribute for representing time units in the pulse dialect.

data: DataElement

name: ClassVar[str] = 'pulse.time_units': The attribute name should be a static field in the attribute classes.

classmethod parse_parameter(parser)

Parses the parameters of the attribute, which are expected to be a string representing the time units.

Return type:: TimeUnits

print_parameter(printer)

Prints the parameters of the attribute, which are expected to be a string representing the time units.

Return type:: None

class WeightsAttr(weights)

Bases: WeightsAttr

An attribute that represents a set of weights that can be used in demodulation.

This is expected to be optionally attached to acquire operations.

Variables:: weights – The weights, represented as a numpy array of complex values.
Parameters:: weights¶ (ndarray[complexfloating] | list[complex | float]) – The weights, represented as a numpy array or a list of complex values.

classmethod get_irdl_definition(): Get the IRDL attribute definition.

name: ClassVar[str] = 'pulse.weights': The attribute name should be a static field in the attribute classes.

verify()

Check that the attribute parameters satisfy the expected invariants. Raise a VerifyException otherwise.

Return type:: None

weights: NumericArrayData