Skip to content

tucoopy.properties.basic

Basic property checks for TU cooperative games.

This module provides quick recognizers for common properties of TU games:

  • Normalized: \(v(\varnothing)=0\),
  • Monotone: if \(S \subseteq T\) then \(v(S) \leq v(T)\),
  • Superadditive: if \(S\) and \(T\) are disjoint then \(v(S)+v(T) \leq v(S \cup T)\),
  • Essential: $v(N) > \sum_{i=1}^{n} v({i})``.
Notes

Some checks are exponential in the number of players. Functions therefore accept max_players to fail fast for large games.

Examples:

>>> from tucoopy.base.game import Game
>>> from tucoopy.properties.basic import is_normalized, is_monotone
>>> g = Game.from_coalitions(n_players=2, values={(): 0.0, (0, 1): 1.0})
>>> is_normalized(g)
True
>>> is_monotone(g)
True

is_essential 

is_essential(game, *, eps=1e-12)

Check whether a TU game is essential.

A game is essential if the grand coalition creates strictly more value than the sum of singleton coalitions:

\[v(N) > \sum_i v(\{i\}).\]

Parameters:

Name Type Description Default
game GameProtocol

TU game.

 required
eps float

Numerical tolerance.

 1e-12

is_monotone 

is_monotone(game, *, eps=1e-12, max_players=12)

Check whether a TU game is monotone.

Monotonicity means that adding players to a coalition cannot decrease its worth:

\[S \subseteq T \implies v(S) \leq v(T).\]

Parameters:

Name Type Description Default
game GameProtocol

TU game.

 required
eps float

Numerical tolerance.

 1e-12
max_players int | None

Fail fast if game.n_players exceeds this bound (check is exponential).

 12

is_normalized 

is_normalized(game, *, eps=0.0)

Normalized game: \(v(\varnothing) = 0\).

Notes

:class:~tucoopy.base.game.Game enforces \(v(\varnothing)=0\), so this is mostly provided for completeness and for defensive checks when ingesting external game specifications.

is_superadditive 

is_superadditive(game, *, eps=1e-12, max_players=12)

Check whether a TU game is superadditive.

Superadditivity requires that disjoint coalitions do not lose value by merging:

\[S \cap T = \varnothing \implies v(S) + v(T) \leq v(S \cup T).\]

Parameters:

Name Type Description Default
game GameProtocol

TU game.

 required
eps float

Numerical tolerance.

 1e-12
max_players int | None

Fail fast if game.n_players exceeds this bound (check is exponential).

 12