Source code for egttools.numerical.estimators

"""
Python wrapper classes for egttools MC estimators.

These wrappers add three things the underlying C++ classes do not provide:

1. **Rich result objects** — every method returns a typed dataclass
   (FixationResult, StrategyDistributionResult, …) that carries the point
   estimate, standard error, 95 % CI, and prints a readable summary.

2. **Optional progress bar** — pass ``verbose=1`` to any estimation method
   and a ``tqdm`` progress bar is shown over the internal chunks.  ``tqdm``
   is an optional dependency; if it is absent the call runs silently.

3. **Optional checkpointing** — pass ``checkpoint_path=<file>`` to any
   estimation method and progress is persisted to disk after every chunk
   (atomically, so a kill mid-write can't corrupt it). If the same
   ``checkpoint_path`` is passed again with identical parameters, the call
   resumes from the last completed chunk instead of starting over — useful
   for long runs on clusters with job time limits. Resuming is statistically
   independent (never repeats a chunk's random draws) and, if
   ``egttools.Random`` state capture succeeds, bit-exact — see
   ``egttools.Random.get_state``/``set_state``. Passing a ``checkpoint_path``
   with parameters that don't match an existing checkpoint raises rather
   than silently resuming incorrectly. The checkpoint file is removed once
   the call completes normally, so a later call with the same path starts
   fresh again.

The wrappers use *chunked execution*: ``nb_runs`` is split into ``n_chunks``
equal pieces, each piece runs as a single C++ call, and the SE is computed as
``std(chunk_means) / sqrt(n_chunks)``.  This gives SE estimates for methods
that otherwise return only a point estimate (e.g.
``PairwiseComparisonNumerical.estimate_fixation_probability``), and doubles
as the natural checkpoint boundary described above.

All other attributes and methods of the underlying C++ object are accessible
directly via ``__getattr__``, so these wrappers are drop-in replacements.
"""

from __future__ import annotations

import hashlib
import os
import pickle
import warnings
from typing import Optional, Sequence

import numpy as np

from .results import (
    AbsorptionProbabilityResult,
    AbsorptionTimeResult,
    AGoSResult,
    FixationResult,
    StationaryDistributionResult,
    StrategyDistributionResult,
)


# ---------------------------------------------------------------------------
# Internal helpers
# ---------------------------------------------------------------------------

def _chunk_iterator(iterable, verbose: int, desc: str):
    """Wrap `iterable` in a tqdm progress bar when verbose>=1, else iterate as-is."""
    if verbose >= 1:
        try:
            from tqdm import tqdm
            return tqdm(iterable, desc=desc, unit="chunk")
        except ImportError:
            pass
    return iterable


def _split_runs(nb_runs: int, n_chunks: int):
    """Split nb_runs into at most n_chunks balanced sizes; return list of ints."""
    n_chunks = max(1, min(n_chunks, nb_runs))
    base, remainder = divmod(nb_runs, n_chunks)
    return [base + (1 if i < remainder else 0) for i in range(n_chunks)]


def _combine_chunks(chunk_means: list, chunk_ses: list | None = None):
    """
    Combine per-chunk (mean, se) arrays.
    SE is the maximum of between-chunk variation and mean within-chunk SE.
    """
    stack = np.stack(chunk_means)
    mean = stack.mean(axis=0)
    n = len(chunk_means)
    between = stack.std(axis=0, ddof=1) / np.sqrt(n) if n > 1 else np.zeros_like(mean)
    if chunk_ses:
        within = np.stack(chunk_ses).mean(axis=0)
        se = np.maximum(between, within)
    else:
        se = between
    return mean, se


def _params_key(*args, **kwargs) -> str:
    """Stable hash of a call's defining parameters, used to detect a
    mismatched/stale checkpoint (e.g. resuming with different nb_generations)."""
    payload = repr((args, sorted(kwargs.items())))
    return hashlib.sha256(payload.encode()).hexdigest()


def _rng_get_state():
    """Best-effort capture of the global RNG state for the checkpoint payload.
    Never fails the caller — checkpointing degrades gracefully to
    statistically-independent-but-not-bit-exact resume if this is unavailable."""
    try:
        import egttools
        return egttools.Random.get_state()
    except Exception:
        return None


def _rng_set_state(state) -> None:
    if state is None:
        return
    try:
        import egttools
        egttools.Random.set_state(state)
    except Exception:
        pass


def _load_checkpoint(checkpoint_path, params_key):
    if checkpoint_path is None or not os.path.exists(checkpoint_path):
        return None
    with open(checkpoint_path, "rb") as f:
        data = pickle.load(f)
    if data.get("params_key") != params_key:
        raise ValueError(
            f"Checkpoint at {checkpoint_path!r} was created with different "
            "parameters than this call (nb_runs/nb_generations/beta/mu/... "
            "differ). Refusing to resume from a mismatched checkpoint — use "
            "a different checkpoint_path, or delete the existing file if "
            "starting over is intentional."
        )
    return data


def _save_checkpoint(checkpoint_path, params_key, chunk_results, next_chunk_idx, rng_state) -> None:
    """Atomically persist checkpoint state: write to a temp file then
    os.replace into place, so a kill mid-write can't corrupt it."""
    data = {
        "params_key": params_key,
        "chunk_results": chunk_results,
        "next_chunk_idx": next_chunk_idx,
        "rng_state": rng_state,
    }
    tmp_path = f"{checkpoint_path}.tmp"
    with open(tmp_path, "wb") as f:
        pickle.dump(data, f)
    os.replace(tmp_path, checkpoint_path)


def _run_chunks_with_checkpoint(
    compute_chunk,
    sizes,
    verbose: int,
    desc: str,
    checkpoint_path=None,
    params_key=None,
):
    """
    Calls ``compute_chunk(sizes[idx])`` once per chunk index, returning the
    list of per-chunk results in the same order as `sizes`.

    When `checkpoint_path` is given, persists progress atomically after every
    chunk and resumes from an existing, matching checkpoint instead of
    starting over — see the module docstring's "Optional checkpointing"
    section. The checkpoint file is removed once all chunks complete.
    """
    if checkpoint_path is None:
        return [compute_chunk(sizes[idx]) for idx in _chunk_iterator(range(len(sizes)), verbose, desc)]

    if len(sizes) < 5:
        warnings.warn(
            f"checkpoint_path is set but n_chunks resolved to only {len(sizes)} "
            "chunk(s) — a single giant chunk gives checkpointing nothing to "
            "resume from until it finishes. Consider a larger n_chunks.",
            RuntimeWarning,
            stacklevel=3,
        )

    checkpoint = _load_checkpoint(checkpoint_path, params_key)
    if checkpoint is not None:
        chunk_results = list(checkpoint["chunk_results"])
        start_idx = checkpoint["next_chunk_idx"]
        _rng_set_state(checkpoint.get("rng_state"))
    else:
        chunk_results = []
        start_idx = 0

    for idx in _chunk_iterator(range(start_idx, len(sizes)), verbose, desc):
        chunk_results.append(compute_chunk(sizes[idx]))
        _save_checkpoint(checkpoint_path, params_key, chunk_results, idx + 1, _rng_get_state())

    if os.path.exists(checkpoint_path):
        os.remove(checkpoint_path)

    return chunk_results


# ---------------------------------------------------------------------------
# PairwiseComparisonEstimator
# ---------------------------------------------------------------------------

[docs] class PairwiseComparisonEstimator: """ Wraps :class:`egttools.numerical.PairwiseComparisonNumerical` and returns rich result objects with standard errors and optional progress bars. Parameters ---------- game : AbstractGame The game to associate with the estimator. ``nb_strategies`` is read from the game object. pop_size : int Population size. cache_size : int, optional LRU cache size for fitness computations (default 100 000). strategy_names : list[str], optional Human-readable strategy names used in result reprs. mutation_weights : array_like, optional Biases the mutation kernel away from uniform. Either a 1D array of length ``nb_strategies`` (target-strategy bias shared by all source strategies) or a 2D array of shape ``(nb_strategies, nb_strategies)`` (row ``i`` is the bias over target strategies when mutating away from strategy ``i``). See ``PairwiseComparisonNumerical.set_mutation_weights`` for details. Defaults to uniform mutation when omitted. """
[docs] def __init__(self, game, pop_size: int, cache_size: int = 100_000, strategy_names: Optional[Sequence[str]] = None, mutation_weights=None): from egttools.numerical import PairwiseComparisonNumerical self._est = PairwiseComparisonNumerical(pop_size, game, cache_size) self._strategy_names = list(strategy_names) if strategy_names else None if mutation_weights is not None: self._est.set_mutation_weights(mutation_weights)
[docs] def __getattr__(self, name): return getattr(self._est, name)
# -------------------------------------------------------------------------
[docs] def estimate_fixation_probability( self, invader: int, resident: int, nb_runs: int, nb_generations: int, beta: float, verbose: int = 0, n_chunks: int = 10, checkpoint_path: Optional[str] = None, ) -> FixationResult: sizes = _split_runs(nb_runs, n_chunks) params_key = _params_key( "estimate_fixation_probability", invader, resident, nb_runs, nb_generations, beta, n_chunks ) estimates = _run_chunks_with_checkpoint( lambda size: float(self._est.estimate_fixation_probability( invader, resident, size, nb_generations, beta )), sizes, verbose, "estimate_fixation_probability", checkpoint_path=checkpoint_path, params_key=params_key, ) mean, se = float(np.mean(estimates)), 0.0 if len(estimates) > 1: se = float(np.std(estimates, ddof=1) / np.sqrt(len(estimates))) result = FixationResult(estimate=mean, stderr=se, nb_runs=nb_runs, invader=invader, resident=resident) if verbose >= 1: print(result) return result
[docs] def estimate_mean_absorption_time( self, beta: float, init_state, nb_runs: int, verbose: int = 0, n_chunks: int = 10, checkpoint_path: Optional[str] = None, ) -> AbsorptionTimeResult: sizes = _split_runs(nb_runs, n_chunks) params_key = _params_key( "estimate_mean_absorption_time", beta, tuple(np.asarray(init_state).tolist()), nb_runs, n_chunks ) means = _run_chunks_with_checkpoint( lambda size: float(self._est.estimate_mean_absorption_time(beta, init_state, size)["mean"]), sizes, verbose, "estimate_mean_absorption_time", checkpoint_path=checkpoint_path, params_key=params_key, ) m = float(np.mean(means)) se = float(np.std(means, ddof=1) / np.sqrt(len(means))) if len(means) > 1 else 0.0 result = AbsorptionTimeResult(mean=m, stderr=se, nb_runs=nb_runs) if verbose >= 1: print(result) return result
[docs] def estimate_absorption_probabilities( self, beta: float, init_state, nb_runs: int, verbose: int = 0, n_chunks: int = 10, checkpoint_path: Optional[str] = None, ) -> AbsorptionProbabilityResult: sizes = _split_runs(nb_runs, n_chunks) params_key = _params_key( "estimate_absorption_probabilities", beta, tuple(np.asarray(init_state).tolist()), nb_runs, n_chunks ) chunks = _run_chunks_with_checkpoint( lambda size: np.asarray( self._est.estimate_absorption_probabilities(beta, init_state, size), dtype=float ), sizes, verbose, "estimate_absorption_probabilities", checkpoint_path=checkpoint_path, params_key=params_key, ) mean, se = _combine_chunks(chunks) result = AbsorptionProbabilityResult( probabilities=mean, stderr=se, nb_runs=nb_runs, strategy_names=self._strategy_names, ) if verbose >= 1: print(result) return result
[docs] def estimate_stationary_distribution( self, nb_runs: int, nb_generations: int, transitory: int, beta: float, mu: float, verbose: int = 0, n_chunks: int = 10, checkpoint_path: Optional[str] = None, **kwargs, ) -> StationaryDistributionResult: sizes = _split_runs(nb_runs, n_chunks) params_key = _params_key( "estimate_stationary_distribution", nb_runs, nb_generations, transitory, beta, mu, n_chunks, **kwargs ) chunks = _run_chunks_with_checkpoint( lambda size: np.asarray( self._est.estimate_stationary_distribution( size, nb_generations, transitory, beta, mu, **kwargs ), dtype=float, ), sizes, verbose, "estimate_stationary_distribution", checkpoint_path=checkpoint_path, params_key=params_key, ) distribution = np.stack(chunks).mean(axis=0) result = StationaryDistributionResult(distribution=distribution, nb_runs=nb_runs) if verbose >= 1: print(result) return result
[docs] def estimate_strategy_distribution( self, nb_runs: int, nb_generations: int, transitory: int, beta: float, mu: float, verbose: int = 0, n_chunks: int = 10, checkpoint_path: Optional[str] = None, **kwargs, ) -> StrategyDistributionResult: sizes = _split_runs(nb_runs, n_chunks) params_key = _params_key( "estimate_strategy_distribution", nb_runs, nb_generations, transitory, beta, mu, n_chunks, **kwargs ) chunks = _run_chunks_with_checkpoint( lambda size: np.asarray( self._est.estimate_strategy_distribution( size, nb_generations, transitory, beta, mu, **kwargs ), dtype=float, ), sizes, verbose, "estimate_strategy_distribution", checkpoint_path=checkpoint_path, params_key=params_key, ) mean, se = _combine_chunks(chunks) result = StrategyDistributionResult( mean=mean, stderr=se, nb_runs=nb_runs, strategy_names=self._strategy_names, ) if verbose >= 1: print(result) return result
# --------------------------------------------------------------------------- # NetworkEstimator # ---------------------------------------------------------------------------
[docs] class NetworkEstimator: """ Wraps any ``NetworkMCEstimator*`` C++ instance and returns rich result objects with optional progress bars. Parameters ---------- cpp_estimator A C++ estimator returned by e.g. ``network_mc_estimator_factory()``. strategy_names : list[str], optional Human-readable strategy names used in result reprs. """
[docs] def __init__(self, cpp_estimator, strategy_names: Optional[Sequence[str]] = None): self._est = cpp_estimator self._strategy_names = list(strategy_names) if strategy_names else None
[docs] def __getattr__(self, name): return getattr(self._est, name)
# -------------------------------------------------------------------------
[docs] def estimate_fixation_probability( self, invader: int, resident: int, nb_runs: int, nb_generations: int, verbose: int = 0, n_chunks: int = 10, checkpoint_path: Optional[str] = None, ) -> FixationResult: sizes = _split_runs(nb_runs, n_chunks) params_key = _params_key( "network_estimate_fixation_probability", invader, resident, nb_runs, nb_generations, n_chunks ) estimates = _run_chunks_with_checkpoint( lambda size: float(self._est.estimate_fixation_probability( invader, resident, size, nb_generations )), sizes, verbose, "estimate_fixation_probability", checkpoint_path=checkpoint_path, params_key=params_key, ) mean, se = float(np.mean(estimates)), 0.0 if len(estimates) > 1: se = float(np.std(estimates, ddof=1) / np.sqrt(len(estimates))) result = FixationResult(estimate=mean, stderr=se, nb_runs=nb_runs, invader=invader, resident=resident) if verbose >= 1: print(result) return result
[docs] def estimate_strategy_distribution( self, nb_runs: int, nb_generations: int, transitory: int = 0, verbose: int = 0, n_chunks: int = 10, checkpoint_path: Optional[str] = None, **kwargs, ) -> StrategyDistributionResult: sizes = _split_runs(nb_runs, n_chunks) params_key = _params_key( "network_estimate_strategy_distribution", nb_runs, nb_generations, transitory, n_chunks, **kwargs ) chunk_pairs = _run_chunks_with_checkpoint( lambda size: tuple( np.asarray(x, dtype=float) for x in self._est.estimate_strategy_distribution(size, nb_generations, transitory, **kwargs) ), sizes, verbose, "estimate_strategy_distribution", checkpoint_path=checkpoint_path, params_key=params_key, ) chunk_means = [m for m, _ in chunk_pairs] chunk_ses = [s for _, s in chunk_pairs] mean, se = _combine_chunks(chunk_means, chunk_ses) result = StrategyDistributionResult( mean=mean, stderr=se, nb_runs=nb_runs, strategy_names=self._strategy_names, ) if verbose >= 1: print(result) return result
[docs] def estimate_agos( self, nb_runs: int, nb_generations: int, transitory: int = 0, runs_per_j: int = 0, verbose: int = 0, n_chunks: int = 10, checkpoint_path: Optional[str] = None, ) -> AGoSResult: if runs_per_j > 0: # runs_per_j mode: nb_runs is ignored by C++; chunk by repeating # runs_per_j calls n_chunks times and averaging. sizes = [runs_per_j] * n_chunks params_key = _params_key( "network_estimate_agos_per_j", nb_generations, transitory, runs_per_j, n_chunks ) chunk_pairs = _run_chunks_with_checkpoint( lambda size: tuple( np.asarray(x, dtype=float) for x in self._est.estimate_agos(0, nb_generations, transitory, size) ), sizes, verbose, "estimate_agos", checkpoint_path=checkpoint_path, params_key=params_key, ) total_runs = runs_per_j * n_chunks else: sizes = _split_runs(nb_runs, n_chunks) params_key = _params_key( "network_estimate_agos", nb_runs, nb_generations, transitory, n_chunks ) chunk_pairs = _run_chunks_with_checkpoint( lambda size: tuple( np.asarray(x, dtype=float) for x in self._est.estimate_agos(size, nb_generations, transitory, 0) ), sizes, verbose, "estimate_agos", checkpoint_path=checkpoint_path, params_key=params_key, ) total_runs = nb_runs chunk_means = [m for m, _ in chunk_pairs] chunk_ses = [s for _, s in chunk_pairs] mean, se = _combine_chunks(chunk_means, chunk_ses) result = AGoSResult( mean_gradient=mean, se_gradient=se, nb_runs=total_runs, strategy_names=self._strategy_names, ) if verbose >= 1: print(result) return result