mixingmatrix 0.2.0__py3-none-any.whl

mixingmatrix/__init__.py

@@ -0,0 +1,93 @@
+"""mixingmatrix -- optimal mixing matrices for graphs.
+
+Compute the edge weights that make averaging, gossip or a random walk converge
+as fast as possible on a given graph.  This is the fastest-mixing Markov chain
+problem (Boyd, Diaconis & Xiao, SIAM Review 2004) and its free-weight variant
+FDLA (Xiao & Boyd, 2004).
+
+    import mixingmatrix
+
+    sol = mixingmatrix.solve(G)          # G is a connected networkx.Graph
+    sol.weights                     # scipy.sparse.csr_matrix
+    sol.to_dict()                   # {(u, v): weight} in your own node labels
+    sol.slem                        # the mixing rate; lower is faster
+    sol.certified_gap               # how far from optimal this might be
+    print(sol.summary())
+
+Check ``sol.status`` and ``sol.certified_gap`` before relying on a result: a
+status other than ``"optimal"`` means the solver stopped on a limit, and the
+gap says how much that cost.
+
+Other entry points:
+
+    mixingmatrix.compare(G)              # is optimising worth it on this graph?
+    mixingmatrix.update(sol, changes=)   # a few edges changed; reuse what you can
+    mixingmatrix.metropolis_hastings(G)  # and max_degree, best_constant, ...
+    mixingmatrix.slem(B)                 # measure any mixing matrix
+    mixingmatrix.gossip(B, x0, rounds=)  # run the chain
+
+Set ``time_limit`` on graphs above about a thousand nodes: every iterate is a
+valid mixing matrix, so a budget returns the best one found rather than
+nothing.
+
+See the docs/ directory: quickstart, cookbook, api, incremental, limits.
+"""
+
+from __future__ import annotations
+
+from ._graph import GraphIndex
+from .api import available_methods, compare, solve
+from .baselines import best_constant, lazy_random_walk, max_degree, metropolis_hastings
+from .certificates import DualCertificate, EdgeCertificate, build_certificate
+from .evaluate import (
+    FeasibilityReport,
+    consensus_rounds,
+    is_valid,
+    mixing_time,
+    slem,
+    spectral_gap,
+    stationary_distribution,
+)
+from .incremental import apply_changes, can_improve, can_remove, update
+from .problem import MixingProblem
+from .simulate import disagreement, gossip, rounds_to_consensus
+from .solution import Solution
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # core
+    "solve",
+    "update",
+    "compare",
+    "Solution",
+    # certificates
+    "can_remove",
+    "can_improve",
+    "build_certificate",
+    "DualCertificate",
+    "EdgeCertificate",
+    # baselines
+    "metropolis_hastings",
+    "max_degree",
+    "best_constant",
+    "lazy_random_walk",
+    # evaluation
+    "slem",
+    "spectral_gap",
+    "consensus_rounds",
+    "mixing_time",
+    "stationary_distribution",
+    "is_valid",
+    "FeasibilityReport",
+    # simulation
+    "gossip",
+    "rounds_to_consensus",
+    "disagreement",
+    # plumbing, exposed for extension
+    "GraphIndex",
+    "MixingProblem",
+    "apply_changes",
+    "available_methods",
+    "__version__",
+]

mixingmatrix/_graph.py

@@ -0,0 +1,164 @@
+"""Node-label bookkeeping.
+
+The solvers work in integer indices; the user works in whatever labels their
+graph has.  :class:`GraphIndex` is the only place that knows both, so a label
+never leaks into a numerical routine and an index never leaks back out to the
+user.  Everything the rest of the package needs about the *shape* of the
+problem -- how many nodes, which pairs are edges, in what order -- comes from
+here, which also makes "is this the same graph as last time?" a cheap identity
+question during an incremental update.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Iterable, Sequence
+
+import networkx as nx
+import numpy as np
+
+__all__ = ["GraphIndex", "edge_key"]
+
+
+def edge_key(u: Hashable, v: Hashable) -> tuple:
+    """Canonical, order-independent key for an undirected edge.
+
+    Sorting labels directly fails on mixed types (``3 < "a"`` raises), so the
+    fallback key is the string form -- deterministic, and only ever used to
+    pick which of ``(u, v)`` and ``(v, u)`` is written down.
+    """
+    try:
+        return (u, v) if u <= v else (v, u)  # type: ignore[operator]
+    except TypeError:
+        return (u, v) if str(u) <= str(v) else (v, u)
+
+
+class GraphIndex:
+    """Immutable view of a graph as ``n`` indexed nodes and ``m`` indexed edges.
+
+    Self-loops are dropped: the diagonal of a mixing matrix is determined by
+    the off-diagonal weights (it is whatever makes the row sum to one), so a
+    self-loop in the input carries no information and is not an error.
+    Edge attributes are ignored as well -- an input graph supplies the
+    *support*, and the weights are what this package computes.
+    """
+
+    __slots__ = ("nodes", "index", "edges", "edge_labels", "n", "m", "_edge_pos")
+
+    def __init__(self, graph: nx.Graph):
+        if graph.is_directed():
+            raise TypeError(
+                "mixingmatrix works on undirected graphs; pass G.to_undirected() if "
+                "the direction is not meaningful"
+            )
+        if graph.number_of_nodes() == 0:
+            raise ValueError("graph has no nodes")
+
+        self.nodes: tuple[Hashable, ...] = tuple(graph.nodes())
+        self.index: dict[Hashable, int] = {u: i for i, u in enumerate(self.nodes)}
+        self.n = len(self.nodes)
+
+        pairs = []
+        for u, v in graph.edges():
+            if u == v:
+                continue                      # self-loop: no information
+            i, j = self.index[u], self.index[v]
+            pairs.append((i, j) if i < j else (j, i))
+        pairs = sorted(set(pairs))
+        self.edges: tuple[tuple[int, int], ...] = tuple(pairs)
+        self.edge_labels: tuple[tuple, ...] = tuple(
+            (self.nodes[i], self.nodes[j]) for i, j in self.edges
+        )
+        self.m = len(self.edges)
+        self._edge_pos = {e: k for k, e in enumerate(self.edges)}
+
+        if self.n > 1 and not nx.is_connected(graph):
+            comps = nx.number_connected_components(graph)
+            raise ValueError(
+                f"graph is not connected ({comps} components): a chain that "
+                "cannot reach every node never mixes, so SLEM = 1 for any "
+                "weights. Solve each component separately, e.g. "
+                "[mixingmatrix.solve(graph.subgraph(c).copy()) for c in "
+                "nx.connected_components(graph)]"
+            )
+
+    # -- lookups ------------------------------------------------------------
+
+    def position(self, u: Hashable, v: Hashable) -> int | None:
+        """Column of edge ``(u, v)`` in weight space, or ``None`` if absent."""
+        try:
+            i, j = self.index[u], self.index[v]
+        except KeyError:
+            return None
+        return self._edge_pos.get((i, j) if i < j else (j, i))
+
+    def has_edge(self, u: Hashable, v: Hashable) -> bool:
+        return self.position(u, v) is not None
+
+    def require_node(self, u: Hashable) -> int:
+        if u not in self.index:
+            raise KeyError(f"node {u!r} is not in the graph")
+        return self.index[u]
+
+    def same_nodes(self, other: GraphIndex) -> bool:
+        """Whether two indices agree on node identity *and* ordering.
+
+        Ordering matters because warm-start state (``Z``, ``U``) is stored as
+        ``n x n`` matrices in index space; reusing it under a permuted labelling
+        would silently transport the dual variable to the wrong nodes.
+        """
+        return self.nodes == other.nodes
+
+    def edge_set(self) -> frozenset[tuple]:
+        """Edges as canonical label pairs."""
+        return frozenset(edge_key(u, v) for u, v in self.edge_labels)
+
+    # -- construction -------------------------------------------------------
+
+    def relabel_array(self, values: Sequence[float]) -> dict[tuple, float]:
+        """Edge-indexed values as a label-keyed dict."""
+        return {edge_key(u, v): float(x) for (u, v), x in zip(self.edge_labels, values, strict=True)}
+
+    def to_graph(self) -> nx.Graph:
+        """A fresh ``nx.Graph`` with the same nodes, ordering and edges."""
+        g = nx.Graph()
+        g.add_nodes_from(self.nodes)
+        g.add_edges_from(self.edge_labels)
+        return g
+
+    def degrees(self) -> np.ndarray:
+        d = np.zeros(self.n)
+        for i, j in self.edges:
+            d[i] += 1
+            d[j] += 1
+        return d
+
+    def stationary_vector(self, pi: dict | Iterable[float] | None) -> np.ndarray | None:
+        """Normalise a user-supplied stationary distribution into index order.
+
+        Accepts a label-keyed mapping or an array already in ``self.nodes``
+        order.  Returns ``None`` for the uniform case so callers can take the
+        cheaper path.
+        """
+        if pi is None:
+            return None
+        if isinstance(pi, dict):
+            missing = [u for u in self.nodes if u not in pi]
+            if missing:
+                raise KeyError(f"stationary distribution is missing nodes: {missing[:5]}")
+            vec = np.array([float(pi[u]) for u in self.nodes])
+        else:
+            vec = np.asarray(list(pi), dtype=float)
+            if vec.shape != (self.n,):
+                raise ValueError(f"stationary distribution has length {vec.size}, expected {self.n}")
+        if np.any(vec <= 0):
+            raise ValueError(
+                "stationary distribution must be strictly positive; a zero "
+                "entry makes the node unreachable and the chain reducible"
+            )
+        return vec / vec.sum()
+
+    def __len__(self) -> int:
+        return self.n
+
+    def __repr__(self) -> str:  # pragma: no cover - display only
+        return f"<GraphIndex n={self.n} m={self.m}>"

mixingmatrix/api.py

@@ -0,0 +1,269 @@
+"""The entry points: :func:`solve` and :func:`compare`.
+
+``solve(G)`` is meant to be the whole API for most users.  Every argument has a
+default that works, ``method="auto"`` picks the solver, and the returned
+:class:`~mixingmatrix.solution.Solution` recomputes its own quality rather than
+reporting the solver's.
+"""
+
+from __future__ import annotations
+
+import time
+import warnings
+from collections.abc import Callable, Sequence
+
+import networkx as nx
+import numpy as np
+
+from ._graph import GraphIndex
+from .baselines import BASELINES
+from .evaluate import consensus_rounds, slem, spectral_gap
+from .problem import MixingProblem
+from .solution import Solution
+from .solvers import SolveOptions, available_methods, choose_method, get_solver
+
+__all__ = ["solve", "compare", "available_methods"]
+
+
+def solve(
+    graph: nx.Graph,
+    method: str = "auto",
+    tol: float = 1e-6,
+    max_iter: int | None = None,
+    time_limit: float | None = None,
+    warm_start: Solution | None = None,
+    verbose: bool = False,
+    callback: Callable[[int, float, float], bool | None] | None = None,
+    *,
+    allow_negative: bool = False,
+    stationary=None,
+    symmetric: bool = True,
+    **options,
+) -> Solution:
+    """Compute the fastest-mixing weights on ``graph``.
+
+    Parameters
+    ----------
+    graph : networkx.Graph
+        Undirected and connected.  Edge attributes are ignored -- the graph
+        supplies the *support*, and the weights are what this computes.  Self
+        loops are ignored: the diagonal is implied by the row sums.
+    method : {"auto", "admm", "smoothing", "subgradient", "cvxpy"}
+        ``"auto"`` uses an exact conic solve for small graphs when CVXPY is
+        installed and ADMM otherwise.  You should not need to change this.
+        ``"admm"`` itself switches to a matrix-free implementation above
+        ``dense_below`` nodes and runs in ``O(m + nk)`` memory from there on;
+        ``"smoothing"`` needs a full eigendecomposition every iteration and
+        refuses above 2000 nodes rather than trying.
+    tol : float
+        Scaled residual tolerance.  Not the same thing as accuracy in the
+        objective: see :attr:`Solution.certified_gap` for that.
+    max_iter : int, optional
+        Iteration cap.  Derived from ``n`` when omitted.
+    time_limit : float, optional
+        Seconds.  On expiry the best feasible iterate found so far is returned
+        with ``status="time_limit"`` and ``converged=False``.  Worth setting on
+        anything unfamiliar: a badly conditioned graph converges slowly, and
+        without a budget that looks exactly like a hang.
+    warm_start : Solution, optional
+        A previous solution on the same node set.  See :func:`mixingmatrix.update`,
+        which does this dispatch for you and can often skip the solve outright.
+    callback : callable, optional
+        ``fn(iteration, residual, slem) -> bool``.  Returning ``False`` stops the
+        solve and returns the best iterate so far with ``status="stopped"``.
+    allow_negative : bool
+        Solve FDLA instead of FMMC (Xiao & Boyd 2004): drop ``w >= 0``, so the
+        result is an averaging operator rather than a Markov chain.  Always at
+        least as fast-mixing as the FMMC optimum, often noticeably so, and it
+        is what the distributed-averaging literature uses.
+    stationary : mapping or array, optional
+        Target stationary distribution.  The result is the fastest reversible
+        chain with that distribution, and ``Solution.weights`` is then a
+        row-stochastic but nonsymmetric transition matrix.  Uniform by default.
+    symmetric : bool
+        Reserved for the non-reversible variant, which is not implemented.
+    **options
+        Passed through to the solver.  The ones worth knowing:
+        ``spectrum`` (``"auto"``/``"dense"``/``"lanczos"``) forces the dense or
+        matrix-free implementation instead of letting size decide;
+        ``dense_below`` (400) moves that crossover; ``rho``, ``adaptive_rho``,
+        ``lanczos_k``, ``qp_backend``, ``adaptive_inner_tol``.
+
+    Returns
+    -------
+    Solution
+
+    Notes
+    -----
+    Nothing here forms a dense ``n x n`` array above ``dense_below`` nodes, so
+    memory is not what limits the size of a solve -- see ``docs/scaling.md``
+    for what is.  Set ``time_limit`` on anything large: every iterate is a
+    legal mixing matrix, so a budget returns the best one reached rather than
+    nothing, and ``certified_gap`` says how good it is.
+
+    Examples
+    --------
+    >>> import networkx as nx, mixingmatrix
+    >>> sol = mixingmatrix.solve(nx.cycle_graph(6), tol=1e-9)
+    >>> round(sol.slem, 4)          # uniform weight 0.4 on every edge
+    0.6
+    >>> sol.converged
+    True
+    """
+    if not symmetric:
+        raise NotImplementedError(
+            "symmetric=False (a non-reversible row-stochastic chain) is not "
+            "implemented. That problem minimises the second-largest *singular* "
+            "value of a nonsymmetric matrix and needs a different spectral "
+            "step; it is not a flag away. Use stationary=pi for a reversible "
+            "chain with a nonuniform stationary distribution."
+        )
+
+    ix = GraphIndex(graph)
+    pi = ix.stationary_vector(stationary)
+    if pi is not None and allow_negative:
+        raise ValueError(
+            "allow_negative=True and stationary=pi are incompatible: a chain "
+            "with negative weights has no stationary distribution to target"
+        )
+    problem = MixingProblem(ix, stationary=pi, nonneg=not allow_negative)
+
+    if method == "auto":
+        method = choose_method(problem.n, nonneg=problem.nonneg)
+    solver = get_solver(method)
+
+    state = None
+    if warm_start is not None:
+        state = _warm_start_state(warm_start, problem)
+
+    opts = SolveOptions(
+        tol=tol, max_iter=max_iter, time_limit=time_limit, verbose=verbose,
+        callback=callback, warm_start=state,
+        **{k: v for k, v in options.items() if k in SolveOptions.__dataclass_fields__},
+    )
+    unknown = set(options) - set(SolveOptions.__dataclass_fields__)
+    if unknown:
+        opts.extra.update({k: options[k] for k in unknown})
+
+    if verbose:
+        print(f"mixingmatrix: {problem!r} via {method}, tol={tol:g}")
+    t0 = time.perf_counter()
+    out = solver(problem, opts)
+    runtime = time.perf_counter() - t0
+
+    sol = Solution(
+        problem=problem, w=np.asarray(out.w, dtype=float), status=out.status,
+        iterations=out.iterations, runtime=runtime, method=method,
+        residuals={"primal": out.primal_residual, "dual": out.dual_residual,
+                   "tolerance": out.tolerance},
+        options={"method": method, "tol": tol, "max_iter": max_iter,
+                 "time_limit": time_limit, **options},
+        solver_state=out.state, info=dict(out.info),
+    )
+    if out.status in ("max_iter", "infeasible"):
+        warnings.warn(
+            f"mixingmatrix.solve did not converge (status={out.status!r}, "
+            f"{out.iterations} iterations, slem={sol.slem:.8f}). The matrix is "
+            "feasible and usable; it is not proven optimal. Raise max_iter or "
+            "loosen tol, and check Solution.certified_gap.",
+            RuntimeWarning, stacklevel=2,
+        )
+    return sol
+
+
+def _warm_start_state(warm_start: Solution, problem: MixingProblem) -> dict:
+    """Carry solver state across a solve, refusing to do so when it is not valid.
+
+    ``Z`` and ``U`` live in node-index space, so they only transfer when the
+    node set *and its ordering* are unchanged.  Weights transfer per edge and
+    are matched by label, so an edge that vanished is dropped and a new one
+    starts at zero -- which is exactly the right guess for an edge that was not
+    worth having a moment ago.
+    """
+    old_ix, new_ix = warm_start.ix, problem.ix
+    state: dict = {}
+    if not old_ix.same_nodes(new_ix):
+        return state
+    if warm_start.problem.uniform != problem.uniform:
+        return state
+    w = np.zeros(problem.m)
+    old = dict(zip(old_ix.edges, warm_start.w, strict=True))
+    for e, key in enumerate(new_ix.edges):
+        if key in old:
+            w[e] = old[key]
+    state["w"] = w
+    for field in ("Z", "U", "rho"):
+        if field in warm_start.solver_state:
+            state[field] = warm_start.solver_state[field]
+    return state
+
+
+def compare(
+    graph: nx.Graph,
+    methods: Sequence[str] = ("optimal", "metropolis", "max_degree", "best_constant"),
+    eps: float = 1e-6,
+    x0=None,
+    **solve_kwargs,
+):
+    """One table showing what optimal weights buy on *this* graph.
+
+    Parameters
+    ----------
+    graph : networkx.Graph
+    methods : sequence of str
+        Any of ``"optimal"`` (:func:`solve`), ``"fdla"`` (``solve`` with
+        ``allow_negative=True``), and the baselines ``"metropolis"``,
+        ``"max_degree"``, ``"best_constant"``, ``"lazy_random_walk"``.
+    eps : float
+        Consensus accuracy the round counts are quoted at.
+    x0 : array, optional
+        If given, the table also reports the *measured* rounds to consensus
+        from this starting state, next to the predicted ones.  The two differ:
+        the prediction is asymptotic and generally conservative for a random
+        start.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Columns ``method, slem, spectral_gap, consensus_rounds, speedup,
+        runtime``, sorted by SLEM.  ``speedup`` is the round-count ratio
+        against Metropolis-Hastings, the weighting a user most likely already
+        has -- the honest statement of the benefit, since a SLEM that is 5%
+        better is not a 5% faster anything.
+    """
+    import pandas as pd
+
+    rows = []
+    for name in methods:
+        t0 = time.perf_counter()
+        if name in ("optimal", "fmmc"):
+            B = solve(graph, allow_negative=False, **solve_kwargs).weights
+        elif name == "fdla":
+            B = solve(graph, allow_negative=True, **solve_kwargs).weights
+        elif name in BASELINES:
+            B = BASELINES[name](graph)
+        else:
+            raise ValueError(
+                f"unknown method {name!r}; choose from 'optimal', 'fdla', "
+                f"{sorted(BASELINES)}"
+            )
+        runtime = time.perf_counter() - t0
+        row = {
+            "method": name,
+            "slem": slem(B),
+            "spectral_gap": spectral_gap(B),
+            "consensus_rounds": consensus_rounds(B, eps=eps),
+            "runtime": runtime,
+        }
+        if x0 is not None:
+            from .simulate import rounds_to_consensus
+
+            row["measured_rounds"] = rounds_to_consensus(B, x0, eps=eps)
+        rows.append(row)
+
+    df = pd.DataFrame(rows).sort_values("slem").reset_index(drop=True)
+    ref = df.loc[df["method"] == "metropolis", "consensus_rounds"]
+    if len(ref) and np.isfinite(ref.iloc[0]):
+        df["speedup"] = ref.iloc[0] / df["consensus_rounds"]
+    return df[[c for c in ("method", "slem", "spectral_gap", "consensus_rounds",
+                           "measured_rounds", "speedup", "runtime") if c in df]]

mixingmatrix/baselines.py

@@ -0,0 +1,152 @@
+"""The weights people actually use, so the optimum has something to beat.
+
+These ship with the package on purpose.  The question a user has is never
+"what is the fastest mixing chain on my graph" in the abstract -- it is
+"is it worth replacing the Metropolis-Hastings weights I already have".
+Answering that should not require them to implement the comparison.
+
+All four return the same type as :attr:`mixingmatrix.Solution.weights`, a
+``scipy.sparse.csr_matrix``, so they drop straight into
+:func:`mixingmatrix.slem`, :func:`mixingmatrix.gossip` and :func:`mixingmatrix.compare`.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+import numpy as np
+import scipy.sparse as sp
+
+import scipy.sparse.linalg as spla
+
+from ._graph import GraphIndex
+from .problem import MixingProblem
+from .spectral import DENSE_LIMIT, symmetrize
+
+__all__ = [
+    "metropolis_hastings",
+    "max_degree",
+    "best_constant",
+    "lazy_random_walk",
+    "BASELINES",
+]
+
+
+def metropolis_hastings(graph: nx.Graph, stationary=None) -> sp.csr_matrix:
+    """``w_ij = 1 / (1 + max(d_i, d_j))`` -- the universal default.
+
+    Needs no global information (each node knows its own degree and its
+    neighbours'), which is why it is what nearly every distributed averaging
+    implementation ships with, and why it is the right thing to measure
+    against.  With ``stationary`` given, this is the Metropolis-Hastings chain
+    targeting that distribution over the graph's uniform proposal.
+    """
+    ix = GraphIndex(graph)
+    problem = MixingProblem(ix, stationary=ix.stationary_vector(stationary))
+    return problem.transition_sparse(problem.metropolis_weights())
+
+
+def max_degree(graph: nx.Graph) -> sp.csr_matrix:
+    """``w_ij = 1 / d_max`` on every edge: one global constant, no tuning.
+
+    The simplest weighting that is guaranteed stochastic, and the one whose
+    weakness is easiest to see: a single high-degree node slows down every edge
+    in the graph, including edges nowhere near it.
+    """
+    ix = GraphIndex(graph)
+    problem = MixingProblem(ix)
+    d_max = float(ix.degrees().max()) if ix.n > 1 else 1.0
+    w = np.full(problem.m, 1.0 / d_max) if d_max > 0 else np.zeros(problem.m)
+    return problem.to_sparse(w)
+
+
+def best_constant(graph: nx.Graph, allow_negative: bool = False) -> sp.csr_matrix:
+    """The best possible *single* weight on every edge: ``B = I - alpha L``.
+
+    Solved exactly, not searched.  The eigenvalues of ``B`` are ``1 - alpha
+    mu_i`` for the Laplacian eigenvalues ``mu_i``, so
+
+        SLEM(alpha) = max(|1 - alpha mu_2|, |1 - alpha mu_n|)
+
+    which is a convex piecewise-linear function of one variable, minimised
+    where the two terms meet: ``alpha* = 2 / (mu_2 + mu_n)`` (Xiao & Boyd 2004).
+    Nonnegativity of the chain caps ``alpha`` at ``1/d_max``, and because
+    ``SLEM`` is convex the constrained optimum is just the clipped ``alpha*``.
+
+    This is the honest measure of what *edge-specific* weights buy: the gap
+    between this and :func:`mixingmatrix.solve` is the part of the improvement that
+    could not have come from a single well-chosen scalar.
+    """
+    ix = GraphIndex(graph)
+    problem = MixingProblem(ix)
+    n = ix.n
+    if n <= 1 or problem.m == 0:
+        return sp.csr_matrix(np.ones((n, n)))
+    mu2, mun = _laplacian_extremes(ix)
+    alpha = 2.0 / (mu2 + mun) if (mu2 + mun) > 0 else 0.0
+    if not allow_negative:
+        d_max = float(ix.degrees().max())
+        alpha = min(alpha, 1.0 / d_max if d_max > 0 else alpha)
+    return problem.to_sparse(np.full(problem.m, alpha))
+
+
+def _laplacian_extremes(ix: GraphIndex) -> tuple[float, float]:
+    """``(mu_2, mu_n)``: the algebraic connectivity and the largest Laplacian
+    eigenvalue, which is all the closed form needs.
+
+    Dense below :data:`~mixingmatrix.spectral.DENSE_LIMIT`; above it, two Lanczos
+    calls -- ``mu_n`` directly, and ``mu_2`` as the smallest eigenvalue of the
+    Laplacian deflated against its known null vector ``1``, which is exact
+    rather than a shift-invert approximation.
+    """
+    n = ix.n
+    L = nx.laplacian_matrix(ix.to_graph(), nodelist=list(ix.nodes)).astype(float)
+    if n <= DENSE_LIMIT:
+        mu = np.sort(np.linalg.eigvalsh(symmetrize(L.toarray())))
+        return float(mu[1]), float(mu[-1])
+    Lc = L.tocsr()
+    mun = float(spla.eigsh(Lc, k=1, which="LA", tol=1e-8,
+                           return_eigenvectors=False)[0])
+    ones = np.full(n, 1.0 / np.sqrt(n))
+
+    def shifted(x):
+        # L + mu_n * (1 1^T / n): pushes the null vector to the top of the
+        # spectrum so that the smallest eigenvalue of the shifted operator is
+        # mu_2 exactly, with no other eigenvalue moved.
+        return Lc @ x + (mun * float(ones @ x)) * ones
+
+    op = spla.LinearOperator((n, n), matvec=shifted, dtype=float)
+    mu2 = float(spla.eigsh(op, k=1, which="SA", tol=1e-8,
+                           ncv=min(n - 1, 60), return_eigenvectors=False)[0])
+    return mu2, mun
+
+
+def lazy_random_walk(graph: nx.Graph, p: float = 0.5) -> sp.csr_matrix:
+    """``P = (1 - p) I + p D^{-1} A`` -- the lazy simple random walk.
+
+    Included because it is the chain most of the Markov-chain literature means
+    by "the random walk on G", and because it is a useful reminder that a valid
+    chain need not be doubly stochastic: this one has stationary distribution
+    proportional to degree, not uniform, so it converges to a *degree-weighted*
+    average rather than the mean.  :func:`mixingmatrix.slem` handles it correctly;
+    :func:`mixingmatrix.gossip` will happily show it converging to the wrong thing.
+    """
+    if not 0.0 < p <= 1.0:
+        raise ValueError(f"laziness p must be in (0, 1], got {p}")
+    ix = GraphIndex(graph)
+    n = ix.n
+    i, j = np.array([e[0] for e in ix.edges] or [], dtype=int), \
+        np.array([e[1] for e in ix.edges] or [], dtype=int)
+    A = sp.csr_matrix((np.ones(2 * ix.m), (np.concatenate([i, j]),
+                                           np.concatenate([j, i]))), shape=(n, n))
+    deg = np.asarray(A.sum(axis=1)).ravel()
+    deg[deg == 0] = 1.0
+    return sp.csr_matrix((1.0 - p) * sp.eye(n) + p * (sp.diags(1.0 / deg) @ A))
+
+
+#: Name -> callable, for :func:`mixingmatrix.compare` and the CLI.
+BASELINES = {
+    "metropolis": metropolis_hastings,
+    "max_degree": max_degree,
+    "best_constant": best_constant,
+    "lazy_random_walk": lazy_random_walk,
+}