TenCirPauli

Fast, Rust-native Pauli algebra and quantum-circuit primitives for TensorCircuit.

TenCirPauli brings a compact Rust core and a Python-first API to the Pauli-heavy parts of quantum workflows. Build Hamiltonians, group measurements, reduce symmetries, work in fixed-particle-number sectors, and propagate observables without leaving the TensorCircuit ecosystem.

Why TenCirPauli?

Install

python -m pip install tencirpauli

Released wheels target CPython 3.9+ on Linux x86_64/aarch64, macOS x86_64/arm64, and Windows x64. A matching wheel does not require a local Rust toolchain.

Quick start

import tencirpauli as tcp

hamiltonian = tcp.PauliOperator.from_terms(
    2,
    (("XX", 0.5), ("ZI", -1.25j)),
)

matrix = hamiltonian.compile(target="dense")
print(matrix.shape)  # (4, 4)

For a complete circuit example, see examples/ and the TensorCircuit integration guide below.

Built for the ecosystem

TenCirPauli is designed for TensorCircuit users, while its Rust core remains independent of Python and TensorCircuit. The public package is distributed on PyPI with wheels and an sdist; source builds require Rust 1.85+, Cargo, and maturin.

Architecture

TensorCircuit / Python facade
        │
        ├── PauliOperator, grouping, symmetry, backend MVP
        ├── U1Circuit
        ├── PropagationCircuit       (deterministic native facade)
        ├── SPPSCircuit              (stochastic native facade)
        └── Majorana/mapping/charge  (structured Majorana and charge facade)
        │
        ▼
PyO3 batch boundary
        │
        ├── Rust U(1) restricted-state executor
        ├── Rust deterministic Heisenberg propagation executor
        └── Rust stochastic Pauli-path executor

The three circuit facades share Python-level construction, parameter and objective conventions. Their native executors remain independent because they implement different numerical contracts.

Core conventions

External Pauli codes are 0=I, 1=X, 2=Y, 3=Z. Internal packed words use qubit zero as the least-significant bit. Matrix and TensorCircuit computational-basis interfaces use qubit zero as the most-significant bit. Coefficients are complex128-compatible, duplicate Pauli terms are aggregated deterministically, and public arrays are returned read-only where the API promises immutable results.

Main objects

Pauli algebra uses native-backed lazy results by default. Each result remains a lightweight PauliOperator backed by a private Rust handle; term_count, algebra, and matrix/MVP targets do not construct Python PauliTerm objects. Use result.to_dict() for a plain {pauli_string: coefficient} mapping, or access result.terms when the full Python term objects are explicitly needed.

native_result = hamiltonian.commutator(hamiltonian)
weights = native_result.to_dict()
python_terms = native_result.terms  # explicit, cached materialization

Fermion, Boson, Qudit, Hybrid, and Majorana operators follow the same default lazy boundary with family-specific canonical native arrays and to_dict() exports. The exact native coverage and intentionally retained Python fallbacks are listed in docs/vibe/operator-lazy-results.md.

Structured operator algebra

The structured API adds FermionOperator, BosonOperator, QuditWeylOperator, and OperatorSpace for canonical fermionic CAR, symbolic bosonic CCR, hybrid mixed-radix layouts, and uniform-dimension Weyl words. Native compile("native_mvp") executes raw Fermion descriptors by default in the Jordan–Wigner occupation-basis order; call map_fermions("jordan_wigner"), or select parity/Bravyi–Kitaev explicitly, when a mapped Pauli representation is required. Boson cutoffs are required only at finite compilation and use the projected open-boundary Fock convention. The batch OperatorBuilder is available under tencirpauli.advanced.

Majorana and charge workflows add exact MajoranaWord/MajoranaOperator conversion, reusable Jordan–Wigner, parity, and Bravyi–Kitaev occupation mappings, and integer AdditiveCharge/ChargeSector workflows. Charge sectors use exact conservation checks, infer simple finite boson bounds, retain uncharged qudit spectators, and expose guarded dense/COO/CSR plus matrix-free restricted plans. See examples/majorana_charge.py and the design index under docs/vibe/README.md.

Optional chemistry interop imports converged PySCF RHF or UHF results directly into the canonical FermionOperator form, including nuclear repulsion by default. Standard fermionic CAR requires orthonormal orbitals; spin-orbital ordering and the fixed integral convention are explicit adapter inputs. OpenFermion is not required. See examples/quantum_chemistry_pyscf.py after installing pip install "tencirpauli[chemistry]".

CPU-native MVP plans default to storage="lazy"; use storage="eager" when a reusable retained representation fits the budget. A restricted facade starts compact, and mvp_plan(storage="eager"), dense(), coo(), or csr() explicitly authorizes a thread-safe eager transition cache that later facade calls may reuse. Fixed plans never change storage, and apply_into(input_state, output_state) writes into caller-owned non-overlapping complex128 buffers.

Finite targets are selected explicitly with compile("dense" | "coo" | "csr" | "native_mvp" | "backend_mvp"). Dense/COO/CSR and native MVP are available for guarded finite structured layouts. backend_mvp is available for Pauli plans and uniform pure-qudit Weyl plans through direct TensorCircuit NumPy/JAX backend operations; finite boson and mixed-dimension hybrid backend plans raise NotImplementedError rather than falling back silently. See the separate minimal Weyl example in examples/qudit_backend.py and the manual Holstein study in examples/research/holstein/.

Common circuit facade

The circuit facade accepts actual gate angles through theta= and exposes angle_count. Direct gradients are returned in deterministic gate-occurrence order; JAX owns any outer parameter sharing or arithmetic. Circuit facades do not expose public compile plans.

import tencirpauli as tcp

circuit = tcp.U1Circuit(nqubits=4, particle_number=2, occupied=[0, 1])
circuit.iswap(0, 1, theta=0.2)
circuit.rzz(1, 2, theta=-0.5)

hamiltonian = tcp.PauliOperator.from_terms(
    4,
    (("XXII", 0.5), ("YYII", 0.5), ("ZIZI", -0.2)),
)

result = circuit.value_and_grad(hamiltonian)
energy = circuit.expectation(hamiltonian)

The same high-level shape is used by the implemented PropagationCircuit and SPPSCircuit facades:

circuit = tcp.PropagationCircuit(nqubits=4, initial_state=tcp.ZeroState())
circuit.ry(0, theta=0.2)
circuit.cnot(0, 1)
circuit.rz(1, theta=-0.3)

result = circuit.value_and_grad(hamiltonian)
energy = circuit.expectation(hamiltonian)

expectation_jax() accepts scalar JAX values or tracers and uses one host callback plus a first-order custom VJP. Build the circuit inside the traced objective when outer parameters are shared or transformed; TenCirPauli sees only independent gate-angle occurrences. The first JAX route requires jax_enable_x64=True and does not promise higher-order derivatives, jvp, or implicit batching.

The current implementation contract and rollout status are recorded in the docs/vibe index.

Backend MVP

Use the TensorCircuit backend path when JAX/JIT/autodiff or a TensorCircuit backend tensor must remain active:

import numpy as np
import tensorcircuit as tc
import tencirpauli as tcp

tc.set_backend("numpy")
tc.set_dtype("complex128")

h = tcp.PauliOperator.from_terms(2, (("XY", 0.5), ("ZI", -1.25j)))
plan = h.backend_mvp_plan()
state = np.arange(4, dtype=np.complex128)
result = tcp.backend_mvp(plan)(state)

The plan structure is static; coefficients may be supplied as backend tensors where the plan API permits it. This path is distinct from native deterministic or stochastic circuit gradients.

Existing low-level propagation API

The low-level API remains available when an Agent needs explicit tape or engine control:

from tencirpauli import advanced

tape = advanced.GateTape(3)
tape.h(0)
tape.cnot(0, 1)
tape.rz(1, parameter=0)

observable = tcp.PauliOperator.from_terms(3, (("ZII", 1.0),))
engine = advanced.PropagationEngine(tape, observable, max_weight=3)
result = engine.value_and_grad([0.125])

PropagationEngine propagates the observable in reverse Heisenberg order. max_weight=None or a cutoff at least as large as nqubits is exact; a finite cutoff applies deterministic Pauli-weight projection after same-word contributions have been aggregated. The gradient is for the executed frozen sparse trace, not a dense derivative at support-change points.

The circuit facade adds a value-only expectation(observable) terminal; it agrees with value_and_grad(observable).value and does not allocate a gradient buffer.

SPPSEngine provides seeded stochastic value-and-gradient estimates with fixed or adaptive per-term sample budgets. Its result includes standard-error and stopping-proxy metadata and must not be interpreted as a deterministic gradient result.

U(1) semantics

U1Sector and U1Circuit use TensorCircuit computational-basis integer ordering. U1Circuit stores and executes only the fixed-Hamming-weight sector; state()/probability() are restricted-space terminals and state_full()/probability_full() are explicit full-space terminals. The native restricted implementation supports arbitrary-width packed occupation limbs, while full-space materialization remains subject to the public DEFAULT_MAX_BYTES guard.

max_bytes is a coarse guard for cheaply estimated major outputs and workspaces, not a peak-RSS promise. Values below 1 GiB are advisory and are treated as unbounded; at or above 1 GiB, readily estimated major allocations are preflighted. Checked dimensions and arithmetic always apply, and an allocator-level out-of-memory failure remains possible for requests that cannot be estimated cheaply.

TensorCircuit conversion

TensorCircuit is the required ecosystem dependency. User-facing conversion uses target-type classmethods:

native_u1 = tcp.U1Circuit.from_circuit(tc_u1_circuit)
native_propagation = tcp.PropagationCircuit.from_circuit(tc_circuit)

Low-level QIR restoration remains available through from_qir() for concrete numeric gate records. JAX-traced angles belong in a circuit built inside the expectation_jax() objective rather than in a serialized QIR payload. TensorCircuit gate objects are normalized at the boundary to a static logical payload, especially for diagonal gates.

Development

The local quality gate is:

python scripts/check.py --benchmark smoke

The full release checks include Rust formatting, Clippy, Rust tests, Black, Ruff, strict mypy, release maturin installation, Python tests, and benchmark harness smoke tests. TensorCircuit differential tests use the supported TensorCircuit installation and compare ordering, gate conventions, state/observable values, backend MVP results, and native conversion behavior.

See CONTRIBUTING.md, docs/vibe/phase-alpha-spec.md, docs/vibe/semantics.md, and docs/vibe/releasing.md.

License

Apache License 2.0.