egttools.numerical.structure.NetworkMCEstimatorBD

class NetworkMCEstimatorBD(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD, game: egttools.numerical.numerical_.games.AbstractSpatialGame, topology: collections.abc.Mapping[SupportsInt | SupportsIndex, collections.abc.Sequence[SupportsInt | SupportsIndex]], nb_strategies: SupportsInt | SupportsIndex, beta: SupportsFloat | SupportsIndex, mu: SupportsFloat | SupportsIndex, cache_size: SupportsInt | SupportsIndex = 100000)

Bases: pybind11_object

Monte Carlo estimator for evolutionary games on networks using the Birth-Death update rule.

In each step a node is selected to reproduce proportional to fitness, then replaces a random neighbour.

Construct a NetworkMCEstimator.

Parameters:

  • game (egttools.games.AbstractSpatialGame) – Spatial game used to evaluate node fitness.

  • topology (dict[int, list[int]]) – Network adjacency dictionary (e.g. from NetworkX G.adjacency()).

  • nb_strategies (int) – Number of distinct strategies.

  • beta (float) – Selection intensity.

  • mu (float) – Mutation probability per time step.

  • cache_size (int, optional) – Per-thread LRU fitness cache size (default 100000).

Methods

beta

calculate_gradient_of_selection

Numerically exact gradient of selection for the given per-node strategy assignment.

estimate_agos

Estimate the time-independent Average Gradient of Selection G^A(j).

estimate_agos_time_dependent

Estimate the time-dependent Average Gradient of Selection G^A(j, t).

estimate_fixation_probability

Estimate the fixation probability of a single invader in an otherwise resident population.

estimate_strategy_distribution

Estimate time-averaged strategy frequencies after the transitory period.

initialize

Overloaded function.

mean_population_state

Return strategy count vector (length = nb_strategies).

mu

nb_strategies

population_size

population_strategies

Return per-node strategy assignments as a list of integers (length = population_size).

run

Run a single trajectory and return aggregate strategy counts per generation.

run_snapshots

Run a trajectory and call callback(generation, population) at each snapshot.

set_beta

set_mu

step

Advance the session by one generation.

topology

__init__(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD, game: egttools.numerical.numerical_.games.AbstractSpatialGame, topology: collections.abc.Mapping[SupportsInt | SupportsIndex, collections.abc.Sequence[SupportsInt | SupportsIndex]], nb_strategies: SupportsInt | SupportsIndex, beta: SupportsFloat | SupportsIndex, mu: SupportsFloat | SupportsIndex, cache_size: SupportsInt | SupportsIndex = 100000) → None

Construct a NetworkMCEstimator.

Parameters:

  • game (egttools.games.AbstractSpatialGame) – Spatial game used to evaluate node fitness.

  • topology (dict[int, list[int]]) – Network adjacency dictionary (e.g. from NetworkX G.adjacency()).

  • nb_strategies (int) – Number of distinct strategies.

  • beta (float) – Selection intensity.

  • mu (float) – Mutation probability per time step.

  • cache_size (int, optional) – Per-thread LRU fitness cache size (default 100000).

__new__(**kwargs)
beta(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD) → float
calculate_gradient_of_selection(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD, population: collections.abc.Sequence[SupportsInt | SupportsIndex]) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']

Numerically exact gradient of selection for the given per-node strategy assignment.

Parameters:

population (list[int]) – Strategy index for each node (length = population_size).

Returns:

Gradient vector of length nb_strategies.

Return type:

numpy.ndarray

estimate_agos(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD, nb_runs: SupportsInt | SupportsIndex, nb_generations: SupportsInt | SupportsIndex, transitory: SupportsInt | SupportsIndex = 0, runs_per_j: SupportsInt | SupportsIndex = 0) → tuple[Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]'], Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]']]

Estimate the time-independent Average Gradient of Selection G^A(j).

Runs independent trajectories; at each post-transitory generation computes the numerically exact gradient and bins the result by cooperator count j. OpenMP-parallelised over runs; per-thread caches prevent contention.

Parameters:

  • nb_runs (int) – Total trajectories when runs_per_j == 0 (random starts).

  • nb_generations (int) – Generations (each = N elementary steps) per trajectory.

  • transitory (int, optional) – Burn-in generations not counted (default 0).

  • runs_per_j (int, optional) – When > 0, uses the paper’s sampling scheme: for each initial cooperator count j0 ∈ {1, …, N-1} exactly runs_per_j trajectories are started with j0 cooperators on random nodes. Total runs = runs_per_j × (N-1); nb_runs is ignored. This gives uniform coverage of all j values.

Returns:

(mean_G, se_G) each of shape (N+1, nb_strategies). Row j holds the average/SE gradient at cooperator count j. Rows 0 and N are zero (absorbing states).

Return type:

tuple[numpy.ndarray, numpy.ndarray]

estimate_agos_time_dependent(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD, nb_runs: SupportsInt | SupportsIndex, nb_generations: SupportsInt | SupportsIndex) → tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]]

Estimate the time-dependent Average Gradient of Selection G^A(j, t).

Like estimate_agos but preserves the generation index, letting you study how the gradient landscape evolves from the initial transient to the stationary regime (e.g. Fig. 2 of Pinheiro et al. 2012).

Returns:

(mean_G_t, se_G_t) each of shape (nb_generations, N+1, nb_strategies). mean_G_t[t, j, k] is the mean gradient of strategy k at generation t and cooperator count j.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

estimate_fixation_probability(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD, invader: SupportsInt | SupportsIndex, resident: SupportsInt | SupportsIndex, nb_runs: SupportsInt | SupportsIndex, nb_generations: SupportsInt | SupportsIndex) → float

Estimate the fixation probability of a single invader in an otherwise resident population.

Parameters:

  • invader (int)

  • resident (int)

  • nb_runs (int)

  • nb_generations (int) – Maximum time-steps per trial.

Returns:

Estimated fixation probability in [0, 1].

Return type:

float

estimate_strategy_distribution(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD, nb_runs: SupportsInt | SupportsIndex, nb_generations: SupportsInt | SupportsIndex, transitory: SupportsInt | SupportsIndex, tolerance: SupportsFloat | SupportsIndex = 0.0, check_every: SupportsInt | SupportsIndex = 0) → tuple[Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']]

Estimate time-averaged strategy frequencies after the transitory period.

Returns:

(mean_frequencies, standard_errors), each of length nb_strategies.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

initialize(*args, **kwargs)

Overloaded function.

  1. initialize(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD, init_state: typing.Annotated[numpy.typing.ArrayLike, numpy.uint64, “[m, 1]”]) -> None

Initialise a manual-stepping session with the given strategy counts.

Parameters:

init_state (numpy.ndarray) – Strategy count vector of length nb_strategies; sum must equal population_size.

  1. initialize(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD) -> None

Initialise a manual-stepping session with a uniformly random strategy assignment.

mean_population_state(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD) → Annotated[numpy.typing.NDArray[numpy.uint64], '[m, 1]']

Return strategy count vector (length = nb_strategies).

mu(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD) → float
nb_strategies(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD) → int
population_size(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD) → int
population_strategies(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD) → list[int]

Return per-node strategy assignments as a list of integers (length = population_size).

run(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD, nb_generations: SupportsInt | SupportsIndex, transitory: SupportsInt | SupportsIndex, init_state: Annotated[numpy.typing.ArrayLike, numpy.uint64, '[m, 1]']) → Annotated[numpy.typing.NDArray[numpy.uint64], '[m, n]']

Run a single trajectory and return aggregate strategy counts per generation.

Returns:

Matrix of shape (nb_generations - transitory, nb_strategies).

Return type:

numpy.ndarray

run_snapshots(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD, nb_generations: SupportsInt | SupportsIndex, transitory: SupportsInt | SupportsIndex, snapshot_interval: SupportsInt | SupportsIndex, init_state: Annotated[numpy.typing.ArrayLike, numpy.uint64, '[m, 1]'], callback: object) → None

Run a trajectory and call callback(generation, population) at each snapshot.

Parameters:

  • snapshot_interval (int) – Call callback every this many generations after transitory.

  • callback (callable) – Called as callback(generation: int, population: list[int]).

set_beta(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD, beta: SupportsFloat | SupportsIndex) → None
set_mu(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD, mu: SupportsFloat | SupportsIndex) → None
step(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD) → None

Advance the session by one generation.

For asynchronous rules: N individual update steps (one per node on average). For synchronous rules (e.g. LinearProportional): one full simultaneous sweep. Raises RuntimeError if initialize() has not been called first.

topology(self: egttools.numerical.numerical_.structure.NetworkMCEstimatorBD) → list[list[int]]
__annotations__ = {}