dense-evolution 8.3.0__tar.gz → 8.3.2__tar.gz

{dense_evolution-8.3.0 → dense_evolution-8.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dense-evolution
-Version: 8.3.0
+Version: 8.3.2
 Summary: High-performance quantum simulation toolkit -- Statevector/MPS engines with JIT compilation, noise modeling, VQE, QEC, quantum chemistry, and agent-native tooling
 Author-email: Salvatore Pennacchio <jtatopenn@libero.it>
 License: Business Source License 1.1
@@ -46,6 +46,8 @@ Requires-Dist: qiskit>=1.0.0; extra == "qiskit"
 Provides-Extra: pennylane
 Requires-Dist: pennylane>=0.35.0; extra == "pennylane"
 Requires-Dist: basis_set_exchange>=0.9; extra == "pennylane"
+Provides-Extra: hf
+Requires-Dist: basis_set_exchange>=0.9; extra == "hf"
 Provides-Extra: stim
 Requires-Dist: stim>=1.13.0; extra == "stim"
 Provides-Extra: pymatching
@@ -99,7 +101,7 @@ Requires-Dist: rdkit>=2023.9.1; extra == "docs"
 Dynamic: license-file
 
 <p align="center">
-  <img src="docs/assets/banner.svg" alt="Dense Evolution — NISQ quantum simulation toolkit, JAX-native" width="900">
+  <img src="docs/assets/banner.png" alt="Dense Evolution — NISQ quantum simulation toolkit, JAX-native" width="900">
 </p>
 
 
@@ -111,8 +113,8 @@ Statevector/MPS engines with compilation, noise, VQE, QEC, chemistry, and agent-
 <p align="center">
   <img src="docs/assets/favicon.svg" width="32" alt=""><br>
   <b>Download the Dense Evolution Dashboard (Streamlit)</b><br>
-  <a href="https://github.com/tatopenn-cell/Dense-Evolution/raw/main/tools/installer/install-dashboard.bat">Windows (.bat)</a> &middot;
-  <a href="https://github.com/tatopenn-cell/Dense-Evolution/raw/main/tools/installer/install-dashboard.sh">macOS / Linux (.sh)</a>
+  <a href="https://tatopenn-cell.github.io/Dense-Evolution/assets/installer/install-dashboard.bat">Windows (.bat)</a> &middot;
+  <a href="https://tatopenn-cell.github.io/Dense-Evolution/assets/installer/install-dashboard.sh">macOS / Linux (.sh)</a>
 </p>
 
 [![CI](https://github.com/tatopenn-cell/Dense-Evolution/actions/workflows/ci.yml/badge.svg)](https://github.com/tatopenn-cell/Dense-Evolution/actions/workflows/ci.yml)
@@ -165,6 +167,9 @@ pip install dense-evolution[full]
 pip install dense-evolution[qiskit]
 pip install dense-evolution[pennylane]
 
+# native Hartree-Fock (basis-set data)
+pip install dense-evolution[hf]
+
 # Composer's local kernel (see "Composer" below)
 pip install dense-evolution[composer]
 
@@ -300,9 +305,11 @@ sim.run_chunk(circuit.to_tuples(), chunk_size_gates=500)
 
 - **JIT-fused statevector engine.** No Kronecker-product overhead — stride-sliced linear kernel fusion compiled through JAX XLA, real GPU/TPU dispatch with no code change. [Simulator](https://tatopenn-cell.github.io/Dense-Evolution/api/simulator/) · [MPS backend](https://tatopenn-cell.github.io/Dense-Evolution/api/mps/) for low-entanglement circuits at scale.
 - **Anti-OOM `Chunk` engine.** Circuits too large for one array, split dynamically and sized off the real compute device's own free memory — with disk-backed overflow past even that ceiling. [Chunk guide](https://tatopenn-cell.github.io/Dense-Evolution/api/chunk/).
-- **Real noise, real mitigation.** Stochastic Kraus channels, real-device noise imported from Qiskit backends, and Zero-Noise Extrapolation to correct for it. [Noise](https://tatopenn-cell.github.io/Dense-Evolution/api/noise/) · [Mitigation](https://tatopenn-cell.github.io/Dense-Evolution/api/mitigation/) · [what noise/mitigation/healing each mean](https://tatopenn-cell.github.io/Dense-Evolution/concepts/).
+- **Real noise, real mitigation.** Stochastic Kraus channels, real-device noise imported from Qiskit backends, and Zero-Noise Extrapolation, with the shot budget split optimally across noise factors and a single-qubit Bloch-vector variant that always returns a valid state, to correct for it. [Noise](https://tatopenn-cell.github.io/Dense-Evolution/api/noise/) · [Mitigation](https://tatopenn-cell.github.io/Dense-Evolution/api/mitigation/) · [what noise/mitigation/healing each mean](https://tatopenn-cell.github.io/Dense-Evolution/concepts/).
 - **Differentiable VQE, from scratch.** `circuit_to_energy_fn` is the same JAX-differentiable engine real molecular VQE runs on — real Hartree-Fock Hamiltonians, UCCSD/hardware-efficient ansätze, Adam optimization. [Autodiff](https://tatopenn-cell.github.io/Dense-Evolution/api/autodiff/).
-- **libcint integrals on Windows, macOS and Linux.** `pip install dense-evolution` ships libcint compiled for each system: the full two-electron tensor of ethanol in 6-31G* in 0.32 s. [native_hf](https://tatopenn-cell.github.io/Dense-Evolution/api/native_hf/).
+- **libcint integrals on Windows, macOS and Linux.** `pip install dense-evolution` ships libcint compiled for each system: the full two-electron tensor of ethanol in 6-31G* in 0.32 s. Open-shell molecules with UHF and ROHF (`run_uhf`, `run_cuhf`). [native_hf](https://tatopenn-cell.github.io/Dense-Evolution/api/native_hf/).
+- **Reversible arithmetic.** Register adders, subtraction, comparisons and modular arithmetic up to modular exponentiation, applied as exact basis permutations, and as OPENQASM 2.0 gate circuits (Cuccaro, Draper and Beauregard adders, controlled modular multiplication), up to Shor order finding with one control qubit. [Arithmetic](https://tatopenn-cell.github.io/Dense-Evolution/api/arithmetic/).
+- **Postselection.** Keep the branch where a qubit is found in `|0>`, `|1>`, `|±>` or `|±i>`, with its probability. [Postselection](https://tatopenn-cell.github.io/Dense-Evolution/api/postselect/).
 - **OpenQASM 2.0/3.0, both directions.** A real parser, plus Qiskit/PennyLane interop bridges. [QASM Parser](https://tatopenn-cell.github.io/Dense-Evolution/api/parser/) · [Interop](https://tatopenn-cell.github.io/Dense-Evolution/api/interop/).
 - **Code-agnostic QEC decoding**, Majorana/Jordan-Wigner fermion mapping, from-scratch Hartree-Fock for elements outside PennyLane's own basis set, a traversable-wormhole-inspired teleportation protocol, and real QM/MM region partitioning (ring-safe BFS, Diffuse2Seg-derived relevance propagation) — see the [full API reference](https://tatopenn-cell.github.io/Dense-Evolution/api/) for all of it.
 

{dense_evolution-8.3.0 → dense_evolution-8.3.2}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/assets/banner.svg" alt="Dense Evolution — NISQ quantum simulation toolkit, JAX-native" width="900">
+  <img src="docs/assets/banner.png" alt="Dense Evolution — NISQ quantum simulation toolkit, JAX-native" width="900">
 </p>
 
 
@@ -11,8 +11,8 @@ Statevector/MPS engines with compilation, noise, VQE, QEC, chemistry, and agent-
 <p align="center">
   <img src="docs/assets/favicon.svg" width="32" alt=""><br>
   <b>Download the Dense Evolution Dashboard (Streamlit)</b><br>
-  <a href="https://github.com/tatopenn-cell/Dense-Evolution/raw/main/tools/installer/install-dashboard.bat">Windows (.bat)</a> &middot;
-  <a href="https://github.com/tatopenn-cell/Dense-Evolution/raw/main/tools/installer/install-dashboard.sh">macOS / Linux (.sh)</a>
+  <a href="https://tatopenn-cell.github.io/Dense-Evolution/assets/installer/install-dashboard.bat">Windows (.bat)</a> &middot;
+  <a href="https://tatopenn-cell.github.io/Dense-Evolution/assets/installer/install-dashboard.sh">macOS / Linux (.sh)</a>
 </p>
 
 [![CI](https://github.com/tatopenn-cell/Dense-Evolution/actions/workflows/ci.yml/badge.svg)](https://github.com/tatopenn-cell/Dense-Evolution/actions/workflows/ci.yml)
@@ -65,6 +65,9 @@ pip install dense-evolution[full]
 pip install dense-evolution[qiskit]
 pip install dense-evolution[pennylane]
 
+# native Hartree-Fock (basis-set data)
+pip install dense-evolution[hf]
+
 # Composer's local kernel (see "Composer" below)
 pip install dense-evolution[composer]
 
@@ -200,9 +203,11 @@ sim.run_chunk(circuit.to_tuples(), chunk_size_gates=500)
 
 - **JIT-fused statevector engine.** No Kronecker-product overhead — stride-sliced linear kernel fusion compiled through JAX XLA, real GPU/TPU dispatch with no code change. [Simulator](https://tatopenn-cell.github.io/Dense-Evolution/api/simulator/) · [MPS backend](https://tatopenn-cell.github.io/Dense-Evolution/api/mps/) for low-entanglement circuits at scale.
 - **Anti-OOM `Chunk` engine.** Circuits too large for one array, split dynamically and sized off the real compute device's own free memory — with disk-backed overflow past even that ceiling. [Chunk guide](https://tatopenn-cell.github.io/Dense-Evolution/api/chunk/).
-- **Real noise, real mitigation.** Stochastic Kraus channels, real-device noise imported from Qiskit backends, and Zero-Noise Extrapolation to correct for it. [Noise](https://tatopenn-cell.github.io/Dense-Evolution/api/noise/) · [Mitigation](https://tatopenn-cell.github.io/Dense-Evolution/api/mitigation/) · [what noise/mitigation/healing each mean](https://tatopenn-cell.github.io/Dense-Evolution/concepts/).
+- **Real noise, real mitigation.** Stochastic Kraus channels, real-device noise imported from Qiskit backends, and Zero-Noise Extrapolation, with the shot budget split optimally across noise factors and a single-qubit Bloch-vector variant that always returns a valid state, to correct for it. [Noise](https://tatopenn-cell.github.io/Dense-Evolution/api/noise/) · [Mitigation](https://tatopenn-cell.github.io/Dense-Evolution/api/mitigation/) · [what noise/mitigation/healing each mean](https://tatopenn-cell.github.io/Dense-Evolution/concepts/).
 - **Differentiable VQE, from scratch.** `circuit_to_energy_fn` is the same JAX-differentiable engine real molecular VQE runs on — real Hartree-Fock Hamiltonians, UCCSD/hardware-efficient ansätze, Adam optimization. [Autodiff](https://tatopenn-cell.github.io/Dense-Evolution/api/autodiff/).
-- **libcint integrals on Windows, macOS and Linux.** `pip install dense-evolution` ships libcint compiled for each system: the full two-electron tensor of ethanol in 6-31G* in 0.32 s. [native_hf](https://tatopenn-cell.github.io/Dense-Evolution/api/native_hf/).
+- **libcint integrals on Windows, macOS and Linux.** `pip install dense-evolution` ships libcint compiled for each system: the full two-electron tensor of ethanol in 6-31G* in 0.32 s. Open-shell molecules with UHF and ROHF (`run_uhf`, `run_cuhf`). [native_hf](https://tatopenn-cell.github.io/Dense-Evolution/api/native_hf/).
+- **Reversible arithmetic.** Register adders, subtraction, comparisons and modular arithmetic up to modular exponentiation, applied as exact basis permutations, and as OPENQASM 2.0 gate circuits (Cuccaro, Draper and Beauregard adders, controlled modular multiplication), up to Shor order finding with one control qubit. [Arithmetic](https://tatopenn-cell.github.io/Dense-Evolution/api/arithmetic/).
+- **Postselection.** Keep the branch where a qubit is found in `|0>`, `|1>`, `|±>` or `|±i>`, with its probability. [Postselection](https://tatopenn-cell.github.io/Dense-Evolution/api/postselect/).
 - **OpenQASM 2.0/3.0, both directions.** A real parser, plus Qiskit/PennyLane interop bridges. [QASM Parser](https://tatopenn-cell.github.io/Dense-Evolution/api/parser/) · [Interop](https://tatopenn-cell.github.io/Dense-Evolution/api/interop/).
 - **Code-agnostic QEC decoding**, Majorana/Jordan-Wigner fermion mapping, from-scratch Hartree-Fock for elements outside PennyLane's own basis set, a traversable-wormhole-inspired teleportation protocol, and real QM/MM region partitioning (ring-safe BFS, Diffuse2Seg-derived relevance propagation) — see the [full API reference](https://tatopenn-cell.github.io/Dense-Evolution/api/) for all of it.
 

{dense_evolution-8.3.0 → dense_evolution-8.3.2}/dense_evolution/__init__.py

@@ -31,7 +31,7 @@ from .backends.mps import MPSSimulator
 from .mitigation.zne import (richardson_extrapolate, richardson_amplification_factor,
                           zero_noise_extrapolation, polynomial_extrapolate,
                           bounded_exponential_extrapolate,
-                          project_to_physical, uhlmann_fidelity, zne_density_matrix,
+                          project_to_physical, bloch_zne, bloch_zne_jit, uhlmann_fidelity, zne_density_matrix,
                           jsd_predictive_zne_density_matrix,
                           coherence_predictive_zne_density_matrix,
                           classically_augmented_zne_phaseflip,
@@ -45,6 +45,17 @@ from .physics.observables import (pauli_expectation, pauli_sum_expectation, paul
 from .physics.states import ghz_state
 from .utils.measurement import sample_counts, statevector_fidelity
 from .circuits.qft import qft
+from .circuits.arithmetic import (
+    add_registers, subtract_registers, add_constant,
+    compare_registers, compare_constant,
+    add_registers_mod, add_constant_mod, multiply_add_mod, multiply_mod, power_mod,
+)
+from .circuits.arithmetic_qasm import (
+    cuccaro_adder_qasm, draper_adder_qasm, constant_adder_qasm, modular_constant_adder_qasm,
+    cmult_mod_qasm, controlled_ua_qasm,
+)
+from .circuits.shor import shor_order_finding
+from .circuits.postselect import postselect
 from .circuits.random_circuit import random_circuit
 from .utils.drawing import draw_circuit
 from .solvers.harrison_tb import (ELEMENTS as HARRISON_ELEMENTS, ETA as HARRISON_ETA,
@@ -62,7 +73,7 @@ from .physics.qec import (pauli_commutes, compute_syndrome, erasure_aware_decode
                    peeling_decode, union_find_decode, matching_erasure_decode,
                            estimate_edge_probabilities_from_detection_events)
 
-__version__ = "8.3.0"
+__version__ = "8.3.2"
 
 __all__ = [
     "__version__",
@@ -75,6 +86,12 @@ __all__ = [
     "NoiseModel", "NoiseSpec", "QuantumHardwareRegistry",
     "GATES", "PARAMETRIC_GATES", "GATE_IDS",
     "entangling_layer", "qft",
+    "add_registers", "subtract_registers", "add_constant",
+    "compare_registers", "compare_constant",
+    "add_registers_mod", "add_constant_mod", "multiply_add_mod", "multiply_mod", "power_mod",
+    "cuccaro_adder_qasm", "draper_adder_qasm", "constant_adder_qasm", "modular_constant_adder_qasm",
+    "cmult_mod_qasm", "controlled_ua_qasm", "shor_order_finding",
+    "postselect",
     "pauli_rotation_ops", "trotter_evolve_ops", "continuous_pulse_evolve",
     "continuous_dissipative_evolve",
     "find_excitations", "single_excitation_ops", "double_excitation_ops",
@@ -91,7 +108,7 @@ __all__ = [
     "richardson_extrapolate", "richardson_amplification_factor",
     "zero_noise_extrapolation", "polynomial_extrapolate",
     "bounded_exponential_extrapolate",
-    "project_to_physical", "uhlmann_fidelity", "zne_density_matrix",
+    "project_to_physical", "bloch_zne", "bloch_zne_jit", "uhlmann_fidelity", "zne_density_matrix",
     "jsd_predictive_zne_density_matrix", "coherence_predictive_zne_density_matrix",
     "classically_augmented_zne_phaseflip",
     "global_depolarizing_channel", "amplitude_damping_channel", "phaseflip_channel_exact",

dense_evolution-8.3.2/dense_evolution/circuits/__init__.py

@@ -0,0 +1,37 @@
+"""Circuits subpackage: gate registry, parsing, compilation, topology."""
+from .gates import GATES, PARAMETRIC_GATES, GATE_IDS
+from .parser import QASMParser, QASMCircuit
+from .compiler import QuantumTranspiler
+from .registry import HAS_JAX, NoiseModel, NoiseSpec, QuantumHardwareRegistry
+from .topology import entangling_layer, VALID_PATTERNS
+from .qft import qft
+from .arithmetic import (
+    add_registers, subtract_registers, add_constant,
+    compare_registers, compare_constant,
+    add_registers_mod, add_constant_mod, multiply_add_mod, multiply_mod, power_mod,
+)
+from .arithmetic_qasm import (
+    cuccaro_adder_qasm, draper_adder_qasm, constant_adder_qasm, modular_constant_adder_qasm,
+    cmult_mod_qasm, controlled_ua_qasm,
+)
+from .shor import shor_order_finding
+from .postselect import postselect
+from .random_circuit import random_circuit
+from .trotter import pauli_rotation_ops, trotter_evolve_ops
+
+__all__ = [
+    "GATES", "PARAMETRIC_GATES", "GATE_IDS",
+    "QASMParser", "QASMCircuit",
+    "QuantumTranspiler",
+    "HAS_JAX", "NoiseModel", "NoiseSpec", "QuantumHardwareRegistry",
+    "entangling_layer", "VALID_PATTERNS",
+    "qft",
+    "add_registers", "subtract_registers", "add_constant",
+    "compare_registers", "compare_constant",
+    "add_registers_mod", "add_constant_mod", "multiply_add_mod", "multiply_mod", "power_mod",
+    "cuccaro_adder_qasm", "draper_adder_qasm", "constant_adder_qasm", "modular_constant_adder_qasm",
+    "cmult_mod_qasm", "controlled_ua_qasm", "shor_order_finding",
+    "postselect",
+    "random_circuit",
+    "pauli_rotation_ops", "trotter_evolve_ops",
+]

dense_evolution-8.3.2/dense_evolution/circuits/arithmetic.py

@@ -0,0 +1,241 @@
+"""
+Reversible arithmetic on qubit registers, applied to a statevector.
+
+Every operation here is a bijection f on computational basis states, so its
+unitary is the permutation U|x> = |f(x)> (Vedral, Barenco, Ekert,
+quant-ph/9511018, Sect. II, Eqs. 2-3). It is applied directly as an index
+permutation of the statevector, which is exact and costs one gather over the
+2^n amplitudes. The gate-level circuits from the papers (Cuccaro et al.
+quant-ph/0410184 ripple-carry adder, Draper quant-ph/0008033 transform
+adder) are the references the tests compare against.
+
+A register is a list of qubit indices, least significant bit first. Qubit 0
+is the most significant bit of the statevector index, as everywhere in the
+engine.
+"""
+import numpy as np
+
+from ..config import ensure_x64
+from .registry import HAS_JAX
+
+if HAS_JAX:
+    import jax.numpy as jnp
+    xp = jnp
+else:
+    xp = np
+
+__all__ = ['add_registers', 'subtract_registers', 'add_constant',
+           'compare_registers', 'compare_constant',
+           'add_registers_mod', 'add_constant_mod', 'multiply_add_mod',
+           'multiply_mod', 'power_mod']
+
+_COMPARISONS = {
+    '<': np.less, '>': np.greater, '<=': np.less_equal,
+    '>=': np.greater_equal, '==': np.equal, '!=': np.not_equal,
+}
+
+
+def _register_values(n_qubits, register):
+    idx = np.arange(2 ** n_qubits)
+    value = np.zeros_like(idx)
+    for k, q in enumerate(register):
+        value |= ((idx >> (n_qubits - 1 - q)) & 1) << k
+    return idx, value
+
+
+def _with_register(n_qubits, idx, register, value):
+    out = idx.copy()
+    for k, q in enumerate(register):
+        shift = n_qubits - 1 - q
+        out = (out & ~(1 << shift)) | (((value >> k) & 1) << shift)
+    return out
+
+
+def _check(n_qubits, *registers):
+    used = [q for r in registers for q in r]
+    if len(set(used)) != len(used):
+        raise ValueError("registers must not share qubits")
+    if any(q < 0 or q >= n_qubits for q in used):
+        raise ValueError(f"qubit index out of range for {n_qubits} qubits")
+    if any(len(r) == 0 for r in registers):
+        raise ValueError("registers must not be empty")
+
+
+def _permute(sv, target):
+    if xp is np:
+        sv = np.asarray(sv)
+        out = np.zeros_like(sv)
+        out[target] = sv
+        return out
+    ensure_x64()
+    sv = xp.asarray(sv)
+    return xp.zeros_like(sv).at[target].set(sv)
+
+
+def add_registers(sv, n_qubits, a, b):
+    """
+    |a, b> -> |a, (a + b) mod 2^len(b)>.
+
+    With len(b) = len(a) + 1 the sum never overflows (Vedral et al.,
+    Sect. III.A, Eq. 9); with len(b) = len(a) it is addition modulo 2^n
+    (Cuccaro et al., Sect. 4.1).
+    """
+    _check(n_qubits, a, b)
+    idx, va = _register_values(n_qubits, a)
+    _, vb = _register_values(n_qubits, b)
+    target = _with_register(n_qubits, idx, b, (va + vb) % (1 << len(b)))
+    return _permute(sv, target)
+
+
+def subtract_registers(sv, n_qubits, a, b):
+    """
+    |a, b> -> |a, (b - a) mod 2^len(b)>, the inverse of add_registers.
+
+    If b < a the result is 2^len(b) - (a - b) and, with len(b) = len(a) + 1,
+    its most significant qubit is 1 (Vedral et al., Sect. III.A).
+    """
+    _check(n_qubits, a, b)
+    idx, va = _register_values(n_qubits, a)
+    _, vb = _register_values(n_qubits, b)
+    target = _with_register(n_qubits, idx, b, (vb - va) % (1 << len(b)))
+    return _permute(sv, target)
+
+
+def add_constant(sv, n_qubits, b, c):
+    """
+    |b> -> |(b + c) mod 2^len(b)> for a classical integer c.
+
+    c = 1 is increment, c = -1 decrement. Same operation as Draper's
+    transform adder with classical addend (Sect. 5) and Beauregard's
+    phiADD(c) (quant-ph/0205095, Sect. 2.1).
+    """
+    _check(n_qubits, b)
+    idx, vb = _register_values(n_qubits, b)
+    target = _with_register(n_qubits, idx, b, (vb + int(c)) % (1 << len(b)))
+    return _permute(sv, target)
+
+
+def _flip_if(n_qubits, idx, out, condition):
+    return idx ^ (condition.astype(idx.dtype) << (n_qubits - 1 - out))
+
+
+def _comparison(op):
+    if op not in _COMPARISONS:
+        raise ValueError(f"op must be one of {sorted(_COMPARISONS)}, got {op!r}")
+    return _COMPARISONS[op]
+
+
+def compare_registers(sv, n_qubits, a, b, out, op='<'):
+    """
+    |a, b, z> -> |a, b, z XOR [a op b]>, inputs unchanged.
+
+    op = '<' is the comparator of Cuccaro et al. (Sect. 4.3): the high bit of
+    a - b, which is 1 if and only if a < b. The other comparisons follow by
+    swapping the operands and negating the output qubit.
+    """
+    _check(n_qubits, a, b, [out])
+    idx, va = _register_values(n_qubits, a)
+    _, vb = _register_values(n_qubits, b)
+    return _permute(sv, _flip_if(n_qubits, idx, out, _comparison(op)(va, vb)))
+
+
+def compare_constant(sv, n_qubits, b, c, out, op='<'):
+    """
+    |b, z> -> |b, z XOR [b op c]> for a classical integer c.
+
+    op = '<' is the most significant qubit after the reverse phiADD(c) of
+    Beauregard (quant-ph/0205095, Sect. 2.1, Fig. 4).
+    """
+    _check(n_qubits, b, [out])
+    idx, vb = _register_values(n_qubits, b)
+    return _permute(sv, _flip_if(n_qubits, idx, out, _comparison(op)(vb, int(c))))
+
+
+def _active(n_qubits, idx, controls):
+    on = np.ones(idx.shape, dtype=bool)
+    for q in controls:
+        on &= ((idx >> (n_qubits - 1 - q)) & 1).astype(bool)
+    return on
+
+
+def _check_modulus(N, *registers):
+    if N < 1 or any(N > (1 << len(r)) for r in registers):
+        raise ValueError(f"modulus N={N} must be >= 1 and fit in the register")
+
+
+def add_registers_mod(sv, n_qubits, a, b, N):
+    """
+    |a, b> -> |a, (a + b) mod N> for 0 <= a, b < N (Vedral et al., Sect. III.B,
+    Eq. 10). Basis states with a >= N or b >= N are left unchanged, which
+    keeps the map a permutation.
+    """
+    _check(n_qubits, a, b)
+    _check_modulus(N, a, b)
+    idx, va = _register_values(n_qubits, a)
+    _, vb = _register_values(n_qubits, b)
+    ok = (va < N) & (vb < N)
+    return _permute(sv, _with_register(n_qubits, idx, b, np.where(ok, (va + vb) % N, vb)))
+
+
+def add_constant_mod(sv, n_qubits, b, c, N, controls=()):
+    """
+    |b> -> |(b + c) mod N> for 0 <= b < N, applied only where every control
+    qubit is 1: the doubly controlled phiADD(c)MOD(N) of Beauregard
+    (quant-ph/0205095, Sect. 2.2, Fig. 5). Basis states with b >= N are left
+    unchanged.
+    """
+    _check(n_qubits, b, *([list(controls)] if controls else []))
+    _check_modulus(N, b)
+    idx, vb = _register_values(n_qubits, b)
+    ok = _active(n_qubits, idx, controls) & (vb < N)
+    return _permute(sv, _with_register(n_qubits, idx, b, np.where(ok, (vb + int(c)) % N, vb)))
+
+
+def multiply_add_mod(sv, n_qubits, x, b, a, N, controls=()):
+    """
+    |x, b> -> |x, (b + a*x) mod N> for 0 <= b < N, applied only where every
+    control qubit is 1: CMULT(a)MOD(N) of Beauregard (Sect. 2.3, Fig. 6),
+    built in the paper from n controlled modular additions of 2^i*a mod N
+    (Vedral et al., Sect. III.C). Basis states with b >= N are left unchanged.
+    """
+    _check(n_qubits, x, b, *([list(controls)] if controls else []))
+    _check_modulus(N, b)
+    idx, vx = _register_values(n_qubits, x)
+    _, vb = _register_values(n_qubits, b)
+    ok = _active(n_qubits, idx, controls) & (vb < N)
+    new = (vb + (int(a) % N) * (vx % N)) % N
+    return _permute(sv, _with_register(n_qubits, idx, b, np.where(ok, new, vb)))
+
+
+def multiply_mod(sv, n_qubits, x, a, N, controls=()):
+    """
+    |x> -> |a*x mod N> in place for 0 <= x < N and gcd(a, N) = 1, applied only
+    where every control qubit is 1 (Vedral et al., Sect. II, Eqs. 4-6;
+    Beauregard, Sect. 2.3, Fig. 7). With N = 2^len(x) and odd a this is plain
+    multiplication modulo 2^n. Basis states with x >= N are left unchanged.
+    """
+    _check(n_qubits, x, *([list(controls)] if controls else []))
+    _check_modulus(N, x)
+    if np.gcd(int(a), N) != 1:
+        raise ValueError(f"a={a} and N={N} must be coprime for an in-place multiplication")
+    idx, vx = _register_values(n_qubits, x)
+    ok = _active(n_qubits, idx, controls) & (vx < N)
+    return _permute(sv, _with_register(n_qubits, idx, x, np.where(ok, (int(a) * vx) % N, vx)))
+
+
+def power_mod(sv, n_qubits, x, y, a, N):
+    """
+    |x, y> -> |x, y * a^x mod N> for 0 <= y < N and gcd(a, N) = 1. With y = 1
+    this is the modular exponentiation |x, 1> -> |x, a^x mod N> of Shor's
+    algorithm (Vedral et al., Eq. 1 and Sect. III.D). Basis states with
+    y >= N are left unchanged.
+    """
+    _check(n_qubits, x, y)
+    _check_modulus(N, y)
+    if np.gcd(int(a), N) != 1:
+        raise ValueError(f"a={a} and N={N} must be coprime")
+    idx, vx = _register_values(n_qubits, x)
+    _, vy = _register_values(n_qubits, y)
+    powers = np.array([pow(int(a), int(e), N) for e in range(1 << len(x))])
+    ok = vy < N
+    return _permute(sv, _with_register(n_qubits, idx, y, np.where(ok, (vy * powers[vx]) % N, vy)))