dense-evolution 8.3.0__py3-none-win_amd64.whl

dense_evolution/__init__.py

@@ -0,0 +1,114 @@
+"""
+Dense-Evolution
+High-performance quantum statevector simulator optimized for NISQ circuits.
+"""
+from .backends.statevector import DenseSVSimulator
+from .circuits.parser import QASMParser, QASMCircuit
+from .circuits.compiler import QuantumTranspiler
+from .noise import (NoiseModel, NoiseSpec, global_depolarizing_channel, amplitude_damping_channel,
+                     phaseflip_channel_exact, cosmic_ray_burst_profile, oscillating_p_eff,
+                     pink_noise_p_eff)
+from .circuits.registry import QuantumHardwareRegistry
+from .circuits.gates import GATES, PARAMETRIC_GATES, GATE_IDS
+from .backends.chunk import Chunk
+# Also bind dense_evolution.chunk as an attribute of this package (the
+# shim at dense_evolution/chunk.py is otherwise only reachable via an
+# explicit `import dense_evolution.chunk` / `from dense_evolution.chunk
+# import ...` -- Python only auto-binds a submodule as a package
+# attribute when something actually imports that exact module path, and
+# `from .backends.chunk import Chunk` above binds backends.chunk, not
+# chunk). Real external code (dashboard_core.hamiltonians) does
+# `de.chunk.SafeMemoryGuard()` -- attribute access, not an import -- so
+# this import's only job is that side effect.
+from . import chunk as chunk
+from .config import set_precision
+from .interop import (
+    from_qiskit, from_pennylane, run_qiskit_circuit, run_pennylane_circuit,
+    noise_model_from_qiskit_backend, to_stim,
+)
+from .solvers.autodiff import circuit_to_energy_fn
+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,
+                          jsd_predictive_zne_density_matrix,
+                          coherence_predictive_zne_density_matrix,
+                          classically_augmented_zne_phaseflip,
+                          richardson_extrapolate_jit, zero_noise_extrapolation_jit,
+                          polynomial_extrapolate_jit, uhlmann_fidelity_jit, zne_density_matrix_jit)
+from .circuits.diagram import plot_circuit
+from .circuits.topology import entangling_layer
+from .physics.observables import (pauli_expectation, pauli_sum_expectation, pauli_hamiltonian_to_matrix,
+                                   pauli_sum_matvec, multiply_pauli_terms,
+                                   pauli_sum_matvec_jax, pauli_sum_expectation_jax, PauliSumOperator)
+from .physics.states import ghz_state
+from .utils.measurement import sample_counts, statevector_fidelity
+from .circuits.qft import qft
+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,
+                                   sp3_dimer_hamiltonian, zincblende_hamiltonian)
+from .solvers.vhd_tb import (MATERIALS as VHD_MATERIALS, sp3s_star_hamiltonian,
+                              direct_gap_at_gamma, band_extrema_along_path)
+from .physics.fermions import majorana_pauli_terms, total_parity_operator, hubbard_hamiltonian_pauli_terms, square_lattice_edges
+from .physics.entropy import partial_trace, von_neumann_entropy, mutual_information, central_charge
+from .circuits.trotter import (pauli_rotation_ops, trotter_evolve_ops, continuous_pulse_evolve,
+                                continuous_dissipative_evolve)
+from .circuits.uccsd import find_excitations, single_excitation_ops, double_excitation_ops
+from .physics.qec import (pauli_commutes, compute_syndrome, erasure_aware_decode, pymatching_decode,
+                           blind_minimum_weight_decode, decode_with_erasure_fallback,
+                           counts_in_intervals_dimension, nearest_coset_decode, erasure_ml_decode,
+                   peeling_decode, union_find_decode, matching_erasure_decode,
+                           estimate_edge_probabilities_from_detection_events)
+
+__version__ = "8.3.0"
+
+__all__ = [
+    "__version__",
+    # Precision -- process-wide JAX config, set explicitly (see config.py)
+    "set_precision",
+    # Backends -- the compute engines
+    "DenseSVSimulator", "MPSSimulator",
+    # Circuits -- representation, parsing, compilation
+    "QASMParser", "QASMCircuit", "QuantumTranspiler",
+    "NoiseModel", "NoiseSpec", "QuantumHardwareRegistry",
+    "GATES", "PARAMETRIC_GATES", "GATE_IDS",
+    "entangling_layer", "qft",
+    "pauli_rotation_ops", "trotter_evolve_ops", "continuous_pulse_evolve",
+    "continuous_dissipative_evolve",
+    "find_excitations", "single_excitation_ops", "double_excitation_ops",
+    # Chunking / anti-OOM
+    "Chunk",
+    # Interop -- Qiskit / PennyLane / STIM bridges
+    "from_qiskit", "from_pennylane", "run_qiskit_circuit", "run_pennylane_circuit",
+    "noise_model_from_qiskit_backend", "to_stim",
+    # Solvers -- VQE/autodiff, tight-binding
+    "circuit_to_energy_fn",
+    "HARRISON_ELEMENTS", "HARRISON_ETA", "sp3_dimer_hamiltonian", "zincblende_hamiltonian",
+    "VHD_MATERIALS", "sp3s_star_hamiltonian", "direct_gap_at_gamma", "band_extrema_along_path",
+    # Mitigation -- Zero-Noise Extrapolation
+    "richardson_extrapolate", "richardson_amplification_factor",
+    "zero_noise_extrapolation", "polynomial_extrapolate",
+    "bounded_exponential_extrapolate",
+    "project_to_physical", "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",
+    "cosmic_ray_burst_profile", "oscillating_p_eff", "pink_noise_p_eff",
+    "richardson_extrapolate_jit", "zero_noise_extrapolation_jit",
+    "polynomial_extrapolate_jit", "uhlmann_fidelity_jit", "zne_density_matrix_jit",
+    # Physics -- states, observables, entropy, fermions, QEC
+    "ghz_state",
+    "pauli_expectation", "pauli_sum_expectation", "pauli_hamiltonian_to_matrix", "pauli_sum_matvec",
+    "multiply_pauli_terms",
+    "pauli_sum_matvec_jax", "pauli_sum_expectation_jax", "PauliSumOperator",
+    "partial_trace", "von_neumann_entropy", "mutual_information", "central_charge",
+    "majorana_pauli_terms", "total_parity_operator", "hubbard_hamiltonian_pauli_terms", "square_lattice_edges",
+    "pauli_commutes", "compute_syndrome", "erasure_aware_decode", "pymatching_decode", "blind_minimum_weight_decode",
+    "decode_with_erasure_fallback", "counts_in_intervals_dimension", "nearest_coset_decode",
+    "erasure_ml_decode", "peeling_decode", "union_find_decode", "matching_erasure_decode",
+    "estimate_edge_probabilities_from_detection_events",
+    # Utils -- drawing, measurement, random circuits
+    "draw_circuit", "plot_circuit", "sample_counts", "statevector_fidelity", "random_circuit",
+]

dense_evolution/autodiff.py

@@ -0,0 +1,10 @@
+"""Backward-compatibility shim -- the real implementation moved to
+dense_evolution.solvers.autodiff as part of the Phase 2 subpackage split
+(see prog.txt). Kept so `from dense_evolution.autodiff import
+circuit_to_energy_fn` (used by external consumers, e.g.
+Dense-Evolution-Discovery) keeps working unchanged. Import from
+dense_evolution.solvers.autodiff directly in new code.
+"""
+from dense_evolution.solvers.autodiff import circuit_to_energy_fn
+
+__all__ = ["circuit_to_energy_fn"]

dense_evolution/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Backends subpackage: the dense statevector and MPS compute engines."""
+from .statevector import DenseSVSimulator
+from .mps import MPSSimulator
+
+__all__ = ["DenseSVSimulator", "MPSSimulator"]

dense_evolution/backends/chunk/__init__.py

@@ -0,0 +1,37 @@
+"""Anti-OOM chunked statevector simulation, split into one file per concern:
+
+    guard.py            SafeMemoryGuard, MemoryPressureError
+    geometry.py         MemoryChunker, get_dynamic_chunk (pure arithmetic, no allocation)
+    kernels.py          the JAX multi-chunk / distributed-chunk compiled kernels
+    circuit_chunker.py  CircuitChunker (single-chunk gate-slicing path)
+    core.py             Chunk, the public anti-OOM wrapper
+
+Re-exported here as a flat namespace identical to the pre-split module: this
+package is imported by path in several places (dense_evolution.chunk's own
+sys.modules self-replacement shim, tools/dashboard/core/system_limits.py) that
+reach for names like `.jax`, `.np`, `.psutil`, and `.HAS_JAX` as module
+attributes, not just the classes -- so `jax`/`np`/`psutil` are imported here
+directly, not just via the submodules that happen to use them.
+"""
+import gc
+import numpy as np
+import jax
+import jax.numpy as jnp
+import psutil
+
+from ._engine_imports import DenseSVSimulator, QuantumTranspiler, GATE_IDS
+from .guard import HAS_JAX, MemoryPressureError, SafeMemoryGuard
+from .geometry import MemoryChunker, get_dynamic_chunk
+from .kernels import (
+    _build_multi_chunk_step, _build_multi_chunk_runner,
+    _build_distributed_chunk_step, _build_distributed_chunk_runner,
+    _compile_multi_chunk_ops,
+)
+from .circuit_chunker import CircuitChunker
+from .core import Chunk, chunk1, chunk2, Chunk2Incrociato
+
+__all__ = [
+    "Chunk", "MemoryChunker", "CircuitChunker", "SafeMemoryGuard",
+    "MemoryPressureError", "get_dynamic_chunk",
+    "chunk1", "chunk2", "Chunk2Incrociato",
+]

dense_evolution/backends/chunk/_engine_imports.py

@@ -0,0 +1,57 @@
+import numpy as np
+
+# ── Flexible import with stub fallback ─────────────────────────────────────────
+# Both except-branches below are for deployment layouts other than the
+# installed package this test suite always runs against (a flat/Colab
+# notebook cell with no `dense_evolution.` prefix, or an incomplete
+# install missing simulator/compiler/gates entirely) -- genuinely
+# unreachable here without artificially breaking sys.path, so excluded
+# from coverage rather than chased with an artificial test.
+try:
+    from simulator import DenseSVSimulator
+    from compiler import QuantumTranspiler  # pragma: no cover
+    from circuits.compiler import _gate_1q_matrix  # pragma: no cover
+    from gates import GATE_IDS  # pragma: no cover
+except ModuleNotFoundError:
+    try:
+        from dense_evolution.simulator import DenseSVSimulator
+        from dense_evolution.compiler import QuantumTranspiler
+        from dense_evolution.circuits.compiler import _gate_1q_matrix
+        from dense_evolution.gates import GATE_IDS
+    except ModuleNotFoundError:  # pragma: no cover
+        class DenseSVSimulator:  # type: ignore[no-redef]
+            def __init__(self, n_qubits, **kwargs):
+                self.n     = n_qubits
+                self.dim   = 2 ** n_qubits
+                self.dtype = np.complex128
+                self.sv    = np.zeros(self.dim, dtype=self.dtype)
+                self.sv[0] = 1.0
+            def run_circuit_jit(self, circuit_slice): pass
+            def memory_mb(self) -> float:
+                return (self.dim * np.dtype(self.dtype).itemsize) / 1_000_000
+
+            def _unavailable(self, name):
+                raise NotImplementedError(
+                    f"DenseSVSimulator stub: {name}() is not implemented here -- this "
+                    "class only exists because the real dense_evolution/JAX modules "
+                    "were not importable in this deployment (see this module's own "
+                    "comment above); it is not a working simulator."
+                )
+
+            def get_probabilities(self): self._unavailable("get_probabilities")
+            def get_statevector(self): self._unavailable("get_statevector")
+            def apply_gate_1q(self, gate, q1): self._unavailable("apply_gate_1q")
+            def apply_gate_2q(self, gate, q1, q2): self._unavailable("apply_gate_2q")
+
+        class QuantumTranspiler:  # type: ignore[no-redef]
+            @staticmethod
+            def transpile(circuit): return circuit
+
+        def _gate_1q_matrix(g_id, param, dtype):  # type: ignore[no-redef]
+            raise NotImplementedError(
+                "_gate_1q_matrix stub: real dense_evolution/JAX not importable in this deployment"
+            )
+
+        GATE_IDS: dict = {}
+
+__all__ = ["DenseSVSimulator", "QuantumTranspiler", "GATE_IDS", "_gate_1q_matrix"]

dense_evolution/backends/chunk/circuit_chunker.py

@@ -0,0 +1,55 @@
+from typing import List, Optional
+
+from ._engine_imports import DenseSVSimulator, QuantumTranspiler
+from .guard import SafeMemoryGuard
+
+__all__ = ["CircuitChunker"]
+
+
+class CircuitChunker:
+    """
+    Transpile a circuit once, then execute it in fixed-size gate-slices so
+    XLA sees the same trace shape on every compilation.
+
+    A SafeMemoryGuard is checked **before every slice** — if RAM drops below
+    15% the current slice is aborted with MemoryPressureError before JAX
+    attempts the allocation.
+
+    Parameters
+    ----------
+    simulator_instance : DenseSVSimulator
+        Physical simulator (sized to safe_qubits, not logical n_qubits).
+    memory_threshold   : float
+        Passed to SafeMemoryGuard.  Default 0.15 (15%).
+    """
+
+    def __init__(
+        self,
+        simulator_instance: Optional[DenseSVSimulator] = None,
+        memory_threshold: float = 0.15,
+    ):
+        self.sim   = simulator_instance
+        self._guard = SafeMemoryGuard(threshold_pct=memory_threshold)
+
+    def split_circuit(self, circuit: List, chunk_size: int = 500) -> None:
+        """
+        Execute *circuit* in slices of *chunk_size* gates.
+
+        Raises
+        ------
+        RuntimeError        if no simulator instance is attached.
+        MemoryPressureError if RAM drops below threshold before a slice.
+        """
+        if self.sim is None:
+            raise RuntimeError(
+                "CircuitChunker: no simulator instance attached. "
+                "Pass simulator_instance= at construction or assign .sim."
+            )
+
+        target: List = QuantumTranspiler.transpile(circuit)
+        n_slices     = (len(target) + chunk_size - 1) // chunk_size
+
+        for idx, i in enumerate(range(0, len(target), chunk_size)):
+            # ── Anti-OOM check before every slice ──────────────────────────────────────────────────────────────
+            self._guard.check(f"slice {idx + 1}/{n_slices}")
+            self.sim.run_circuit_jit(target[i : i + chunk_size])