egttools.numerical.numerical_.calculate_expected_indicators_precomputed

calculate_expected_indicators_precomputed()

Compute expected indicators from a precomputed indicator matrix (pure C++, GIL released).

This is the fast path when the indicator values per group configuration are already known. Precomputing the indicator matrix in Python (e.g. via numpy) and then calling this function avoids all Python callbacks inside the hot loop and enables full GIL release.

The matrix indicator_matrix[g, k] must contain the value of indicator k for group configuration g. For boolean indicators use 0.0 / 1.0. The row order must match the group configuration enumeration of sample_simplex, i.e. row g corresponds to sample_simplex(g, group_size, nb_strategies).

result[k] = sum_s sd(s) * indicator_matrix[:, k] @ prob_vector_for_state_s

Parameters:

  • pop_size (int) – Total number of individuals in the population.

  • group_size (int) – Number of individuals sampled per group interaction.

  • nb_strategies (int) – Number of strategies available in the population.

  • stationary_distribution (scipy.sparse.csr_matrix) – Sparse matrix representing the stationary distribution over population states.

  • indicator_matrix (numpy.ndarray) – Dense matrix of shape (nb_group_configs, nb_indicators).

Returns:

Array of length nb_indicators.

Return type:

numpy.ndarray

Examples

>>> nb_group_configs = calculate_nb_states(group_size, nb_strategies)
>>> indicator_matrix = np.array([
...     [float(sample_simplex(g, group_size, nb_strategies)[0] >= threshold)]
...     for g in range(nb_group_configs)
... ])
>>> eta_G = calculate_expected_indicators_precomputed(
...     pop_size, group_size, nb_strategies, sd, indicator_matrix
... )[0]