physicskit 0.1.0__py3-none-any.whl

physicskit/statphys/visualizers/interactive.py

@@ -0,0 +1,161 @@
+"""Interactive Plotly visualizations.
+
+Every other module in :mod:`physicskit.statphys.visualizers` produces static Matplotlib
+figures, well suited to publication and to this documentation's example
+gallery. This module offers the same information as pan/zoom/hover-enabled
+Plotly figures instead -- convenient for interactively exploring a parameter
+sweep or a dense vector field in a Jupyter notebook, or for embedding in a
+standalone HTML page.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+
+__all__ = [
+    "interactive_particle_snapshot",
+    "interactive_temperature_sweep",
+    "interactive_vortex_field",
+]
+
+
+def interactive_temperature_sweep(result, T_c=None):
+    """Build an interactive 2x2 subplot figure of a temperature sweep result.
+
+    Parameters
+    ----------
+    result : dict of str -> ndarray
+        Output of e.g. ``Ising2D.run_temperature_sweep`` or
+        ``PottsModel2D.run_temperature_sweep``.
+    T_c : float, optional
+        Critical temperature to mark with a vertical line on every panel.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+        A 2x2 subplot figure with hoverable energy, order-parameter,
+        specific-heat, and susceptibility traces.
+
+    Examples
+    --------
+    >>> from physicskit.statphys.chapters.ising_lattice import Ising2D
+    >>> model = Ising2D(L=10, seed=0)
+    >>> result = model.run_temperature_sweep([2.0, 2.269, 2.5], n_equil=10, n_measure=10)
+    >>> fig = interactive_temperature_sweep(result, T_c=model.T_C)
+    >>> len(fig.data) > 0
+    True
+    """
+    T = result["T"]
+    panels = [
+        ("E", "Energy per site"),
+        ("M" if "M" in result else "m", "Order parameter"),
+        ("C_v", "Specific heat"),
+        ("chi", "Susceptibility"),
+    ]
+    fig = make_subplots(rows=2, cols=2, subplot_titles=[label for _, label in panels])
+    positions = [(1, 1), (1, 2), (2, 1), (2, 2)]
+    for (key, label), (row, col) in zip(panels, positions):
+        if key not in result:
+            continue
+        fig.add_trace(go.Scatter(x=T, y=result[key], mode="lines+markers", name=label), row=row, col=col)
+        if T_c is not None:
+            fig.add_vline(x=T_c, line_dash="dash", line_color="black", row=row, col=col)
+    fig.update_layout(title="Temperature sweep", showlegend=False, height=600)
+    return fig
+
+
+def interactive_vortex_field(theta, vorticity=None, step=1):
+    """Build an interactive XY spin field plot with vortex/antivortex markers.
+
+    Parameters
+    ----------
+    theta : ndarray of shape (L, L)
+        XY model spin angles, e.g. ``XYModel2D.theta``.
+    vorticity : ndarray of shape (L, L), optional
+        Precomputed plaquette vorticity; computed from ``theta`` if omitted.
+    step : int, default=1
+        Subsampling factor for the arrow field.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    if vorticity is None:
+        from physicskit.statphys.core.monte_carlo import xy_plaquette_vorticity
+
+        vorticity = xy_plaquette_vorticity(theta)
+
+    L = theta.shape[0]
+    idx = np.arange(0, L, step)
+    ii, jj = np.meshgrid(idx, idx, indexing="ij")
+    sub_theta = theta[np.ix_(idx, idx)]
+
+    scale = 0.4 * step
+    xs, ys = [], []
+    for a, b, t in zip(ii.ravel(), jj.ravel(), sub_theta.ravel()):
+        xs += [float(b), float(b) + scale * np.cos(t), None]
+        ys += [float(a), float(a) + scale * np.sin(t), None]
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatter(
+            x=xs,
+            y=ys,
+            mode="lines",
+            line={"color": "steelblue"},
+            showlegend=False,
+            hoverinfo="skip",
+        )
+    )
+    vi, vj = np.nonzero(vorticity > 0.5)
+    ai, aj = np.nonzero(vorticity < -0.5)
+    fig.add_trace(go.Scatter(x=vj, y=vi, mode="markers", marker={"color": "red", "size": 10}, name="vortex"))
+    fig.add_trace(
+        go.Scatter(
+            x=aj,
+            y=ai,
+            mode="markers",
+            marker={"color": "blue", "size": 10, "symbol": "x"},
+            name="antivortex",
+        )
+    )
+    fig.update_yaxes(autorange="reversed", scaleanchor="x", scaleratio=1)
+    fig.update_layout(title="XY spin field and vortices", height=600)
+    return fig
+
+
+def interactive_particle_snapshot(gas):
+    """Build an interactive scatter plot of a Lennard-Jones gas snapshot, colored by speed.
+
+    Parameters
+    ----------
+    gas : LennardJonesGas
+        Simulation instance to render.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    speeds = gas.speeds()
+    fig = go.Figure(
+        data=go.Scatter(
+            x=gas.positions[:, 0],
+            y=gas.positions[:, 1],
+            mode="markers",
+            marker={
+                "color": speeds,
+                "colorscale": "Plasma",
+                "showscale": True,
+                "size": 8,
+                "colorbar": {"title": "speed"},
+            },
+            text=[f"speed={s:.2f}" for s in speeds],
+            hoverinfo="text",
+        )
+    )
+    fig.update_xaxes(range=[0, gas.box_size])
+    fig.update_yaxes(range=[0, gas.box_size], scaleanchor="x", scaleratio=1)
+    fig.update_layout(title=f"Lennard-Jones gas, t={gas.time:.2f}", height=600)
+    return fig

physicskit/statphys/visualizers/jarzynski_render.py

@@ -0,0 +1,44 @@
+"""Visualizations of the Jarzynski equality: nonequilibrium work distributions."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+__all__ = ["plot_work_distribution"]
+
+
+def plot_work_distribution(work, dF_true=0.0, dF_estimate=None, ax=None, bins=50):
+    """Histogram nonequilibrium work samples against the true and Jarzynski-estimated free energy.
+
+    Parameters
+    ----------
+    work : array_like
+        Work samples, e.g. from :meth:`JarzynskiHarmonicTrap.run_protocol`.
+    dF_true : float, default=0.0
+        Known equilibrium free energy difference, marked with a solid line.
+    dF_estimate : float, optional
+        Jarzynski-equality estimate of the free energy (e.g. from
+        :meth:`JarzynskiHarmonicTrap.jarzynski_free_energy_estimate`),
+        marked with a dashed line if given.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into.
+    bins : int, default=50
+        Number of histogram bins.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    work = np.asarray(work)
+    if ax is None:
+        _, ax = plt.subplots(figsize=(6, 4))
+    ax.hist(work, bins=bins, density=True, alpha=0.6, label="work samples")
+    ax.axvline(work.mean(), color="tab:blue", linestyle=":", label=rf"$\langle W \rangle$={work.mean():.2f}")
+    ax.axvline(dF_true, color="black", linewidth=2, label=rf"$\Delta F$={dF_true:.2f}")
+    if dF_estimate is not None:
+        ax.axvline(dF_estimate, color="tab:red", linestyle="--", label=rf"Jarzynski $\Delta F$={dF_estimate:.2f}")
+    ax.set_xlabel("work W")
+    ax.set_ylabel("density")
+    ax.legend()
+    return ax

physicskit/statphys/visualizers/kpz_render.py

@@ -0,0 +1,65 @@
+"""Visualizations of KPZ/RSOS interface growth: height profiles and width scaling."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+__all__ = ["plot_interface_profile", "plot_width_growth"]
+
+
+def plot_interface_profile(interface, ax=None):
+    """Plot the current 1D interface height profile.
+
+    Parameters
+    ----------
+    interface : KPZInterface
+        Interface instance to render.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into. A new figure and axes are created if not given.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(7, 3))
+    x = np.arange(interface.L)
+    ax.plot(x, interface.heights, drawstyle="steps-mid")
+    ax.set_xlabel("site")
+    ax.set_ylabel("height h(x)")
+    ax.set_title(f"RSOS interface at t={interface.time:.0f} sweeps")
+    return ax
+
+
+def plot_width_growth(times, widths, ax=None, show_theory=True, beta=1.0 / 3.0):
+    """Log-log plot of interface width vs. time, with a t^beta growth reference line.
+
+    Parameters
+    ----------
+    times, widths : array_like
+        Growth curve, e.g. from :meth:`KPZInterface.run_growth_curve`.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into.
+    show_theory : bool, default=True
+        Overlay a :math:`t^\\beta` reference line (matched in amplitude to
+        the first data point) for the KPZ growth exponent.
+    beta : float, default=1/3
+        Growth exponent for the reference line (the 1+1D KPZ value).
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    times = np.asarray(times)
+    widths = np.asarray(widths)
+    if ax is None:
+        _, ax = plt.subplots(figsize=(5, 4))
+    ax.loglog(times, widths, marker="o", ms=3, linestyle="none", label="simulation")
+    if show_theory:
+        amplitude = widths[0] / times[0] ** beta
+        ax.loglog(times, amplitude * times**beta, linestyle="--", label=rf"$t^{{{beta:.2f}}}$")
+    ax.set_xlabel("t (sweeps)")
+    ax.set_ylabel("interface width w(t)")
+    ax.legend()
+    return ax

physicskit/statphys/visualizers/lattice_render.py

@@ -0,0 +1,212 @@
+"""Static and animated visualizations of lattice spin configurations."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.animation import FuncAnimation
+
+__all__ = [
+    "animate_lattice_sweeps",
+    "plot_cluster_size_distribution",
+    "plot_percolation_clusters",
+    "plot_spin_grid",
+    "plot_thermodynamics",
+]
+
+
+def plot_spin_grid(spins, ax=None, cmap="coolwarm", title=None, colorbar=False):
+    """Render a spin (or Potts state) configuration as a heatmap.
+
+    Parameters
+    ----------
+    spins : ndarray of shape (L, L)
+        Spin configuration, e.g. ``Ising2D.spins`` or ``PottsModel2D.spins``.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into. A new figure and axes are created if not given.
+    cmap : str, default="coolwarm"
+        Matplotlib colormap name.
+    title : str, optional
+        Axes title.
+    colorbar : bool, default=False
+        Whether to attach a colorbar.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+
+    Examples
+    --------
+    >>> from physicskit.statphys.chapters import Ising2D
+    >>> model = Ising2D(L=16, seed=0)
+    >>> ax = plot_spin_grid(model.spins)
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(4, 4))
+    im = ax.imshow(spins, cmap=cmap, interpolation="nearest")
+    ax.set_xticks([])
+    ax.set_yticks([])
+    if title:
+        ax.set_title(title)
+    if colorbar:
+        plt.colorbar(im, ax=ax, fraction=0.046, pad=0.04)
+    return ax
+
+
+def animate_lattice_sweeps(model, beta, n_frames=100, sweeps_per_frame=1, algorithm="metropolis", cmap="coolwarm"):
+    """Animate a lattice model relaxing under repeated Monte Carlo sweeps.
+
+    Parameters
+    ----------
+    model : Ising2D or PottsModel2D
+        A model instance exposing a ``sweep(beta, ...)`` method and a
+        ``spins`` attribute.
+    beta : float
+        Inverse temperature at which to sweep.
+    n_frames : int, default=100
+        Number of animation frames.
+    sweeps_per_frame : int, default=1
+        Sweeps performed between consecutive frames.
+    algorithm : str, default="metropolis"
+        Forwarded to ``model.sweep`` when supported (``Ising2D`` only).
+    cmap : str, default="coolwarm"
+        Matplotlib colormap name.
+
+    Returns
+    -------
+    matplotlib.animation.FuncAnimation
+    """
+    fig, ax = plt.subplots(figsize=(4, 4))
+    im = ax.imshow(model.spins, cmap=cmap, interpolation="nearest")
+    ax.set_xticks([])
+    ax.set_yticks([])
+    title = ax.set_title("sweep 0")
+
+    def update(frame):
+        try:
+            model.sweep(beta, algorithm=algorithm, n_sweeps=sweeps_per_frame)
+        except TypeError:
+            model.sweep(beta, n_sweeps=sweeps_per_frame)
+        im.set_data(model.spins)
+        title.set_text(f"sweep {(frame + 1) * sweeps_per_frame}")
+        return im, title
+
+    return FuncAnimation(fig, update, frames=n_frames, blit=False, interval=50)
+
+
+def plot_thermodynamics(result, T_c=None, ax=None):
+    """Plot energy, magnetization, specific heat, and susceptibility versus temperature.
+
+    Parameters
+    ----------
+    result : dict of str -> ndarray
+        Output of ``Ising2D.run_temperature_sweep`` (or the analogous Potts
+        method, in which case ``"M"``/``"chi"`` keys may be absent).
+    T_c : float, optional
+        Critical temperature to mark with a vertical dashed line on every
+        panel.
+    ax : ndarray of matplotlib.axes.Axes, optional
+        A ``(2, 2)`` array of axes to draw into. A new figure is created if
+        not given.
+
+    Returns
+    -------
+    ndarray of matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots(2, 2, figsize=(9, 7), sharex=True)
+    T = result["T"]
+
+    panels = [
+        (ax[0, 0], "E", "Energy per site"),
+        (ax[0, 1], "M" if "M" in result else "m", "Magnetization / order parameter"),
+        (ax[1, 0], "C_v", "Specific heat"),
+        (ax[1, 1], "chi", "Susceptibility"),
+    ]
+    for axis, key, label in panels:
+        if key not in result:
+            axis.axis("off")
+            continue
+        axis.plot(T, result[key], marker="o", ms=3)
+        axis.set_ylabel(label)
+        axis.set_xlabel("Temperature")
+        if T_c is not None:
+            axis.axvline(T_c, color="k", linestyle="--", linewidth=1, alpha=0.6)
+    plt.tight_layout()
+    return ax
+
+
+def plot_percolation_clusters(percolation, ax=None, highlight_spanning=True, cmap="nipy_spectral"):
+    """Render a percolation lattice with each connected cluster in a distinct color.
+
+    Parameters
+    ----------
+    percolation : Percolation2D
+        Percolation instance whose current ``labels`` should be drawn.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into. A new figure and axes are created if not given.
+    highlight_spanning : bool, default=True
+        Whether to redraw spanning clusters (if any) in solid black on top
+        of the color-coded background.
+    cmap : str, default="nipy_spectral"
+        Colormap used to distinguish clusters. Unoccupied sites are drawn in
+        white.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(5, 5))
+    labels = percolation.labels
+    display = np.ma.masked_equal(labels, 0)
+    cmap_obj = plt.get_cmap(cmap).copy()
+    cmap_obj.set_bad("white")
+    ax.imshow(display, cmap=cmap_obj, interpolation="nearest")
+    if highlight_spanning:
+        spanning = percolation.spanning_labels()
+        if len(spanning):
+            mask = np.isin(labels, spanning)
+            spanning_display = np.ma.masked_where(~mask, mask.astype(float))
+            ax.imshow(spanning_display, cmap="Greys", vmin=0, vmax=1, alpha=0.7, interpolation="nearest")
+    ax.set_xticks([])
+    ax.set_yticks([])
+    ax.set_title(f"{percolation.mode} percolation, p = {percolation.p:.3f}")
+    return ax
+
+
+def plot_cluster_size_distribution(sizes, ax=None, bins=30, tau_theory=187 / 91):
+    """Log-log histogram of percolation cluster sizes against the theoretical Fisher exponent.
+
+    Parameters
+    ----------
+    sizes : array_like
+        Cluster sizes, e.g. from ``Percolation2D.cluster_size_distribution``.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into.
+    bins : int, default=30
+        Number of logarithmically spaced bins.
+    tau_theory : float, default=187/91
+        Theoretical Fisher exponent to overlay as a reference power law.
+        Pass ``None`` to omit it.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    sizes = np.asarray(sizes)
+    sizes = sizes[sizes > 0]
+    if ax is None:
+        _, ax = plt.subplots(figsize=(5, 4))
+    log_bins = np.logspace(0, np.log10(sizes.max()), bins)
+    counts, edges = np.histogram(sizes, bins=log_bins, density=True)
+    centers = np.sqrt(edges[:-1] * edges[1:])
+    mask = counts > 0
+    ax.loglog(centers[mask], counts[mask], marker="o", ms=3, linestyle="none", label="simulation")
+    if tau_theory is not None and np.any(mask):
+        ref = counts[mask][0] * (centers[mask] / centers[mask][0]) ** (-tau_theory)
+        ax.loglog(centers[mask], ref, linestyle="--", color="k", label=f"$s^{{-{tau_theory:.3f}}}$")
+    ax.set_xlabel("cluster size s")
+    ax.set_ylabel("P(s)")
+    ax.legend()
+    return ax

physicskit/statphys/visualizers/particle_render.py

@@ -0,0 +1,121 @@
+"""Visualizations of the Lennard-Jones gas: particle snapshots and velocity statistics."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.animation import FuncAnimation
+
+from physicskit.statphys.utils.thermodynamics import maxwell_boltzmann_speed_pdf
+
+__all__ = ["animate_gas", "plot_particle_snapshot", "plot_velocity_histogram"]
+
+
+def plot_particle_snapshot(gas, ax=None, show_velocities=False, color_by_speed=True):
+    """Draw a single snapshot of the particle gas's positions.
+
+    Parameters
+    ----------
+    gas : LennardJonesGas
+        Simulation instance to render.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into. A new figure and axes are created if not given.
+    show_velocities : bool, default=False
+        Whether to overlay velocity vectors as arrows.
+    color_by_speed : bool, default=True
+        Whether to color particles by their instantaneous speed.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(5, 5))
+    speeds = gas.speeds()
+    c = speeds if color_by_speed else "steelblue"
+    scatter = ax.scatter(gas.positions[:, 0], gas.positions[:, 1], c=c, cmap="plasma", s=25)
+    if color_by_speed:
+        plt.colorbar(scatter, ax=ax, fraction=0.046, pad=0.04, label="speed")
+    if show_velocities:
+        ax.quiver(
+            gas.positions[:, 0],
+            gas.positions[:, 1],
+            gas.velocities[:, 0],
+            gas.velocities[:, 1],
+            color="black",
+            alpha=0.5,
+            scale_units="xy",
+            angles="xy",
+            scale=1.0,
+        )
+    ax.set_xlim(0, gas.box_size)
+    ax.set_ylim(0, gas.box_size)
+    ax.set_aspect("equal")
+    ax.set_title(f"t = {gas.time:.2f}, T = {gas.temperature():.2f}")
+    return ax
+
+
+def plot_velocity_histogram(gas, ax=None, bins=40, show_theory=True):
+    """Plot the current speed histogram against the theoretical Maxwell-Boltzmann curve.
+
+    Parameters
+    ----------
+    gas : LennardJonesGas
+        Simulation instance to render.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into.
+    bins : int, default=40
+        Histogram bin count.
+    show_theory : bool, default=True
+        Whether to overlay the equilibrium Maxwell-Boltzmann density at the
+        gas's instantaneous kinetic temperature.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(5, 4))
+    speeds = gas.speeds()
+    ax.hist(speeds, bins=bins, density=True, alpha=0.6, color="steelblue", label="simulation")
+    if show_theory:
+        v = np.linspace(0, speeds.max() * 1.2, 200)
+        pdf = maxwell_boltzmann_speed_pdf(v, gas.temperature(), mass=gas.mass, kB=gas.kB, dim=2)
+        ax.plot(v, pdf, color="crimson", linewidth=2, label="Maxwell-Boltzmann")
+    ax.set_xlabel("speed")
+    ax.set_ylabel("probability density")
+    ax.legend()
+    return ax
+
+
+def animate_gas(gas, n_frames=200, steps_per_frame=5):
+    """Animate the particle gas evolving under Velocity Verlet dynamics.
+
+    Parameters
+    ----------
+    gas : LennardJonesGas
+        Simulation instance to animate; advanced in place.
+    n_frames : int, default=200
+        Number of animation frames.
+    steps_per_frame : int, default=5
+        Integration steps performed between consecutive frames.
+
+    Returns
+    -------
+    matplotlib.animation.FuncAnimation
+    """
+    fig, ax = plt.subplots(figsize=(5, 5))
+    scatter = ax.scatter(gas.positions[:, 0], gas.positions[:, 1], c=gas.speeds(), cmap="plasma", s=25)
+    ax.set_xlim(0, gas.box_size)
+    ax.set_ylim(0, gas.box_size)
+    ax.set_aspect("equal")
+    title = ax.set_title(f"t = {gas.time:.2f}")
+
+    def update(_frame):
+        gas.step(steps_per_frame)
+        scatter.set_offsets(gas.positions)
+        scatter.set_array(gas.speeds())
+        title.set_text(f"t = {gas.time:.2f}, T = {gas.temperature():.2f}")
+        return scatter, title
+
+    return FuncAnimation(fig, update, frames=n_frames, blit=False, interval=40)