Skip to content

tucoopy.diagnostics.least_core_diagnostics

Least-core diagnostics.

The least-core is the epsilon-core with the smallest feasible epsilon value \(\epsilon*\).

This module provides least_core_diagnostics, which:

  1. Computes \(\epsilon*\) via an LP (requires an LP backend),
  2. Reuses tucoopy.diagnostics.epsilon_core_diagnostics.epsilon_core_diagnostics to assess membership of a specific allocation \(x\) in the epsilon-core at \(\epsilon = \epsilon*\).
Notes

If the LP backend is unavailable, diagnostics are returned with available=False and a human-readable reason.

Examples:

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

LeastCoreDiagnostics dataclass

Diagnostics for membership in the least-core (\(\epsilon*\)).

If the LP backend is unavailable, available=False and reason is set.

Attributes:

Name Type Description
available bool

Whether the least-core computation was available (LP backend present).
reason str | None

Explanation when available is False.
epsilon_star float | None

The least-core value epsilon* when available.
epsilon_core EpsilonCoreDiagnostics | None

Epsilon-core diagnostics at epsilon = epsilon* when available.

Examples:

>>> d = LeastCoreDiagnostics(available=False, reason="no backend", epsilon_star=None, epsilon_core=None)
>>> d.available
False

to_dict 

to_dict()

Convert diagnostics to a JSON-serializable dictionary.

Returns:

Type Description
dict

Dictionary representation of the diagnostics dataclass.

Examples:

>>> d = LeastCoreDiagnostics(available=False, reason="no backend", epsilon_star=None, epsilon_core=None)
>>> d.to_dict()["available"]
False

least_core_diagnostics 

least_core_diagnostics(
    game, x, *, tol=DEFAULT_GEOMETRY_TOL, top_k=8
)

Compute least-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
tol float

Numerical tolerance passed to the least-core LP routine and to the epsilon-core diagnostic.

 DEFAULT_GEOMETRY_TOL
top_k int

Maximum number of violating coalitions to include in the epsilon-core sub-diagnostic.

 8

Returns:

Type Description
LeastCoreDiagnostics

Diagnostics including the computed epsilon_star (when available) and the epsilon-core diagnostics at that epsilon.
Notes

This function catches exceptions from the least-core LP routine and returns them as reason. This is intentional to keep diagnostics "UI-friendly".

Examples:

Minimal example (requires an LP backend; skip if not available):

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