Skip to content

tucoopy.geometry.core_cover_set

Core cover (polyhedral superset of the core).

This module provides :class:CoreCover, a set-valued object with a polyhedral representation (H-representation) accessible via the :attr:CoreCover.poly property.

The core cover is a classical polyhedral superset of the core defined using the minimal rights vector and the utopia payoff vector.

See Also

tucoopy.solutions.tau.minimal_rights tucoopy.solutions.tau.utopia_payoff tucoopy.geometry.PolyhedralSet

Examples:

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

CoreCover dataclass

Core cover polytope.

Definition

Let:

\[ M_i = \text{ utopia payoff of player } i \\ m_i = \text{ minimal rights of player } i \]

The core cover is the polytope:

\[ CC(v) = \left\{ x \in \mathbb{R}^n \, : \, \sum_{i=1}^n x_i = v(N), m_i \leq x_i \leq M_i \text{ for all } i \right\} \]
Interpretation
  • The utopia payoff \(M_i\) represents the maximum amount player \(i\) could hope to obtain without making any coalition worse off.
  • The minimal rights \(m_i\) represent the minimal amount player \(i\) can guarantee for themselves considering all coalitional possibilities.
  • The core cover is therefore a box-constrained efficiency slice, often much easier to compute and visualize than the core.

The core is always contained in the core cover:

\[ \text{Core}(v) \subseteq \text{CoreCover}(v) \]

and for many classes of games, the core cover provides a very tight outer approximation of the core.

Notes
  • This object is purely geometric and built as a PolyhedralSet.
  • All geometric operations (sampling, Chebyshev center, projection, extreme points) are delegated to the underlying polyhedron.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import CoreCover
>>> g = Game.from_value_function(3, lambda S: float(len(S)))
>>> cc = CoreCover(g)
>>> cc.is_empty()
False
>>> cc.sample_point()
[1.0, 1.0, 1.0]

poly property 

poly

Underlying polyhedral representation of the core cover.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import CoreCover
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> CoreCover(g).poly.n_vars
2

chebyshev_center 

chebyshev_center()

Compute the Chebyshev center of the core cover.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import CoreCover
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> CoreCover(g).chebyshev_center()
([0.5, 0.5], 0.0)

check 

check(x, *, tol=DEFAULT_GEOMETRY_TOL)

Return core-cover membership diagnostics for \(x\).

Notes

This delegates to tucoopy.diagnostics.core_cover_diagnostics.core_cover_diagnostics.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import CoreCover
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> CoreCover(g).check([0.5, 0.5]).in_set
True

contains 

contains(x, *, tol=DEFAULT_GEOMETRY_TOL)

Check if \(x\) belongs to the core cover.

Examples:

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

explain 

explain(x, *, tol=DEFAULT_GEOMETRY_TOL)

Return a short human-readable explanation of core-cover membership.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import CoreCover
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> CoreCover(g).explain([0.5, 0.5])
['In the core cover.']

extreme_points 

extreme_points(
    *,
    tol=DEFAULT_GEOMETRY_TOL,
    max_dim=DEFAULT_GEOMETRY_MAX_DIM,
)

Enumerate extreme points of the core cover (small dimension).

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import CoreCover
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> CoreCover(g).extreme_points(max_dim=2)
[[0.0, 1.0], [1.0, 0.0]]

is_empty 

is_empty()

Check if the core cover is empty.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import CoreCover
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> CoreCover(g).is_empty()
False

project 

project(
    dims,
    *,
    tol=DEFAULT_GEOMETRY_TOL,
    max_dim=DEFAULT_GEOMETRY_MAX_DIM,
)

Project the core cover onto selected dimensions.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import CoreCover
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> CoreCover(g).project((0,), max_dim=2)
[[0.0], [1.0]]

sample_point 

sample_point()

Sample a feasible point from the core cover.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import CoreCover
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> CoreCover(g).sample_point()
[0.5, 0.5]

vertices 

vertices(
    *,
    tol=DEFAULT_GEOMETRY_TOL,
    max_players=DEFAULT_GEOMETRY_MAX_PLAYERS,
    max_dim=DEFAULT_GEOMETRY_MAX_DIM,
)

Vertices of the core cover (small dimension).

Notes

This delegates to extreme_points for consistency with other set-valued objects.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import CoreCover
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> CoreCover(g).vertices(max_dim=2)
[[0.0, 1.0], [1.0, 0.0]]