physicskit 0.1.0__py3-none-any.whl

physicskit/statphys/tests/test_renormalization.py

@@ -0,0 +1,44 @@
+import numpy as np
+import pytest
+
+from physicskit.statphys.chapters.renormalization import BlockSpinRG
+
+
+def test_iterate_shrinks_grid_by_half_each_step():
+    rg = BlockSpinRG(L=16, T=100.0, seed=0, n_equil_sweeps=5)
+    grids = rg.iterate(n_steps=3)
+    assert [g.shape[0] for g in grids] == [16, 8, 4, 2]
+
+
+def test_default_n_steps_stops_at_2x2():
+    rg = BlockSpinRG(L=16, T=100.0, seed=0, n_equil_sweeps=5)
+    grids = rg.iterate()
+    assert grids[-1].shape == (2, 2)
+
+
+def test_high_temperature_flows_toward_disorder():
+    rg = BlockSpinRG(L=32, T=1000.0, seed=1, n_equil_sweeps=5)
+    grids = rg.iterate(n_steps=4)
+    orders = [rg.order_parameter(g) for g in grids]
+    # disordered starting point: order parameter should stay small throughout
+    assert orders[0] < 0.3
+
+
+def test_low_temperature_flows_toward_order():
+    rg = BlockSpinRG(L=32, T=0.5, seed=2, n_equil_sweeps=200)
+    grids = rg.iterate(n_steps=3)
+    orders = [rg.order_parameter(g) for g in grids]
+    assert orders[-1] > 0.8
+
+
+def test_coarse_grain_step_requires_even_size():
+    rg = BlockSpinRG(L=16, T=100.0, seed=0, n_equil_sweeps=1)
+    with pytest.raises(ValueError):
+        rg.coarse_grain_step(np.ones((5, 5), dtype=np.int64))
+
+
+def test_majority_rule_unanimous_block():
+    rg = BlockSpinRG(L=8, T=100.0, seed=3, n_equil_sweeps=1)
+    block = np.ones((4, 4), dtype=np.int64)
+    coarse = rg.coarse_grain_step(block)
+    assert np.all(coarse == 1)

physicskit/statphys/tests/test_sandpile.py

@@ -0,0 +1,44 @@
+import numpy as np
+
+from physicskit.statphys.chapters.sandpile import BTWSandpile
+
+
+def test_initial_heights_are_zero():
+    pile = BTWSandpile(L=10, seed=0)
+    assert np.all(pile.heights == 0)
+
+
+def test_heights_stay_below_threshold_after_relaxation():
+    pile = BTWSandpile(L=16, seed=1)
+    pile.run(n_grains=500)
+    assert np.all(pile.heights < pile.threshold)
+
+
+def test_avalanche_sizes_are_non_negative():
+    pile = BTWSandpile(L=16, seed=2)
+    sizes = pile.run(n_grains=200)
+    assert np.all(sizes >= 0)
+
+
+def test_add_grain_at_specific_site_below_threshold():
+    pile = BTWSandpile(L=10, threshold=4, seed=3)
+    size = pile.add_grain(site=(5, 5))
+    assert size == 0
+    assert pile.heights[5, 5] == 1
+
+
+def test_forced_toppling_conserves_grains_in_bulk():
+    pile = BTWSandpile(L=20, threshold=4, seed=4)
+    pile.heights[10, 10] = 3
+    grains_before = pile.total_grains()
+    size = pile.add_grain(site=(10, 10))
+    assert size == 1
+    # a single interior toppling conserves grains (4 out, 4 in); only the
+    # one added grain changes the total.
+    assert pile.total_grains() == grains_before + 1
+
+
+def test_large_run_produces_nontrivial_avalanches():
+    pile = BTWSandpile(L=24, seed=5)
+    sizes = pile.run(n_grains=2000, warmup=1000)
+    assert sizes.max() > 1

physicskit/statphys/tests/test_spin_glass.py

@@ -0,0 +1,73 @@
+import numpy as np
+import pytest
+
+from physicskit.statphys.chapters.spin_glass import EdwardsAndersonSpinGlass2D, SherringtonKirkpatrick
+
+
+def test_bonds_are_bimodal():
+    model = EdwardsAndersonSpinGlass2D(L=10, J=1.0, seed=0)
+    assert set(np.unique(model.J_right)) <= {-1.0, 1.0}
+    assert set(np.unique(model.J_down)) <= {-1.0, 1.0}
+
+
+def test_frustration_density_between_zero_and_one():
+    model = EdwardsAndersonSpinGlass2D(L=20, seed=1)
+    f = model.frustration_density()
+    assert 0.0 <= f <= 1.0
+
+
+def test_frustration_density_near_one_half_for_random_bonds():
+    model = EdwardsAndersonSpinGlass2D(L=40, seed=2)
+    assert model.frustration_density() == pytest.approx(0.5, abs=0.05)
+
+
+def test_ferromagnet_has_zero_frustration():
+    model = EdwardsAndersonSpinGlass2D(L=10, seed=3)
+    model.J_right[:] = 1.0
+    model.J_down[:] = 1.0
+    assert model.frustration_density() == pytest.approx(0.0)
+
+
+def test_sweep_changes_configuration():
+    model = EdwardsAndersonSpinGlass2D(L=16, seed=4)
+    before = model.spins.copy()
+    model.sweep(beta=1.0, n_sweeps=5)
+    assert not np.array_equal(before, model.spins)
+
+
+def test_energy_is_finite():
+    model = EdwardsAndersonSpinGlass2D(L=12, seed=5)
+    model.sweep(beta=1.0, n_sweeps=10)
+    assert np.isfinite(model.energy())
+
+
+def test_ea_order_parameter_bounds():
+    model = EdwardsAndersonSpinGlass2D(L=8, seed=6)
+    q2 = model.edwards_anderson_order_parameter(beta=2.0, n_equil=20, n_measure=20)
+    assert 0.0 <= q2 <= 1.0 + 1e-9
+
+
+def test_sk_coupling_matrix_is_symmetric_with_zero_diagonal():
+    model = SherringtonKirkpatrick(N=30, seed=0)
+    assert np.allclose(model.J, model.J.T)
+    assert np.all(np.diag(model.J) == 0.0)
+
+
+def test_sk_sweep_changes_configuration():
+    model = SherringtonKirkpatrick(N=40, seed=1)
+    before = model.spins.copy()
+    model.sweep(beta=1.0, n_sweeps=5)
+    assert not np.array_equal(before, model.spins)
+
+
+def test_sk_energy_is_finite():
+    model = SherringtonKirkpatrick(N=30, seed=2)
+    model.sweep(beta=1.0, n_sweeps=5)
+    assert np.isfinite(model.energy())
+
+
+def test_sk_overlap_distribution_shape_and_bounds():
+    model = SherringtonKirkpatrick(N=20, seed=3)
+    samples = model.overlap_distribution(beta=1.5, n_disorder=4, n_equil=10, n_measure=5)
+    assert samples.shape == (20,)
+    assert np.all(samples >= -1.0 - 1e-9) and np.all(samples <= 1.0 + 1e-9)

physicskit/statphys/tests/test_thermodynamics.py

@@ -0,0 +1,121 @@
+import numpy as np
+import pytest
+from scipy.integrate import trapezoid
+
+from physicskit.statphys.utils.thermodynamics import (
+    bec_condensate_fraction,
+    binder_cumulant,
+    bose_einstein_occupation,
+    fermi_dirac_occupation,
+    maxwell_boltzmann_component_pdf,
+    maxwell_boltzmann_speed_pdf,
+    specific_heat,
+    spin_correlation_function,
+    susceptibility,
+)
+
+
+def test_specific_heat_zero_for_constant_energy():
+    E = np.full(1000, -50.0)
+    assert specific_heat(E, temperature=2.0, n_sites=64) == pytest.approx(0.0)
+
+
+def test_specific_heat_positive_for_fluctuating_energy():
+    rng = np.random.default_rng(0)
+    E = rng.normal(-100.0, 5.0, size=5000)
+    assert specific_heat(E, temperature=2.0, n_sites=64) > 0
+
+
+def test_susceptibility_scales_with_variance():
+    rng = np.random.default_rng(1)
+    M_low = rng.normal(0.0, 1.0, size=5000)
+    M_high = rng.normal(0.0, 5.0, size=5000)
+    assert susceptibility(M_high, 1.0, 64) > susceptibility(M_low, 1.0, 64)
+
+
+def test_binder_cumulant_gaussian_limit():
+    rng = np.random.default_rng(2)
+    m = rng.normal(0.0, 1.0, size=200_000)
+    # for a zero-mean Gaussian, <m^4>/<m^2>^2 = 3, so U4 -> 0
+    assert binder_cumulant(m) == pytest.approx(0.0, abs=0.05)
+
+
+def test_binder_cumulant_delta_distribution():
+    m = np.full(1000, 2.5)
+    assert binder_cumulant(m) == pytest.approx(2.0 / 3.0)
+
+
+def test_spin_correlation_function_zero_lag_equals_variance():
+    rng = np.random.default_rng(3)
+    spins = rng.choice([-1, 1], size=(20, 20))
+    r, G = spin_correlation_function(spins)
+    assert r[0] == 0
+    assert G[0] == pytest.approx(1.0 - spins.mean() ** 2, abs=1e-9)
+
+
+def test_maxwell_boltzmann_speed_pdf_normalizes_to_one():
+    v = np.linspace(0, 20, 200_000)
+    pdf = maxwell_boltzmann_speed_pdf(v, temperature=2.0, mass=1.0, dim=2)
+    integral = trapezoid(pdf, v)
+    assert integral == pytest.approx(1.0, abs=1e-3)
+
+
+def test_maxwell_boltzmann_speed_pdf_invalid_dim_raises():
+    with pytest.raises(ValueError):
+        maxwell_boltzmann_speed_pdf(np.array([1.0]), temperature=1.0, dim=4)
+
+
+@pytest.mark.parametrize("dim", [1, 3])
+def test_maxwell_boltzmann_speed_pdf_normalizes_to_one_in_1d_and_3d(dim):
+    v = np.linspace(0, 20, 200_000)
+    pdf = maxwell_boltzmann_speed_pdf(v, temperature=2.0, mass=1.0, dim=dim)
+    integral = trapezoid(pdf, v)
+    assert integral == pytest.approx(1.0, abs=1e-3)
+
+
+def test_maxwell_boltzmann_component_pdf_is_gaussian():
+    vx = np.linspace(-10, 10, 200_000)
+    pdf = maxwell_boltzmann_component_pdf(vx, temperature=1.5, mass=1.0)
+    integral = trapezoid(pdf, vx)
+    assert integral == pytest.approx(1.0, abs=1e-3)
+
+
+def test_bose_einstein_occupation_diverges_near_ground_state():
+    n_close = bose_einstein_occupation(1.001, mu=1.0, temperature=1.0)
+    n_far = bose_einstein_occupation(5.0, mu=1.0, temperature=1.0)
+    assert n_close > n_far > 0
+
+
+def test_fermi_dirac_occupation_bounded_between_zero_and_one():
+    energies = np.linspace(-5, 5, 50)
+    n = fermi_dirac_occupation(energies, mu=0.0, temperature=1.0)
+    assert np.all(n > 0.0) and np.all(n < 1.0)
+
+
+def test_fermi_dirac_occupation_step_function_at_zero_temperature():
+    # small enough to sharpen into a step, large enough that exp(x) doesn't overflow
+    n_below = fermi_dirac_occupation(-1.0, mu=0.0, temperature=0.05)
+    n_above = fermi_dirac_occupation(1.0, mu=0.0, temperature=0.05)
+    assert n_below == pytest.approx(1.0, abs=1e-6)
+    assert n_above == pytest.approx(0.0, abs=1e-6)
+
+
+def test_fermi_dirac_occupation_half_at_the_fermi_energy():
+    n = fermi_dirac_occupation(2.0, mu=2.0, temperature=1.0)
+    assert n == pytest.approx(0.5)
+
+
+def test_bec_condensate_fraction_full_at_zero_temperature():
+    f = bec_condensate_fraction(0.0, critical_temperature=1.0)
+    assert float(f) == pytest.approx(1.0)
+
+
+def test_bec_condensate_fraction_zero_above_tc():
+    f = bec_condensate_fraction(2.0, critical_temperature=1.0)
+    assert float(f) == pytest.approx(0.0)
+
+
+def test_bec_condensate_fraction_monotonically_decreasing():
+    T = np.linspace(0.0, 1.5, 20)
+    f = bec_condensate_fraction(T, critical_temperature=1.0)
+    assert np.all(np.diff(f) <= 1e-12)

physicskit/statphys/tests/test_xy_model.py

@@ -0,0 +1,45 @@
+import numpy as np
+
+from physicskit.statphys.chapters.ising_lattice import XYModel2D
+
+
+def test_theta_in_valid_range():
+    model = XYModel2D(L=12, seed=0)
+    assert np.all(model.theta >= 0.0)
+    assert np.all(model.theta < 2.0 * np.pi)
+
+
+def test_sweep_keeps_theta_in_range():
+    model = XYModel2D(L=12, seed=1)
+    model.sweep(beta=1.0, n_sweeps=10)
+    assert np.all(model.theta >= 0.0)
+    assert np.all(model.theta < 2.0 * np.pi)
+
+
+def test_kt_temperature_is_positive_and_reasonable():
+    model = XYModel2D(J=1.0, kB=1.0)
+    assert 0.5 < model.T_KT < 1.5
+
+
+def test_uniform_configuration_has_zero_vorticity():
+    model = XYModel2D(L=10, seed=2)
+    model.theta[:] = 0.0
+    q = model.vorticity()
+    assert np.allclose(q, 0.0, atol=1e-9)
+    n_v, n_av = model.vortex_count()
+    assert n_v == 0 and n_av == 0
+
+
+def test_low_temperature_has_small_ordered_magnetization():
+    model = XYModel2D(L=14, seed=3)
+    model.theta[:] = model._rng.uniform(-0.05, 0.05, size=model.theta.shape) % (2 * np.pi)
+    model.sweep(beta=10.0, n_sweeps=30)
+    mag = model.magnetization_vector()
+    norm = np.linalg.norm(mag) / model.n_sites
+    assert norm > 0.5  # strongly aligned spins retain a large net moment
+
+
+def test_energy_is_finite():
+    model = XYModel2D(L=10, seed=4)
+    model.sweep(beta=1.0, n_sweeps=5)
+    assert np.isfinite(model.energy())

physicskit/statphys/utils/__init__.py

@@ -0,0 +1 @@
+"""Thermodynamic observables computed from simulation trajectories."""

physicskit/statphys/utils/dynamics.py

@@ -0,0 +1,100 @@
+"""Dynamical diagnostics for Monte Carlo time series: autocorrelation and critical slowing down.
+
+Near a continuous phase transition, successive Monte Carlo configurations
+become strongly correlated in (simulation) time -- "critical slowing down"
+-- so that naively spaced samples are not statistically independent. The
+integrated autocorrelation time quantifies exactly how many sweeps separate
+effectively independent samples, and comparing it between update algorithms
+(e.g. single-spin-flip Metropolis versus the Wolff cluster algorithm) is the
+standard way to demonstrate why cluster algorithms were invented.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["autocorrelation_function", "integrated_autocorrelation_time"]
+
+
+def autocorrelation_function(series, max_lag=None):
+    """Normalized autocorrelation function of a scalar Monte Carlo time series.
+
+    .. math::
+
+        \\rho(t) = \\frac{\\langle (x_i - \\bar x)(x_{i+t} - \\bar x) \\rangle}{\\mathrm{Var}(x)}
+
+    computed efficiently via the FFT (Wiener-Khinchin theorem).
+
+    Parameters
+    ----------
+    series : array_like
+        A scalar observable sampled at successive Monte Carlo sweeps (e.g.
+        magnetization or energy).
+    max_lag : int, optional
+        Largest lag to return. Defaults to ``len(series) // 2``.
+
+    Returns
+    -------
+    ndarray
+        :math:`\\rho(t)` for :math:`t = 0, 1, \\ldots,` ``max_lag``, with
+        :math:`\\rho(0) = 1`.
+    """
+    x = np.asarray(series, dtype=np.float64)
+    x = x - x.mean()
+    n = len(x)
+    if max_lag is None:
+        max_lag = n // 2
+
+    padded = np.zeros(2 * n)
+    padded[:n] = x
+    fft = np.fft.fft(padded)
+    autocorr = np.fft.ifft(fft * np.conj(fft)).real[:n]
+    autocorr /= np.arange(n, 0, -1)
+    return autocorr[: max_lag + 1] / autocorr[0]
+
+
+def integrated_autocorrelation_time(series, c=5.0, max_lag=None):
+    """Estimate the integrated autocorrelation time via Sokal's automatic windowing.
+
+    .. math::
+
+        \\tau_{\\text{int}}(M) = 1 + 2 \\sum_{t=1}^{M} \\rho(t)
+
+    The summation window :math:`M` is chosen automatically as the smallest
+    value satisfying :math:`M \\ge c \\, \\tau_{\\text{int}}(M)` (Sokal
+    1997), balancing statistical noise against truncation bias.
+    :math:`2\\tau_{\\text{int}}` gives (approximately) the number of Monte
+    Carlo sweeps needed between effectively independent samples -- the
+    standard quantitative measure of critical slowing down.
+
+    Parameters
+    ----------
+    series : array_like
+        A scalar Monte Carlo observable time series.
+    c : float, default=5.0
+        Windowing constant (Sokal recommends 4-10; smaller is noisier,
+        larger is more biased).
+    max_lag : int, optional
+        Largest lag considered; defaults to ``len(series) // 2``.
+
+    Returns
+    -------
+    float
+        Estimated integrated autocorrelation time, in units of sweeps.
+
+    Examples
+    --------
+    >>> rng = np.random.default_rng(0)
+    >>> x = rng.normal(size=5000)  # independent samples: tau ~ 0.5-1
+    >>> tau = integrated_autocorrelation_time(x)
+    >>> tau < 3.0
+    True
+    """
+    rho = autocorrelation_function(series, max_lag=max_lag)
+    cumulative = 0.0
+    for M in range(1, len(rho)):
+        cumulative += rho[M]
+        tau = 1.0 + 2.0 * cumulative
+        if c * tau <= M:
+            return float(tau)
+    return float(1.0 + 2.0 * cumulative)

physicskit/statphys/utils/finite_size_scaling.py

@@ -0,0 +1,171 @@
+"""Finite-size scaling analysis: locating T_C and estimating critical exponents.
+
+Monte Carlo simulations necessarily run on finite lattices, so an apparent
+thermodynamic singularity is always rounded and shifted relative to its
+infinite-volume value. Finite-size scaling theory predicts precisely how
+observables at different lattice sizes :math:`L` relate near a continuous
+phase transition, letting :math:`T_C` and the critical exponents be
+extracted from a family of finite simulations without ever simulating an
+infinite system.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = [
+    "binder_cumulant_crossing",
+    "estimate_beta_over_nu",
+    "estimate_gamma_over_nu",
+    "estimate_nu_from_binder_slope",
+    "power_law_exponent",
+]
+
+
+def power_law_exponent(x, y):
+    """Fit the exponent of an assumed power law :math:`y = A x^p` via log-log linear regression.
+
+    Parameters
+    ----------
+    x, y : array_like
+        Positive-valued samples believed to follow a power law.
+
+    Returns
+    -------
+    exponent : float
+        The fitted exponent :math:`p`.
+    prefactor : float
+        The fitted prefactor :math:`A`.
+
+    Examples
+    --------
+    >>> x = np.array([1.0, 2.0, 4.0, 8.0, 16.0])
+    >>> y = 3.0 * x**1.5
+    >>> p, A = power_law_exponent(x, y)
+    >>> round(p, 6)
+    1.5
+    """
+    x = np.asarray(x, dtype=np.float64)
+    y = np.asarray(y, dtype=np.float64)
+    p, log_A = np.polyfit(np.log(x), np.log(y), 1)
+    return float(p), float(np.exp(log_A))
+
+
+def estimate_gamma_over_nu(L_values, chi_max_values):
+    """Estimate :math:`\\gamma/\\nu` from the lattice-size scaling of the peak susceptibility.
+
+    Finite-size scaling predicts :math:`\\chi_{\\max}(L) \\sim L^{\\gamma/\\nu}`.
+
+    Parameters
+    ----------
+    L_values : array_like
+        Lattice sizes.
+    chi_max_values : array_like
+        Peak susceptibility measured at each lattice size (e.g. the maximum
+        of the ``"chi"`` array returned by ``Ising2D.run_temperature_sweep``).
+
+    Returns
+    -------
+    float
+        Estimated :math:`\\gamma / \\nu`.
+    """
+    exponent, _ = power_law_exponent(L_values, chi_max_values)
+    return exponent
+
+
+def estimate_beta_over_nu(L_values, magnetization_at_tc_values):
+    """Estimate :math:`\\beta/\\nu` from the lattice-size scaling of the order parameter at T_C.
+
+    Finite-size scaling predicts :math:`M(T_C, L) \\sim L^{-\\beta/\\nu}`.
+
+    Parameters
+    ----------
+    L_values : array_like
+        Lattice sizes.
+    magnetization_at_tc_values : array_like
+        Order parameter measured at (approximately) :math:`T_C` for each
+        lattice size.
+
+    Returns
+    -------
+    float
+        Estimated :math:`\\beta / \\nu`.
+    """
+    exponent, _ = power_law_exponent(L_values, magnetization_at_tc_values)
+    return -exponent
+
+
+def estimate_nu_from_binder_slope(L_values, T_grids, U4_grids, T_c):
+    """Estimate the correlation-length exponent :math:`\\nu` from the Binder cumulant's slope at T_C.
+
+    Finite-size scaling predicts the Binder cumulant's temperature
+    derivative at criticality scales as
+    :math:`\\left.\\frac{dU_4}{dT}\\right|_{T_C} \\sim L^{1/\\nu}`. This
+    numerically differentiates each lattice size's :math:`U_4(T)` curve at
+    :math:`T_C` (a finite-difference slope between the two grid points
+    bracketing :math:`T_C`) and fits the resulting :math:`L`-scaling.
+
+    Parameters
+    ----------
+    L_values : array_like
+        Lattice sizes.
+    T_grids : list of array_like
+        Temperature grid used at each lattice size (need not be identical
+        across sizes, but each must bracket ``T_c``).
+    U4_grids : list of array_like
+        Binder cumulant values on each temperature grid.
+    T_c : float
+        Critical temperature at which to evaluate the slope.
+
+    Returns
+    -------
+    float
+        Estimated :math:`\\nu`.
+    """
+    slopes = []
+    for T, U4 in zip(T_grids, U4_grids):
+        T = np.asarray(T, dtype=np.float64)
+        U4 = np.asarray(U4, dtype=np.float64)
+        order = np.argsort(T)
+        T, U4 = T[order], U4[order]
+        idx = np.clip(np.searchsorted(T, T_c), 1, len(T) - 1)
+        slope = (U4[idx] - U4[idx - 1]) / (T[idx] - T[idx - 1])
+        slopes.append(abs(slope))
+    exponent, _ = power_law_exponent(L_values, slopes)
+    return 1.0 / exponent
+
+
+def binder_cumulant_crossing(T, U4_by_L):
+    """Estimate T_C as the crossing point of the two largest lattice sizes' Binder cumulant curves.
+
+    Interpolates linearly between grid points to find where the two curves
+    cross -- the standard, finite-size-correction-robust way to locate a
+    continuous transition's critical temperature.
+
+    Parameters
+    ----------
+    T : array_like
+        Common temperature grid shared by all lattice sizes.
+    U4_by_L : dict of int -> array_like
+        Binder cumulant values at each lattice size, evaluated on ``T``.
+
+    Returns
+    -------
+    float
+        Estimated crossing temperature.
+
+    Raises
+    ------
+    ValueError
+        If the two largest lattice sizes' curves never cross on ``T``.
+    """
+    L1, L2 = sorted(U4_by_L.keys())[-2:]
+    T = np.asarray(T, dtype=np.float64)
+    diff = np.asarray(U4_by_L[L1], dtype=np.float64) - np.asarray(U4_by_L[L2], dtype=np.float64)
+    sign_changes = np.where(np.diff(np.sign(diff)) != 0)[0]
+    if len(sign_changes) == 0:
+        raise ValueError("Binder cumulant curves for the two largest L do not cross on this grid")
+    i = sign_changes[0]
+    t0, t1 = T[i], T[i + 1]
+    d0, d1 = diff[i], diff[i + 1]
+    return float(t0 - d0 * (t1 - t0) / (d1 - d0))