Pular para conteúdo

tucoopy.diagnostics.epsilon_core_diagnostics

Epsilon-core diagnostics.

This module provides :func:epsilon_core_diagnostics, which evaluates whether a payoff vector \(x\) belongs to the epsilon-core of a transferable-utility (TU) game.

Definitions

For a TU game with characteristic function \(v\) and an allocation \(x\):

  • Coalition sum: \(x(S) = \sum_{i in S} x_i\)
  • Excess: \(e(S, x) = v(S) - x(S)\)

The epsilon-core consists of efficient allocations such that:

$\(\max_{\{S \subset N, S \neq \varnothing\}} e(S, x) \leq \epsilon\)$.

Notes
  • This diagnostic scans all coalitions (excluding \(\varnothing\) and \(N\)), so it is exponential in n_players.
  • Numerical comparisons use tol for efficiency checks and tie detection.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.diagnostics.epsilon_core_diagnostics import epsilon_core_diagnostics
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> d = epsilon_core_diagnostics(g, [0.5, 0.5], epsilon=0.0)
>>> d.in_set
True

EpsilonCoreDiagnostics dataclass

Diagnostics for epsilon-core membership at an allocation \(x\).

In addition to efficiency, the epsilon-core membership test is:

$$ \text{max excess} \leq \epsilon $$.

Attributes:

Name Type Description
n_players int

Number of players.
vN float

Grand coalition value v(N).
sum_x float

Sum of the allocation vector.
efficient bool

Whether sum_x matches vN within tol.
epsilon float

The epsilon parameter of the epsilon-core.
in_set bool

Whether x belongs to the epsilon-core with the provided epsilon.
max_excess float

Maximum excess over all proper non-empty coalitions.
tight_coalitions list[int]

Coalitions attaining max_excess (ties within tol).
violations list[EpsilonCoreViolation]

Most violated coalitions, sorted by excess descending.

Examples:

>>> d = EpsilonCoreDiagnostics(
...     n_players=2,
...     vN=1.0,
...     sum_x=1.0,
...     efficient=True,
...     epsilon=0.0,
...     in_set=True,
...     max_excess=-0.5,
...     tight_coalitions=[1, 2],
...     violations=[],
... )
>>> d.in_set
True

to_dict 

to_dict()

Convert diagnostics to a JSON-serializable dictionary.

Returns:

Type Description
dict

Dictionary representation of the diagnostics dataclass.

Examples:

>>> d = EpsilonCoreDiagnostics(
...     n_players=2,
...     vN=1.0,
...     sum_x=1.0,
...     efficient=True,
...     epsilon=0.0,
...     in_set=True,
...     max_excess=-0.5,
...     tight_coalitions=[1, 2],
...     violations=[],
... )
>>> d.to_dict()["epsilon"]
0.0

EpsilonCoreViolation dataclass

One epsilon-core inequality evaluation at an allocation \(x\).

The epsilon-core constraints are:

\(v(S) - x(S) \leq \epsilon\) for all proper non-empty coalitions \(S\).

Attributes:

Name Type Description
coalition_mask int

Coalition bitmask.
players list[int]

List of player indices in the coalition.
vS float

Coalition value v(S).
xS float

Coalition payoff sum x(S).
excess float

Excess e(S, x) = v(S) - x(S).

Examples:

>>> v = EpsilonCoreViolation(1, [0], 1.0, 0.8, 0.2)
>>> v.excess
0.2

epsilon_core_diagnostics 

epsilon_core_diagnostics(
    game, x, *, epsilon, tol=DEFAULT_GEOMETRY_TOL, top_k=8
)

Compute epsilon-core membership diagnostics for an allocation \(x\).

Parameters:

Name Type Description Default
game GameProtocol

TU game.

 required
x list[float]

Allocation vector of length game.n_players.

 required
epsilon float

Epsilon parameter for the epsilon-core.

 required
tol float

Numerical tolerance used for: - efficiency check (abs(sum(x) - v(N)) <= tol), - tie detection for tight_coalitions.

 DEFAULT_GEOMETRY_TOL
top_k int

Maximum number of violating coalitions to include in violations.

 8

Returns:

Type Description
EpsilonCoreDiagnostics

Diagnostics object including in_set and the most violated coalitions.

Raises:

Type Description
InvalidParameterError

If x does not have length game.n_players.
Notes

Internally, this uses a shared coalition scanner (scan_excesses) to avoid duplicating the exponential coalition loop across diagnostics.

Examples:

A minimal 2-player example (only the grand coalition has value 1):

>>> from tucoopy import Game
>>> from tucoopy.diagnostics.epsilon_core_diagnostics import epsilon_core_diagnostics
>>> g = Game.from_coalitions(n_players=2, values={0:0, 1:0, 2:0, 3:1})
>>> d = epsilon_core_diagnostics(g, [0.5, 0.5], epsilon=0.0)
>>> d.efficient
True
>>> d.in_set
True