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.

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