Classical types¶

Classical values inside a Qoala program are recorded values — the SDK's classical types build AST nodes rather than holding plain Python values. From the user's perspective, they behave like the analogous Python types (you can +, -, *, / numeric values; you can index arrays), but they emit HIR ops behind the scenes.

Source: euqalyptus/types/classical/.

Numeric types¶

All numeric types live in euqalyptus.types.classical. They share a NumericOperandsOverload mixin that overloads +, -, *, /, ==, !=, <, >, <=, >=. Comparisons return AST nodes (a recorded comparison op), not Python booleans.

Class	Width	Signedness	Description
`Int32`	32	signed	Signed 32-bit integer.
`Int`	32	signed	Alias for `Int32`.
`UInt32`	32	unsigned	Unsigned 32-bit integer.
`Float`	32	—	32-bit floating-point value.
`Double`	32	—	Alias for `Float`. (Yes, despite the name.)
`Bit`	1	unsigned	Single-bit value, typically a measurement outcome.
`Bool`	—	—	Boolean. Available under `euqalyptus.types.classical.booleans`. Not re-exported from the package's `__init__`.

from euqalyptus.types.classical import Int, UInt32, Float

x = Int(10)             # records: %x = qnet integer constant 10
y = Int(20)
z = x + y               # records: %z = qnet add %x, %y
half = Float(0.5)       # records: %half = float constant 0.5

Don't mix types in the same expression

Operating on instances of different fundamental types (e.g. Int + Float) is not currently supported and yields unspecified behavior. Convert explicitly via the constructor of the desired target type.

Constructor patterns¶

Each numeric type accepts either a Python literal or another value of the same type:

a = Int(10)
b = Int(other=a)        # deep copy of a

The other= form creates a new instance with the same value. Useful when the linearity constraints of HIR require a fresh value for every use site. You can also pass immediate= keyword instead of positional.

Arrays¶

euqalyptus.types.classical.arrays exposes:

Class	Element type
`IntArray`	`Int`
`FloatArray`	`Float`

Both inherit from a generic _Array and expose:

array[i] — bracket indexing returns the element type.
array.store(value) — append an element. Otherwise arrays are fixed-length.

from euqalyptus.types.classical import IntArray

xs = IntArray(1, 2, 3, 4)
first = xs[0]            # an Int AST node
xs.store(5)              # appends to xs

The length= keyword can be used to declare a fixed-length empty array:

buf = IntArray(length=10)

`ScopedVar`¶

euqalyptus.types.classical.ScopedVar is the type used by branching constructs that need to "yield" a value out of a conditional block. It's primarily used together with the branching operators. Outside of branching, you won't reach for it directly.

Constants and immediates¶

Pass a Python literal to a numeric type's constructor to materialize a runtime constant:

n = Int(0)
ten = Int(10)
total = n + ten          # adds the two recorded values

Comparisons against immediates are also recorded:

m = qubit.measure()     # m is a Bit
is_one = m == 1          # recorded equality op, not a Python bool

This is how the branching operators end up with rich predicate expressions even though the user wrote them as ordinary Python.

API reference¶

Integers¶

integer ¶

Int `module-attribute` ¶

Int = Int32

Alias of :class:Int32. The recommended name for a 32-bit signed integer.

Int32 ¶

Int32(immediate: int = 0, other: Optional[Self] = None)

Bases: _SignedIntegerType[int]

A 32-bit signed integer.

Constructing an Int32 inside a @QoalaProgram body records a new classical integer value of width 32 and signed signedness. The returned object supports the standard numeric and bitwise operators inherited from :class:NumericOperandsOverload.

Parameters:

Name	Type	Description	Default
`immediate`	`int`	A Python `int` literal that becomes the immediate value of the new integer. Defaults to `0`.	`0`
`other`	`Optional[Self]`	If provided, the new integer is initialized as a copy of `other`'s value. Use this to deep-copy an existing integer into a fresh SSA value.	`None`

Raises:

Type	Description
`NotIntegerArgumentError`	If the positional `immediate` argument is not a Python `int`.

UInt32 ¶

UInt32(immediate: int = 0, other: Optional[Self] = None)

Bases: _UnsignedIntegerType[int]

A 32-bit unsigned integer.

Constructing a UInt32 inside a @QoalaProgram body records a new classical integer value of width 32 and unsigned signedness. The returned object supports the standard numeric and bitwise operators inherited from :class:NumericOperandsOverload.

Parameters:

Name	Type	Description	Default
`immediate`	`int`	A non-negative Python `int` literal that becomes the immediate value of the new integer. Defaults to `0`.	`0`
`other`	`Optional[Self]`	If provided, the new integer is initialized as a copy of `other`'s value.	`None`

Raises:

Type	Description
`NotIntegerArgumentError`	If the positional `immediate` argument is not a Python `int`.
`NotUnsignedIntegerArgumentError`	If the positional `immediate` argument is negative.

Bit ¶

Bases: QoalaClassicalType[int]

A single classical bit (the outcome of a qubit measurement).

A Bit value can only take the values 0 or 1 — the possible outcomes of measuring a qubit. The class deliberately does not support arithmetic operations (such as +): those are not meaningful semantics for a measurement result.

Note

Although the class is exposed in euqalyptus.types.classical.integer, you should rarely construct a Bit yourself. The canonical way to obtain one is to call q.measure() on a qubit, which returns a Bit carrying the measurement outcome.

Booleans¶

booleans ¶

Bool ¶

Bool(immediate: bool = False, other: Optional[Self] = None)

Bases: QoalaBooleanType

A classical boolean value.

Constructing a Bool inside a @QoalaProgram body records a new classical boolean SSA value. Booleans are typically used as branching predicates (the condition of an if_cond(...) block) and support the bitwise operators inherited from :class:BitwiseOperandsOverload.

Parameters:

Name	Type	Description	Default
`immediate`	`bool`	A Python `bool` (or `int`) literal that becomes the immediate value of the new boolean. Defaults to `False`.	`False`
`other`	`Optional[Self]`	If provided, the new boolean is initialized as a copy of `other`.	`None`

Raises:

Type	Description
`NotBooleanArgumentError`	If the positional `immediate` argument is not coercible to a boolean.

Floats¶

floats ¶

Double `module-attribute` ¶

Double = Float

Alias of :class:Float. Provided for consistency with code that distinguishes float and double width; both point at the same 32-bit floating-point type.

Float ¶

Float(immediate: float = 0.0, other: Self = None)

Bases: QoalaFloatingPointType[float]

A 32-bit floating-point value.

Constructing a Float inside a @QoalaProgram body records a new classical floating-point SSA value. The returned object supports the standard numeric operators inherited from :class:NumericOperandsOverload.

Parameters:

Name	Type	Description	Default
`immediate`	`float`	A Python `float` (or `int`) literal that becomes the immediate value of the new float. Defaults to `0.0`.	`0.0`
`other`	`Self`	If provided, the new value is initialized as a copy of `other`.	`None`

Arrays¶

arrays ¶

IntArray ¶

IntArray(*elements: Int | Int32 | int, base: QoalaArray[Int, int] | None = None)

Bases: _Array[Int, int]

An immutable fixed-length array of 32-bit signed integers.

The array is immutable in two senses: its length is fixed at construction time, and the values it stores cannot be reassigned in place. Use :meth:_Array.store to append (which extends the array) and array[i] to read.

Parameters:

Name	Type	Description	Default
`*elements`	`Int \| Int32 \| int`	The initial elements of the array. Each element must be either a Python `int` literal or a Qoala integer-typed value (`Int`, `Int32`, …). Mixing element types — for instance passing a `float` — raises :class:`InvalidArrayArgumentError`.	`()`
`base`	`QoalaArray[Int, int] \| None`	An optional existing :class:`QoalaArray` to shallow-copy from. When provided in addition to positional elements, the resulting array contains the values of `base` followed by the new `elements`.	`None`

Raises:

Type	Description
`InvalidArrayArgumentError`	If any element is not consistent with the integer base type.

FloatArray ¶

FloatArray(*elements: Float | Double | float, base: QoalaArray[Float, float] | None = None)

Bases: _Array[Float, float]

An immutable fixed-length array of 32-bit floating-point values.

Like :class:IntArray, but with single-precision floating-point elements. Length is fixed at construction time and values cannot be reassigned in place; use :meth:_Array.store to append and array[i] to read.

Parameters:

Name	Type	Description	Default
`*elements`	`Float \| Double \| float`	The initial elements of the array. Each element must be either a Python `float` literal or a Qoala floating-point–typed value (`Float`, `Double`). Passing an `int` raises :class:`InvalidArrayArgumentError`.	`()`
`base`	`QoalaArray[Float, float] \| None`	An optional existing :class:`QoalaArray` to shallow-copy from. When provided in addition to positional elements, the resulting array contains the values of `base` followed by the new `elements`.	`None`

Raises:

Type	Description
`InvalidArrayArgumentError`	If any element is not consistent with the floating-point base type.

Classical types¶

Numeric types¶

Constructor patterns¶

Arrays¶

ScopedVar¶

Constants and immediates¶

API reference¶

Integers¶

integer ¶

Int module-attribute ¶

Int32 ¶

UInt32 ¶

Bit ¶

Booleans¶

booleans ¶

Bool ¶

Floats¶

floats ¶

Double module-attribute ¶

Float ¶

Arrays¶

arrays ¶

IntArray ¶

FloatArray ¶

`ScopedVar`¶

Int `module-attribute` ¶

Double `module-attribute` ¶