tucoopy.geometry.epsilon_core_set¶
Epsilon-core as a polyhedral set and a set-valued wrapper.¶
This module defines the epsilon-core constraints
\(x(S) \geq v(S) - \epsilon\) for all non-empty proper coalitions \(S\),
plus efficiency. It provides both:
- polyhedral constructors (H-representation), and
EpsilonCore, a convenience wrapper exposingEpsilonCore.poly.
Notes
The epsilon-core is a key building block for the least-core and for LP-based explanations (e.g. "most violated coalition").
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry import EpsilonCore
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> EpsilonCore(g, epsilon=0.0).contains([0.5, 0.5])
True
EpsilonCore dataclass ¶
Epsilon-core polytope as a set-valued object.
This is a thin wrapper around epsilon_core_polyhedron(...) that exposes convenience methods like containment, sampling, Chebyshev center, projections, and (small-\(n\)) brute-force vertex enumeration.
Attributes:
| Name | Type | Description |
|---|---|---|
game | Game | TU game. |
epsilon | float | Relaxation parameter epsilon. |
restrict_to_imputation | bool | If True, intersect with individual rationality bounds x_i >= v({i}). |
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry import EpsilonCore
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> C = EpsilonCore(g, epsilon=0.0)
>>> C.contains([0.5, 0.5])
True
poly property ¶
poly
The underlying polyhedral representation (H-rep).
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry import EpsilonCore
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> EpsilonCore(g, epsilon=0.0).poly.n_vars
2
chebyshev_center ¶
chebyshev_center()
Compute a Chebyshev center of the epsilon-core (if available).
Returns:
| Type | Description |
|---|---|
(x, r) or None | x is the center point and r is the radius of the largest inscribed ball. |
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry import EpsilonCore
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> EpsilonCore(g, epsilon=0.0).chebyshev_center()
([0.5, 0.5], 0.0)
check ¶
check(x, *, tol=DEFAULT_GEOMETRY_TOL, top_k=8)
Return epsilon-core membership diagnostics for x.
Notes
This delegates to :func:tucoopy.diagnostics.epsilon_core_diagnostics.epsilon_core_diagnostics.
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry import EpsilonCore
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> EpsilonCore(g, epsilon=0.0).check([0.5, 0.5]).in_set
True
contains ¶
contains(x, *, tol=DEFAULT_GEOMETRY_TOL)
Check whether x lies in the epsilon-core (within tolerance).
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry import EpsilonCore
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> EpsilonCore(g, epsilon=0.0).contains([0.5, 0.5])
True
explain ¶
explain(x, *, tol=DEFAULT_GEOMETRY_TOL, top_k=3)
Return a short human-readable explanation of epsilon-core membership.
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry import EpsilonCore
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> EpsilonCore(g, epsilon=0.0).explain([0.5, 0.5])[0].startswith("In the epsilon-core")
True
extreme_points ¶
extreme_points(
*,
tol=DEFAULT_GEOMETRY_TOL,
max_dim=DEFAULT_GEOMETRY_MAX_DIM,
)
Enumerate extreme points of the epsilon-core (backend-dependent).
Notes
This method delegates to PolyhedralSet.extreme_points and may be more robust to degeneracy than the brute-force vertices method, depending on the backend implementation.
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry import EpsilonCore
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> EpsilonCore(g, epsilon=0.0).extreme_points(max_dim=2)
[[0.0, 1.0], [1.0, 0.0]]
is_empty ¶
is_empty()
Return True if the epsilon-core polytope is empty.
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry import EpsilonCore
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> EpsilonCore(g, epsilon=0.0).is_empty()
False
project ¶
project(
dims,
*,
tol=DEFAULT_GEOMETRY_TOL,
max_dim=DEFAULT_GEOMETRY_MAX_DIM,
)
Project the epsilon-core onto selected coordinates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dims | tuple[int, ...] | list[int] | Coordinates to keep (e.g., (0,1) for a 2D projection). | required |
tol | float | Numerical tolerance. | DEFAULT_GEOMETRY_TOL |
max_dim | int | Safety cap for projection dimension in the backend. | DEFAULT_GEOMETRY_MAX_DIM |
Returns:
| Type | Description |
|---|---|
list[list[float]] | Extreme points of the projected polytope (backend-dependent). |
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry import EpsilonCore
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> EpsilonCore(g, epsilon=0.0).project((0,), max_dim=2)
[[0.0], [1.0]]
sample_point ¶
sample_point()
Attempt to find any feasible point in the epsilon-core.
Returns None if the set is empty or if the backend fails to find a point.
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry import EpsilonCore
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> EpsilonCore(g, epsilon=0.0).sample_point()
[0.5, 0.5]
vertices ¶
vertices(
*,
tol=DEFAULT_GEOMETRY_TOL,
max_players=DEFAULT_GEOMETRY_MAX_PLAYERS,
max_dim=DEFAULT_GEOMETRY_MAX_DIM,
)
Enumerate vertices of the epsilon-core polytope (small \(n\)).
This is intended mainly for visualization and delegates to PolyhedralSet.extreme_points via poly.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tol | float | Numerical tolerance used for feasibility and de-duplication. | DEFAULT_GEOMETRY_TOL |
max_players | int | Safety cap. This method is exponential in n and intended for small n. | DEFAULT_GEOMETRY_MAX_PLAYERS |
Returns:
| Type | Description |
|---|---|
list[list[float]] | List of epsilon-core vertices, or an empty list if the epsilon-core is empty. |
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry import EpsilonCore
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> EpsilonCore(g, epsilon=0.0).vertices(max_dim=2)
[[0.0, 1.0], [1.0, 0.0]]
LeastCorePolytope dataclass ¶
Container for the least-core polytope (small-n visualization output).
Attributes:
| Name | Type | Description |
|---|---|---|
epsilon | float | Least-core epsilon (minimum relaxation that makes the epsilon-core non-empty). |
vertices | list[list[float]] | Vertices of the least-core polytope (computed via brute-force enumeration). |
Examples:
>>> lc = LeastCorePolytope(epsilon=0.0, vertices=[[1.0, 1.0, 1.0]])
>>> lc.epsilon
0.0
epsilon_core_polyhedron ¶
epsilon_core_polyhedron(
game, epsilon, *, restrict_to_imputation=False
)
Build the epsilon-core as a PolyhedralSet (H-representation).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
game | GameProtocol | TU game. | required |
epsilon | float | Relaxation parameter epsilon. | required |
restrict_to_imputation | bool | If True, also enforce individual rationality bounds x_i >= v({i}). | False |
Returns:
| Type | Description |
|---|---|
PolyhedralSet | The epsilon-core polyhedron represented as linear equalities/inequalities. |
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry.epsilon_core_set import epsilon_core_polyhedron
>>> g = Game.from_value_function(n_players=3, value_fn=lambda S: float(len(S)))
>>> poly = epsilon_core_polyhedron(g, epsilon=0.0)
>>> poly.contains([1.0, 1.0, 1.0])
True
least_core_polytope ¶
least_core_polytope(
game,
*,
restrict_to_imputation=False,
tol=DEFAULT_GEOMETRY_TOL,
max_players=DEFAULT_GEOMETRY_MAX_PLAYERS,
)
Compute the least-core epsilon and (small-\(n\)) vertices of the least-core set.
The least-core is the epsilon-core with the smallest epsilon for which the epsilon-core is non-empty. This function:
- computes least-core epsilon via an LP (SciPy/HiGHS),
- enumerates vertices of the resulting epsilon-core (small \(n\), brute force).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
game | GameProtocol | TU game. | required |
restrict_to_imputation | bool | If True, also enforce individual rationality bounds \(x_i \geq v(\{i\})\). | False |
tol | float | Numerical tolerance passed to the LP solver and vertex enumeration. | DEFAULT_GEOMETRY_TOL |
max_players | int | Safety cap for brute-force vertex enumeration. | DEFAULT_GEOMETRY_MAX_PLAYERS |
Returns:
| Type | Description |
|---|---|
LeastCorePolytope | Object containing (epsilon, vertices). |
Requires
SciPy at runtime (install with: pip install "tucoopy[lp]").
Examples:
>>> from tucoopy import Game
>>> from tucoopy.geometry.epsilon_core_set import least_core_polytope
>>> g = Game.from_value_function(n_players=3, value_fn=lambda S: float(len(S)))
>>> lc = least_core_polytope(g)
>>> lc.epsilon
0.0
>>> lc.vertices
[[1.0, 1.0, 1.0]]