TenCirPauli

TenCirPauli is TensorCircuit's Rust-native companion for Pauli algebra, Hamiltonian construction, measurement grouping, symmetry reduction, U(1) restricted circuits, deterministic Pauli propagation, and stochastic Pauli-path estimation. The Python package targets TensorCircuit users; TensorCircuit is a required runtime dependency, while the Rust core remains independent of both Python and TensorCircuit.

Install

pip install tencirpauli

Released wheels target CPython 3.9+ on Linux x86_64/aarch64, macOS x86_64/aarch64, and Windows x64. A matching wheel does not require a local Rust toolchain. 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)
        │
        ▼
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

Task Entry point
Pauli algebra PauliWord, PauliOperator
Hamiltonian targets .dense(), .coo(), .csr(), .mvp()
Reusable native MVP .native_mvp_plan()
TensorCircuit backend MVP .backend_mvp_plan(), backend_mvp()
QWC/general grouping .group_commuting()
Z2 symmetry/tapering .find_z2_symmetries(), .taper_z2()
Fixed-particle-number operator U1Sector, .restrict_u1()
Fixed-particle-number circuit U1Circuit
Deterministic Pauli propagation PropagationCircuit (low-level GateTape/PropagationEngine remains available)
Stochastic Pauli-path estimation SPPSCircuit (low-level SPPSEngine remains available)

Common circuit facade

Phase Alpha defines the target Python contract for the three circuit classes. The circuit structure is built once; runtime values are supplied as a parameter vector.

import tencirpauli as tcp

p0 = tcp.Parameter(0)
p1 = tcp.Parameter(1)

circuit = tcp.U1Circuit(nqubits=4, k=2, filled=[0, 1])
circuit.iswap(0, 1, theta=p0)
circuit.rzz(1, 2, theta=2.0 * p1 + 0.1)

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

result = circuit.value_and_grad(
    hamiltonian,
    parameters=[0.2, -0.3],
)
energy = circuit.expectation(hamiltonian, parameters=[0.2, -0.3])

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=p0)
circuit.cnot(0, 1)
circuit.rz(1, theta=p1)

result = circuit.value_and_grad(hamiltonian, parameters=[0.2, -0.3])
energy = circuit.expectation(hamiltonian, parameters=[0.2, -0.3])

Parameter reuse means shared differentiation. A static theta=0.2 is not a differentiable parameter. Concrete NumPy arrays, Python sequences, and concrete JAX arrays are converted to host contiguous float64 vectors for native calls. Native circuit calls are not JAX-traceable; use the backend MVP path when the computation must remain inside a JAX graph.

The current implementation contract and rollout status are recorded in docs/vibe/phase-alpha-spec.md.

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:

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

observable = tcp.PauliOperator.from_terms(3, (("ZII", 1.0),))
engine = tcp.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 Phase Alpha facade adds the corresponding value-only form circuit.expectation(observable, parameters=...); it must agree with value_and_grad(...).value for deterministic execution without computing a gradient.

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; to_dense() and 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.

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(). Numeric QIR produces static gates; direct symbolic references produce parameter slots. 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.

Project links

Data verified by PyPI on Aug 3, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.5.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for refraction-ray from gravatar.com refraction-ray

Credits

Author: refraction-ray

GitHub Statistics

Data verified by PyPI on Aug 3, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License (Apache-2.0)

Requires

Python >=3.9

Provides Extra

benchmark examples quality test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tencirpauli-0.1.0.tar.gz (127.2 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

tencirpauli-0.1.0-cp39-abi3-win_amd64.whl (642.3 kB view details)

Uploaded CPython 3.9+Windows x86-64

tencirpauli-0.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (830.2 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

tencirpauli-0.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (822.6 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

tencirpauli-0.1.0-cp39-abi3-macosx_11_0_arm64.whl (752.4 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

tencirpauli-0.1.0-cp39-abi3-macosx_10_12_x86_64.whl (781.3 kB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file tencirpauli-0.1.0.tar.gz.

File metadata

  • Download URL: tencirpauli-0.1.0.tar.gz
  • Upload date:
  • Size: 127.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tencirpauli-0.1.0.tar.gz
Algorithm Hash digest
SHA256 17ee70d10a0a1a75b6705c2a98bfd272740d8a043330e249ff3da92ddb13fa5a
MD5 90094cf097ce0929266f3117a7e23284
BLAKE2b-256 8276fc4b60e244d8fe9016799754dd50a3b02323524ba69b744a652a52d5132b

See more details on using hashes here.

Provenance

The following attestation bundles were made for tencirpauli-0.1.0.tar.gz:

Publisher: release.yml on tensorcircuit/TenCirPauli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tencirpauli-0.1.0-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: tencirpauli-0.1.0-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 642.3 kB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tencirpauli-0.1.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 eec8dc0563a29b4594e3416688f1186977e53ac0a3e4b2ef16ad303afdcb7b59
MD5 3ef498bb506f279f58b3fc373589fef1
BLAKE2b-256 0263c13af68081b989d0c0dc2388987198d2b4f984f249a56252c708e8c246dc

See more details on using hashes here.

Provenance

The following attestation bundles were made for tencirpauli-0.1.0-cp39-abi3-win_amd64.whl:

Publisher: release.yml on tensorcircuit/TenCirPauli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tencirpauli-0.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for tencirpauli-0.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 bbfffc5d241d13fa5519c9f55fb8aa681e868decf1b51f8536757cfdf92c62ef
MD5 b091f00ad179163357794965a316202c
BLAKE2b-256 4be8b8aac4c7b8d4f976fc5f5f75f25867c193c8b28b31bb13499620f058eec7

See more details on using hashes here.

Provenance

The following attestation bundles were made for tencirpauli-0.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on tensorcircuit/TenCirPauli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tencirpauli-0.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for tencirpauli-0.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 4104d026e0f875099145b5fc3a63948e3ac46126cdfd1a7f10d606ca1143616d
MD5 e66c23d765c8def7af4f3a1d70f46681
BLAKE2b-256 194896f01c6c3fd882d9d2c5501e1841e70a1fddf28ff7c8e85e6f0a20313916

See more details on using hashes here.

Provenance

The following attestation bundles were made for tencirpauli-0.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on tensorcircuit/TenCirPauli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tencirpauli-0.1.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for tencirpauli-0.1.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f6bef24a0f839960b8ba6a6d7da245a8c36547cca1dffe8fd05974c873e788e7
MD5 ce93084ce11dda1e3f83a1aeaa6eb0d0
BLAKE2b-256 f23a32045a342f088ec44340ff3305d184bb19604c253101a61bcaabc560ea22

See more details on using hashes here.

Provenance

The following attestation bundles were made for tencirpauli-0.1.0-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on tensorcircuit/TenCirPauli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tencirpauli-0.1.0-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for tencirpauli-0.1.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 5de93cb6409d473251d3932aa14c335e2074201901729330949e72d34d39542f
MD5 2af804c0afe12d19e8cb9ac6493dd7d1
BLAKE2b-256 7335576557f91eb1e4927d2ad72e02675f96b3a58a3a80cf2d38151e6a4ebd6a

See more details on using hashes here.

Provenance

The following attestation bundles were made for tencirpauli-0.1.0-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on tensorcircuit/TenCirPauli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.5.0

6 files

0.4.1

6 files

0.4.0

6 files

0.3.0

6 files

0.2.0

6 files

This release

0.1.0 This release

6 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page