qang — The Qang (qg) Python Framework

Reference implementation and computational toolkit for:

V. H. Monteverde, "The Qang (qg): A Unified Angular-Probability Unit and Metric for Parametric Quantum Circuit Design." ORCID: 0000-0001-8884-4811 · DOI: 10.5281/zenodo.22832150

qang bridges the gap between continuous Bloch-sphere rotation angles (θ ∈ [0, π]) and projective measurement spaces in parameterized quantum circuits (PQCs). It provides native representations for:

• Polar Bias Qang (qg_Z): qg_Z(θ) = cos θ = ⟨σ_z⟩ ∈ [−1, 1].
• Measurement-Outcome Entropy Qang (qg_S): qg_S(θ) = H(cos²(θ/2)) ∈ [0, 1] (Shannon entropy of computational-basis outcomes).
• Native SDK gate classes for Qiskit, Cirq and PennyLane (differentiable in qg_Z), regularized gradient optimizers, shot-noise error propagation, and density matrix/POVM metrics.

What is in the library

Installation

Install the minimal core library (NumPy only):

pip install qang          # from PyPI
pip install "qang @ git+https://github.com/Viny2030/qang.git"   # or from GitHub (latest main)
pip install .             # or from a local clone

pip install "qang[qiskit]" # Native Qiskit gate integration (from a clone: pip install ".[qiskit]")
pip install ".[cirq]"     # Native Cirq gate integration
pip install ".[pennylane]" # Native PennyLane operations (autodiff in qg_Z)
pip install ".[hardware]" # IBM Quantum hardware / calibrated fake backends
pip install ".[ionq]"     # IonQ simulator / hardware scripts (qiskit-ionq)
pip install ".[qec]"      # Surface-code decoding examples (pymatching)
pip install ".[chemistry]" # PySCF/OpenFermion molecules (Linux/macOS or WSL)
pip install ".[all]"      # Everything except chemistry (Qiskit, IBM Runtime, IonQ, pymatching, Cirq, PennyLane, SciPy, Pytest, Matplotlib)
pip install -r requirements.txt  # same as .[all], without installing qang itself

Quickstart

1. Basic Unit Conversions & Inversion

from qang import Qang

# Anchor values
q_zero = Qang.from_angles(0.0, mode="polar")
print(q_zero.value)  # +1.0 (|0>)

q_max_ent = Qang.from_angles(1.5707963, mode="entropic")
print(q_max_ent.value)  # 1.0 (Maximum measurement uncertainty)

# Full Bloch sphere and statevector round-trip
q = Qang.from_angles(theta=0.9, phi=1.1, mode="polar")
bx, by, bz = q.to_bloch_vector()
alpha, beta = q.to_statevector()

# Engineering subunit (milliqang)
print(Qang(0.5).milliqang)  # 500.0 m-qg

2. Qiskit Native Gate Integration

from qang import Qang
from qang.qiskit_gate import FullRQangGate
from qiskit import QuantumCircuit

qc = QuantumCircuit(1, 1)
# Append gate directly parameterized in qg_Z without manual arccos conversion
qc.append(FullRQangGate(Qang(0.5, phi=0.3)), [0])
qc.measure(0, 0)

3. Cirq Native Gate Integration

import cirq
from qang import Qang
from qang.cirq_gate import full_rqang_gate

q = cirq.LineQubit(0)
circuit = cirq.Circuit(
    full_rqang_gate(Qang(0.5, phi=0.3)).on(q),
    cirq.measure(q, key="m")
)

3b. PennyLane: optimize directly in qg_Z

import pennylane as qml
from pennylane import numpy as pnp
from qang.pennylane_gate import rqang

dev = qml.device("default.qubit", wires=1)

@qml.qnode(dev)
def z_expval(qg):
    rqang(qg, wires=0)          # RY(arccos(qg)), differentiable in qg
    return qml.expval(qml.PauliZ(0))

qg = pnp.array(0.3, requires_grad=True)
print(qml.grad(z_expval)(qg))   # 1.0: <Z> = qg_Z exactly

4. Error Propagation & Shot Budgeting

from qang.statistics import propagated_theta_std, confidence_interval_theta

# First-order delta-method uncertainty: invariant across the Bloch sphere (~1/sqrt(N))
std_theta = propagated_theta_std(theta=1.0, n_shots=10000)
ci_lower, ci_upper = confidence_interval_theta(theta_hat=1.0, n_shots=10000, confidence=0.95)
print(f"Theta 95% CI: [{ci_lower:.4f}, {ci_upper:.4f}] rad")

Start here: gates and algorithms in qg

English  ·  Español

notebooks/qang_start_here.ipynb (English; Spanish: qang_inicio_formulacion.ipynb) installs qang from PyPI and walks through the 15 main gates and 14 main algorithms in qg language with qang.formulation: a state is described by its qg values (qg_P =

for every Pauli string) and a gate acts as qg'P = qg{U^dag P U}. Article: manuscript/qang_formulation.pdf (Spanish draft: manuscript/qang_teoria_es.pdf).

from qang import formulation as F
bell = F.apply_gate(F.apply_gate(F.qg_values([1, 0, 0, 0]), F.kron(F.H, F.I2)), F.CX)
# {'II': 1.0, 'XX': 1.0, 'YY': -1.0, 'ZZ': 1.0}   (qang >= 0.5.1)
F.radius_profile(bell)        # [0.0, 0.0]: both qubits at the centre of the sphere  (qang >= 0.6.4)

The local radius (§97). Each qubit lives on a sphere of squared radius r² = qg_X² + qg_Y² + qg_Z² = 2 Tr ρ² − 1 (area 4π r², surface deficit 4π(1 − r²)). One-qubit gates rotate the sphere and keep r; SWAP exchanges radii; CNOT, CZ, iSWAP, Toffoli and Fredkin can move a qubit to the centre. For a pure global state 1 − r² is the one-tangle (known physics: Coffman–Kundu–Wootters, Meyer–Wallach); for a noisy state it mixes entanglement and noise. In a definite-weight state r = |qg_Z|, so after the qg filter (equal T1) the deficit is an entanglement measure read from Z-basis shots alone (§98). On five device noise models (IBM, IonQ) the filter cuts the deficit error 3.2–4.0×, but in-sector gate errors still make product states look entangled (§100). F.algorithm_radii() gives the radius of the readout qubits of the 14 algorithms. The angle in radians separates from the radius, θ = atan2(√(qg_X² + qg_Y²), qg_Z) = arccos(qg_Z / r) (F.direction_from_qg): it is exact under depolarizing noise, where arccos(qg_Z) drifts towards π/2 (§102, §103). Short note: manuscript/qang_radius.pdf (Spanish: manuscript/qang_radio_es.pdf).

Quantum neural networks with and without qang

English  ·  Español

qang.qml (qang >= 0.6.4) trains weight-conserving QNN classifiers and reads every result with qang (the qg filter keeps only the shots that stayed in the input's Hamming-weight sector) and without it. These models are classically simulable: a robustness tool, not a quantum advantage. Every prediction was committed before its run (108 so far in this line, §75–§108: 82 passed, 26 failed, all reported). Note (with the echo calibration, §104–§106): manuscript/qang_qml.pdf (Spanish: manuscript/qang_qml_es.pdf).

Results so far (simulation; RESEARCH_NOTES §75–§98):

Hardware runs are prepared, with explicit cost confirmation, and pending: examples/qnn_hardware_qg.py --mode ionq_qpu (IonQ Forte-1) or --mode ibm, and examples/qec_syndrome_destructive_qg.py --mode ibm (T1 and dephasing from Leung-code syndromes; within 1–4% of the calibration on IBM noise models, §93; the dephasing reads the product mean over the four qubits, §99).

from qang.qml import WeightQNN
m = WeightQNN(n_qubits=5, weight=2, encoding="dual", readout="zz").fit(X_train, y_train)  # 4 features in [-1, 1]
m.score(X_test, y_test, gamma=0.08, qang=True)                      # = noiseless accuracy (equal T1)
m.score(X_test, y_test, gamma=0.08, qang=False)                     # raw readout, biased by T1

Polarized light and geometric phase in qg units

English  ·  Español

qang.polarization and qang.geometric (qang >= 0.6.0): the normalized Stokes parameters are qg values (the Poincare sphere is the Bloch sphere), a lossless Mueller matrix is the qg gate rule, Malus's law reads I = I0 (1 + qg_Z cos 2theta + qg_X sin 2theta)/2, and the geometric phase of a loop at constant qg_Z is (qg_Z - 1)/2 of a turn (Stokes' theorem on the sphere). Note: manuscript/qang_optics.pdf (Spanish: manuscript/qang_optics_es.pdf).

Full Reference Notebook

notebooks/qang_full_reference.ipynb is the single canonical, self-contained walkthrough of the whole project — the Qang class, the Section 4.1 gradient singularity (regularized and benchmarked), mixed states/POVMs, multi-qubit profiles, the native Qiskit and Cirq gates, shot-noise error propagation, Quantum Natural Gradient, a live round-trip against IonQ's cloud simulator, and a closing section that reformulates every result above into concrete, measured speed/cost comparisons (including one negative result, kept in on purpose). Open it directly in Colab with the badge above.

Three further notebooks (in Spanish) cover the research notes:

• notebooks/qang_verificado.ipynb — §1–§19: exact identities, blind spots, noise diagnostics, optimization, knitting, few-shot estimation, QML, control quantization.
• notebooks/qang_avances_colab.ipynb — §20–§93: the qg symmetry witness and filter (chemistry, Hubbard, constrained QAOA), filter vs ZNE, qubit characterization, error correction (Leung code, syndrome tracking), coherence, few-shot estimation, and the recorded IonQ noisy-simulator runs, each with an honest "for / against" reading.
• notebooks/qang_criptografia_colab.ipynb — cryptography line, kept separate: why qg does not apply to post-quantum cryptography, BB84 drift-vs-eavesdropper monitoring (§40) and certified quantum random numbers (§41); companion PDF manuscript/qang_criptografia.pdf.

Testing

The package includes an extensive test suite (1255 tests, run in CI on Python 3.9–3.12) verifying analytical anchors, numerical stability, gradient regularizations, backend fidelity, and every numerical finding quoted in RESEARCH_NOTES.md:

pytest -v

Contributing & Community

We welcome contributions, bug reports, and suggestions!

Issues: Please use the GitHub Issue Tracker to report bugs or request features.

Contributions: See CONTRIBUTING.md for local development and pull request guidelines.

Citation

If you use qang in your research, please cite the paper that defines the unit:

@article{monteverde2026qang,
  title     = {The Qang (qg): A Unified Angular-Probability Unit and Metric for Parametric Quantum Circuit Design},
  author    = {Monteverde, Vicente Humberto},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.22832150}
}

and, for the software itself, the repository: https://github.com/Viny2030/qang.