`tucoopy.diagnostics.core_diagnostics`¶

Core-family diagnostics (core and epsilon-core membership).¶

This module provides computations around the coalition excess function \(e(S, x) = v(S) - x(S)\) and uses it to:

test whether an allocation is in the core (max_excess <= tol),
compute max-excess coalitions (ties),
list the most violated coalitions for explanation/debug.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.diagnostics.core_diagnostics import core_diagnostics, explain_core_membership
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 1: 0, 2: 0, 3: 1})
>>> d = core_diagnostics(g, [0.5, 0.5])
>>> d.in_core
True
>>> explain_core_membership(g, [0.25, 0.75])[0].startswith("In the core")
True

CoreDiagnostics `dataclass` ¶

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

max_excess is the maximum excess over all non-empty proper coalitions.
violations is the list of the most violated coalitions (sorted by excess desc).
tight_coalitions are coalitions achieving max_excess (within tol used in computation).

Parameters:

Name	Type	Description	Default
`n_players`	`int`	Number of players in the game.	required
`vN`	`float`	Value of the grand coalition.	required
`sum_x`	`float`	Sum of the allocation vector.	required
`efficient`	`bool`	Whether the allocation is efficient.	required
`in_core`	`bool`	Whether the allocation is in the core.	required
`max_excess`	`float`	Maximum excess over all coalitions.	required
`tight_coalitions`	`list of int`	Coalitions achieving the maximum excess.	required
`violations`	`list of CoreViolation`	List of most violated coalitions.	required

Examples:

>>> from tucoopy.base.game import Game
>>> from tucoopy.diagnostics import core_diagnostics
>>> g = Game([0, 0, 0, 1, 1, 1, 2])
>>> x = [1, 1]
>>> cd = core_diagnostics(g, x)
>>> cd.in_core
True
>>> cd.max_excess
0.0

to_dict ¶

to_dict()

Convert diagnostics to a dictionary for serialization.

Returns:

Type	Description
`dict`	Dictionary representation of diagnostics.

Examples:

>>> cd.to_dict()
{...}

CoreViolation `dataclass` ¶

One coalition constraint evaluation at allocation x.

Excess: \(e(S, x) = v(S) - x(S)\). A positive excess means coalition \(S\) can improve by deviating (\(x\) violates the core constraint).

Parameters:

Name	Type	Description	Default
`coalition_mask`	`int`	Bitmask representing the coalition.	required
`players`	`list of int`	List of player indices in the coalition.	required
`vS`	`float`	Value of the coalition.	required
`xS`	`float`	Sum of allocation to coalition members.	required
`excess`	`float`	Excess value for the coalition.	required

Examples:

>>> cv = CoreViolation(3, [0, 1], 1.0, 0.8, 0.2)
>>> cv.excess
0.2

TightCoalitions `dataclass` ¶

Coalitions achieving the maximum excess (within tolerance).

Examples:

>>> TightCoalitions(max_excess=0.0, coalitions=[1, 2]).coalitions
[1, 2]

core_diagnostics ¶

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

Compute a compact explanation of why \(x\) is (not) in the core.

Parameters:

Name	Type	Description	Default
`game`	`GameProtocol`	TU game.	required
`x`	`list[float]`	Allocation vector (length n_players).	required
`tol`	`float`	Numerical tolerance. `x` is considered in the core if max_excess <= tol and efficient.	`DEFAULT_GEOMETRY_TOL`
`top_k`	`int`	Return up to this many most violated coalitions.	`8`

Returns:

Type	Description
`CoreDiagnostics`	Diagnostics object for core membership.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.diagnostics.core_diagnostics import core_diagnostics
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> core_diagnostics(g, [0.5, 0.5]).max_excess
-0.5

core_frame_highlight ¶

core_frame_highlight(game, x, *, tol=DEFAULT_GEOMETRY_TOL)

Small per-frame highlight payload for UI display.

Intended for embedding into FrameSpec.highlights.

Parameters:

Name	Type	Description	Default
`game`	`Game`	The cooperative game instance.	required
`x`	`list of float`	The candidate allocation vector.	required
`tol`	`float`	Tolerance for numerical checks (default 1e-9).	`DEFAULT_GEOMETRY_TOL`

Returns:

Type	Description
`dict`	Dictionary with highlight information for UI.

Examples:

>>> from tucoopy.base.game import Game
>>> from tucoopy.diagnostics import core_frame_highlight
>>> g = Game([0, 0, 0, 1, 1, 1, 2])
>>> x = [1, 1]
>>> core_frame_highlight(g, x)
{'in_core': True, 'efficient': True, ...}

core_violations ¶

core_violations(game, x, *, tol=DEFAULT_GEOMETRY_TOL)

List all core constraints violated by allocation x (excess > tol).

Returns a list ordered by descending excess and coalition mask.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.diagnostics.core_diagnostics import core_violations
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 1: 1, 2: 0, 3: 1})
>>> core_violations(g, [0.0, 1.0])  # v({0})=1 violates x0>=1
[CoreViolation(coalition_mask=1, players=[0], vS=1.0, xS=0.0, excess=1.0)]

excesses ¶

excesses(
    game, x, *, include_empty=False, include_grand=False
)

Excess function e(S, x) = v(S) - x(S) over coalitions.

This is a small helper to export the full excess vector as a dict keyed by coalition mask.

Parameters:

Name	Type	Description	Default
`game`	`GameProtocol`	TU game.	required
`x`	`list[float]`	Allocation vector (length `n_players`).	required
`include_empty`	`bool`	Whether to include the empty coalition (mask 0). Default False.	`False`
`include_grand`	`bool`	Whether to include the grand coalition (mask `2**n - 1`). Default False.	`False`

Returns:

Type	Description
`dict[int, float]`	Dict mapping coalition mask to excess `v(S) - x(S)`.

Raises:

Type	Description
`InvalidParameterError`	If `x` does not have length `n_players`.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.diagnostics.core_diagnostics import excesses
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> ex = excesses(g, [0.5, 0.5])
>>> ex[0b01]  # v({0})-x0
-0.5

explain_core_membership ¶

explain_core_membership(
    game, x, *, tol=DEFAULT_GEOMETRY_TOL, top_k=3
)

Generate a short textual explanation about core membership of an allocation.

This is a human-friendly wrapper around core_diagnostics. It reports (i) efficiency, (ii) whether the allocation is in the core, and (iii) the most violated coalitions when it is not.

Parameters:

Name	Type	Description	Default
`game`	`GameProtocol`	TU game.	required
`x`	`list[float]`	Allocation vector.	required
`tol`	`float`	Numerical tolerance for efficiency and core constraints.	`DEFAULT_GEOMETRY_TOL`
`top_k`	`int`	Maximum number of violations to compute (default 3). The explanation itself reports at most the most violated coalition plus the tight set.	`3`

Returns:

Type	Description
`list[str]`	One sentence per line, ready for UI tooltips/logs.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.diagnostics.core_diagnostics import explain_core_membership
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> explain_core_membership(g, [0.5, 0.5])[0]
'In the core (max excess=-0.5 <= tol=1e-09).'

is_in_core ¶

is_in_core(game, x, *, tol=DEFAULT_GEOMETRY_TOL)

Check if allocation is in the core (efficient and max_excess <= tol).

Examples:

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

is_in_epsilon_core ¶

is_in_epsilon_core(
    game, x, epsilon, *, tol=DEFAULT_GEOMETRY_TOL
)

Check if allocation is in the epsilon-core (efficient and max_excess <= epsilon + tol).

Examples:

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

max_excess ¶

max_excess(game, x)

Maximum excess over all proper coalitions (non-empty, excluding the grand coalition).

Examples:

>>> from tucoopy import Game
>>> from tucoopy.diagnostics.core_diagnostics import max_excess
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> max_excess(g, [0.5, 0.5])
-0.5

tight_coalitions ¶

tight_coalitions(game, x, *, tol=DEFAULT_GEOMETRY_TOL)

Find coalitions achieving the maximum excess (within tolerance).

Examples:

>>> from tucoopy import Game
>>> from tucoopy.diagnostics.core_diagnostics import tight_coalitions
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> tight_coalitions(g, [0.5, 0.5]).coalitions
[1, 2]

tucoopy.diagnostics.core_diagnostics¶

Core-family diagnostics (core and epsilon-core membership).¶

CoreDiagnostics dataclass ¶

to_dict ¶

CoreViolation dataclass ¶

TightCoalitions dataclass ¶

core_diagnostics ¶

core_frame_highlight ¶

core_violations ¶

excesses ¶

explain_core_membership ¶

is_in_core ¶

is_in_epsilon_core ¶

max_excess ¶

tight_coalitions ¶

`tucoopy.diagnostics.core_diagnostics`¶

CoreDiagnostics `dataclass` ¶

CoreViolation `dataclass` ¶

TightCoalitions `dataclass` ¶