Building Quantum Kernels

A kernel is the unit of quantum computation. This page walks through every building block: defining kernels, allocating and initializing qubits, applying gates, control and adjoint modifiers, custom operations, composing kernels, and parameterization.

Defining a kernel

Decorate a Python function with @qalgora.kernel (in C++, mark it __qpu__). Allocate a single qubit with qalgora.qubit() or a register with qalgora.qvector(n); index it like a list, including q[-1] for the last.

import qalgora

@qalgora.kernel
def kernel(n: int):
    a = qalgora.qubit()          # single qubit
    reg = qalgora.qvector(n)     # register of n qubits
    first, last = reg[0], reg[-1]

Initializing states

Qubits start in |0…0⟩. Allocating a register and applying gates is the runnable way to prepare a state on the reference build:

import qalgora

@qalgora.kernel
def prepare():
    q = qalgora.qvector(2)   # starts in |00⟩
    h(q[0])
    x.ctrl(q[0], q[1])       # now a Bell state

import numpy as np

# pass a normalized amplitude vector as a kernel argument
@qalgora.kernel
def from_vector(vec: list[complex]):
    q = qalgora.qvector(vec)

# precision-agnostic amplitudes (match the simulator's float width)
data = np.array([1, 0, 0, 1], dtype=np.complex128) / np.sqrt(2)

# amplitude preparation inside a kernel
@qalgora.kernel
def from_amplitudes():
    q = qalgora.qvector(2)
    qalgora.amplitudes(q, [0.5, 0.5, 0.5, 0.5])

# hand off a prepared state from one kernel to another
# `bell` is the predefined Bell-state kernel from the examples
state = qalgora.get_state(bell)
@qalgora.kernel
def continue_from(s: qalgora.State):
    q = qalgora.qvector(s)

Applying gates

The standard library currently provides single-qubit gates h, x, y, z, s, t, r1, rx, ry, rz and the two-qubit swap; u3 is a specification interface that can be decomposed into rotation gates. Apply a gate to one qubit or broadcast across a whole register.

@qalgora.kernel
def gates():
    q = qalgora.qvector(3)
    h(q)                 # broadcast Hadamard to every qubit
    x(q[0])              # single qubit
    rx(0.5, q[1])        # parameterized rotation
    # u3(0.1, 0.2, 0.3, q[2])   # specification interface — decompose into rz/ry/rz
    swap(q[0], q[2])

Controlled operations

Any gate takes a .ctrl modifier. One control gives a standard controlled gate (e.g. CNOT from x.ctrl); multiple controls give a multi-controlled gate. Pass the controls as an explicit list [q[0], q[1]] to stay runnable. A qview slice such as q[0:k] denotes the same set of control qubits, but that form depends on slice support in the reference build (see the note below) — prefer the explicit list.

@qalgora.kernel
def controls():
    q = qalgora.qvector(3)
    x.ctrl(q[0], q[1])              # CNOT
    x.ctrl([q[0], q[1]], q[2])     # Toffoli — controls as an explicit list
    rz.ctrl(0.5, q[0], q[1])       # controlled rotation

Adjoint operations

Append .adj to invert a single gate, or qalgora.adjoint to invert a whole sub-kernel — the basis of compute–uncompute patterns.

@qalgora.kernel
def prep(q: qalgora.qview):
    h(q[0]); x.ctrl(q[0], q[1])

@qalgora.kernel
def compute_uncompute():
    q = qalgora.qvector(2)
    prep(q)
    t.adj(q[0])                # inverse of a single gate
    qalgora.adjoint(prep, q)   # inverse of the whole kernel (uncompute)

Custom operations

Register your own unitary from its matrix (given as a flat row-major array), then use it like any built-in gate — including a .ctrl form.

import numpy as np
qalgora.register_operation("custom_x", np.array([0, 1, 1, 0]))   # row-major 2x2

@qalgora.kernel
def use_custom():
    q = qalgora.qvector(2)
    custom_x(q[0])
    custom_x.ctrl(q[0], q[1])

The .ctrl and .adj modifiers currently apply to the built-in gates supported by the reference build; .ctrl/.adj on custom gates is supported in the specification, but is unavailable in the reference build until custom-gate registration is built in.

Building kernels with kernels

Kernels compose: pass qubits as a qalgora.qview (a non-owning reference) and call one kernel from another to build modular circuits.

@qalgora.kernel
def entangle(q0: qalgora.qubit, q1: qalgora.qubit):
    x.ctrl(q0, q1)

@qalgora.kernel
def chain():
    reg = qalgora.qvector(10)
    h(reg[0])
    for i in range(9):
        entangle(reg[i], reg[i + 1])

Parameterized kernels

Accept a list of classical parameters to drive rotation angles — the foundation of every variational algorithm.

@qalgora.kernel
def ansatz(thetas: list[float]):
    q = qalgora.qvector(2)
    ry(thetas[0], q[0])
    ry(thetas[1], q[1])
    x.ctrl(q[0], q[1])