physicskit 0.1.0__py3-none-any.whl

physicskit/statphys/visualizers/random_walk_render.py

@@ -0,0 +1,106 @@
+"""Visualizations of random walk trajectories and diffusive scaling."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+__all__ = ["plot_clt_histogram", "plot_msd", "plot_trajectories_2d"]
+
+
+def plot_trajectories_2d(walk, ax=None, n_show=20):
+    """Plot a subset of a 2D random walk ensemble's trajectories.
+
+    Parameters
+    ----------
+    walk : RandomWalk
+        A walk instance with ``dim=2``; run automatically if not already.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into. A new figure and axes are created if not given.
+    n_show : int, default=20
+        Number of individual trajectories to draw.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if walk.dim != 2:
+        raise ValueError("plot_trajectories_2d requires a RandomWalk with dim=2")
+    if walk.trajectories is None:
+        walk.run()
+    if ax is None:
+        _, ax = plt.subplots(figsize=(5, 5))
+    n_show = min(n_show, walk.n_walkers)
+    for w in range(n_show):
+        ax.plot(walk.trajectories[:, w, 0], walk.trajectories[:, w, 1], alpha=0.6, linewidth=0.8)
+    ax.set_xlabel("x")
+    ax.set_ylabel("y")
+    ax.set_aspect("equal")
+    ax.set_title(f"{n_show} random walk trajectories")
+    return ax
+
+
+def plot_msd(walk, ax=None, show_theory=True):
+    """Plot the ensemble mean squared displacement against the Einstein-relation prediction.
+
+    Parameters
+    ----------
+    walk : RandomWalk
+        Walk instance to summarize.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into.
+    show_theory : bool, default=True
+        Whether to overlay the fitted line :math:`2 d D t`.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    t, msd = walk.mean_squared_displacement()
+    if ax is None:
+        _, ax = plt.subplots(figsize=(5, 4))
+    ax.plot(t, msd, label="simulation")
+    if show_theory:
+        D = walk.diffusion_coefficient()
+        ax.plot(t, 2 * walk.dim * D * t, linestyle="--", label=f"$2dDt$, D={D:.3f}")
+    ax.set_xlabel("t")
+    ax.set_ylabel("MSD(t)")
+    ax.legend()
+    return ax
+
+
+def plot_clt_histogram(walk, ax=None, axis=0, bins=40):
+    """Histogram the final-time displacement against the Gaussian predicted by the CLT.
+
+    Parameters
+    ----------
+    walk : RandomWalk
+        Walk instance to summarize.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into.
+    axis : int, default=0
+        Spatial axis to histogram.
+    bins : int, default=40
+        Number of histogram bins.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    from physicskit.statphys.utils.thermodynamics import maxwell_boltzmann_component_pdf
+
+    centers, density = walk.final_displacement_histogram(axis=axis, bins=bins)
+    if ax is None:
+        _, ax = plt.subplots(figsize=(5, 4))
+    ax.bar(centers, density, width=(centers[1] - centers[0]), alpha=0.6, label="simulation")
+
+    if walk.trajectories is None:
+        walk.run()
+    var = np.var(walk.trajectories[-1, :, axis])
+    xs = np.linspace(centers.min(), centers.max(), 200)
+    gaussian = maxwell_boltzmann_component_pdf(xs, temperature=var, mass=1.0, kB=1.0)
+    ax.plot(xs, gaussian, color="crimson", label="Gaussian (CLT)")
+    ax.set_xlabel(f"final displacement (axis {axis})")
+    ax.set_ylabel("density")
+    ax.legend()
+    return ax

physicskit/statphys/visualizers/rg_render.py

@@ -0,0 +1,45 @@
+"""Visualization of block-spin renormalization group flows."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+
+__all__ = ["plot_rg_flow"]
+
+
+def plot_rg_flow(grids, titles=None, cmap="coolwarm"):
+    """Plot a sequence of coarse-grained lattices side by side.
+
+    Parameters
+    ----------
+    grids : list of ndarray
+        Sequence of spin configurations at increasing coarse-graining
+        levels, e.g. the output of ``BlockSpinRG.iterate``.
+    titles : list of str, optional
+        One title per panel. Defaults to ``"L = {size}"`` for each grid.
+    cmap : str, default="coolwarm"
+        Matplotlib colormap name.
+
+    Returns
+    -------
+    ndarray of matplotlib.axes.Axes
+
+    Examples
+    --------
+    >>> from physicskit.statphys.chapters import BlockSpinRG
+    >>> rg = BlockSpinRG(L=16, T=2.269, seed=0)
+    >>> axes = plot_rg_flow(rg.iterate())
+    """
+    n = len(grids)
+    _fig, axes = plt.subplots(1, n, figsize=(3 * n, 3))
+    if n == 1:
+        axes = [axes]
+    if titles is None:
+        titles = [f"L = {g.shape[0]}" for g in grids]
+    for ax, grid, title in zip(axes, grids, titles):
+        ax.imshow(grid, cmap=cmap, interpolation="nearest")
+        ax.set_title(title)
+        ax.set_xticks([])
+        ax.set_yticks([])
+    plt.tight_layout()
+    return axes

physicskit/statphys/visualizers/sandpile_render.py

@@ -0,0 +1,65 @@
+"""Visualizations of the BTW sandpile: pile heights and avalanche statistics."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+__all__ = ["plot_avalanche_size_distribution", "plot_sandpile_heights"]
+
+
+def plot_sandpile_heights(sandpile, ax=None, cmap="viridis"):
+    """Render the current pile heights as a heatmap.
+
+    Parameters
+    ----------
+    sandpile : BTWSandpile
+        Sandpile instance to render.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into. A new figure and axes are created if not given.
+    cmap : str, default="viridis"
+        Matplotlib colormap name.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(5, 5))
+    im = ax.imshow(sandpile.heights, cmap=cmap, vmin=0, vmax=sandpile.threshold - 1, interpolation="nearest")
+    plt.colorbar(im, ax=ax, fraction=0.046, pad=0.04, label="height")
+    ax.set_xticks([])
+    ax.set_yticks([])
+    ax.set_title(f"Sandpile: {sandpile.total_grains()} grains")
+    return ax
+
+
+def plot_avalanche_size_distribution(sizes, ax=None, bins=40):
+    """Log-log histogram of avalanche sizes, the self-organized-criticality power-law signature.
+
+    Parameters
+    ----------
+    sizes : array_like
+        Avalanche sizes, e.g. from :meth:`BTWSandpile.run`.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into.
+    bins : int, default=40
+        Number of logarithmically spaced bins.
+
+    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")
+    ax.set_xlabel("avalanche size s")
+    ax.set_ylabel("P(s)")
+    ax.set_title("Avalanche size distribution (SOC power law)")
+    return ax

physicskit/statphys/visualizers/spin_glass_render.py

@@ -0,0 +1,40 @@
+"""Visualizations of spin-glass replica overlaps."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+__all__ = ["plot_overlap_distribution"]
+
+
+def plot_overlap_distribution(samples, ax=None, bins=40, label=None):
+    """Histogram the replica-overlap samples P(q).
+
+    Parameters
+    ----------
+    samples : array_like
+        Overlap samples in ``[-1, 1]``, e.g. from
+        :meth:`SherringtonKirkpatrick.overlap_distribution`.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into. A new figure and axes are created if not given.
+    bins : int, default=40
+        Number of histogram bins.
+    label : str, optional
+        Legend label for this histogram (useful when overlaying several
+        temperatures on the same axes).
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    samples = np.asarray(samples)
+    if ax is None:
+        _, ax = plt.subplots(figsize=(6, 4))
+    ax.hist(samples, bins=bins, range=(-1, 1), density=True, alpha=0.6, label=label)
+    ax.set_xlabel("overlap q")
+    ax.set_ylabel("P(q)")
+    ax.set_xlim(-1, 1)
+    if label is not None:
+        ax.legend()
+    return ax

physicskit/statphys/visualizers/urn_render.py

@@ -0,0 +1,38 @@
+"""Visualization of the Ehrenfest urn model's relaxation to equilibrium."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+
+__all__ = ["plot_ehrenfest_history"]
+
+
+def plot_ehrenfest_history(history, n_balls, ax=None):
+    """Plot the box occupancy and entropy history of an Ehrenfest urn run.
+
+    Parameters
+    ----------
+    history : dict of str -> ndarray
+        Output of :meth:`EhrenfestUrn.run`.
+    n_balls : int
+        Total ball count, used to mark the equilibrium level N/2.
+    ax : ndarray of matplotlib.axes.Axes, optional
+        A pair 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(1, 2, figsize=(10, 4))
+    ax[0].plot(history["t"], history["n_left"], linewidth=0.8)
+    ax[0].axhline(n_balls / 2, color="k", linestyle="--", linewidth=1, alpha=0.6)
+    ax[0].set_xlabel("step")
+    ax[0].set_ylabel("balls in left box")
+    ax[0].set_title("Relaxation to equilibrium")
+
+    ax[1].plot(history["t"], history["entropy"], color="crimson")
+    ax[1].set_xlabel("step")
+    ax[1].set_ylabel("entropy $S/k_B$")
+    ax[1].set_title("Monotonic entropy growth")
+    return ax

physicskit/statphys/visualizers/vortex_render.py

@@ -0,0 +1,84 @@
+"""Visualizations of the XY model: spin vector fields and topological vortices."""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+__all__ = ["plot_vortices", "plot_xy_vector_field"]
+
+
+def plot_xy_vector_field(theta, ax=None, step=1, cmap="hsv"):
+    """Draw the XY model's planar spins as a quiver plot, colored by angle.
+
+    Parameters
+    ----------
+    theta : ndarray of shape (L, L)
+        Spin angles in radians, e.g. ``XYModel2D.theta``.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into. A new figure and axes are created if not given.
+    step : int, default=1
+        Subsample every ``step``-th spin along each axis, useful for large
+        lattices where a dense quiver plot is unreadable.
+    cmap : str, default="hsv"
+        Colormap used to color arrows by their angle (a cyclic colormap is
+        the natural choice for a periodic quantity).
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(5, 5))
+    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)]
+    u = np.cos(sub_theta)
+    v = np.sin(sub_theta)
+    ax.quiver(jj, ii, u, v, sub_theta, cmap=cmap, pivot="mid", angles="xy", clim=(0, 2 * np.pi))
+    ax.set_xlim(-1, L)
+    ax.set_ylim(-1, L)
+    ax.set_aspect("equal")
+    ax.invert_yaxis()
+    ax.set_xticks([])
+    ax.set_yticks([])
+    return ax
+
+
+def plot_vortices(theta, vorticity=None, ax=None, threshold=0.5, step=1):
+    """Overlay the XY spin field with markers at vortex and antivortex cores.
+
+    Parameters
+    ----------
+    theta : ndarray of shape (L, L)
+        Spin angles in radians.
+    vorticity : ndarray of shape (L, L), optional
+        Precomputed plaquette vorticity (see
+        :func:`physicskit.statphys.core.monte_carlo.xy_plaquette_vorticity`); computed
+        from ``theta`` if not given.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into.
+    threshold : float, default=0.5
+        Minimum ``|vorticity|`` to mark as a topological charge.
+    step : int, default=1
+        Subsampling for the underlying vector field, forwarded to
+        :func:`plot_xy_vector_field`.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    if vorticity is None:
+        from physicskit.statphys.core.monte_carlo import xy_plaquette_vorticity
+
+        vorticity = xy_plaquette_vorticity(theta)
+
+    ax = plot_xy_vector_field(theta, ax=ax, step=step)
+    vi, vj = np.nonzero(vorticity > threshold)
+    ai, aj = np.nonzero(vorticity < -threshold)
+    ax.scatter(vj + 0.5, vi + 0.5, c="red", marker="o", s=60, label="vortex (+1)", zorder=5)
+    ax.scatter(aj + 0.5, ai + 0.5, c="blue", marker="x", s=60, label="antivortex (-1)", zorder=5)
+    if len(vi) or len(ai):
+        ax.legend(loc="upper right", fontsize=8, framealpha=0.9)
+    return ax

physicskit/tests/test_constants.py

@@ -0,0 +1,38 @@
+"""Tests for physicskit.constants."""
+
+import pytest
+
+import physicskit.constants as const
+
+
+def test_speed_of_light_exact():
+    assert const.C == 299_792_458.0
+
+
+def test_energy_temperature_roundtrip():
+    T = 300.0
+    E = const.temperature_to_energy(T)
+    assert const.energy_to_temperature(E) == pytest.approx(T)
+
+
+def test_ev_joule_roundtrip():
+    E_ev = 13.6
+    assert const.joules_to_ev(const.ev_to_joules(E_ev)) == pytest.approx(E_ev)
+
+
+def test_electronvolt_matches_elementary_charge():
+    # 1 eV is, by definition, the elementary charge times 1 volt.
+    assert const.ELECTRONVOLT == pytest.approx(const.ELEMENTARY_CHARGE)
+
+
+def test_gravitational_unit_system_consistent_with_G():
+    units = const.gravitational_unit_system(length_m=const.PARSEC_M, mass_kg=const.SOLAR_MASS_KG)
+    # G_SI = length_m^3 / (mass_kg * time_s^2) should reproduce G by construction.
+    recovered_G = units["length_m"] ** 3 / (units["mass_kg"] * units["time_s"] ** 2)
+    assert recovered_G == pytest.approx(const.G)
+    assert units["velocity_m_s"] == pytest.approx(units["length_m"] / units["time_s"])
+
+
+def test_gravitational_unit_system_rejects_nonpositive_inputs():
+    with pytest.raises(ZeroDivisionError):
+        const.gravitational_unit_system(length_m=1.0, mass_kg=0.0)

physicskit-0.1.0.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: physicskit
+Version: 0.1.0
+Summary: Unified scientific toolkit for computational physics: General Relativity, Quantum Mechanics, Chaos, Random Matrix Theory, Statistical Mechanics, Classical Dynamics, and Condensed Matter.
+Author-email: Charles Poli <cpoli374@gmail.com>
+Maintainer-email: Charles Poli <cpoli374@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/cpoli/physicskit
+Project-URL: Issues, https://github.com/cpoli/physicskit/issues
+Project-URL: Changelog, https://github.com/cpoli/physicskit/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://physicskit.readthedocs.io
+Keywords: physics,condensed-matter,general-relativity,quantum-mechanics,chaos,random-matrix-theory,statistical-mechanics,classical-mechanics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: numba>=0.58
+Requires-Dist: plotly>=5.15
+Requires-Dist: sympy>=1.11
+Requires-Dist: tqdm>=4.65
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-xdist>=3.0; extra == "test"
+Requires-Dist: hypothesis>=6.90; extra == "test"
+Requires-Dist: pillow>=9.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Requires-Dist: sphinx-gallery>=0.15; extra == "docs"
+Requires-Dist: sphinx-design>=0.6; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: physicskit[docs,test]; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Dynamic: license-file
+
+# physicskit
+
+| | |
+|:--|:-:|
+| Package | [![PyPI version](https://img.shields.io/pypi/v/physicskit)](https://pypi.org/project/physicskit/) [![Python versions](https://img.shields.io/pypi/pyversions/physicskit)](https://pypi.org/project/physicskit/) |
+| Quality | [![License](https://img.shields.io/github/license/cpoli/physicskit)](https://github.com/cpoli/physicskit/blob/main/LICENSE) [![CI](https://github.com/cpoli/physicskit/actions/workflows/ci.yml/badge.svg)](https://github.com/cpoli/physicskit/actions/workflows/ci.yml) [![Coverage](https://img.shields.io/codecov/c/github/cpoli/physicskit)](https://codecov.io/gh/cpoli/physicskit) |
+| Documentation | [![Docs](https://readthedocs.org/projects/physicskit/badge/?version=latest)](https://physicskit.readthedocs.io) |
+| Code style | [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
+| Downloads | [![Downloads](https://static.pepy.tech/badge/physicskit)](https://pepy.tech/project/physicskit) [![Downloads/Month](https://static.pepy.tech/badge/physicskit/month)](https://pepy.tech/project/physicskit) |
+| Community | [![GitHub Stars](https://img.shields.io/github/stars/cpoli/physicskit?style=social)](https://github.com/cpoli/physicskit) [![GitHub Forks](https://img.shields.io/github/forks/cpoli/physicskit?style=social)](https://github.com/cpoli/physicskit) [![Contributors](https://img.shields.io/github/contributors/cpoli/physicskit)](https://github.com/cpoli/physicskit/graphs/contributors) [![Last Commit](https://img.shields.io/github/last-commit/cpoli/physicskit)](https://github.com/cpoli/physicskit/commits/main) |
+
+A unified scientific toolkit for computational physics, spanning the
+field end to end: the quantum mechanics of a single hydrogen atom, the
+numerical relativity of colliding black holes, turbulent fluid
+instabilities, topological superconductors, magnetically confined
+plasmas, and chaotic quantum billiards -- with each domain's docs
+tracing the field's own foundational breakthroughs in chronological,
+pedagogical order, every historical milestone linked directly to the
+runnable code that reproduces it. 14 domain subpackages, one consistent
+NumPy-based API, sharing common ODE integrators and physical constants
+throughout. Conventionally imported as `pk`.
+
+## Install
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+import physicskit as pk
+import numpy as np
+
+H = lambda k1, k2: pk.condensed.haldane_model(k1, k2, phi=np.pi / 2)
+chern_numbers = pk.condensed.compute_chern_number(H, grid_size=30)
+print(chern_numbers)  # [1, -1]
+```
+
+Every subpackage below links to its worked examples; see
+[Subpackages](#subpackages) for the full list, or browse the docs at
+<https://physicskit.readthedocs.io>.
+
+## Subpackages
+
+Domain subpackages, each with runnable examples linked below:
+
+- [`physicskit.astro`](https://physicskit.readthedocs.io/en/latest/examples/astro.html) -- stellar structure (Tolman-Oppenheimer-Volkoff, polytropes), N-body dynamics, orbital mechanics, galactic rotation curves, stellar convection and the magnetic dynamo.
+- [`physicskit.chaos`](https://physicskit.readthedocs.io/en/latest/examples/chaos.html) -- chaotic dynamical systems and 2D quantum billiards.
+- [`physicskit.classical`](https://physicskit.readthedocs.io/en/latest/examples/classical.html) -- classical mechanics: Newtonian, Lagrangian, Hamiltonian, lattice, and rigid-body dynamics.
+- [`physicskit.condensed`](https://physicskit.readthedocs.io/en/latest/examples/condensed.html) -- tight-binding models, topological band theory (Chern numbers, edge states), correlated-electron superconductivity.
+- [`physicskit.fields`](https://physicskit.readthedocs.io/en/latest/examples/fields.html) -- FDTD electrodynamics, KdV/NLS/Sine-Gordon solitons, BEC vortex lattices.
+- [`physicskit.fluids`](https://physicskit.readthedocs.io/en/latest/examples/fluids.html) -- potential flow, viscous exact solutions, point-vortex dynamics, Kelvin-Helmholtz and Rayleigh-Taylor instabilities, compressible shocks, and the 2D incompressible Navier-Stokes solver underlying them.
+- [`physicskit.optics`](https://physicskit.readthedocs.io/en/latest/examples/optics.html) -- ray, wave, and Gaussian-beam optics; quantum optics (squeezed states, Wigner functions).
+- [`physicskit.particle`](https://physicskit.readthedocs.io/en/latest/examples/particle.html) -- relativistic kinematics, particle decays and scattering, nuclear physics.
+- [`physicskit.plasma`](https://physicskit.readthedocs.io/en/latest/examples/plasma.html) -- Boris-pusher single-particle motion, guiding-center drifts, Grad-Shafranov MHD equilibrium, magnetic reconnection, cold-plasma wave dispersion, particle-in-cell Vlasov-Poisson kinetics.
+- [`physicskit.quantum`](https://physicskit.readthedocs.io/en/latest/examples/quantum.html) -- quantum mechanics: wave packets, potentials, hydrogen, entanglement, measurement.
+- [`physicskit.relativity`](https://physicskit.readthedocs.io/en/latest/examples/relativity.html) -- numerical general relativity: black holes, lensing, gravitational waves, cosmology.
+- [`physicskit.rmt`](https://physicskit.readthedocs.io/en/latest/examples/rmt.html) -- random matrix theory, organized around Dyson's threefold way.
+- [`physicskit.semiclassical`](https://physicskit.readthedocs.io/en/latest/examples/semiclassical.html) -- WKB/EBK quantization, Van Vleck/Herman-Kluk semiclassical propagators, the Gutzwiller trace formula, and quantum scarring.
+- [`physicskit.statphys`](https://physicskit.readthedocs.io/en/latest/examples/statphys.html) -- statistical mechanics: lattice models, molecular dynamics, criticality, disordered systems.
+
+Shared infrastructure, used across the subpackages above rather than
+standalone toolkits:
+
+- `physicskit.constants` -- SI physical constants shared across subpackages, plus a few well-defined unit conversions (energy/temperature, eV/joules, gravitational G=1 unit systems).
+- `physicskit.integrators` -- shared numerical ODE integrators (RK4, leapfrog, Yoshida4, adaptive Dormand-Prince) used across the other subpackages.
+
+## Test
+
+Tests live alongside each subpackage, at `physicskit/<name>/tests/`.
+
+```bash
+pytest                                              # everything
+pytest physicskit/rmt/tests                         # a single subpackage
+
+# docstring examples, across every subpackage (pyvista's 3D viewer is
+# optional and skipped rather than installed as a hard test dependency):
+MPLBACKEND=Agg pytest --doctest-modules physicskit \
+    --ignore-glob="*/tests/*" \
+    --ignore=physicskit/chaos/visualizers/viewer3d.py
+```
+
+Both commands, plus `ruff check`/`ruff format --check`, run in CI on
+every PR (`.github/workflows/ci.yml`) across Python 3.10-3.12 on Linux and
+macOS. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
+
+### Coverage
+
+```bash
+MPLBACKEND=Agg pytest -q -n auto --cov=physicskit --cov-report=term
+```
+
+1,720 tests, 96% line coverage overall. Per-subpackage coverage:
+
+| Subpackage | Coverage | | Subpackage | Coverage |
+|:--|--:|---|:--|--:|
+| `astro` | 100% | | `plasma` | 99% |
+| `chaos` | 87% | | `quantum` | 96% |
+| `classical` | 100% | | `relativity` | 99% |
+| `condensed` | 100% | | `rmt` | 100% |
+| `fields` | 100% | | `semiclassical` | 99% |
+| `fluids` | 100% | | `statphys` | 86% |
+| `integrators` | 100% | | `constants` | 100% |
+| `optics` | 100% | | | |
+| `particle` | 100% | | | |
+
+Every subpackage is at 100% coverage outside `visualizers/` modules (99.9%
+in aggregate — six rare bootstrap-loop edge cases remain uncovered across
+`statphys.chapters.percolation` and `rmt.stats`). `chaos`, `quantum`, and
+`statphys` still sit lower overall because their `visualizers/` modules
+are smoke-tested only (correct return type/shape, or that `anim.save()`
+succeeds) rather than covered line-by-line, per the testing convention in
+[CLAUDE.md](CLAUDE.md). `@njit`-compiled lines are excluded from coverage
+entirely (`pyproject.toml`, `[tool.coverage.report]`) since
+`coverage.py` cannot trace into numba-compiled native code.
+
+## Docs
+
+Built docs are hosted at <https://physicskit.readthedocs.io>. To build
+locally:
+
+```bash
+pip install -e ".[docs]"
+cd docs && make html
+```
+
+See `docs/source/history/` for a chronology of each field's foundational
+breakthroughs, linked to the corresponding implementation at each step.
+
+## Citation
+
+If you use physicskit in your research, please cite it — see
+[CITATION.cff](CITATION.cff).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Please note that this project
+follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
+
+## License
+
+MIT -- see [LICENSE](LICENSE).