qat.runtime.expressions module

Variables and Expressions for Quantum Program Runtime Arguments.

Provides a Pydantic-serializable representation of typed variables and expressions (unary/binary) over those variables and literals. Intended for use in variational quantum circuits, software-iterated sweeps, and general runtime argument injection via virtual registers.

This module adds support for different quantum variable types, such as Phase and Frequency, which are important for correctly interpreting their meaning in quantum programs, in addition to standard numeric types. It also supports a variety of unary and binary operators over variables (and literals), allowing for the construction of complex expressions that can be evaluated at runtime. The top-level node for these expressions used in compiled parameterised programs is RuntimeExpression, which wraps an expression tree and includes the necessary context for evaluation. Similarly, the ParameterisedWaveform class allows us to represent waveforms that are parameterised by these expressions, which can be used to represent parameterised analytical pulse shapes in compiled programs.

class BinaryExpression(**data)

Bases: BaseModel

A representation of a binary operation on two nodes, which might be literals, variables, or nested expressions.

Variables:

• operator – The binary operator to apply.

• left – The left operand, which can be a Variable, Literal, or another expression.

• right – The right operand, which can be a Variable, Literal, or another expression.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

evaluate(params=None)

Evaluate the expression, resolving free variables from params.

Parameters:

params (Optional[dict[str, Any]]) – Dictionary of variable values to use for evaluation.

Return type:

Any

left: Node

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

operator: BinaryOp

right: Node

simplify(params=None)

Recursively simplify the expression. If both operands reduce to Literal values, evaluate immediately and return a Literal.

Parameters:

params (Optional[dict[str, Any]]) – Dictionary of variable values used for simplification, optional.

Return type:

Variable | Literal | UnaryExpression | BinaryExpression

class BinaryOp(value)

Bases: str, Enum

Binary operators supported in expressions.

For now, this only includes basic arithmetic operators, but we can easily expand this in the future.

Variables:

• ADD – Addition operator, does a + b

• SUB – Subtraction operator, does a - b

• MUL – Multiplication operator, does a * b

• DIV – Division operator, does a / b

• POW – Power operator, does a ** b

• MOD – Modulo operator, does a % b

ADD = 'add'

DIV = 'div'

MOD = 'mod'

MUL = 'mul'

POW = 'pow'

SUB = 'sub'

class Literal(**data)

Bases: BaseModel

A concrete numeric constant wrapped for use inside an expression tree.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

evaluate(_params=None)

Evaluate the literal, which just returns its value.

Return type:

Any

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

simplify(_params=None)

Does nothing, as a literal is already as simple as it can be.

Return type:

Literal

value: int | float | complex | bool

class ParameterisedWaveform(**data)

Bases: NoExtraFieldsFrozenModel

Represents an analytical waveform that is parameterised by a set of parameters, including runtime expressions.

Variables:

• waveform_type – The type of the waveform, which determines the functional form of the waveform.

• sample_time – The sample time of the waveform in seconds, which determines the time resolution of the waveform.

• amplitude – The amplitude of the waveform, which can be given as a complex number or a runtime expression with evaluated type VariableType.AMPLITUDE.

• width – The width of the waveform, which can be given as a float or a runtime expression that evaluates to a float.

• parameters – A dictionary of additional parameters for the waveform, which can be boolean, float, complex, or runtime expressions.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

amplitude: complex | RuntimeExpression[VariableType.AMPLITUDE]

evaluate(params=None)

Evaluate the parameterised waveform, resolving any runtime expressions from params.

Returns a sampled representation of the waveform.

Parameters:

params (Optional[dict[str, Any]]) – Dictionary of variable values to use for evaluation, optional.

Return type:

SampledWaveform

Returns:

A SampledWaveform instance representing the evaluated waveform.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True, 'ser_json_inf_nan': 'constants', 'use_enum_values': False, 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: dict[str, bool | float | complex | RuntimeExpression]

sample_time: PositiveFloat

waveform_type: type[Waveform]

width: PositiveFloat | RuntimeExpression[VariableType.TIME]

class RuntimeExpression(**data)

Bases: NoExtraFieldsFrozenModel

Represents an expression that can be evaluated at runtime.

It is expected to return a value of a given type when evaluated.

The RuntimeExpression is generically typed to allow it be used for expressions that return different types, e.g. RuntimeExpression[VariableType.TIME] returns this class with an annotation to validate the evaluated type. This can be used in other Pydantic models to enforce expressions of the correct type.

It allows us to represent an expression tree that is unknown at compile time, but can be evaluated at runtime given a set of variable bindings. This is used to allow parameterised runtime arguments in programs for backends that lack runtime argument support. RuntimeExpression will be used within the representation of compiled programs to represent these unknown values.

For example, there might be a runtime expression to represent a variable number of shots in a program, which would only contain a variable node. Similarly, if the frequency of a program is being varied, we can compile a program with the frequency provided at runtime, representing that as a RuntimeExpression containing a variable node for the frequency variable.

A more sophisticated example would be using runtime expressions within variational quantum circuits, where parameters of gates become phases within phase shift operations. After optimizations and compressions, those phase shifts would be represented as expressions over those parameters (in the most simple case, sums of parameters). This allows us to represent the parameterised program in a way that can be compiled and optimized without knowing the parameter values, but still allows us to evaluate the final program with specific parameter values at runtime.

Variables:

• evaluated_type – The type that this expression is expected to evaluate to. This is used for bitcasting the result to the correct type when assembling the program.

• expression – The expression or variable to be evaluated given the runtime variables.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

evaluate(params=None)

Evaluate the expression, resolving free variables from params.

Does not handle details of the evaluated_type, such as bitcasting and legalisation. This is to be done by the consumer.

Parameters:

params (Optional[dict[str, Any]]) – Dictionary of variable values to use for evaluation, optional.

Return type:

Any

Returns:

The result of evaluating the expression with the given params.

evaluated_type: VariableType

expression: Node

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True, 'ser_json_inf_nan': 'constants', 'use_enum_values': False, 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class UnaryExpression(**data)

Bases: BaseModel

An expression that applies a unary operator to a single operand.

Variables:

• operator – The unary operator to apply.

• operand – The operand, which can be a Variable, Literal, or another expression.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

evaluate(params=None)

Evaluate the expression, resolving free variables from params.

Parameters:

params (Optional[dict[str, Any]]) – Optional dict of variable values to use for evaluation.

Return type:

Any

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

operand: Node

operator: UnaryOp

simplify(params=None)

Recursively simplify the expression.

Parameters:

params (Optional[dict[str, Any]]) – Dictionary of variable values used for simplification, optional.

Return type:

Variable | Literal | UnaryExpression | BinaryExpression

class UnaryOp(value)

Bases: str, Enum

Unary operators supported in expressions.

This only includes a basic subset of operators, but we can easily expand this in the future.

Variables:

• NEG – Negation operator, does -x

• ABS – Absolute value operator, does abs(x)

• SIN – Sine operator, does sin(x)

• COS – Cosine operator, does cos(x)

• SQRT – Square root operator, does sqrt(x)

ABS = 'abs'

COS = 'cos'

NEG = 'neg'

SIN = 'sin'

SQRT = 'sqrt'

class Variable(**data)

Bases: BaseModel

A named and typed variable representing a runtime argument.

Variables:

• name – Unique identifier for the variable.

• var_type – The VariableType of this variable.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

evaluate(params=None)

Evaluate the variable, fetching the value from params.

Parameters:

params (Optional[dict[str, Any]]) – Optional dict of variable values to use for evaluation.

Return type:

Any

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

classmethod name_must_be_nonempty(v)

Return type:

str

simplify(params=None)

Simplifies a variable by replacing it with a literal if the value is known.

Parameters:

params (Optional[dict[str, Any]]) – Optional dict of variable values to use for simplification.

Return type:

Variable | Literal

var_type: VariableType

class VariableType(value)

Bases: str, Enum

Supported types for program variables.

This includes standard numeric types, but also domain-specific types such as Phase and Frequency, which are contextually needed to correctly interpret their meaning in quantum programs.

AMPLITUDE = 'amplitude'

BOOL = 'bool'

COMPLEX = 'complex'

FLOAT = 'float'

FREQUENCY = 'frequency'

INT = 'int'

PHASE = 'phase'

TIME = 'time'

cos(operand)

Construct a cos UnaryExpression.

Return type:

UnaryExpression

sin(operand)

Construct a sin UnaryExpression.

Return type:

UnaryExpression

sqrt(operand)

Construct a sqrt UnaryExpression.

Return type:

UnaryExpression