Skip to content

tucoopy.base.game

TU cooperative game defined by its characteristic function \(v(S)\).

Coalitions are encoded as bitmasks over players \(0 \ldots n-1\).

Parameters:

Name Type Description Default
n_players int

Number of players n.

 required
v dict[int, float]

Mapping from coalition masks (ints) or iterables of player indices to coalition values. Missing coalitions are treated as value 0.0 by :meth:value.

 required
player_labels list[str] | None

Optional display labels for players (length must match n_players).

 None
Notes
  • TU convention: \(v( \varnothing) = 0\) is enforced.
  • The grand coalition mask is (1 << n_players) - 1.

Examples:

Author with Pythonic coalition keys:

>>> g = Game.from_coalitions(
...     n_players=3,
...     values={(): 0.0, (0,): 1.0, (1,): 1.0, (2,): 1.0, (0, 1, 2): 4.0},
... )
>>> g.value(g.grand_coalition)
4.0

grand_coalition property 

grand_coalition

Return the grand coalition mask (all players).

Returns:

Type Description
int

Mask (1 << n_players) - 1.

Examples:

>>> from tucoopy import Game
>>> Game.from_coalitions(n_players=3, values={0:0, 7:1}).grand_coalition
7

value 

value(coalition_mask)

Return the coalition worth \(v(S)\).

Parameters:

Name Type Description Default
coalition_mask int

Coalition mask (bitmask).

 required

Returns:

Type Description
float

Coalition value v(S).
Notes

Missing coalitions in self.v are treated as value 0.0.

Examples:

>>> from tucoopy import Game
>>> g = Game.from_coalitions(n_players=2, values={0:0, 3:1})
>>> g.value(0b01)  # missing singleton defaults to 0.0
0.0
>>> g.value(0b11)
1.0

with_values 

with_values(v)

Return a copy of the game with a replaced value table.

Parameters:

Name Type Description Default
v dict[int, float]

New characteristic function values (by coalition mask).

 required

Returns:

Type Description
Game

A new game with the same n_players and (if present) the same player_labels.

Examples:

>>> from tucoopy import Game
>>> g1 = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> g2 = g1.with_values({0: 0, 3: 2})
>>> g1.value(0b11), g2.value(0b11)
(1.0, 2.0)

from_coalitions staticmethod 

from_coalitions(
    *,
    n_players: int,
    values: Mapping[int, float],
    player_labels: list[str] | None = None,
    require_complete: bool = False,
) -> "Game"

from_coalitions(
    *,
    n_players: int,
    values: Mapping[Iterable[int], float],
    player_labels: list[str] | None = None,
    require_complete: bool = False,
) -> "Game"

from_coalitions(
    *,
    n_players,
    values,
    player_labels=None,
    require_complete=False,
)

Convenience constructor for a TU game from coalition values.

Accepts coalition keys as either:

  • int bitmasks, or
  • iterables of player indices (e.g. (0, 2) or frozenset({1})).

Parameters:

Name Type Description Default
n_players int

Number of players.

 required
values Mapping[int, float] or Mapping[Iterable[int], float]

Coalition values, indexed by bitmask or iterable of player indices.

 required
player_labels list of str

Optional display labels for players.

 None
require_complete bool

If True, require all \(2^n\) coalitions to be specified.

 False

Returns:

Type Description
Game

Instantiated game object.

Raises:

Type Description
InvalidCoalitionError

If a coalition key uses invalid player indices.
InvalidGameError

If parameters are invalid or required coalitions are missing.

Examples:

>>> Game.from_coalitions(n_players=2, values={(): 0, (0,): 1, (1,): 2, (0, 1): 3})
Game(n_players=2, v={0: 0.0, 1: 1.0, 2: 2.0, 3: 3.0})

from_value_function staticmethod 

from_value_function(
    *,
    n_players,
    value_fn,
    player_labels=None,
    include_empty=True,
)

Build a tabular TU game from a Python function defined on coalitions.

This helper enumerates all coalitions and calls value_fn(players(S)).

Parameters:

Name Type Description Default
n_players int

Number of players.

 required
value_fn Callable[[Sequence[int]], float]

Function that receives a list of player indices and returns the coalition value.

 required
player_labels list[str] | None

Optional display labels for players.

 None
include_empty bool

If False, do not call value_fn on the empty coalition (the value is still normalized to v(0)=0).

 True

Returns:

Type Description
Game

A tabular game storing all coalition values.
Notes

This is an O(2^n) constructor. Prefer :class:ValueFunctionGame when you do not want to materialize all coalitions.

Examples:

A "size" game (value equals coalition size):

>>> from tucoopy.base.game import Game
>>> g = Game.from_value_function(n_players=3, value_fn=lambda S: float(len(S)))
>>> g.value(0b101)
2.0