Quantum Types

Once initialized, Qmod variables reference a quantum object in some state. Quantum types determine the overall number of qubits used to store the object, as well as the interpretation of its state. For example, a quantum object stored on 4 qubits can represent an array of 4 bits, an integer number in the domain 0 to 15, or an array of two fixed-point numbers in the domain [-1.0, -0.5, 0, -0.5]. The type determines which interpretation is the intended one, for example, when evaluating quantum operators.

Qmod has two categories of quantum scalar types - bits and numbers. Qmod also supports quantum array and struct types, which can be arbitrarily nested.

Certain quantum type attributes can be retrieved using field access: var.attr-name. For example, the total number of qubits referenced by variable my_var is obtained by writing my_var.size. The attributes associated with each quantum type are listed below.

Quantum Scalar Types

In Qmod, there are two kinds of scalar quantum types:

qbit represents the states \(|0\rangle\), \(|1\rangle\), or a superposition of the two
qnum represents numbers in some discrete domain - integers or fixed-point reals

When declaring a qnum variable, you can optionally specify its numeric attributes - overall size in bits, whether it is signed, and the number of binary fraction digits.

Syntax

PythonNative

In Python the classes QBit and QNum are used as type hints in the declaration of arguments:

name : QBit

name : QNum [ [ size-int-expr [ , sign-bool-expr , frac-digits-int-expr ] ] ]

The same classes are used to declare local variables:

name = QBit ( " local_name " )

name = QNum ( " name " , [ [ size = ] size-int-expr , [ [ is_signed = ] sign-bool-expr , [ [ fraction_digits = ] frac-digits-int-expr ] )

qbit

qnum [ < size-int-expr [ , sign-bool-expr , frac-digits-int-expr ] > ]

It is recommended to use the SIGNED and UNSIGNED built-in constants instead of True and False respectively when specifying the sign-bool-expr qnum property.

Semantics

Computational-basis encoding of numeric types is big-endian (the most significant bit has the highest index).
size-int-expr determines the overall number of qubits used to store the number, including sign and fraction where applicable.
If sign-bool-expr is True (SIGNED), two's complement is used to represent signed numbers, utilizing the most-significant bit for sign.
frac-digits-int-expr determines the number of least-significant bits representing binary fraction digits.
When only size-int-expr is specified and sign-bool-expr and frac-digits-int-expr are left out, the later two are set to UNSIGNED and 0 (integer) respectively.

Attributes

qbit:
- size: The total number of qubits (always 1).
qnum:
- size: The total number of qubits (including the fraction digits and the sign bit).
- is_signed: Whether the number is signed.
- fraction_digits: The number of fraction digits.

Examples

In the following example, two 4-qubit numeric variables, x and y, are prepared to store the bit string 1101. x is declared with no sign bit and no fraction digits, and therefore its state represents the number 13. y is declared to be signed and have one fraction-digit, and thus, the same bit-level state represents the number -1.5.

PythonNative

from classiq import *


@qfunc
def prepare_1101(qba: Output[QArray[QBit]]):
    allocate(4, qba)
    X(qba[0])
    X(qba[2])
    X(qba[3])


@qfunc
def main(x: Output[QNum[4]], y: Output[QNum[4, SIGNED, 1]]):
    prepare_1101(x)
    prepare_1101(y)

qfunc prepare_1101(output qba: qbit[]) {
  allocate(4, qba);
  X(qba[0]);
  X(qba[2]);
  X(qba[3]);
}

qfunc main(output x: qnum<4>, output y: qnum<4, SIGNED, 1>) {
  prepare_1101(x);
  prepare_1101(y);
}

Numeric Inference Rules

Numeric representation modifiers are optional in the declaration. When left out, the representation attributes of a qnum variable are determined upon its first initialization. Following are the inference rules for these cases:

When the varialbe is initialized with allocate, the size is determined by the num_qubits argument, while sign and fraction-digits are either explicitly specified or default to False (UNSIGNED) and 0 respectively.
When the variable is passed to a function as its output argument with declared type qbit[], the size is determined by the actual array size, while sign and fraction-digits default to False (UNSIGNED) and 0 respectively.
When the variable is passed to a function as its output argument with declared type qnum, the size is determined by the actual size, sign, and fraction-digits of the function's output.
When the variable is initialized on the left of an out-of-place assignment =, the domain of the expression determines its representation properties.
Variables retain their type, including the representation attributes, even after being un-initialized (for example, when occurring on the left side of a bind statement). Subsequent initializations must agree with the specific qnum type.
On the right side of a bind statement (->) the representation attributes of qnum variables must already be known either through declaration, or by previous initialization (and subsequent un-initialization).

Examples

The following example demonstrates the default and explicit numeric interpretation of quantum states. Two variables, a and b, are initialized to some quantum state. a is left with the default unsigned integer interpretation. b is initialized to a superposition of the bit strings 01 and 10 interpreted with a sign bit and one fraction digit. This implies that its domain is [-1.0, -0.5, 0, 0.5] and its value is in a superposition of -1.0 and 0.5. res is accordingly uniformly distributed on the 8 possible addition values.

PythonNative

from classiq import *


@qfunc
def main(a: Output[QNum], b: Output[QNum[2, SIGNED, 1]], res: Output[QNum]) -> None:
    allocate(2, a)  # 'a' is a 2 qubit unsigned int in the domain [0, 1, 2, 3]
    hadamard_transform(a)  # 'a' is in a superposition of all values in its domain
    prepare_state([0, 0.5, 0.5, 0], 0, b)  # 'b' is in superposition of 01 and 10
    res |= a + b

qfunc main(output a: qnum, output b: qnum<2, SIGNED, 1>, output res: qnum) {
  allocate(2, a);
  hadamard_transform(a);
  prepare_state([0, 0.5, 0.5, 0], 0, b);
  res = a + b;
}

Rounding a `qnum` in Qmod

QNum variables may occasionally be declared with too few qubits to represent their intended values. This can occur, for example, when a variable is the result of an arithmetic operation. In such cases, Qmod automatically resolves the issue by adjusting the variable’s possible outcomes. Specifically, it rounds down the numeric values to fit within the allocated number of qubits.

Examples

The following example shows that when allocating a qnum and then performing some arithmetic operation, the values are rounded down:

PythonNative

from classiq import *


@qfunc
def main(x: Output[QNum[3, False, 1]], y: Output[QNum[4, False, 2]]):
    allocate(
        x
    )  # Allocate x as a quantum number with 3 qubits, no sign and 1 fraction digit
    allocate(
        y
    )  # Allocate y as a quantum number with 4 qubits, no sign and 1 fraction digit
    hadamard_transform(x)  # Create a superposition of all possible numbers of x
    y ^= 1.4 * x  # Evaluate y = 1.4 * x

qfunc main(output x: qnum<3, False, 1>, output y: qnum<4, False, 2>) {
    allocate(x);
    allocate(y);
    hadamard_transform(x);
    y ^= 1.4 * x;
}

Output measurements:

state=[{'x': 1.0, 'y': 1.25}: 268,
        {'x': 1.5, 'y': 2.0}: 262,
        {'x': 2.5, 'y': 3.25}: 261,
        {'x': 0.0, 'y': 0.0}: 260,
        {'x': 2.0, 'y': 2.75}: 255,
        {'x': 3.5, 'y': 0.75}: 253,
        {'x': 0.5, 'y': 0.5}: 251,
        {'x': 3.0, 'y': 0.0}: 238]

Notice, for instance, when x = 1.0, the exact product 1.4 is rounded down to 1.25 to fit into y's available qubits.

Quantum arrays

A quantum array is an object that supports indexed access to parts of its state - its elements. Elements are interpreted as values of the specified array element type. A quantum array is one object with respect to its lifetime. Elements of an array cannot be initialized separately or bound separately to other variables. Also, an array's length (the number of elements it represents) is fixed at the time of its initialization and remains constant throughout its lifetime.

Syntax

PythonNative

In Python the class QArray is used as type hints in the declaration of arguments:

name : QArray [ [ element-type [ , length-expr ] ] ]

The same class is used to declare local variables:

name = QArray ( " name " [ , element-type [ , length-expr ] ] )

element-type [ [ length-expr ] ]

Semantics

element_type optionally determines the type of the array elements. Arrays are homogenous, that is, all elements are of the same type. When left unspecified, the type defaults to qbit.
length-expr optionally determines the number of elements in the array. The overall size of the array is its length multiplied by the size of the element type. When the length is unspecified, it is determined upon initialization based on the element size. Similarly, when the size of the element type is not specified, it is inferred upon initialization based on the length. Either the length, or the size of the element type, must be specified in the declaration
The length cannot change throughout the lifetime of an array.

Expressions of quantum array type support the following operations:

Subscript: array-expression [ index-expression ]
Slice: array-expression [ from-index-expression : to-index-expression ]
Length: array-expression . len

Attributes

size: The total number of qubits (= length × element size).
len: The number of array elements.

Examples

In the following example, a Boolean expression of a 3-SAT formula is evaluated over the elements of a qubit array, which is prepared in the state of uniform superposition. Note that bitwise operators are used in this case, but equivalent logical operators and, or, and not (and their respective Python counterparts in package qmod.symbolic) are also supported.

PythonNative

from classiq import qfunc, Output, QArray, QBit, hadamard_transform, bind


@qfunc
def main(x: Output[QArray[QBit, 3]], res: Output[QBit]) -> None:
    allocate(x)
    hadamard_transform(x)
    res |= (x[0] | ~x[1] | ~x[2]) & (~x[0] | x[1] | ~x[2])

qfunc main(output x: qbit[3], output res: qbit) {
  allocate(x);
  hadamard_transform(x);
  res = (x[0] | ~x[1] | ~x[2]) & (~x[0] | x[1] | ~x[2]);
}

The next example demonstrates the initialization of a numeric array using the bind statement (->). Two numeric variables are declared and initialized separately and subsequently bound together to initialize the array. The declared type of these variables is an unsigned integer, but the declared element type of the array is signed. Hence,
the values 6 and 7 are interpreted as -2 and -1, respectively. When executing the resulting quantum program, res is sampled with the value -3 (with probability 1).

PythonNative

from classiq import qfunc, Output, QArray, QNum, SIGNED, bind


@qfunc
def main(res: Output[QNum]) -> None:
    n0 = QNum("n0", 3)
    n0 |= 6
    n1 = QNum("n1", 3)
    n1 |= 7

    n_arr = QArray("n_arr", QNum[3, SIGNED, 0])
    bind([n0, n1], n_arr)

    res |= n_arr[0] + n_arr[1]

qfunc main(output res: qnum) {
  n0: qnum<3>;
  n0 = 6;
  n1: qnum<3>;
  n1 = 7;
  n_arr: qnum<3, SIGNED, 0>[];
  {n0, n1} -> n_arr;
  res = n_arr[0] + n_arr[1];
}

Quantum structs

A quantum struct is an object that supports named access to parts of its state - its fields. Each field corresponds to a slice of the overall object, interpreted according to its declared type. A quantum struct is one object with respect to its lifetime. Fields of a struct cannot be initialized separately or bound separately to other variables.

Quantum structs are typically used to pack and unpack multiple variables, that is, to switch between contexts that treat the object in a generic way (as a qubit array) and in a problem-specific way (to capture expressions over fields).

Syntax

The following syntax is used to define a quantum struct type -

PythonNative

A quantum struct type in Python is defined using a Python class derived from the class QStruct. Fields are declared with type hints, similar to how member variables are declared in a Python dataclass.

qstruct name { field_declarations }

field-declarations is a list of one or more field declarations in the form - name : quantum-type ;.

Semantics

Only quantum types are allowed as field types in a quantum struct.
Quantum structs may be arbitrarily nested, that is, a field of a struct may itself be a struct or a struct array. However, recursive struct types are not allowed.
The overall size of a struct (the number of qubits used to store it) must be known upon declaration. This means that the size of all fields, except at most one, must be fully specified.

Expressions of quantum struct type support field-access operation in the form - struct-expression . field-name.

Attributes

size: The total number of qubits (= the sum of field sizes).

In Qmod's Python embedding, the quantum struct's total number of qubits can be retrieved using the num_qubits class attribute.

Examples

In the following example, quantum struct MyQStruct is defined and subsequently initialized and prepared in a specific state in function main.

PythonNative

from classiq import *


class MyQStruct(QStruct):
    a: QBit
    b: QNum[3]


@qfunc
def main(s: Output[MyQStruct]) -> None:
    allocate(s)
    H(s.a)
    s.b ^= 6

qstruct MyQStruct {
  a: qbit;
  b: qnum<3>;
}

qfunc main(output s: MyQStruct) {
allocate(s);
H(s.a);
s.b ^= 6;
}

The example below demonstrates the common situation where an algorithm alternates between the two views of a quantum state - the structured view with partition into problem variables, and the unstructured view as an array of qubits. The example defines a constraint over two variables, a and b, of different numeric types. It uses Grover-search to find a solution. In the Grover-search algorithm, encapsulated by the function grover_search, the oracle application uses the structured view of the state to evaluate the constraint, while the diffuser is defined in a generic way and uses the qubit array view of the state.

PythonNative

from classiq import *


class MyProblem(QStruct):
    a: QNum[2, UNSIGNED, 2]
    b: QNum[3, UNSIGNED, 3]


@qfunc
def my_problem_constraint(p: Const[MyProblem], res: Permutable[QBit]) -> None:
    res ^= p.a + p.b == 0.625


@qfunc
def main(p: Output[MyProblem]) -> None:
    allocate(p)
    grover_search(2, lambda p: phase_oracle(my_problem_constraint, p), p)

qstruct MyProblem {
  a: qnum<2, UNSIGNED, 2>;
  b: qnum<3, UNSIGNED, 3>;
}

qfunc my_problem_constraint(const p: MyProblem, permutable res: qbit) {
  res ^= (p.a + p.b) == 0.625;
}

qfunc main(output p: MyProblem) {
  allocate(p);
  grover_search(2, lambda(p) {
    phase_oracle(my_problem_constraint, p);
  }, p);
}

Executing this model will sample a state representing a solution to the problem in very high probability. This is an example of an output. Here is an output example:

state={'p': {'a': 0.0, 'b': 0.625}} shots=350
state={'p': {'a': 0.25, 'b': 0.375}} shots=344
state={'p': {'a': 0.5, 'b': 0.125}} shots=306

In Qmod's Python embedding, the size of MyProblem is given by MyProblem.num_qubits:

print(MyProblem.num_qubits)  # 5

Quantum Types

Quantum Scalar Types

Syntax

Semantics

Attributes

Examples

Numeric Inference Rules

Examples

Rounding a qnum in Qmod

Examples

Quantum arrays

Syntax

Semantics

Attributes

Examples

Quantum structs

Syntax

Semantics

Attributes

Examples

Rounding a `qnum` in Qmod