ket.expv

Expected value calculation utilities.

This module provides Pauli, Hamiltonian, ExpValue, and the commutator helper for constructing quantum observables and computing their expectation values.

The preferred workflow is to use the obs context manager together with gate functions (X, Y, Z) to build Hamiltonians in a symbolic, Dirac-like notation. The exp_value function then wraps the resulting Hamiltonian into an ExpValue handle.

Example

from ket import *
p = Process()
q = p.alloc(2)
CNOT(H(q[0]), q[1])     # prepare Bell state
with obs():
    # Heisenberg XX + YY + ZZ Hamiltonian
    h = X(q[0])*X(q[1]) + Y(q[0])*Y(q[1]) + Z(q[0])*Z(q[1])
ev = exp_value(h)
print(ev.get())          # -3.0 for the singlet Bell state

Classes ket.expv

ExpValue

A deferred handle for the expectation value of a Hamiltonian.

Hamiltonian

A sum of weighted Pauli operator products representing a quantum observable.

Pauli

Pauli operator for Hamiltonian creation.
class ExpValue(hamiltonian: Hamiltonian | Pauli)

A deferred handle for the expectation value of a Hamiltonian.

Registering an expectation value does not immediately compute it, in live execution mode, the value is computed right away; in batch execution mode it is deferred and becomes available only after get (or a measurement) triggers process execution.

Note

Do not instantiate this class directly. Use exp_value instead.

Example

from ket import *
p = Process()
q = p.alloc(2)
CNOT(H(q[0]), q[1])    # Bell state |Φ+⟩
with obs():
    observable = X(q[0]) * X(q[1]) - Y(q[0]) * Y(q[1])
ev = exp_value(observable)
print(ev.get())        # 2.0 for the Bell state
property value: float | None

The expectation value if available, otherwise None.

In live execution mode this is populated immediately after ExpValue is created. In batch mode it is None until the process executes.

Returns:

The computed expectation value, or None if the process has not yet executed.

get() → float

Retrieve the expectation value, executing the process if necessary.

Blocks until the expectation value is available. In batch execution mode this call triggers process execution.

Returns:

The computed expectation value.

class Hamiltonian(terms: list[Pauli], process: Process)

A sum of weighted Pauli operator products representing a quantum observable.

A Hamiltonian is a linear combination of Pauli terms:

\[H = \sum_k c_k \, P_k\]

where each \(P_k\) is a tensor product of single-qubit Pauli operators (\(X\), \(Y\), \(Z\), or \(I\)) and \(c_k\) is a real or complex scalar coefficient.

Note

Do not instantiate this class directly. Create Hamiltonians by adding Pauli objects together, or by using the obs context manager:

from ket import *
p = Process()
q = p.alloc(3)
with obs():
    # TFIM Hamiltonian: -J Σ Z_i Z_{i+1} - h Σ X_i
    J, h = 1.0, 0.5
    zz = sum(-J * Z(q[i]) * Z(q[i+1]) for i in range(2))
    xx = sum(-h * X(q[i]) for i in range(3))
    H = zz + xx

Supported arithmetic operators:

  • Addition (+): Combine two Hamiltonians or add a scalar constant.

  • Subtraction (-): Subtract a Hamiltonian or scalar.

  • Multiplication (*): Scale by a scalar, or form the operator product with another Hamiltonian/Pauli.

  • Matrix multiplication (@): Full Pauli-algebra operator product.

  • Power (**): Repeated operator product (\(H^n\)).

  • Division (/): Scale by the reciprocal of a scalar.

  • Negation (-H): Negate all coefficients.

class Pauli(pauli: Literal['X', 'Y', 'Z', 'I'] | None, qubits: Quant | None, *, _process: Process | None = None, _map: dict[int, str] | None = None, _coef: float | complex | None = None)

Pauli operator for Hamiltonian creation.

Tip

The preferred way to create a Hamiltonian is by using the obs context manager, which allows you to define a Hamiltonian using a more intuitive syntax. However, you can also create Hamiltonians directly by instantiating this class.

This class represents a Pauli operator for Hamiltonian creation. The primary usage of this class is to prepare a Hamiltonian by adding and multiplying Pauli operators and scalars for calculating the expected value of a quantum state.

Parameters:

  • pauli – Pauli operator type.

  • qubits – Qubits to apply the Pauli operator to.

  • process – For internal usage. Quantum process, default is the process of the given qubits.

  • pauli_list – For internal usage. List of Pauli operators.

  • qubits_list – For internal usage. List of Qubit.

  • coef – For internal usage. Coefficient for the Pauli operator, default is 1.0.

static x(qubits: Quant) → Pauli

Pauli X operator.

Parameters:

qubits – Qubits to apply the Pauli operator to.

static y(qubits: Quant) → Pauli

Pauli Y operator.

Parameters:

qubits – Qubits to apply the Pauli operator to.

static z(qubits: Quant) → Pauli

Pauli Z operator.

Parameters:

qubits – Qubits to apply the Pauli operator to.

static i(qubits: Quant) → Pauli

Pauli I operator.

Parameters:

qubits – Qubits to apply the Pauli I operator to.

Functions ket.expv

commutator(a, b)

Calculate the commutator of two Hamiltonians.
commutator(a: Hamiltonian, b: Hamiltonian) → Hamiltonian

Calculate the commutator of two Hamiltonians.

Computes \([A, B] = AB - BA\) using the Hamiltonian matrix-multiplication operator (@).

The commutator is zero if and only if the two operators share a common eigenbasis, i.e., they can be measured simultaneously. A non-zero commutator implies Heisenberg uncertainty between the corresponding observables.

Example

from ket import *
p = Process()
q = p.alloc()
with obs():
    x = X(q)
    z = Z(q)
xz_comm = commutator(x, z)    # [X, Z] = -2iY
print(xz_comm)                # displays the Pauli Y term
Parameters:

  • a – Left-hand operator.

  • b – Right-hand operator.

Returns:

The commutator \([A, B]\).