physicskit 0.1.0__py3-none-any.whl

physicskit/statphys/chapters/percolation.py

@@ -0,0 +1,305 @@
+"""Site and bond percolation on the square lattice, via Hoshen-Kopelman cluster labeling.
+
+Percolation theory studies the sudden, geometric phase transition that
+appears when a fraction ``p`` of a lattice's sites (or bonds) are randomly
+occupied: below a critical threshold :math:`p_c` only small, finite clusters
+exist, while above it a single cluster spans the entire system. The
+transition is purely geometric -- there is no energy scale or temperature --
+yet it shares the full apparatus of critical phenomena: a sharp threshold,
+power-law cluster-size distributions, and universal critical exponents.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["Percolation2D", "hoshen_kopelman"]
+
+
+def hoshen_kopelman(occupied):
+    """Label connected clusters of occupied sites with the Hoshen-Kopelman algorithm.
+
+    A single raster pass assigns provisional labels while a union-find
+    structure tracks label equivalences (created whenever a site connects two
+    previously separate provisional clusters); a second pass resolves every
+    label to its cluster's root.
+
+    Parameters
+    ----------
+    occupied : ndarray of shape (L, L), dtype bool
+        Site occupation grid (open boundary conditions -- no wraparound).
+
+    Returns
+    -------
+    ndarray of shape (L, L), dtype int64
+        Cluster label at each site; ``0`` marks unoccupied sites, and
+        occupied sites sharing a label belong to the same connected cluster.
+        Labels are not necessarily contiguous integers.
+
+    Examples
+    --------
+    >>> grid = np.array([[True, True, False], [False, True, False], [False, False, True]])
+    >>> labels = hoshen_kopelman(grid)
+    >>> bool(labels[0, 0] == labels[0, 1] == labels[1, 1])
+    True
+    >>> bool(labels[2, 2] not in (0, labels[0, 0]))
+    True
+    """
+    L0, L1 = occupied.shape
+    labels = np.zeros((L0, L1), dtype=np.int64)
+    parent = [0]
+
+    def find(x):
+        root = x
+        while parent[root] != root:
+            root = parent[root]
+        while parent[x] != root:
+            parent[x], x = root, parent[x]
+        return root
+
+    def union(x, y):
+        rx, ry = find(x), find(y)
+        if rx != ry:
+            parent[max(rx, ry)] = min(rx, ry)
+
+    next_label = 1
+    for i in range(L0):
+        for j in range(L1):
+            if not occupied[i, j]:
+                continue
+            left = labels[i, j - 1] if j > 0 and occupied[i, j - 1] else 0
+            up = labels[i - 1, j] if i > 0 and occupied[i - 1, j] else 0
+            if left == 0 and up == 0:
+                labels[i, j] = next_label
+                parent.append(next_label)
+                next_label += 1
+            elif left != 0 and up == 0:
+                labels[i, j] = find(left)
+            elif left == 0 and up != 0:
+                labels[i, j] = find(up)
+            else:
+                union(left, up)
+                labels[i, j] = find(left)
+
+    for i in range(L0):
+        for j in range(L1):
+            if labels[i, j] != 0:
+                labels[i, j] = find(labels[i, j])
+    return labels
+
+
+class Percolation2D:
+    """Site or bond percolation on a periodic-free (open-boundary) square lattice.
+
+    Parameters
+    ----------
+    L : int, default=64
+        Linear lattice size.
+    p : float, default=0.5
+        Occupation probability: fraction of sites (site percolation) or
+        bonds (bond percolation) that are open.
+    mode : {"site", "bond"}, default="site"
+        Percolation type. Known exact thresholds for the square lattice are
+        :math:`p_c \\approx 0.592746` (site) and :math:`p_c = 0.5` (bond,
+        exact by self-duality).
+    seed : int, optional
+        Seed for reproducible lattice realizations.
+
+    Attributes
+    ----------
+    labels : ndarray of shape (L, L)
+        Cluster labels of the current realization, from
+        :func:`hoshen_kopelman`.
+    """
+
+    #: Known threshold for square-lattice site percolation (numerical estimate).
+    P_C_SITE = 0.592746
+    #: Exact threshold for square-lattice bond percolation (self-duality).
+    P_C_BOND = 0.5
+
+    def __init__(self, L=64, p=0.5, mode="site", seed=None):
+        if mode not in ("site", "bond"):
+            raise ValueError("mode must be 'site' or 'bond'")
+        self.L = L
+        self.p = p
+        self.mode = mode
+        self._rng = np.random.default_rng(seed)
+        self.labels = None
+        self.generate()
+
+    @property
+    def p_c(self):
+        """Threshold occupation probability for the current ``mode``."""
+        return self.P_C_SITE if self.mode == "site" else self.P_C_BOND
+
+    def generate(self, p=None):
+        """Draw a fresh random realization and label its clusters.
+
+        Parameters
+        ----------
+        p : float, optional
+            Occupation probability to use; defaults to ``self.p``. If given,
+            also updates ``self.p``.
+
+        Returns
+        -------
+        ndarray of shape (L, L)
+            The updated cluster ``labels`` array.
+        """
+        if p is not None:
+            self.p = p
+        if self.mode == "site":
+            occupied = self._rng.random((self.L, self.L)) < self.p
+        else:
+            occupied = self._bond_occupation_to_sites(self.p)
+        self.labels = hoshen_kopelman(occupied)
+        return self.labels
+
+    def _bond_occupation_to_sites(self, p):
+        """Build an effective all-occupied site grid whose HK labeling respects bond connectivity.
+
+        Bond percolation is reduced to Hoshen-Kopelman site labeling by
+        working on a doubled lattice: real sites at even indices, and
+        "bond sites" at the odd indices between them, present only when the
+        corresponding bond is open.
+        """
+        L = self.L
+        expanded = np.zeros((2 * L - 1, 2 * L - 1), dtype=bool)
+        expanded[0::2, 0::2] = True  # all real sites present
+
+        h_bonds = self._rng.random((L, L - 1)) < p  # horizontal bonds
+        v_bonds = self._rng.random((L - 1, L)) < p  # vertical bonds
+        expanded[0::2, 1::2] = h_bonds
+        expanded[1::2, 0::2] = v_bonds
+        return expanded
+
+    def spanning_labels(self):
+        """Cluster labels of the current realization that span top to bottom.
+
+        For bond percolation the doubled lattice is used internally, but
+        returned labels index the real (even-index) sites.
+
+        Returns
+        -------
+        ndarray
+            Labels present on both the first and last row of real sites.
+        """
+        if self.mode == "site":
+            top_labels = set(self.labels[0, :]) - {0}
+            bottom_labels = set(self.labels[-1, :]) - {0}
+        else:
+            top_labels = set(self.labels[0, 0::2]) - {0}
+            bottom_labels = set(self.labels[-1, 0::2]) - {0}
+        return np.array(sorted(top_labels & bottom_labels), dtype=np.int64)
+
+    def spans(self):
+        """Whether the current realization has a top-to-bottom spanning cluster."""
+        return len(self.spanning_labels()) > 0
+
+    def _real_labels(self):
+        """Cluster labels restricted to real (non-bond-auxiliary) lattice sites."""
+        return self.labels if self.mode == "site" else self.labels[0::2, 0::2]
+
+    def largest_cluster_size(self):
+        """Number of (real) sites in the largest cluster of the current realization."""
+        sizes = self.cluster_size_distribution()
+        return int(sizes.max()) if sizes.size else 0
+
+    def cluster_size_distribution(self):
+        """Sizes of every cluster in the current realization.
+
+        At the percolation threshold, the number of clusters of size ``s``
+        follows a power law :math:`n_s \\sim s^{-\\tau}` with the Fisher
+        exponent :math:`\\tau = 187/91 \\approx 2.055` for 2D percolation --
+        the geometric analogue of the divergent susceptibility seen at a
+        thermal critical point.
+
+        Returns
+        -------
+        ndarray
+            Cluster sizes, in sites, one entry per cluster (including the
+            spanning cluster if one exists).
+        """
+        real_labels = self._real_labels()
+        labels = real_labels[real_labels != 0]
+        if labels.size == 0:
+            return np.array([], dtype=np.int64)
+        _, counts = np.unique(labels, return_counts=True)
+        return counts
+
+    def spanning_probability(self, p_values, n_trials=100):
+        """Monte Carlo estimate of the spanning probability :math:`P_{\\text{span}}(p)`.
+
+        For each probability in ``p_values``, generates ``n_trials``
+        independent realizations and reports the fraction that contain a
+        top-to-bottom spanning cluster. As :math:`L \\to \\infty` this curve
+        sharpens into a step function at :math:`p_c`.
+
+        Parameters
+        ----------
+        p_values : array_like
+            Occupation probabilities to sample.
+        n_trials : int, default=100
+            Independent realizations per probability.
+
+        Returns
+        -------
+        p_values : ndarray
+        P_span : ndarray
+            Estimated spanning probability at each ``p``.
+
+        Examples
+        --------
+        >>> perc = Percolation2D(L=20, seed=0)
+        >>> p, P = perc.spanning_probability([0.3, 0.593, 0.8], n_trials=20)
+        >>> bool(P[0] < P[2])
+        True
+        """
+        p_values = np.asarray(p_values, dtype=np.float64)
+        P_span = np.empty(len(p_values))
+        for k, p in enumerate(p_values):
+            hits = 0
+            for _ in range(n_trials):
+                self.generate(p)
+                hits += self.spans()
+            P_span[k] = hits / n_trials
+        return p_values, P_span
+
+    def fractal_dimension(self, n_trials=20):
+        """Estimate the fractal dimension of the largest cluster at :math:`p = p_c`.
+
+        A single lattice size gives no direct mass-versus-``L`` scaling, so
+        instead this estimates :math:`d_f` from the mass-radius relation of
+        the largest cluster in each realization,
+        :math:`d_f = \\log(\\text{cluster size}) / \\log(R_g)`, where
+        :math:`R_g` is the cluster's radius of gyration, averaged over
+        trials. The 2D percolation universality class predicts
+        :math:`d_f = 91/48 \\approx 1.896`.
+
+        Parameters
+        ----------
+        n_trials : int, default=20
+            Number of critical realizations to average over.
+
+        Returns
+        -------
+        float
+            Estimated fractal dimension.
+        """
+        dims = []
+        for _ in range(n_trials):
+            self.generate(self.p_c)
+            real_labels = self._real_labels()
+            labels = real_labels[real_labels != 0]
+            if labels.size == 0:
+                continue
+            values, counts = np.unique(labels, return_counts=True)
+            biggest = values[np.argmax(counts)]
+            ii, jj = np.nonzero(real_labels == biggest)
+            size = len(ii)
+            if size < 4:
+                continue
+            Rg = np.sqrt(np.mean((ii - ii.mean()) ** 2 + (jj - jj.mean()) ** 2))
+            if Rg > 0:
+                dims.append(np.log(size) / np.log(Rg))
+        return float(np.mean(dims)) if dims else float("nan")

physicskit/statphys/chapters/random_walk.py

@@ -0,0 +1,142 @@
+"""Random walks: diffusion, the Einstein relation, and the central limit theorem.
+
+The random walk is arguably the most foundational model in statistical
+physics: it underlies Einstein's 1905 explanation of Brownian motion (which
+provided the first direct evidence for the atomic hypothesis), and its
+Gaussian long-time limit is the simplest nontrivial instance of the central
+limit theorem, whose universality is itself the deep reason so many
+different microscopic models flow to the same few macroscopic diffusion
+laws.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from physicskit.statphys.core.monte_carlo import seed_numba_random
+from physicskit.statphys.core.random_walk_engine import simulate_gaussian_walks, simulate_lattice_walks
+
+__all__ = ["RandomWalk"]
+
+
+class RandomWalk:
+    """An ensemble of independent random walkers used to study diffusion.
+
+    Parameters
+    ----------
+    n_walkers : int, default=500
+        Number of independent walkers in the ensemble.
+    n_steps : int, default=1000
+        Number of steps each walker takes.
+    dim : int, default=2
+        Spatial dimension.
+    kind : {"lattice", "gaussian"}, default="lattice"
+        ``"lattice"`` walkers take unit steps along a randomly chosen axis
+        (a simple-cubic lattice walk); ``"gaussian"`` walkers take
+        continuous, independent Gaussian steps in every dimension at every
+        time step (a discrete-time model of Brownian motion).
+    step_std : float, default=1.0
+        Per-axis standard deviation of a single step. Only used for
+        ``kind="gaussian"``.
+    seed : int, optional
+        Seed for reproducible trajectories.
+
+    Attributes
+    ----------
+    trajectories : ndarray of shape (n_steps + 1, n_walkers, dim) or None
+        Walker positions at every time, populated by :meth:`run`.
+
+    Examples
+    --------
+    >>> walk = RandomWalk(n_walkers=200, n_steps=200, dim=2, seed=0)
+    >>> t, msd = walk.mean_squared_displacement()
+    >>> bool(msd[-1] > msd[10])
+    True
+    """
+
+    def __init__(self, n_walkers=500, n_steps=1000, dim=2, kind="lattice", step_std=1.0, seed=None):
+        self.n_walkers = n_walkers
+        self.n_steps = n_steps
+        self.dim = dim
+        self.kind = kind
+        self.step_std = step_std
+        if seed is not None:
+            seed_numba_random(seed)
+        self.trajectories = None
+
+    def run(self):
+        """Simulate every walker's full trajectory.
+
+        Returns
+        -------
+        ndarray of shape (n_steps + 1, n_walkers, dim)
+            The same array stored in :attr:`trajectories`.
+        """
+        if self.kind == "lattice":
+            self.trajectories = simulate_lattice_walks(self.n_walkers, self.n_steps, self.dim).astype(np.float64)
+        elif self.kind == "gaussian":
+            self.trajectories = simulate_gaussian_walks(self.n_walkers, self.n_steps, self.dim, self.step_std)
+        else:
+            raise ValueError("kind must be 'lattice' or 'gaussian'")
+        return self.trajectories
+
+    def mean_squared_displacement(self):
+        """Ensemble-averaged mean squared displacement :math:`\\text{MSD}(t) = \\langle |r(t)|^2 \\rangle`.
+
+        Returns
+        -------
+        t : ndarray of shape (n_steps + 1,)
+            Time (in steps), starting at 0.
+        msd : ndarray of shape (n_steps + 1,)
+            Mean squared displacement from the (shared) origin at each time.
+        """
+        if self.trajectories is None:
+            self.run()
+        disp2 = np.sum(self.trajectories**2, axis=2)
+        msd = disp2.mean(axis=1)
+        t = np.arange(self.n_steps + 1)
+        return t, msd
+
+    def diffusion_coefficient(self):
+        """Estimate the diffusion coefficient D via the Einstein relation.
+
+        Fits :math:`\\text{MSD}(t) = 2 d D t` (a line through the origin,
+        least-squares) to the ensemble MSD, where :math:`d` is
+        :attr:`dim`.
+
+        Returns
+        -------
+        float
+            Estimated diffusion coefficient.
+        """
+        t, msd = self.mean_squared_displacement()
+        slope = np.sum(t[1:] * msd[1:]) / np.sum(t[1:] ** 2)
+        return float(slope / (2.0 * self.dim))
+
+    def final_displacement_histogram(self, axis=0, bins=40):
+        """Density histogram of the final-time displacement along one axis.
+
+        A demonstration of the central limit theorem: regardless of the
+        (highly non-Gaussian) single-step distribution, the sum of many
+        independent steps approaches a Gaussian.
+
+        Parameters
+        ----------
+        axis : int, default=0
+            Which spatial axis to histogram.
+        bins : int, default=40
+            Number of histogram bins.
+
+        Returns
+        -------
+        centers : ndarray of shape (bins,)
+            Bin center positions.
+        density : ndarray of shape (bins,)
+            Probability density in each bin.
+        """
+        if self.trajectories is None:
+            self.run()
+        final = self.trajectories[-1, :, axis]
+        density, edges = np.histogram(final, bins=bins, density=True)
+        centers = 0.5 * (edges[:-1] + edges[1:])
+        return centers, density

physicskit/statphys/chapters/renormalization.py

@@ -0,0 +1,148 @@
+"""Real-space renormalization group: Kadanoff block-spin coarse-graining.
+
+Kadanoff's block-spin construction groups an Ising lattice into
+:math:`b \\times b` blocks and replaces each block by a single effective spin
+(here, majority rule with ``b = 2``), producing a new, smaller lattice at the
+same nominal temperature. Iterating this map is a real-space renormalization
+group transformation: starting configurations flow toward one of the
+theory's fixed points -- a fully ordered state at :math:`T \\ll T_c`, a fully
+disordered state at :math:`T \\gg T_c`, and a self-similar, scale-invariant
+critical configuration at :math:`T = T_c`, where the coarse-grained lattice
+looks statistically identical to the original.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from physicskit.statphys.chapters.ising_lattice import Ising2D
+
+__all__ = ["BlockSpinRG"]
+
+
+class BlockSpinRG:
+    """Iterated 2x2 majority-rule block-spin coarse-graining of an Ising configuration.
+
+    Parameters
+    ----------
+    L : int, default=64
+        Linear size of the initial lattice. Should be a power of 2 times the
+        largest block factor you intend to reach, e.g. ``L=64`` supports up
+        to 6 coarse-graining steps.
+    T : float, default=None
+        Temperature at which to equilibrate the initial configuration, in
+        units of ``J/kB``. Defaults to the exact critical temperature
+        (``Ising2D.T_C``) if not given, i.e. the critical fixed point.
+    J : float, default=1.0
+        Ising coupling constant used to equilibrate the initial
+        configuration.
+    n_equil_sweeps : int, default=500
+        Wolff cluster updates used to equilibrate the initial fine-grained
+        configuration at temperature ``T`` before coarse-graining begins.
+    seed : int, optional
+        Seed for the initial equilibration and for majority-rule tie
+        breaking.
+
+    Attributes
+    ----------
+    initial_spins : ndarray of shape (L, L)
+        The equilibrated fine-grained configuration coarse-graining starts
+        from.
+    """
+
+    def __init__(self, L=64, T=None, J=1.0, n_equil_sweeps=500, seed=None):
+        self.L = L
+        self.J = J
+        self._rng = np.random.default_rng(seed)
+
+        model = Ising2D(L=L, J=J, seed=seed)
+        self.T = model.T_C if T is None else T
+        beta = 1.0 / self.T if self.T > 0 else np.inf
+        if np.isfinite(beta):
+            # Wolff cluster updates equilibrate far more reliably than single-spin
+            # Metropolis: at low T, Metropolis dynamics from a random start undergoes
+            # slow domain-wall coarsening that a modest sweep budget cannot outrun.
+            model.sweep(beta, algorithm="wolff", n_sweeps=n_equil_sweeps)
+        self.initial_spins = model.spins.copy()
+
+    def coarse_grain_step(self, spins):
+        """Apply one 2x2 majority-rule block-spin transformation.
+
+        Each non-overlapping :math:`2 \\times 2` block of the input is
+        replaced by a single spin equal to the sign of the block's sum; an
+        exact tie (sum of zero) is broken by an independent fair coin flip.
+
+        Parameters
+        ----------
+        spins : ndarray of shape (L, L)
+            Input configuration. ``L`` must be even.
+
+        Returns
+        -------
+        ndarray of shape (L // 2, L // 2)
+            Coarse-grained spin configuration.
+        """
+        L = spins.shape[0]
+        if L % 2 != 0:
+            raise ValueError("lattice size must be even to block by 2x2")
+        blocks = spins.reshape(L // 2, 2, L // 2, 2).sum(axis=(1, 3))
+        new_spins = np.sign(blocks).astype(np.int64)
+        ties = new_spins == 0
+        if np.any(ties):
+            coin = self._rng.choice(np.array([-1, 1], dtype=np.int64), size=ties.sum())
+            new_spins[ties] = coin
+        return new_spins
+
+    def iterate(self, n_steps=None):
+        """Repeatedly coarse-grain the initial configuration.
+
+        Parameters
+        ----------
+        n_steps : int, optional
+            Number of coarse-graining steps. Defaults to
+            ``floor(log2(L)) - 1``, i.e. as many as keep the lattice at least
+            :math:`2 \\times 2`.
+
+        Returns
+        -------
+        list of ndarray
+            The sequence of configurations
+            ``[initial_spins, step_1, step_2, ...]``, of shrinking size
+            :math:`L, L/2, L/4, \\ldots`
+
+        Examples
+        --------
+        >>> rg = BlockSpinRG(L=16, T=100.0, seed=0)
+        >>> grids = rg.iterate(n_steps=3)
+        >>> [g.shape[0] for g in grids]
+        [16, 8, 4, 2]
+        """
+        if n_steps is None:
+            n_steps = int(np.floor(np.log2(self.L))) - 1
+        grids = [self.initial_spins]
+        current = self.initial_spins
+        for _ in range(n_steps):
+            current = self.coarse_grain_step(current)
+            grids.append(current)
+        return grids
+
+    @staticmethod
+    def order_parameter(spins):
+        """Magnitude of the mean magnetization per site, :math:`|\\langle s \\rangle|`.
+
+        A convenient scalar summary of a grid in the RG flow: it drifts to
+        ``1`` under iteration when the starting temperature is below
+        :math:`T_c` (flow to the ordered fixed point), to ``0`` when above
+        (flow to the disordered fixed point), and hovers at an intermediate,
+        scale-invariant value at :math:`T_c`.
+
+        Parameters
+        ----------
+        spins : ndarray
+            A spin configuration.
+
+        Returns
+        -------
+        float
+        """
+        return float(np.abs(spins.mean()))

physicskit/statphys/chapters/sandpile.py

@@ -0,0 +1,109 @@
+"""The Bak-Tang-Wiesenfeld sandpile: self-organized criticality.
+
+Ordinary critical phenomena require fine-tuning a parameter (temperature,
+occupation probability) to a special value. Bak, Tang, and Wiesenfeld's 1987
+sandpile model was the first example of a system that tunes *itself* to a
+critical state through its own slow-driving, fast-relaxation dynamics --
+"self-organized criticality" (SOC) -- and was proposed as a generic
+explanation for the ubiquity of power laws in nature (earthquakes, forest
+fires, neural avalanches), without needing anyone to tune anything.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from physicskit.statphys.core.sandpile_engine import topple_to_stability
+
+__all__ = ["BTWSandpile"]
+
+
+class BTWSandpile:
+    """The Bak-Tang-Wiesenfeld sandpile on an L x L grid with open (absorbing) boundaries.
+
+    Grains are added one at a time to a chosen (or random) site; whenever a
+    site's height reaches the toppling threshold, it topples, distributing
+    one grain to each orthogonal neighbor (grains that fall off the grid's
+    edge are permanently lost). A single added grain can trigger a chain
+    reaction of topplings -- an avalanche -- whose size has no
+    characteristic scale once the pile has self-organized to its critical
+    state.
+
+    Parameters
+    ----------
+    L : int, default=64
+        Linear grid size.
+    threshold : int, default=4
+        Toppling threshold (4 is the standard value on the square lattice).
+    seed : int, optional
+        Seed for the random drop-site sequence.
+
+    Attributes
+    ----------
+    heights : ndarray of shape (L, L)
+        Current pile heights; always ``< threshold`` everywhere immediately
+        after a call to :meth:`add_grain` or :meth:`run`.
+    """
+
+    def __init__(self, L=64, threshold=4, seed=None):
+        self.L = L
+        self.threshold = threshold
+        self._rng = np.random.default_rng(seed)
+        self.heights = np.zeros((L, L), dtype=np.int64)
+
+    def add_grain(self, site=None):
+        """Add one grain and relax the pile to stability.
+
+        Parameters
+        ----------
+        site : tuple of int, optional
+            ``(i, j)`` grid coordinates to drop the grain at. A uniformly
+            random site is chosen if not given.
+
+        Returns
+        -------
+        int
+            Avalanche size: the number of individual topplings triggered by
+            this grain (``0`` if it did not trigger any toppling).
+        """
+        if site is None:
+            i = self._rng.integers(0, self.L)
+            j = self._rng.integers(0, self.L)
+        else:
+            i, j = site
+        self.heights[i, j] += 1
+        return topple_to_stability(self.heights, self.threshold)
+
+    def run(self, n_grains, warmup=0):
+        """Drop many grains at random sites, recording each one's avalanche size.
+
+        Parameters
+        ----------
+        n_grains : int
+            Number of grains to add and record after the warmup period.
+        warmup : int, default=0
+            Grains added first, to let the pile reach its self-organized
+            critical state, whose avalanche sizes are discarded.
+
+        Returns
+        -------
+        ndarray of shape (n_grains,), dtype int64
+            Avalanche size triggered by each recorded grain.
+
+        Examples
+        --------
+        >>> pile = BTWSandpile(L=20, seed=0)
+        >>> sizes = pile.run(n_grains=500, warmup=500)
+        >>> sizes.shape
+        (500,)
+        """
+        for _ in range(warmup):
+            self.add_grain()
+        sizes = np.empty(n_grains, dtype=np.int64)
+        for k in range(n_grains):
+            sizes[k] = self.add_grain()
+        return sizes
+
+    def total_grains(self):
+        """Total number of grains currently on the pile."""
+        return int(self.heights.sum())