Pular para conteúdo

tucoopy.geometry.reasonable_set

Reasonable set (polyhedral superset of the core).

This module provides :class:ReasonableSet, which is the efficient box defined by per-player lower bounds (individual rationality) and upper bounds (utopia payoffs).

The reasonable set is polyhedral and is often used as a computationally friendly outer approximation of the core.

Examples:

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

ReasonableSet dataclass

Reasonable set as a polyhedral set.

Background

For a TU cooperative game, define for each player the utopia payoff

\[ M_i = v(N) - v(N \setminus \{i\}), \]

which represents the maximum amount player \(i\) could conceivably receive without making the remaining players worse off than standing alone.

The reasonable set is defined as

\[ R = \left\{ x \in \mathbb{R}^n : \sum_i x_i = v(N), \quad v(\{i\}) \le x_i \le M_i \ \text{for all } i \right\}. \]

It is the set of allocations that are:

  • efficient (use the whole worth of the grand coalition),
  • individually rational (\(x_i \ge v(\{i\})\)),
  • utopia-bounded (\(x_i \le M_i\)).

Geometrically, this is the intersection of the imputation simplex with the hyper-rectangle defined by the utopia payoffs.

Parameters:

Name Type Description Default
game GameProtocol

TU game.

 required

Attributes:

Name Type Description
poly PolyhedralSet

Underlying PolyhedralSet representing the reasonable set in H-representation.
Notes
  • The reasonable set always contains the tau-value (when defined).
  • It is typically a superset of the core when the core is non-empty.
  • For small n, vertices() can be used for visualization.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import ReasonableSet
>>> g = Game.from_value_function(n_players=3, value_fn=lambda S: float(len(S)))
>>> R = ReasonableSet(g)
>>> R.contains([1.0, 1.0, 1.0])
True

poly property 

poly

Underlying polyhedral representation of the reasonable set.

Examples:

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

chebyshev_center 

chebyshev_center()

Chebyshev center of the reasonable set.

Examples:

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

check 

check(x, *, tol=DEFAULT_GEOMETRY_TOL)

Return reasonable-set membership diagnostics for x.

Notes

This delegates to :func:tucoopy.diagnostics.reasonable_diagnostics.reasonable_set_diagnostics.

Examples:

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

contains 

contains(x, *, tol=DEFAULT_GEOMETRY_TOL)

Check if x belongs to the reasonable set (within tolerance).

Examples:

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

explain 

explain(x, *, tol=DEFAULT_GEOMETRY_TOL)

Return a short human-readable explanation of reasonable-set membership.

Examples:

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

extreme_points 

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

Enumerate extreme points (small dimension).

Examples:

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

is_empty 

is_empty()

Check if the reasonable set is empty.

Examples:

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

project 

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

Project the reasonable set to selected coordinates.

Examples:

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

sample_point 

sample_point()

Attempt to sample one point from the reasonable set.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import ReasonableSet
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> ReasonableSet(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 reasonable set (small dimension).

Examples:

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