tucoopy.diagnostics.allocation_diagnostics¶
Allocation-level diagnostics.¶
This module contains small checks for payoff vectors \(x\) such as:
- efficiency (\(\sum_{i=1}^n x_i = v(N)\)),
- individual rationality (\(x_i \geq v(\{i\})\)),
- and convenience wrappers used by core-family diagnostics.
The functions here are lightweight and intended to be stable and serialization-friendly.
Examples:
>>> from tucoopy import Game
>>> from tucoopy.diagnostics.allocation_diagnostics import is_imputation
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 1: 0, 2: 0, 3: 1})
>>> is_imputation(g, [0.5, 0.5])
True
AllocationChecks dataclass ¶
Small set of boolean checks + core explanation for a candidate allocation.
This is intended for UI/debug usage and for JSON export.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
efficient | bool | Whether the allocation is efficient (sum equals grand coalition value). | required |
imputation | bool | Whether the allocation is an imputation (efficient and individually rational). | required |
core | CoreDiagnostics | Diagnostics for core membership. | required |
Examples:
>>> from tucoopy.base.game import Game
>>> from tucoopy.diagnostics.allocation_diagnostics import check_allocation
>>> g = Game([0, 0, 0, 1, 1, 1, 2])
>>> x = [1, 1]
>>> result = check_allocation(g, x)
>>> result.efficient
True
>>> result.imputation
True
>>> isinstance(result.core, object)
True
to_dict ¶
to_dict()
Convert the checks to a dictionary for serialization.
Returns:
| Type | Description |
|---|---|
dict | Dictionary representation of the checks. |
Examples:
>>> from tucoopy import Game
>>> from tucoopy.diagnostics.allocation_diagnostics import check_allocation
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> d = check_allocation(g, [0.5, 0.5])
>>> d.to_dict()["efficient"]
True
check_allocation ¶
check_allocation(
game, x, *, tol=DEFAULT_GEOMETRY_TOL, core_top_k=8
)
Check common conditions for an allocation \(x\): - efficiency - imputation membership - core membership diagnostics
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
game | GameProtocol | TU game (game-like object). | required |
x | list of float | The candidate allocation vector. | required |
tol | float | Tolerance for numerical checks (default 1e-9). | DEFAULT_GEOMETRY_TOL |
core_top_k | int | Number of top core violations to include in diagnostics (default 8). | 8 |
Returns:
| Type | Description |
|---|---|
AllocationChecks | Object containing boolean checks and core diagnostics. |
Examples:
>>> from tucoopy.base.game import Game
>>> from tucoopy.diagnostics.allocation_diagnostics import check_allocation
>>> g = Game([0, 0, 0, 1, 1, 1, 2])
>>> x = [1, 1]
>>> result = check_allocation(g, x)
>>> result.efficient
True
>>> result.imputation
True
is_efficient ¶
is_efficient(game, x, *, tol=DEFAULT_GEOMETRY_TOL)
Check efficiency: \(\sum_{i=1}^n x_i = v(N)\) within tolerance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
game | GameProtocol | TU game. | required |
x | list[float] | Allocation vector. | required |
tol | float | Numerical tolerance. | DEFAULT_GEOMETRY_TOL |
Returns:
| Type | Description |
|---|---|
bool | True if efficient. |
Examples:
>>> from tucoopy import Game
>>> from tucoopy.diagnostics.allocation_diagnostics import is_efficient
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> is_efficient(g, [0.2, 0.8])
True
is_imputation ¶
is_imputation(game, x, *, tol=DEFAULT_GEOMETRY_TOL)
Check imputation membership: efficiency + individual rationality.
Examples:
>>> from tucoopy import Game
>>> from tucoopy.diagnostics.allocation_diagnostics import is_imputation
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 1: 0.2, 2: 0.0, 3: 1.0})
>>> is_imputation(g, [0.2, 0.8])
True
>>> is_imputation(g, [0.2, 0.9]) # not efficient
False
is_individually_rational ¶
is_individually_rational(
game, x, *, tol=DEFAULT_GEOMETRY_TOL
)
Check individual rationality: \(x_i \geq v(\{i\})\) for all \(i\) (within tolerance).
Examples:
>>> from tucoopy import Game
>>> from tucoopy.diagnostics.allocation_diagnostics import is_individually_rational
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 1: 0.2, 2: 0.0, 3: 1.0})
>>> is_individually_rational(g, [0.2, 0.8])
True
>>> is_individually_rational(g, [0.1, 0.9])
False