dense-evolution 8.3.0__py3-none-win_amd64.whl

dense_evolution/circuits/qft.py

@@ -0,0 +1,66 @@
+"""
+Quantum Fourier Transform circuit builder -- the textbook cascade of H and
+controlled-phase gates, plus the trailing qubit-order swap, returned as a
+gate-tuple list ready for run_circuit. A standard building block (phase
+estimation, Shor's algorithm, arithmetic circuits) that every general-
+purpose SDK ships (Qiskit's `QFT`, Cirq's `cirq.QuantumFourierTransformGate`).
+"""
+import numpy as np
+
+__all__ = ['qft']
+
+
+def _invert_op(op):
+    """H and SWAP are self-inverse; CP(theta)^-1 = CP(-theta)."""
+    if op[0] == 'cp':
+        gate, ctrl, tgt, angle = op
+        return (gate, ctrl, tgt, -angle)
+    return op
+
+
+def qft(n_qubits, inverse=False, do_swaps=True):
+    """
+    Build the Quantum Fourier Transform circuit on n_qubits.
+
+    Parameters
+    ----------
+    n_qubits : int
+        Number of qubits, must be >= 1.
+    inverse : bool
+        Build the inverse QFT instead (same gate set, reversed order,
+        negated phase angles).
+    do_swaps : bool
+        Include the trailing qubit-reversal swaps that put the output in
+        the same qubit order as the input. The H/CP cascade alone
+        produces the Fourier-transformed amplitudes in bit-reversed
+        qubit order; set this to False only if the caller will account
+        for that reversal itself (e.g. chaining straight into another
+        subroutine that expects it).
+
+    Returns
+    -------
+    list[tuple]
+
+    Examples
+    --------
+    >>> import dense_evolution as de
+    >>> sim = de.DenseSVSimulator(3)
+    >>> sim.run_circuit(de.qft(3))
+    >>> sim.get_probabilities()  # uniform: QFT|000> = equal superposition
+    """
+    if n_qubits < 1:
+        raise ValueError(f"qft needs at least 1 qubit, got {n_qubits}")
+
+    ops = []
+    for j in range(n_qubits):
+        ops.append(('h', j))
+        for k in range(j + 1, n_qubits):
+            angle = np.pi / (2 ** (k - j))
+            ops.append(('cp', k, j, angle))
+    if do_swaps:
+        for i in range(n_qubits // 2):
+            ops.append(('swap', i, n_qubits - 1 - i))
+
+    if inverse:
+        ops = [_invert_op(op) for op in reversed(ops)]
+    return ops

dense_evolution/circuits/random_circuit.py

@@ -0,0 +1,85 @@
+"""
+Random circuit generation for benchmarking and fuzz-testing -- the same
+purpose Qiskit's `random_circuit` serves.
+"""
+import numpy as np
+
+__all__ = ['random_circuit']
+
+_1Q_STATIC = ('h', 'x', 'y', 'z', 's', 'sdg', 't', 'tdg', 'sx')
+_1Q_PARAMETRIC = ('rx', 'ry', 'rz')
+_2Q_STATIC = ('cx', 'cz', 'cy', 'swap')
+_ALL_KNOWN = set(_1Q_STATIC) | set(_1Q_PARAMETRIC) | set(_2Q_STATIC)
+
+
+def random_circuit(n_qubits, n_gates, seed=None, gate_set=None, two_qubit_prob=0.4):
+    """
+    Build a random circuit for benchmarking or fuzz-testing.
+
+    Parameters
+    ----------
+    n_qubits : int
+        Number of qubits, must be >= 1.
+    n_gates : int
+        Number of gate operations to generate, must be >= 0.
+    seed : int | numpy.random.Generator, optional
+        Seed (or an existing Generator) for reproducible circuits.
+    gate_set : iterable of str, optional
+        Restrict generation to this set of gate names, mixing 1- and
+        2-qubit gates freely (default spans both: h, x, y, z, s, sdg, t,
+        tdg, sx, rx, ry, rz, cx, cz, cy, swap). Unrecognized names raise
+        immediately rather than failing later inside run_circuit.
+    two_qubit_prob : float
+        Probability in [0, 1] of picking a 2-qubit gate at each step.
+        Ignored (forced to single-qubit gates) once n_qubits < 2, or once
+        gate_set excludes every 2-qubit gate name.
+
+    Returns
+    -------
+    list[tuple]
+    """
+    if n_qubits < 1:
+        raise ValueError(f"random_circuit needs at least 1 qubit, got {n_qubits}")
+    if n_gates < 0:
+        raise ValueError(f"n_gates must be >= 0, got {n_gates}")
+    if not (0.0 <= two_qubit_prob <= 1.0):
+        raise ValueError(f"two_qubit_prob must be in [0, 1], got {two_qubit_prob}")
+
+    rng = seed if isinstance(seed, np.random.Generator) else np.random.default_rng(seed)
+
+    if gate_set is not None:
+        gate_set = list(gate_set)
+        unknown = set(gate_set) - _ALL_KNOWN
+        if unknown:
+            raise ValueError(f"unknown gate name(s) in gate_set: {sorted(unknown)}")
+        one_q_static = [g for g in gate_set if g in _1Q_STATIC]
+        one_q_param = [g for g in gate_set if g in _1Q_PARAMETRIC]
+        two_q = [g for g in gate_set if g in _2Q_STATIC]
+    else:
+        one_q_static = list(_1Q_STATIC)
+        one_q_param = list(_1Q_PARAMETRIC)
+        two_q = list(_2Q_STATIC) if n_qubits >= 2 else []
+
+    one_q_pool = one_q_static + one_q_param
+    if not one_q_pool and not two_q:
+        raise ValueError("gate_set leaves no usable gates for this n_qubits")
+
+    ops = []
+    for _ in range(n_gates):
+        use_two_qubit = (
+            bool(two_q) and n_qubits >= 2
+            and (not one_q_pool or rng.random() < two_qubit_prob)
+        )
+        if use_two_qubit:
+            name = two_q[rng.integers(len(two_q))]
+            a, b = rng.choice(n_qubits, size=2, replace=False)
+            ops.append((name, int(a), int(b)))
+        else:
+            name = one_q_pool[rng.integers(len(one_q_pool))]
+            q = int(rng.integers(n_qubits))
+            if name in _1Q_PARAMETRIC:
+                theta = float(rng.uniform(0, 2 * np.pi))
+                ops.append((name, q, theta))
+            else:
+                ops.append((name, q))
+    return ops

dense_evolution/circuits/registry.py

@@ -0,0 +1,74 @@
+import subprocess
+import platform
+import psutil
+import matplotlib
+import matplotlib.pyplot as plt
+
+from ..config import ensure_x64
+
+# NoiseModel/NoiseSpec moved to dense_evolution.noise -- this was the
+# wrong home for them (this module is hardware-capability detection,
+# an unrelated concern). Re-exported here for backward compatibility
+# with existing `from dense_evolution.registry import NoiseModel`-style
+# imports; new code should import from dense_evolution.noise directly.
+from ..noise import NoiseModel, NoiseSpec
+from ..noise.kraus_channels import HAS_JAX
+
+__all__ = ["QuantumHardwareRegistry", "NoiseModel", "NoiseSpec", "HAS_JAX", "apply_dark_theme"]
+
+
+class QuantumHardwareRegistry:
+    def __init__(self):
+        # Lazy, not at import time -- see dense_evolution/config.py.
+        ensure_x64()
+        self.processor = platform.processor()
+        self.ram_total = psutil.virtual_memory().total / (1024**3)
+        self.ram_avail = psutil.virtual_memory().available / (1024**3)
+        self.has_jax = HAS_JAX
+        self.has_gpu = self._detect_gpu()
+        self.max_dense_qubits = self._get_qubit_limit()
+
+    def _detect_gpu(self) -> bool:
+        try:
+            subprocess.check_output(['nvidia-smi'], stderr=subprocess.DEVNULL)
+            return True
+        except Exception:
+            return False
+
+    def _get_qubit_limit(self) -> int:
+        if self.ram_total >= 50: return 28
+        elif self.ram_total >= 12: return 24
+        return 20
+
+    def print_diagnostics(self):
+        print(f"MAX_DENSE={self.max_dense_qubits}q | JAX={self.has_jax} | GPU={self.has_gpu}")
+
+
+# BUG FIX: this module used to instantiate a module-level
+# `HARDWARE_REGISTRY = QuantumHardwareRegistry()` singleton here -- never
+# referenced anywhere else in the codebase (dead code), but its __init__
+# calls ensure_x64() unconditionally, so merely `import dense_evolution`
+# still forced jax_enable_x64=True at import time even after PR #130
+# supposedly made that lazy (see dense_evolution/config.py) -- the
+# laziness moved into ensure_x64() itself, but this eager singleton
+# construction defeated it one level up. Removed entirely: nothing
+# needs it, and QuantumHardwareRegistry() remains available for any
+# caller who actually wants one, constructed on their own schedule.
+
+
+def apply_dark_theme():
+    """Dashboard-only diagnostic-plot styling (dark background + GitHub-
+    dark-ish palette). Used to run as a `plt.style.use('dark_background')`
+    module-level side effect here, so it fired on ANY `import
+    dense_evolution` and silently recolored every matplotlib figure a
+    caller made afterward, dashboard or not (prog.txt point 2). Now
+    opt-in: call this explicitly from the dashboard's own startup."""
+    plt.style.use('dark_background')
+    matplotlib.rcParams.update({
+        'figure.facecolor': '#010409',
+        'axes.facecolor': '#0d1117',
+        'axes.edgecolor': '#21262d',
+        'grid.color': '#21262d',
+        'font.family': 'monospace',
+        'font.size': 9,
+    })

dense_evolution/circuits/topology.py

@@ -0,0 +1,79 @@
+"""
+Entangling-layer topology helpers.
+
+Every variational circuit (VQE, QAOA, hardware-efficient ansätze) needs an
+entangling layer, and hand-writing it as a `for` loop of two-qubit gates is
+one of the most repeated patterns across quantum-circuit code. Other
+libraries give it a name and a single call instead (Qiskit's
+`TwoLocal(entanglement=...)`, PennyLane's `qml.broadcast(pattern=...)`).
+`entangling_layer` is the Dense-Evolution equivalent: it returns a plain
+list of gate tuples in the circuit format `run_circuit` already accepts, so
+it drops straight into any existing circuit list via concatenation.
+"""
+
+VALID_PATTERNS = ('linear', 'circular', 'full', 'star', 'brick')
+
+
+def entangling_layer(n_qubits, pattern='linear', gate='cx', reverse=False, hub=0):
+    """
+    Build a list of two-qubit gate tuples connecting n_qubits according to
+    a named topology.
+
+    Patterns
+    --------
+    'linear'   -- chain: (0,1), (1,2), ..., (n-2,n-1)
+    'circular' -- linear + one wraparound edge (n-1,0) ("ring"); identical
+                  to 'linear' when n_qubits == 2, since there is only one
+                  possible edge between two qubits
+    'full'     -- every pair (i,j) with i<j ("complete"/all-to-all)
+    'star'     -- a single hub qubit connected to every other qubit
+    'brick'    -- alternating even/odd layers: (0,1)(2,3).. then (1,2)(3,4)..
+                  ("brickwork"/staircase, the pattern behind most Trotterized
+                  and hardware-efficient ansätze)
+
+    Parameters
+    ----------
+    n_qubits : int
+        Number of qubits involved, must be >= 2.
+    pattern : str
+        One of VALID_PATTERNS.
+    gate : str
+        Two-qubit gate name applied to every edge (e.g. 'cx', 'cz', 'cy').
+        Not validated against dense_evolution.gates.GATES here, so a custom
+        gate name registered elsewhere still works.
+    reverse : bool
+        Swap (control, target) -> (target, control) for every edge. Some
+        ansätze alternate direction layer to layer for symmetry.
+    hub : int
+        Hub qubit index, only used by pattern='star'.
+
+    Returns
+    -------
+    list[tuple[str, int, int]]
+    """
+    if n_qubits < 2:
+        raise ValueError(f"entangling_layer needs at least 2 qubits, got {n_qubits}")
+    if pattern not in VALID_PATTERNS:
+        raise ValueError(f"unknown pattern {pattern!r}, expected one of {VALID_PATTERNS}")
+
+    if pattern == 'linear':
+        edges = [(q, q + 1) for q in range(n_qubits - 1)]
+    elif pattern == 'circular':
+        edges = [(q, q + 1) for q in range(n_qubits - 1)]
+        if n_qubits > 2:
+            edges.append((n_qubits - 1, 0))
+    elif pattern == 'full':
+        edges = [(i, j) for i in range(n_qubits) for j in range(i + 1, n_qubits)]
+    elif pattern == 'star':
+        if not (0 <= hub < n_qubits):
+            raise ValueError(f"hub={hub} out of range for n_qubits={n_qubits}")
+        edges = [(hub, q) for q in range(n_qubits) if q != hub]
+    elif pattern == 'brick':
+        even = [(q, q + 1) for q in range(0, n_qubits - 1, 2)]
+        odd = [(q, q + 1) for q in range(1, n_qubits - 1, 2)]
+        edges = even + odd
+
+    if reverse:
+        edges = [(b, a) for a, b in edges]
+
+    return [(gate, a, b) for a, b in edges]

dense_evolution/circuits/trotter.py

@@ -0,0 +1,265 @@
+"""
+Real-time Hamiltonian evolution as an actual gate circuit (Trotterization)
+-- did not exist anywhere in this package before. Every existing piece of
+"evolution" machinery here is either gate-based-and-fixed (a hand-written
+or VQE-optimized circuit template) or exact-and-not-a-circuit
+(dashboard_core.hamiltonians.ground_state_energy's dense diagonalization).
+Nothing composed exp(-i*H*t) for an arbitrary Hamiltonian into gates a
+real quantum computer could run.
+
+Originated in research/wormhole_syk.py, where it closed an explicit,
+previously-open follow-on: reproducing a traversable-wormhole-teleportation
+signal (arXiv:2604.10090) first via exact matrix exponentiation (cheap,
+but not what real hardware executes), then via this module's Trotterized
+gate circuit -- verified the signal wasn't an artifact of the exact-
+evolution shortcut, it survives with real gates too. Neither function
+here is specific to that experiment or to SYK physics; both drop
+straight into any future feature needing exp(-i*H*t) as gates (a
+Trotterized VQE-adjacent ansatz, quench dynamics, etc.).
+
+pauli_rotation_ops is exact for a single Pauli-string term (fidelity
+1.0 against scipy.linalg.expm, verified in tests/unit/test_trotter.py for
+1-4 qubit mixed X/Y/Z strings, not just Z-strings); trotter_evolve_ops
+composes many such terms via the first-order product formula by default,
+which is an *approximation* whose error shrinks as n_steps grows (also
+verified: infidelity drops roughly 4x per doubling of steps against a
+real, non-trivial multi-qubit Hamiltonian, consistent with the expected
+quadratic convergence of first-order Trotter error in state overlap).
+
+order=2 selects the second-order (Strang/symmetric) product formula
+instead -- each step applies the terms forward at half the angle, then
+backward (reversed order) at half the angle again:
+[prod_k exp(-i*c_k*P_k*dt/2)] * [prod_k(reversed) exp(-i*c_k*P_k*dt/2)],
+which cancels the first-order formula's leading error term (verified in
+tests/unit/test_trotter.py: infidelity drops roughly 16x per doubling of
+steps, consistent with the expected quartic convergence of second-order
+Trotter error in state overlap, vs. order=1's ~4x). Costs 2x the gates
+of order=1 for the same n_steps -- the standard second-order tradeoff,
+worth it when n_steps would otherwise need to be large for accuracy
+(e.g. the noise-robustness experiments in wormhole_syk_teleportation.py,
+where gate count directly limits how much depolarizing noise the
+circuit accumulates).
+"""
+
+import jax
+import jax.numpy as jnp
+from jax.scipy.linalg import expm
+
+__all__ = ['pauli_rotation_ops', 'trotter_evolve_ops', 'continuous_pulse_evolve',
+           'continuous_dissipative_evolve']
+
+
+def pauli_rotation_ops(pauli_dict, angle):
+    """Gate-tuple circuit for exp(-i*angle*P), P a Pauli string given as
+    {qubit: 'X'/'Y'/'Z'} -- basis-change + CNOT-staircase + RZ + inverse,
+    the same identity already used elsewhere in this codebase
+    (dashboard_core.vqe's UCCSD/QAOA-style ZZ interactions) generalized
+    here to arbitrary mixed X/Y/Z strings, not just Z-strings.
+
+    This package's rz(theta) = exp(-i*theta/2*Z) (checked directly
+    against scipy.linalg.expm when this was written, not assumed from
+    convention) -- rz(2*angle) on the accumulator qubit therefore gives
+    exactly exp(-i*angle*Z) on the accumulated parity.
+
+    Parameters
+    ----------
+    pauli_dict : dict
+        {qubit: 'X'|'Y'|'Z'}. An empty dict (identity term) returns [].
+    angle : float
+
+    Returns
+    -------
+    list[tuple]
+        Gate tuples ready for DenseSVSimulator.run_circuit /
+        QASMParser-compatible circuits.
+    """
+    qubits = sorted(pauli_dict.keys())
+    if not qubits:
+        return []
+    ops = []
+    for q in qubits:
+        letter = pauli_dict[q]
+        if letter == 'X':
+            ops.append(('h', q))
+        elif letter == 'Y':
+            ops.append(('sdg', q))
+            ops.append(('h', q))
+    for i in range(len(qubits) - 1):
+        ops.append(('cx', qubits[i], qubits[i + 1]))
+    ops.append(('rz', qubits[-1], 2 * angle))
+    for i in reversed(range(len(qubits) - 1)):
+        ops.append(('cx', qubits[i], qubits[i + 1]))
+    for q in qubits:
+        letter = pauli_dict[q]
+        if letter == 'X':
+            ops.append(('h', q))
+        elif letter == 'Y':
+            ops.append(('h', q))
+            ops.append(('s', q))
+    return ops
+
+
+def trotter_evolve_ops(terms, t, n_steps, order=1):
+    """Trotter product formula for exp(-i*H*t), H = sum_k c_k*P_k.
+
+    order=1 (default): [prod_k exp(-i*c_k*P_k*(t/n_steps))]^n_steps.
+    Term order within one step follows `terms`' own order, identical
+    every repetition (not re-randomized per step).
+
+    order=2: Strang/symmetric splitting -- each step is a forward half-
+    angle pass through `terms` followed by a backward half-angle pass
+    through `terms` reversed, [prod_k exp(-i*c_k*P_k*dt/2)] *
+    [prod_k(reversed) exp(-i*c_k*P_k*dt/2)], repeated n_steps times.
+    Quadratically more accurate than order=1 for the same n_steps (see
+    module docstring), at 2x the gate count per step.
+
+    Parameters
+    ----------
+    terms : list[(float, dict)]
+        (coefficient, pauli_dict) pairs, e.g. from
+        dense_evolution.pauli_hamiltonian_to_matrix's own term format,
+        or dense_evolution.majorana_pauli_terms products.
+    t : float
+        Total evolution time.
+    n_steps : int
+        Number of Trotter steps -- higher is more accurate and more
+        gates, the standard Trotter accuracy/cost tradeoff.
+    order : int
+        1 (default) or 2 -- see above.
+
+    Returns
+    -------
+    list[tuple]
+        Gate tuples for the whole Trotterized evolution.
+    """
+    if order not in (1, 2):
+        raise ValueError(f"order must be 1 or 2, got {order}")
+    dt = t / n_steps
+    if order == 1:
+        step_ops = []
+        for c, pdict in terms:
+            step_ops.extend(pauli_rotation_ops(pdict, c * dt))
+    else:
+        half_dt = dt / 2
+        step_ops = []
+        for c, pdict in terms:
+            step_ops.extend(pauli_rotation_ops(pdict, c * half_dt))
+        for c, pdict in reversed(terms):
+            step_ops.extend(pauli_rotation_ops(pdict, c * half_dt))
+    return step_ops * n_steps
+
+
+def continuous_pulse_evolve(psi0, hamiltonian_fn, coeffs_t, dt, observable_fn=None):
+    """Evolve a statevector under a time-dependent Hamiltonian via
+    jax.lax.scan, generalized out of a pattern first written ad hoc for a
+    real time-dependent pulse (Dense-Evolution-Discovery's
+    germanium_iswap_validation.py, exact_final_state/exact_final_state_general
+    -- a 56ns raised-cosine baseband iSWAP pulse, arXiv:2608.16716). That
+    script's own Trotterized-gate-circuit version of the same pulse
+    (build_pulse_circuit) instead builds a plain Python list of gate tuples,
+    one exp(-i*H*dt) per slice via pauli_rotation_ops -- fine for producing a
+    circuit a discrete-gate simulator can run, but not what this function is
+    for: this evolves the statevector directly, slice by slice, entirely
+    inside JAX, with no Python-side list that grows with the number of
+    slices (the O(1)-per-step scan carry is the whole point -- many slices
+    for a finely-resolved pulse cost compile time, not accumulating Python
+    memory).
+
+    Not specific to any one Hamiltonian, qubit count, or pulse shape --
+    `hamiltonian_fn` supplies the (possibly qubit-count-dependent) operator
+    for a given instantaneous coefficient, and `coeffs_t` can be any sampled
+    time-dependent profile (a smooth pulse envelope, a sudden burst, a
+    constant array for a time-independent Hamiltonian, etc.).
+
+    Parameters
+    ----------
+    psi0 : array_like
+        Initial statevector, shape (2**n_qubits,).
+    hamiltonian_fn : callable
+        coeff -> Hamiltonian matrix, shape (2**n_qubits, 2**n_qubits), for
+        that instant's coefficient. Called once per entry of `coeffs_t`
+        under jax.lax.scan, so it must be JAX-traceable.
+    coeffs_t : array_like
+        Per-slice instantaneous coefficient, one entry per time slice
+        (e.g. a peak amplitude times a sampled pulse envelope). The
+        evolution applies exp(-i*hamiltonian_fn(coeff)*dt) for each entry,
+        in order.
+    dt : float
+        Duration of one slice (coeffs_t is assumed sampled on a uniform
+        grid of this spacing -- same convention as the germanium
+        experiment's dt=0.05 ns midpoint/linspace sampling).
+    observable_fn : callable, optional
+        If given, applied to the statevector after each slice; the stacked
+        per-slice results are returned as `trajectory` (mirrors the
+        experiment's own step_record, used there to plot |01>/|10>
+        occupation probability over the pulse). If omitted, `trajectory`
+        is None and only the final state is computed.
+
+    Returns
+    -------
+    final_psi : jnp.ndarray
+    trajectory : jnp.ndarray or None
+    """
+    def step(psi, coeff):
+        H_t = hamiltonian_fn(coeff)
+        U_step = expm(-1j * H_t * dt)
+        next_psi = jnp.dot(U_step, psi)
+        y = observable_fn(next_psi) if observable_fn is not None else None
+        return next_psi, y
+
+    final_psi, trajectory = jax.lax.scan(step, jnp.asarray(psi0), jnp.asarray(coeffs_t))
+    return final_psi, trajectory
+
+
+def continuous_dissipative_evolve(rho0, channel_fn, params_t, observable_fn=None):
+    """Evolve a density matrix through a time-dependent open-system (CPTP)
+    channel via jax.lax.scan -- the dissipative counterpart of
+    `continuous_pulse_evolve`, which only ever does unitary exp(-i*H*dt)
+    steps on a pure state.
+
+    Needed because not every real time-dependent physical event is coherent.
+    E.g. a cosmic-ray/gamma impact on a superconducting qubit chip (real
+    data: McEwen et al., arXiv:2104.05219) produces a burst of quasiparticles
+    that transiently collapses the chip's effective T1 -- a rise (~10us to a
+    first plateau, ~1ms to near-saturation) followed by a ~25-30ms
+    exponential decay back to baseline, measured directly, not modeled as a
+    static before/after depolarizing parameter. That is dissipation with a
+    time-varying rate, which cannot be expressed as a coefficient inside a
+    Hermitian Hamiltonian and passed to `continuous_pulse_evolve` -- it has
+    to act on rho through an actual CPTP map at each instant.
+
+    `channel_fn` supplies that per-slice CPTP map (e.g.
+    `dense_evolution.global_depolarizing_channel`, or any other Kraus
+    channel taking a time-varying parameter), so this function is not
+    specific to any one noise mechanism, exactly like `continuous_pulse_evolve`
+    is not specific to any one Hamiltonian.
+
+    Parameters
+    ----------
+    rho0 : array_like
+        Initial density matrix, shape (dim, dim).
+    channel_fn : callable
+        (rho, param) -> rho_next, a single-slice CPTP map. Called once per
+        entry of `params_t` under jax.lax.scan, so it must be
+        JAX-traceable.
+    params_t : array_like
+        Per-slice instantaneous channel parameter (e.g. a depolarizing/
+        decay probability sampled on a time grid reproducing a measured
+        event's rise-and-decay profile).
+    observable_fn : callable, optional
+        If given, applied to rho after each slice; the stacked per-slice
+        results are returned as `trajectory`. If omitted, `trajectory` is
+        None and only the final density matrix is computed.
+
+    Returns
+    -------
+    final_rho : jnp.ndarray
+    trajectory : jnp.ndarray or None
+    """
+    def step(rho, param):
+        rho_next = channel_fn(rho, param)
+        y = observable_fn(rho_next) if observable_fn is not None else None
+        return rho_next, y
+
+    final_rho, trajectory = jax.lax.scan(step, jnp.asarray(rho0), jnp.asarray(params_t))
+    return final_rho, trajectory