dense-evolution 8.3.0__py3-none-win_amd64.whl

dense_evolution/circuits/uccsd.py

@@ -0,0 +1,275 @@
+"""
+Native (PennyLane-free) UCCSD excitation circuits.
+
+UCCSD's single/double fermionic excitation generators
+(a_p^dagger a_q - h.c., a_p^dagger a_q^dagger a_r a_s - h.c.) were
+previously only reachable through PennyLane's own FermionicSingleExcitation/
+FermionicDoubleExcitation decomposition (see dashboard/core/vqe.py's
+_uccsd_tape_to_qasm) -- not because a native circuit is theoretically
+impossible, but because deriving the exact (non-Trotterized) circuit
+identity requires real derivation, not just wiring PennyLane through.
+
+This module IS that derivation, done directly against
+dense_evolution.physics.fermions.majorana_pauli_terms (already-verified
+Jordan-Wigner mapping) rather than against PennyLane's internals, and
+every circuit identity below was verified against scipy.linalg.expm of
+the exact generator matrix (independently reconstructed from raw
+Jordan-Wigner ladder operators, not from PennyLane) before being written
+here -- see tests/unit/test_uccsd.py.
+
+Single excitation (any orbital distance): exact closed form, always.
+G_pq = a_p^dagger a_q - a_q^dagger a_p decomposes (via
+a_p^dagger=(chi_X(p)-i*chi_Y(p))/2) into exactly 2 Pauli strings that
+share the Jordan-Wigner Z-string between p and q and differ only by an
+X<->Y swap at p and q. This is the standard "Givens rotation" generator
+(G^2 = 2I): exact circuit is CNOT(p,q), fold each Z-string qubit's
+parity onto p via CNOT(k,p), CRY(2*theta, control=q, target=p), then
+undo. Verified for adjacent and long-Z-string pairs alike (any p<q).
+
+Double excitation: exact closed form when the occupied pair (p,q) is
+adjacent (q=p+1) AND the virtual pair (r,s) is adjacent (s=r+1) -- the
+gap between q and r (HOMO-LUMO gap) can be any length, no restriction.
+This is the case dashboard/core/vqe.py's UCCSD ansatz always produces
+for a 2-occupied/2-virtual active space (e.g. H2 in a minimal basis),
+and generally whenever qml.qchem.excitations pairs consecutive occupied
+orbitals with consecutive virtual orbitals. G_pqrs (8 Pauli terms)
+reduces to a clean 2-level coupling between |p=0,q=1,r=1,s=1,...> and
+its bit-flip, realized via a CNOT fan (mirroring the p,q,r,s pattern
+onto q) plus a triple-controlled RY (Toffoli-mediated, 2 ancilla
+qubits, always returned to |0>).
+
+For a double excitation where the occupied pair or the virtual pair is
+itself non-adjacent (occurs for active spaces with 3+ occupied or 3+
+virtual orbitals, e.g. LiH/BeH2), the same closed-form Z-string folding
+used for single excitations does NOT carry over cleanly (verified
+directly: the naive fold leaves genuine leakage, not just an
+unsimplified-but-correct circuit) -- deriving a comparably compact
+closed form for that case is unresolved, so double_excitation_ops falls
+back to per-term exponentiation of the 8 Pauli terms via
+dense_evolution.circuits.trotter.pauli_rotation_ops for that specific
+case, applied sequentially in a fixed term order.
+
+That fallback turned out to be exact too, not a Trotter approximation:
+verified exhaustively (every computational basis state, several p<q<r<s
+choices including non-adjacent pairs, theta up to pi) against
+scipy.linalg.expm of the exact generator matrix, to floating-point
+precision (~1e-15) at every theta tested, not just small theta the way
+a genuine first-order Trotter error would show. The 8 terms don't
+commute as operators on the full Hilbert space, but the generator only
+ever couples two basis states for any fixed setting of the qubits it
+doesn't act on (same structure as the closed-form case), and within
+that 2-dimensional invariant subspace the per-term exponentials
+apparently compose without error -- not derived from first principles
+here, just confirmed by the exhaustive check above. Only the GATE COUNT
+differs from the closed form, not correctness.
+"""
+from typing import List, Tuple
+
+from .trotter import pauli_rotation_ops
+
+__all__ = ['find_excitations', 'single_excitation_ops', 'double_excitation_ops']
+
+
+def find_excitations(electrons: int, n_qubits: int):
+    """
+    Enumerate spin-conserving single/double excitation index tuples for
+    a Hartree-Fock reference with the given electron count -- pure
+    classical combinatorics (occupied = orbitals [0, electrons), virtual
+    = the rest, even index = spin-up, odd = spin-down under the standard
+    Jordan-Wigner interleaved spin-orbital ordering), no quantum
+    computation involved. Verified to reproduce
+    qml.qchem.excitations(electrons, n_qubits) exactly across several
+    (electrons, n_qubits) pairs -- see tests/unit/test_uccsd.py -- kept
+    here so finding *which* excitations exist doesn't need PennyLane
+    installed any more than building their circuits does.
+
+    Returns (singles, doubles): singles is a list of [p, q] (p occupied,
+    q virtual, same spin); doubles is a list of [p, q, r, s] with
+    p<q both occupied, r<s both virtual, total spin conserved.
+    """
+    occupied = list(range(electrons))
+    virtual = list(range(electrons, n_qubits))
+    singles = [[p, q] for p in occupied for q in virtual if p % 2 == q % 2]
+    doubles = []
+    for i, p in enumerate(occupied):
+        for q in occupied[i + 1:]:
+            for j, r in enumerate(virtual):
+                for s in virtual[j + 1:]:
+                    if (p % 2 + q % 2) == (r % 2 + s % 2):
+                        doubles.append([p, q, r, s])
+    return singles, doubles
+
+
+# ── Pauli-string algebra (needed only for the per-term fallback path's
+# generator decomposition -- the closed-form circuits below are pure
+# combinatorial gate templates and never call this at all) ──────────────
+
+_MUL = {
+    ('I', 'I'): ('I', 1), ('I', 'X'): ('X', 1), ('I', 'Y'): ('Y', 1), ('I', 'Z'): ('Z', 1),
+    ('X', 'I'): ('X', 1), ('Y', 'I'): ('Y', 1), ('Z', 'I'): ('Z', 1),
+    ('X', 'X'): ('I', 1), ('Y', 'Y'): ('I', 1), ('Z', 'Z'): ('I', 1),
+    ('X', 'Y'): ('Z', 1j), ('Y', 'X'): ('Z', -1j),
+    ('Y', 'Z'): ('X', 1j), ('Z', 'Y'): ('X', -1j),
+    ('Z', 'X'): ('Y', 1j), ('X', 'Z'): ('Y', -1j),
+}
+
+
+def _pauli_mul_term(term_a, term_b):
+    ca, da = term_a
+    cb, db = term_b
+    phase = ca * cb
+    out = {}
+    for q in set(da) | set(db):
+        la, lb = da.get(q, 'I'), db.get(q, 'I')
+        letter, ph = _MUL[(la, lb)]
+        phase *= ph
+        if letter != 'I':
+            out[q] = letter
+    return (phase, out)
+
+
+def _psum_mul(terms_a, terms_b):
+    return [_pauli_mul_term(ta, tb) for ta in terms_a for tb in terms_b]
+
+
+def _psum_scale(terms, s):
+    return [(c * s, d) for c, d in terms]
+
+
+def _psum_combine(terms):
+    acc = {}
+    for c, d in terms:
+        key = tuple(sorted(d.items()))
+        acc[key] = acc.get(key, 0) + c
+    return [(c, dict(key)) for key, c in acc.items() if abs(c) > 1e-12]
+
+
+def _chi(mode_index, n_qubits):
+    from ..physics.fermions import majorana_pauli_terms
+    return majorana_pauli_terms(mode_index, n_qubits)[1]
+
+
+def _a_dagger(p, n_qubits):
+    return [(0.5, _chi(2 * p + 1, n_qubits)), (-0.5j, _chi(2 * p + 2, n_qubits))]
+
+
+def _a(p, n_qubits):
+    return [(0.5, _chi(2 * p + 1, n_qubits)), (0.5j, _chi(2 * p + 2, n_qubits))]
+
+
+def _double_excitation_generator(p, q, r, s, n_qubits):
+    """8 Pauli terms of a_p^dagger a_q^dagger a_r a_s - h.c. (JW-mapped).
+    Used only by the per-term fallback path -- verified against direct
+    fermionic ladder operators in tests/unit/test_uccsd.py."""
+    term1 = _psum_mul(_psum_mul(_a_dagger(p, n_qubits), _a_dagger(q, n_qubits)),
+                       _psum_mul(_a(r, n_qubits), _a(s, n_qubits)))
+    term2 = _psum_mul(_psum_mul(_a_dagger(s, n_qubits), _a_dagger(r, n_qubits)),
+                       _psum_mul(_a(q, n_qubits), _a(p, n_qubits)))
+    return _psum_combine(term1 + _psum_scale(term2, -1))
+
+
+# ── Single excitation: exact closed form, any p<q ───────────────────────
+
+def single_excitation_ops(p: int, q: int, theta: float) -> List[Tuple]:
+    """
+    Exact circuit for exp(theta * (a_p^dagger a_q - a_q^dagger a_p)),
+    the UCCS single-excitation unitary, for ANY p < q (any Jordan-Wigner
+    Z-string length in between) -- no Trotter error, ever.
+
+    Gate count: 2*(1 + (q-p-1)) CX + 1 CRY (itself 2 CX + 2 RY), so
+    2*(q-p) + 2 CX total.
+    """
+    if not p < q:
+        raise ValueError(f"single_excitation_ops requires p < q, got p={p}, q={q}")
+    inter = list(range(p + 1, q))
+    ops: List[Tuple] = []
+    ops.append(('cx', p, q))
+    for k in inter:
+        ops.append(('cx', k, p))
+    ops.extend(_cry_ops(2 * theta, control=q, target=p))
+    for k in reversed(inter):
+        ops.append(('cx', k, p))
+    ops.append(('cx', p, q))
+    return ops
+
+
+def _cry_ops(theta, control, target):
+    """CRY(theta) from native RY+CX: RY(theta/2)_t ; CX(c,t) ; RY(-theta/2)_t ; CX(c,t)."""
+    return [
+        ('ry', target, theta / 2),
+        ('cx', control, target),
+        ('ry', target, -theta / 2),
+        ('cx', control, target),
+    ]
+
+
+# ── Double excitation ────────────────────────────────────────────────────
+
+def double_excitation_ops(p: int, q: int, r: int, s: int, theta: float,
+                           ancilla1: int = None, ancilla2: int = None) -> List[Tuple]:
+    """
+    Circuit for exp(theta * (a_p^dagger a_q^dagger a_r a_s - h.c.)), the
+    UCCD double-excitation unitary, for p < q < r < s.
+
+    Exact closed form (no Trotter error) when ancilla1/ancilla2 are both
+    given AND the occupied pair is adjacent (q == p+1) AND the virtual
+    pair is adjacent (s == r+1) -- the gap between q and r can be any
+    length. This is what qml.qchem.excitations always produces for a
+    2-occupied/2-virtual active space, and sometimes for larger ones.
+
+    Falls back to per-term exponentiation of the 8-term Pauli
+    decomposition whenever no ancillas are given, or the pairs aren't
+    adjacent -- verified exact (not an approximation), just more gates
+    than the closed form; see the module docstring for why the closed
+    form doesn't generalize to a non-adjacent occupied or virtual pair
+    yet.
+
+    ancilla1, ancilla2 : two qubits that MUST be |0> on entry and are
+    guaranteed returned to |0> on exit -- only touched by the
+    closed-form path (never referenced by the per-term fallback), so
+    the same two ancillas can be reused across every double excitation
+    in an ansatz. Omit both (leave as None) to force the ancilla-free
+    per-term path unconditionally -- e.g. when the caller's qubit
+    register has no spare qubits to offer.
+    """
+    if not p < q < r < s:
+        raise ValueError(f"double_excitation_ops requires p<q<r<s, got {p},{q},{r},{s}")
+
+    have_ancillas = ancilla1 is not None and ancilla2 is not None
+    if have_ancillas and q == p + 1 and s == r + 1:
+        return _double_excitation_ops_closed_form(p, q, r, s, theta, ancilla1, ancilla2)
+    return _double_excitation_ops_per_term(p, q, r, s, theta)
+
+
+def _double_excitation_ops_closed_form(p, q, r, s, theta, a1, a2) -> List[Tuple]:
+    ops: List[Tuple] = []
+    ops.append(('cx', q, s))
+    ops.append(('cx', q, r))
+    ops.append(('cx', q, p))
+    ops.append(('x', p))
+    ops.extend(_toffoli_ops(p, r, a1))
+    ops.extend(_toffoli_ops(a1, s, a2))
+    ops.extend(_cry_ops(-2 * theta, control=a2, target=q))
+    ops.extend(_toffoli_ops(a1, s, a2))
+    ops.extend(_toffoli_ops(p, r, a1))
+    ops.append(('x', p))
+    ops.append(('cx', q, p))
+    ops.append(('cx', q, r))
+    ops.append(('cx', q, s))
+    return ops
+
+
+def _toffoli_ops(c1, c2, t):
+    from .compiler import QuantumTranspiler
+    return QuantumTranspiler.decompose_toffoli(c1, c2, t)
+
+
+def _double_excitation_ops_per_term(p, q, r, s, theta) -> List[Tuple]:
+    n_qubits = s + 1
+    terms = _double_excitation_generator(p, q, r, s, n_qubits)
+    ops: List[Tuple] = []
+    for coeff, pauli_dict in terms:
+        real_part = (coeff / 1j).real
+        angle = -theta * real_part
+        ops.extend(pauli_rotation_ops(pauli_dict, angle))
+    return ops

dense_evolution/cli.py

@@ -0,0 +1,199 @@
+"""
+`dense-evolution` console script (see pyproject.toml [project.scripts]).
+
+Three real subcommands:
+  serve             starts the local Composer kernel (local_site.app.server)
+                    that the published Composer page (docs/composer.md)
+                    talks to.
+  offline-composer  downloads the real published Composer page (the same
+                    HTML Github Pages serves, not a hand-rolled copy) plus
+                    the same-origin assets it references, into a local
+                    folder -- so it opens via file:// with no internet at
+                    all, while still talking to the local kernel above.
+  mcp               starts the dense_evolution_mcp MCP server (mcp_server/),
+                    a thin adapter that exposes the same Composer kernel
+                    endpoints as MCP tools for an agent to call directly.
+                    Requires `serve` running separately -- this process
+                    talks to that kernel over HTTP, it doesn't embed it.
+
+fastapi/uvicorn/pydantic (composer) and mcp/httpx (mcp) are optional
+extras, not core dependencies -- imported here, inside their own command
+branch, not at module level, so `import dense_evolution` itself never
+requires them.
+"""
+
+import sys
+
+USAGE = """usage: dense-evolution <command>
+
+commands:
+  serve                    Start the local Composer kernel (http://127.0.0.1:8800)
+                           that the published Composer page (docs/composer.md)
+                           connects to.
+  offline-composer [DEST]  Download the real published Composer page and its
+                           assets into DEST (default: ./composer-offline) so
+                           it works via file:// with no internet.
+  mcp                      Start the dense_evolution_mcp MCP server (stdio
+                           transport) so an agent can call the Composer
+                           kernel's endpoints directly. Requires `serve`
+                           running separately (default http://127.0.0.1:8800,
+                           override with DENSE_EVOLUTION_KERNEL_URL).
+
+Requires the composer extra: pip install dense-evolution[composer]
+The mcp command requires the mcp extra: pip install dense-evolution[mcp]
+"""
+
+COMPOSER_PAGE_URL = "https://tatopenn-cell.github.io/Dense-Evolution/composer/"
+
+
+def _require_composer_extra():
+    try:
+        import fastapi, uvicorn, pydantic  # noqa: F401
+    except ImportError as exc:
+        print(
+            "dense-evolution needs the composer extra:\n"
+            "  pip install dense-evolution[composer]\n"
+            f"(missing: {exc.name})",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def _cmd_serve():
+    _require_composer_extra()
+    from local_site.app.server import main as serve_main
+    serve_main()
+
+
+def _require_mcp_extra():
+    try:
+        import mcp, httpx  # noqa: F401
+    except ImportError as exc:
+        print(
+            "dense-evolution needs the mcp extra:\n"
+            "  pip install dense-evolution[mcp]\n"
+            f"(missing: {exc.name})",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def _cmd_mcp():
+    _require_mcp_extra()
+    from mcp_server.server import main as mcp_main
+    mcp_main()
+
+
+def _cmd_offline_composer(dest: str):
+    """Mirrors COMPOSER_PAGE_URL into `dest`: the page itself plus every
+    same-origin <link href>/<script src> it references (Material's shared
+    theme CSS/JS bundle, the Composer-specific app.js/style.css), each
+    saved at the same relative path it already uses on the live site --
+    mkdocs/Material already generate those as page-relative, precisely so
+    a subtree like this stays self-consistent once copied elsewhere. Not a
+    full recursive mirror (fonts referenced only from inside a CSS url()
+    are not followed -- Material falls back to system fonts without them,
+    a cosmetic gap, not a functional one): scoped to what the page's own
+    <head>/<body> actually link to, which is everything the Composer UI
+    itself needs to run."""
+    import os
+    import urllib.request
+    from html.parser import HTMLParser
+    from urllib.parse import urljoin, urlparse
+
+    class _AssetFinder(HTMLParser):
+        def __init__(self):
+            super().__init__()
+            self.assets = []
+
+        def handle_starttag(self, tag, attrs):
+            attrs = dict(attrs)
+            # mkdocs Material's <head> has plenty of other <link> rels
+            # (canonical, prev, next, preconnect, ...) that point at other
+            # *pages* (directories, not files) or aren't fetchable assets
+            # at all -- verified directly against the real page: following
+            # rel="prev"/"next" tried to write a file at a directory-shaped
+            # path and failed with a permission error. Only stylesheet/icon
+            # links are real same-origin files worth mirroring.
+            if tag == "link" and attrs.get("href") and attrs.get("rel") in ("stylesheet", "icon"):
+                self.assets.append(attrs["href"])
+            elif tag == "script" and attrs.get("src"):
+                self.assets.append(attrs["src"])
+            elif tag == "img" and attrs.get("src"):
+                self.assets.append(attrs["src"])
+
+    print(f"Scarico {COMPOSER_PAGE_URL} ...")
+    with urllib.request.urlopen(COMPOSER_PAGE_URL, timeout=30) as resp:
+        html_bytes = resp.read()
+    html_text = html_bytes.decode("utf-8", errors="replace")
+
+    parser = _AssetFinder()
+    parser.feed(html_text)
+
+    page_url = urlparse(COMPOSER_PAGE_URL)
+    base_origin = f"{page_url.scheme}://{page_url.netloc}"
+    # mkdocs generates every relative link (../assets/...) relative to the
+    # SITE root, not to whatever folder happens to hold index.html -- so
+    # the page itself has to be saved at the same depth under `dest` it
+    # already has under the site root (site_root_path stripped from its
+    # own path leaves "composer/"), or its own "../assets/..." references
+    # end up pointing one directory above `dest` instead of inside it.
+    # site_root_path is derived from COMPOSER_PAGE_URL itself (this
+    # project's one fixed, known URL), not guessed from each asset URL.
+    site_root_path = page_url.path.rsplit("composer/", 1)[0]
+
+    def _relative_to_site_root(url: str) -> str:
+        path = urlparse(url).path
+        if path.startswith(site_root_path):
+            path = path[len(site_root_path):]
+        return path.lstrip("/")
+
+    os.makedirs(dest, exist_ok=True)
+    page_relative_path = _relative_to_site_root(COMPOSER_PAGE_URL) + "index.html"
+    page_local_path = os.path.join(dest, page_relative_path)
+    os.makedirs(os.path.dirname(page_local_path), exist_ok=True)
+    with open(page_local_path, "w", encoding="utf-8") as f:
+        f.write(html_text)
+
+    seen = set()
+    for href in parser.assets:
+        absolute_url = urljoin(COMPOSER_PAGE_URL, href)
+        if not absolute_url.startswith(base_origin) or absolute_url in seen:
+            continue  # a genuinely external resource (e.g. a CDN) -- not ours to mirror
+        seen.add(absolute_url)
+
+        relative_path = _relative_to_site_root(absolute_url)
+        local_path = os.path.join(dest, relative_path)
+        os.makedirs(os.path.dirname(local_path), exist_ok=True)
+        try:
+            with urllib.request.urlopen(absolute_url, timeout=30) as resp:
+                data = resp.read()
+            with open(local_path, "wb") as f:
+                f.write(data)
+            print(f"  scaricato: {relative_path}")
+        except Exception as exc:
+            print(f"  saltato (non essenziale): {relative_path} ({exc})")
+
+    print(f"\nCopia offline pronta: {page_local_path}")
+    return page_local_path
+
+
+def main(argv=None):
+    args = argv if argv is not None else sys.argv[1:]
+    if args == ["serve"]:
+        _cmd_serve()
+        return
+    if args and args[0] == "offline-composer":
+        dest = args[1] if len(args) > 1 else "composer-offline"
+        _cmd_offline_composer(dest)
+        return
+    if args == ["mcp"]:
+        _cmd_mcp()
+        return
+
+    print(USAGE, file=sys.stderr if args else sys.stdout)
+    sys.exit(1 if args else 0)
+
+
+if __name__ == "__main__":
+    main()

dense_evolution/compiler.py

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

dense_evolution/config.py

@@ -0,0 +1,49 @@
+"""
+Centralized JAX precision control for dense_evolution.
+
+jax_enable_x64 is a process-wide JAX flag: once set, it affects every
+JAX array in the process, not just dense_evolution's own. Before this
+module existed, registry.py, compiler.py and statevector.py each called
+jax.config.update("jax_enable_x64", True) unconditionally at MODULE
+IMPORT time -- so merely `import dense_evolution`, even without ever
+constructing a simulator, silently overrode a precision a caller had
+already configured for unrelated JAX code running earlier in the same
+process. mps.py and chunk.py never did this; their own docstrings
+already documented the intended convention (see mps.py): dense_evolution
+enables x64 lazily, only when something that actually needs complex128
+precision is used, not as an import-time side effect.
+
+This module is that single point. ensure_x64() is idempotent and safe
+to call from every float64 entry point (DenseSVSimulator.__init__,
+QuantumHardwareRegistry.__init__, circuit_to_energy_fn); set_precision()
+is the public opt-out for a caller who wants to choose precision
+explicitly, before constructing anything, and have that choice stick.
+"""
+import jax
+
+_explicit = False
+
+
+def set_precision(float64: bool = True) -> None:
+    """
+    Explicitly configure JAX's process-wide numeric precision.
+
+    Call this yourself, before constructing anything, if you need
+    control over exactly when/whether dense_evolution enables x64 --
+    for example because another float32-only JAX library must be
+    initialized first. Once called, dense_evolution's own lazy
+    ensure_x64() (used internally by DenseSVSimulator, etc.) no longer
+    forces float64 back on, so an explicit set_precision(False) sticks.
+    """
+    global _explicit
+    jax.config.update("jax_enable_x64", float64)
+    _explicit = True
+
+
+def ensure_x64() -> None:
+    """Enable jax_enable_x64 unless a caller has already explicitly
+    configured precision via set_precision(). Called internally,
+    lazily, by dense_evolution components that need complex128
+    precision -- never at import time."""
+    if not _explicit:
+        jax.config.update("jax_enable_x64", True)

dense_evolution/drawing.py

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

dense_evolution/entropy.py

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

dense_evolution/fermions.py

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

dense_evolution/gates.py

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

dense_evolution/harrison_tb.py

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

dense_evolution/healing.py

@@ -0,0 +1,18 @@
+"""Backward-compatibility shim -- the real implementation moved to
+dense_evolution.mitigation.healing as part of the Phase 2 subpackage
+split (see prog.txt). Kept so `from dense_evolution.healing import
+calculate_phi_ab` (used by external consumers, e.g. tools/ia_utils and
+Dense-Evolution-Discovery) keeps working unchanged. Import from
+dense_evolution.mitigation.healing directly in new code.
+"""
+from dense_evolution.mitigation.healing import (
+    calculate_advanced_sigma, calculate_phi_ab, calculate_vettore_dinamico,
+    calculate_vettore_statico, calculate_delta_preemp, evaluate_phi_trigger,
+    calculate_jax_reflection, MemoryReflectionEngine, GLOBAL_CONSTANTS,
+)
+
+__all__ = [
+    "calculate_advanced_sigma", "calculate_phi_ab", "calculate_vettore_dinamico",
+    "calculate_vettore_statico", "calculate_delta_preemp", "evaluate_phi_trigger",
+    "calculate_jax_reflection", "MemoryReflectionEngine", "GLOBAL_CONSTANTS",
+]

dense_evolution/interop/__init__.py

@@ -0,0 +1,18 @@
+"""Interop subpackage: bridges to Qiskit and PennyLane circuits/backends."""
+from .qiskit_pennylane import (
+    from_qiskit,
+    from_pennylane,
+    run_qiskit_circuit,
+    run_pennylane_circuit,
+    noise_model_from_qiskit_backend,
+    to_stim,
+)
+
+__all__ = [
+    "from_qiskit",
+    "from_pennylane",
+    "run_qiskit_circuit",
+    "run_pennylane_circuit",
+    "noise_model_from_qiskit_backend",
+    "to_stim",
+]