physicskit 0.1.0__py3-none-any.whl

physicskit/quantum/utils/measure.py

@@ -0,0 +1,253 @@
+r"""Quantum measurement simulator and expectation-value / uncertainty monitors."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .._compat import trapz
+
+__all__ = ["expectation_value", "uncertainty", "momentum_density", "ExpectationMonitor", "simulate_position_measurement"]
+
+
+def expectation_value(operator_action, x: np.ndarray, psi: np.ndarray) -> complex:
+    r"""Expectation value of a local/differential operator.
+
+    .. math::
+
+        \langle\psi\rvert\hat A\lvert\psi\rangle
+            = \int \psi^*(x)\, [\hat A\psi](x)\, dx.
+
+    Parameters
+    ----------
+    operator_action : callable
+        A function ``operator_action(x, psi) -> A_psi`` applying
+        :math:`\hat A` to ``psi``.
+    x : numpy.ndarray
+        Positions.
+    psi : numpy.ndarray
+        Wavefunction sampled on ``x``.
+
+    Returns
+    -------
+    complex
+    """
+    A_psi = operator_action(x, psi)
+    return complex(trapz(np.conj(psi) * A_psi, x))
+
+
+def position_expectation(x: np.ndarray, psi: np.ndarray) -> float:
+    r"""Position expectation value :math:`\langle x\rangle = \int x\,\lvert\psi(x)\rvert^2\,dx`.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+    psi : numpy.ndarray
+
+    Returns
+    -------
+    float
+    """
+    return float(np.real(trapz(x * np.abs(psi) ** 2, x)))
+
+
+def position_variance(x: np.ndarray, psi: np.ndarray) -> float:
+    r"""Position variance :math:`\langle x^2\rangle - \langle x\rangle^2`.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+    psi : numpy.ndarray
+
+    Returns
+    -------
+    float
+    """
+    density = np.abs(psi) ** 2
+    mean = trapz(x * density, x)
+    mean_sq = trapz(x**2 * density, x)
+    return float(np.real(mean_sq - mean**2))
+
+
+def momentum_density(x: np.ndarray, psi: np.ndarray, hbar: float = 1.0):
+    """FFT-based momentum-space wavefunction and probability density.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+        Positions (uniform grid).
+    psi : numpy.ndarray
+        Wavefunction sampled on ``x``.
+    hbar : float, default=1.0
+        Value of :math:`\\hbar` to use.
+
+    Returns
+    -------
+    p : numpy.ndarray
+        Momentum grid, ascending.
+    psi_p : numpy.ndarray
+        Normalized momentum-space wavefunction.
+    """
+    dx = x[1] - x[0]
+    N = x.shape[0]
+    k = 2 * np.pi * np.fft.fftfreq(N, d=dx)
+    psi_k = np.fft.fft(psi) * dx / np.sqrt(2 * np.pi)
+    p = hbar * k
+    order = np.argsort(p)
+    p_sorted, psi_k_sorted = p[order], psi_k[order]
+    norm = np.sqrt(trapz(np.abs(psi_k_sorted) ** 2, p_sorted))
+    return p_sorted, psi_k_sorted / norm
+
+
+def momentum_expectation(x: np.ndarray, psi: np.ndarray, hbar: float = 1.0) -> float:
+    r"""Momentum expectation value :math:`\langle p\rangle`, via :func:`momentum_density`.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+    psi : numpy.ndarray
+    hbar : float, default=1.0
+
+    Returns
+    -------
+    float
+    """
+    p, psi_p = momentum_density(x, psi, hbar)
+    return float(np.real(trapz(p * np.abs(psi_p) ** 2, p)))
+
+
+def momentum_variance(x: np.ndarray, psi: np.ndarray, hbar: float = 1.0) -> float:
+    r"""Momentum variance :math:`\langle p^2\rangle - \langle p\rangle^2`, via :func:`momentum_density`.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+    psi : numpy.ndarray
+    hbar : float, default=1.0
+
+    Returns
+    -------
+    float
+    """
+    p, psi_p = momentum_density(x, psi, hbar)
+    density = np.abs(psi_p) ** 2
+    mean = trapz(p * density, p)
+    mean_sq = trapz(p**2 * density, p)
+    return float(np.real(mean_sq - mean**2))
+
+
+def uncertainty(x: np.ndarray, psi: np.ndarray, hbar: float = 1.0) -> tuple[float, float, float]:
+    r"""Position/momentum uncertainties and their product.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+    psi : numpy.ndarray
+    hbar : float, default=1.0
+
+    Returns
+    -------
+    dx, dp, product : float
+        :math:`\Delta x`, :math:`\Delta p`, and :math:`\Delta x\,\Delta p`,
+        for checking the Heisenberg bound :math:`\Delta x\,\Delta p \ge \hbar/2`.
+    """
+    dx = np.sqrt(position_variance(x, psi))
+    dp = np.sqrt(momentum_variance(x, psi, hbar))
+    return dx, dp, dx * dp
+
+
+@dataclass
+class ExpectationMonitor:
+    """Tracks expectation values along a time-evolution trajectory.
+
+    Records :math:`\\langle x\\rangle(t)`, :math:`\\langle p\\rangle(t)`,
+    :math:`\\Delta x(t)`, :math:`\\Delta p(t)`, and the norm, e.g. from the
+    frames returned by a
+    :meth:`~physicskit.quantum.core.solvers.SplitOperatorSolver1D.propagate` call.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+        Positions the wavefunction is sampled on.
+    hbar : float, default=1.0
+        Value of :math:`\\hbar` to use.
+    """
+
+    x: np.ndarray
+    hbar: float = 1.0
+    history: dict = field(default_factory=lambda: {"t": [], "norm": [], "x": [], "p": [], "dx": [], "dp": []})
+
+    def record(self, t: float, psi: np.ndarray):
+        """Record one snapshot.
+
+        Parameters
+        ----------
+        t : float
+            Time of the snapshot.
+        psi : numpy.ndarray
+            Wavefunction at time ``t``, sampled on ``self.x``.
+        """
+        norm = trapz(np.abs(psi) ** 2, self.x)
+        dx, dp, _ = uncertainty(self.x, psi, self.hbar)
+        self.history["t"].append(t)
+        self.history["norm"].append(float(norm))
+        self.history["x"].append(position_expectation(self.x, psi))
+        self.history["p"].append(momentum_expectation(self.x, psi, self.hbar))
+        self.history["dx"].append(dx)
+        self.history["dp"].append(dp)
+
+    def record_all(self, times: np.ndarray, frames: np.ndarray):
+        """Record a full trajectory.
+
+        Parameters
+        ----------
+        times : numpy.ndarray
+            Times of each snapshot.
+        frames : numpy.ndarray
+            Wavefunction snapshots, shape ``(len(times), len(self.x))``.
+        """
+        for t, psi in zip(times, frames):
+            self.record(t, psi)
+
+    def as_arrays(self) -> dict:
+        """Return the recorded history as arrays.
+
+        Returns
+        -------
+        dict
+            Maps ``'t'``, ``'norm'``, ``'x'``, ``'p'``, ``'dx'``, ``'dp'``
+            to :class:`numpy.ndarray`.
+        """
+        return {k: np.array(v) for k, v in self.history.items()}
+
+
+def simulate_position_measurement(x: np.ndarray, psi: np.ndarray, n_samples: int = 1, rng: np.random.Generator | None = None) -> np.ndarray:
+    r"""Sample simulated projective position measurements.
+
+    Draws :math:`x_i \sim \lvert\psi(x)\rvert^2` (the Born rule), via
+    inverse-CDF sampling on the discretized density.
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+        Positions.
+    psi : numpy.ndarray
+        Wavefunction sampled on ``x``.
+    n_samples : int, default=1
+        Number of simulated measurement outcomes to draw.
+    rng : numpy.random.Generator or None, optional
+        Random number generator; a fresh default one is used if omitted.
+
+    Returns
+    -------
+    numpy.ndarray
+        Simulated measurement outcomes, shape ``(n_samples,)``.
+    """
+    rng = rng or np.random.default_rng()
+    density = np.abs(psi) ** 2
+    density = density / trapz(density, x)
+    cdf = np.concatenate([[0.0], np.cumsum((density[1:] + density[:-1]) / 2 * np.diff(x))])
+    cdf /= cdf[-1]
+    u = rng.random(n_samples)
+    return np.interp(u, cdf, x)

physicskit/quantum/visualizers/bloch_sphere.py

@@ -0,0 +1,205 @@
+r"""Interactive 3D Bloch-sphere qubit trajectories (Plotly), and a frame-by-frame
+matplotlib animation of the vector advancing along a trajectory."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+import plotly.graph_objects as go
+from matplotlib.animation import FuncAnimation
+
+from ..core.operators import sigma_x, sigma_y, sigma_z
+
+__all__ = ["bloch_vector", "state_to_bloch_trajectory", "plot_bloch_sphere", "animate_bloch_sphere"]
+
+
+def bloch_vector(psi: np.ndarray) -> np.ndarray:
+    r"""The Bloch-sphere coordinates of a single-qubit pure state.
+
+    .. math::
+
+        \mathbf n = \left(\langle\psi\rvert\sigma_x\lvert\psi\rangle,\;
+                           \langle\psi\rvert\sigma_y\lvert\psi\rangle,\;
+                           \langle\psi\rvert\sigma_z\lvert\psi\rangle\right).
+
+    Parameters
+    ----------
+    psi : numpy.ndarray
+        A 2-component qubit state vector.
+
+    Returns
+    -------
+    numpy.ndarray
+        The 3-component Bloch vector ``(x, y, z)``.
+    """
+    psi = np.asarray(psi, dtype=complex)
+    x = np.real(np.vdot(psi, sigma_x @ psi))
+    y = np.real(np.vdot(psi, sigma_y @ psi))
+    z = np.real(np.vdot(psi, sigma_z @ psi))
+    return np.array([x, y, z])
+
+
+def state_to_bloch_trajectory(states: np.ndarray) -> np.ndarray:
+    """Convert a time series of qubit states to Bloch-vector coordinates.
+
+    Parameters
+    ----------
+    states : numpy.ndarray
+        Qubit state vectors over time, shape ``(n_times, 2)``.
+
+    Returns
+    -------
+    numpy.ndarray
+        Bloch vectors, shape ``(n_times, 3)``.
+    """
+    return np.array([bloch_vector(psi) for psi in states])
+
+
+def _sphere_mesh(n: int = 40):
+    u = np.linspace(0, 2 * np.pi, n)
+    v = np.linspace(0, np.pi, n)
+    xs = np.outer(np.cos(u), np.sin(v))
+    ys = np.outer(np.sin(u), np.sin(v))
+    zs = np.outer(np.ones_like(u), np.cos(v))
+    return xs, ys, zs
+
+
+def plot_bloch_sphere(trajectory: np.ndarray | None = None, vectors: list[np.ndarray] | None = None, labels: list[str] | None = None) -> go.Figure:
+    """Render the Bloch sphere.
+
+    Parameters
+    ----------
+    trajectory : numpy.ndarray or None, optional
+        Bloch vectors traced over time, shape ``(n_times, 3)`` (e.g. from
+        :func:`state_to_bloch_trajectory`).
+    vectors : list of numpy.ndarray or None, optional
+        Static vectors to mark, each a 3-component array.
+    labels : list of str or None, optional
+        Labels for ``vectors``; defaults to ``v0, v1, ...``.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    xs, ys, zs = _sphere_mesh()
+    fig = go.Figure()
+    fig.add_trace(go.Surface(x=xs, y=ys, z=zs, opacity=0.15, showscale=False, colorscale=[[0, "lightblue"], [1, "lightblue"]]))
+
+    axis_len = 1.3
+    for axis, name in zip(np.eye(3), ["x", "y", "z"]):
+        fig.add_trace(
+            go.Scatter3d(
+                x=[-axis_len * axis[0], axis_len * axis[0]],
+                y=[-axis_len * axis[1], axis_len * axis[1]],
+                z=[-axis_len * axis[2], axis_len * axis[2]],
+                mode="lines",
+                line=dict(color="gray", width=2),
+                showlegend=False,
+            )
+        )
+        fig.add_trace(go.Scatter3d(x=[axis_len * axis[0]], y=[axis_len * axis[1]], z=[axis_len * axis[2]], mode="text", text=[name], showlegend=False))
+
+    if trajectory is not None:
+        fig.add_trace(
+            go.Scatter3d(
+                x=trajectory[:, 0],
+                y=trajectory[:, 1],
+                z=trajectory[:, 2],
+                mode="lines+markers",
+                marker=dict(size=3, color=np.arange(len(trajectory)), colorscale="Viridis"),
+                line=dict(color="darkred", width=4),
+                name="trajectory",
+            )
+        )
+
+    if vectors is not None:
+        for i, v in enumerate(vectors):
+            label = labels[i] if labels else f"v{i}"
+            fig.add_trace(
+                go.Scatter3d(
+                    x=[0, v[0]],
+                    y=[0, v[1]],
+                    z=[0, v[2]],
+                    mode="lines+markers",
+                    line=dict(width=6),
+                    marker=dict(size=[0, 6]),
+                    name=label,
+                )
+            )
+
+    fig.update_layout(
+        scene=dict(
+            xaxis=dict(range=[-1.4, 1.4]),
+            yaxis=dict(range=[-1.4, 1.4]),
+            zaxis=dict(range=[-1.4, 1.4]),
+            aspectmode="cube",
+        ),
+        margin=dict(l=0, r=0, t=30, b=0),
+        title="Bloch sphere",
+    )
+    return fig
+
+
+def animate_bloch_sphere(trajectory: np.ndarray, times: np.ndarray | None = None, interval: int = 30, trail: bool = True, ax=None) -> FuncAnimation:
+    """A matplotlib mplot3d ``FuncAnimation`` of the Bloch vector advancing along a trajectory.
+
+    Unlike :func:`plot_bloch_sphere` (which draws the whole path as one
+    static Plotly trace), this genuinely animates: the arrow from the
+    origin sweeps frame-by-frame along ``trajectory``, optionally leaving a
+    fading trail.
+
+    Parameters
+    ----------
+    trajectory : numpy.ndarray
+        Bloch vectors over time, shape ``(n_frames, 3)`` (e.g. from
+        :func:`state_to_bloch_trajectory`).
+    times : numpy.ndarray or None, optional
+        Time of each frame, used to label the animation title.
+    interval : int, default=30
+        Delay between frames, in milliseconds.
+    trail : bool, default=True
+        Whether to draw the path swept out so far.
+    ax : mpl_toolkits.mplot3d.axes3d.Axes3D or None, optional
+        Axis to draw on; a new 3D figure/axis is created if omitted.
+
+    Returns
+    -------
+    matplotlib.animation.FuncAnimation
+    """
+    if ax is None:
+        fig = plt.figure(figsize=(6, 6))
+        ax = fig.add_subplot(111, projection="3d")
+    else:
+        fig = ax.figure
+
+    u = np.linspace(0, 2 * np.pi, 30)
+    v = np.linspace(0, np.pi, 30)
+    xs = np.outer(np.cos(u), np.sin(v))
+    ys = np.outer(np.sin(u), np.sin(v))
+    zs = np.outer(np.ones_like(u), np.cos(v))
+    ax.plot_wireframe(xs, ys, zs, color="lightblue", alpha=0.2, linewidth=0.5)
+
+    axis_len = 1.3
+    for axis in np.eye(3):
+        ax.plot(*zip(-axis_len * axis, axis_len * axis), color="gray", lw=1)
+
+    ax.set_xlim(-1.3, 1.3)
+    ax.set_ylim(-1.3, 1.3)
+    ax.set_zlim(-1.3, 1.3)
+    ax.set_box_aspect((1, 1, 1))
+
+    (arrow_line,) = ax.plot([0, trajectory[0, 0]], [0, trajectory[0, 1]], [0, trajectory[0, 2]], color="darkred", lw=3, marker="o", markevery=[1])
+    (trail_line,) = ax.plot([], [], [], color="darkorange", lw=1.5, alpha=0.7)
+
+    def update(i):
+        vec = trajectory[i]
+        arrow_line.set_data([0, vec[0]], [0, vec[1]])
+        arrow_line.set_3d_properties([0, vec[2]])
+        if trail:
+            trail_line.set_data(trajectory[: i + 1, 0], trajectory[: i + 1, 1])
+            trail_line.set_3d_properties(trajectory[: i + 1, 2])
+        title = f"t = {times[i]:.3f}" if times is not None else f"frame {i}"
+        ax.set_title(title)
+        return arrow_line, trail_line
+
+    return FuncAnimation(fig, update, frames=len(trajectory), interval=interval, blit=False)

physicskit/quantum/visualizers/entanglement.py

@@ -0,0 +1,58 @@
+r"""Animated growth of an entanglement measure over time."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.animation import FuncAnimation
+
+__all__ = ["animate_entanglement_growth"]
+
+
+def animate_entanglement_growth(t_values: np.ndarray, metric_values: np.ndarray, ylabel: str = "concurrence", interval: int = 30, ax=None) -> FuncAnimation:
+    """Animate a point tracing out an entanglement-measure curve as it builds up over time.
+
+    Draws the curve ``metric_values`` vs. ``t_values`` progressively (rather
+    than all at once), with a marker at the current time -- e.g. the
+    concurrence or reduced-state purity of
+    :class:`~physicskit.quantum.chapters.entanglement.IsingEntangler` growing
+    from 0 (product state) toward 1 (maximally entangled) as the coupling acts.
+
+    Parameters
+    ----------
+    t_values : numpy.ndarray
+        Times.
+    metric_values : numpy.ndarray
+        The entanglement measure evaluated at each time in ``t_values``.
+    ylabel : str, default='concurrence'
+        Label for the y-axis.
+    interval : int, default=30
+        Delay between frames, in milliseconds.
+    ax : matplotlib.axes.Axes or None, optional
+        Axis to draw on; a new figure/axis is created if omitted.
+
+    Returns
+    -------
+    matplotlib.animation.FuncAnimation
+    """
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(7, 4))
+    else:
+        fig = ax.figure
+
+    ax.set_xlim(t_values.min(), t_values.max())
+    ymax = metric_values.max() * 1.1 if metric_values.max() > 0 else 1.0
+    ax.set_ylim(0, ymax)
+    ax.set_xlabel("t")
+    ax.set_ylabel(ylabel)
+
+    (line,) = ax.plot([], [], color="C0", lw=2)
+    (point,) = ax.plot([], [], "o", color="darkred", markersize=8)
+
+    def update(i):
+        line.set_data(t_values[: i + 1], metric_values[: i + 1])
+        point.set_data([t_values[i]], [metric_values[i]])
+        ax.set_title(f"t = {t_values[i]:.3f}")
+        return line, point
+
+    return FuncAnimation(fig, update, frames=len(t_values), interval=interval, blit=False)

physicskit/quantum/visualizers/orbitals.py

@@ -0,0 +1,187 @@
+r"""3D volumetric rendering of hydrogen electron density clouds (Plotly)."""
+
+from __future__ import annotations
+
+import numpy as np
+import plotly.graph_objects as go
+
+from ..chapters.hydrogen_am import HydrogenOrbital, orbital_superposition_density
+
+__all__ = ["orbital_density_grid", "plot_orbital_cloud", "animate_orbital_beating"]
+
+
+def orbital_density_grid(orbital: HydrogenOrbital, extent: float | None = None, n_points: int = 60):
+    r"""Evaluate :math:`\lvert\psi_{nlm}\rvert^2` on a Cartesian grid.
+
+    Parameters
+    ----------
+    orbital : physicskit.quantum.chapters.hydrogen_am.HydrogenOrbital
+        The orbital to evaluate.
+    extent : float or None, optional
+        Half-width of the cubic grid; defaults to a value scaled to the
+        orbital's expected extent.
+    n_points : int, default=60
+        Number of grid points along each Cartesian axis.
+
+    Returns
+    -------
+    X, Y, Z : numpy.ndarray
+        Cartesian coordinate meshgrid.
+    density : numpy.ndarray
+        :math:`\lvert\psi_{nlm}\rvert^2` on the grid.
+    """
+    if extent is None:
+        extent = 3 * orbital.n**2 * orbital.a0 / orbital.Z + 8
+
+    lin = np.linspace(-extent, extent, n_points)
+    X, Y, Z = np.meshgrid(lin, lin, lin, indexing="ij")
+    r = np.sqrt(X**2 + Y**2 + Z**2)
+    r_safe = np.where(r == 0, 1e-9, r)
+    theta = np.arccos(np.clip(Z / r_safe, -1, 1))
+    phi = np.arctan2(Y, X) % (2 * np.pi)
+
+    density = orbital.density(r, theta, phi)
+    return X, Y, Z, density
+
+
+def plot_orbital_cloud(
+    orbital: HydrogenOrbital, extent: float | None = None, n_points: int = 55, iso_fraction: float = 0.02, surface_count: int = 12
+) -> go.Figure:
+    r"""Volumetric isosurface render of the electron probability density.
+
+    Renders :math:`\lvert\psi_{nlm}(r,\theta,\phi)\rvert^2` for a hydrogen
+    orbital as a set of nested isosurfaces.
+
+    Parameters
+    ----------
+    orbital : physicskit.quantum.chapters.hydrogen_am.HydrogenOrbital
+        The orbital to render.
+    extent : float or None, optional
+        Half-width of the cubic grid; see :func:`orbital_density_grid`.
+    n_points : int, default=55
+        Number of grid points along each Cartesian axis.
+    iso_fraction : float, default=0.02
+        Lowest isosurface level, as a fraction of the peak density.
+    surface_count : int, default=12
+        Number of nested isosurfaces to draw.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    X, Y, Z, density = orbital_density_grid(orbital, extent, n_points)
+    dmax = density.max()
+
+    fig = go.Figure(
+        data=go.Volume(
+            x=X.flatten(),
+            y=Y.flatten(),
+            z=Z.flatten(),
+            value=density.flatten(),
+            isomin=iso_fraction * dmax,
+            isomax=dmax,
+            opacity=0.12,
+            surface_count=surface_count,
+            colorscale="Plasma",
+            caps=dict(x_show=False, y_show=False, z_show=False),
+        )
+    )
+    fig.update_layout(
+        title=f"|psi_{{{orbital.n},{orbital.l},{orbital.m}}}|^2",
+        scene=dict(xaxis_title="x", yaxis_title="y", zaxis_title="z", aspectmode="cube"),
+        margin=dict(l=0, r=0, t=30, b=0),
+    )
+    return fig
+
+
+def animate_orbital_beating(
+    orb_a: HydrogenOrbital,
+    orb_b: HydrogenOrbital,
+    times: np.ndarray,
+    extent: float | None = None,
+    n_points: int = 35,
+    ca: complex = 2**-0.5,
+    cb: complex = 2**-0.5,
+    iso_fraction: float = 0.05,
+    surface_count: int = 8,
+) -> go.Figure:
+    r"""Plotly ``frames``-based animation of a two-orbital density beating.
+
+    Unlike a single stationary orbital (:func:`plot_orbital_cloud`, static in
+    time since :math:`\lvert\psi_{nlm}\rvert^2` is time-independent), the
+    density of a coherent superposition of two eigenstates
+    (:func:`~physicskit.quantum.chapters.hydrogen_am.orbital_superposition_density`)
+    genuinely reshapes at the Bohr frequency :math:`\omega_{ab}=E_a-E_b` --
+    rendered here as a play-button-driven sequence of isosurface frames.
+
+    Parameters
+    ----------
+    orb_a, orb_b : HydrogenOrbital
+        The two eigenstates in the superposition.
+    times : numpy.ndarray
+        Times to render frames at.
+    extent : float or None, optional
+        Half-width of the cubic grid; defaults to a value scaled to
+        ``orb_a``'s expected extent.
+    n_points : int, default=35
+        Number of grid points along each Cartesian axis (kept modest since
+        a full 3D grid is evaluated at every frame).
+    ca, cb : complex, default=1/sqrt(2) each
+        Superposition amplitudes.
+    iso_fraction : float, default=0.05
+        Lowest isosurface level, as a fraction of the peak density (over all
+        frames).
+    surface_count : int, default=8
+        Number of nested isosurfaces to draw per frame.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+        With a "Play"/"Pause" button stepping through ``times``.
+    """
+    if extent is None:
+        extent = 3 * orb_a.n**2 * orb_a.a0 / orb_a.Z + 8
+
+    lin = np.linspace(-extent, extent, n_points)
+    X, Y, Z = np.meshgrid(lin, lin, lin, indexing="ij")
+    r = np.sqrt(X**2 + Y**2 + Z**2)
+    r_safe = np.where(r == 0, 1e-9, r)
+    theta = np.arccos(np.clip(Z / r_safe, -1, 1))
+    phi = np.arctan2(Y, X) % (2 * np.pi)
+
+    densities = [orbital_superposition_density(orb_a, orb_b, r, theta, phi, t, ca, cb) for t in times]
+    dmax = max(d.max() for d in densities)
+
+    def volume_trace(density):
+        return go.Volume(
+            x=X.flatten(),
+            y=Y.flatten(),
+            z=Z.flatten(),
+            value=density.flatten(),
+            isomin=iso_fraction * dmax,
+            isomax=dmax,
+            opacity=0.12,
+            surface_count=surface_count,
+            colorscale="Plasma",
+            caps=dict(x_show=False, y_show=False, z_show=False),
+        )
+
+    frames = [go.Frame(data=[volume_trace(d)], name=f"{i}") for i, d in enumerate(densities)]
+
+    fig = go.Figure(data=[volume_trace(densities[0])], frames=frames)
+    fig.update_layout(
+        title=f"|c_a psi_{{{orb_a.n},{orb_a.l},{orb_a.m}}} + c_b psi_{{{orb_b.n},{orb_b.l},{orb_b.m}}}|^2",
+        scene=dict(xaxis_title="x", yaxis_title="y", zaxis_title="z", aspectmode="cube"),
+        margin=dict(l=0, r=0, t=30, b=0),
+        updatemenus=[
+            dict(
+                type="buttons",
+                showactive=False,
+                buttons=[
+                    dict(label="Play", method="animate", args=[None, dict(frame=dict(duration=100, redraw=True), fromcurrent=True)]),
+                    dict(label="Pause", method="animate", args=[[None], dict(frame=dict(duration=0, redraw=False), mode="immediate")]),
+                ],
+            )
+        ],
+    )
+    return fig