`tucoopy.geometry.core_set`¶

Core as a polyhedral set and a set-valued wrapper.¶

This module provides:

core_polyhedron: build the core in H-representation,
Core: a thin wrapper exposing a Core.poly and delegating common operations to it (membership, sampling, vertex enumeration for small \(n\)).

Notes

The core is described by one equality (efficiency) and one inequality per non-empty proper coalition. For large \(n\), enumerating all inequalities is expensive; most geometry helpers in this package assume "small \(n\)" workflows.

Examples:

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

Core `dataclass` ¶

Core as a set-valued object (polyhedron).

This is a thin wrapper around core_polyhedron providing convenience methods such as membership tests, sampling, and (small-n) vertex enumeration.

Parameters:

Name	Type	Description	Default
`game`	`GameProtocol`	TU game.	required
`restrict_to_imputation`	`bool`	If True, use individual-rationality bounds `x_i >= v({i})` when building the underlying polyhedron.	`False`

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import Core
>>>
>>> g = Game.from_value_function(n_players=3, value_fn=lambda ps: float(len(ps)))
>>> C = Core(g)
>>> C.contains([1.0, 1.0, 1.0])
True
>>> C.vertices()
[[1.0, 1.0, 1.0]]

poly `property` ¶

poly

Underlying polyhedral representation of the core.

Examples:

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

chebyshev_center ¶

chebyshev_center()

Chebyshev center of the core polyhedron (if non-empty).

Returns:

Type	Description
`(x, r) \| None`	`x` is the center and `r` is the radius of the largest Euclidean ball contained in the core (as computed by the underlying backend). Returns None if the core is empty.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import Core
>>> g = Game.from_value_function(n_players=3, value_fn=lambda ps: float(len(ps)))
>>> cc = Core(g).chebyshev_center()
>>> cc is not None
True
>>> x, r = cc
>>> Core(g).contains(x)  # center is feasible
True

check ¶

check(x, *, tol=DEFAULT_GEOMETRY_TOL, top_k=8)

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

Notes

This method delegates to tucoopy.diagnostics.core_diagnostics.core_diagnostics.

Examples:

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

contains ¶

contains(x, *, tol=DEFAULT_GEOMETRY_TOL)

Membership test: check whether \(x\) lies in the core.

Parameters:

Name	Type	Description	Default
`x`	`list[float]`	Allocation vector.	required
`tol`	`float`	Numerical tolerance.	`DEFAULT_GEOMETRY_TOL`

Returns:

Type	Description
`bool`	True if `x` satisfies efficiency and all core inequalities.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import Core
>>> g = Game.from_value_function(n_players=3, value_fn=lambda ps: float(len(ps)))
>>> C = Core(g)
>>> C.contains([1.0, 1.0, 1.0])
True
>>> C.contains([2.0, 0.0, 0.0])  # violates some coalitional constraints
False

explain ¶

explain(x, *, tol=DEFAULT_GEOMETRY_TOL, top_k=3)

Return a short human-readable explanation of core membership.

This delegates to :func:tucoopy.diagnostics.core_diagnostics.explain_core_membership.

Examples:

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

extreme_points ¶

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

Enumerate extreme points of the core polyhedron via the underlying polyhedral representation.

This is a more general (but potentially more expensive) alternative to vertices, delegated to the polyhedral backend.

Parameters:

Name	Type	Description	Default
`tol`	`float`	Numerical tolerance for feasibility and de-duplication.	`DEFAULT_GEOMETRY_TOL`
`max_dim`	`int`	Safety limit for the backend enumeration routine.	`DEFAULT_GEOMETRY_MAX_DIM`

Returns:

Type	Description
`list of list of float`	Extreme points of the core, or an empty list if the core is empty.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import Core
>>> g = Game.from_value_function(n_players=3, value_fn=lambda ps: float(len(ps)))
>>> C = Core(g)
>>> eps = C.extreme_points()
>>> len(eps) > 0
True
>>> all(C.contains(x) for x in eps)
True

is_empty ¶

is_empty()

Check whether the core is empty.

Returns:

Type	Description
`bool`	True if the underlying polyhedron is infeasible.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import Core
>>> empty = Game.from_coalitions(
...     n_players=3,
...     values={
...         (): 0.0,
...         (0,): 1.0, (1,): 1.0, (2,): 1.0,
...         (0, 1): 2.0, (0, 2): 2.0, (1, 2): 2.0,
...         (0, 1, 2): 2.0,
...     },
... )
>>> Core(empty).is_empty()
True

project ¶

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

Project the core polyhedron onto a subset of coordinates.

This is useful for visualization in low dimensions (e.g. 2D/3D plots of the core by selecting two or three players).

Parameters:

Name	Type	Description	Default
`dims`	`tuple[int, ...] \| list[int]`	Indices of players (coordinates) to keep in the projection.	required
`tol`	`float`	Numerical tolerance for the backend projection routine.	`DEFAULT_GEOMETRY_TOL`
`max_dim`	`int`	Safety limit for the backend routine.	`DEFAULT_GEOMETRY_MAX_DIM`

Returns:

Type	Description
`list of list of float`	Vertices of the projected polytope.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import Core
>>> g = Game.from_value_function(n_players=3, value_fn=lambda ps: float(len(ps)))
>>> C = Core(g)
>>> # Project core onto players 0 and 1
>>> proj = C.project((0, 1))
>>> len(proj) > 0
True

sample_point ¶

sample_point()

Return an arbitrary feasible point in the core, if any.

Returns:

Type	Description
`list[float] \| None`	A feasible core allocation, or None if the core is empty.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import Core
>>> g = Game.from_value_function(n_players=3, value_fn=lambda ps: float(len(ps)))
>>> x = Core(g).sample_point()
>>> x is not None
True
>>> Core(g).contains(x)
True

vertices ¶

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

Enumerate core vertices (small \(n\)).

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import Core
>>> g = Game.from_value_function(n_players=3, value_fn=lambda ps: float(len(ps)))
>>> Core(g).vertices()
[[1.0, 1.0, 1.0]]

core_polyhedron ¶

core_polyhedron(game, *, restrict_to_imputation=False)

Core as a polyhedral set in H-representation.

Constraints

Efficiency:

\[\sum_{i=1}^n x_i = v(N)\]

Coalitional rationality (core constraints):

\[x(S) \geq v(S) \text{ for all non-empty proper coalitions } S\]

If restrict_to_imputation=True, also enforce individual rationality \(x_i \geq v(\{i\})\) via bounds.

Parameters:

Name	Type	Description	Default
`game`	`GameProtocol`	TU game.	required
`restrict_to_imputation`	`bool`	If True, add bounds `x_i >= v({i})`. This can be useful for numerical stability when sampling/centers, but note the core is already a subset of the imputation set for TU games.	`False`

Returns:

Type	Description
`PolyhedralSet`	A polyhedral set in H-representation.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.geometry import core_polyhedron
>>>
>>> g = Game.from_value_function(n_players=3, value_fn=lambda ps: float(len(ps)))
>>> poly = core_polyhedron(g)
>>> poly.contains([1.0, 1.0, 1.0])
True
>>>
>>> # Same object but with explicit individual-rationality bounds:
>>> poly2 = core_polyhedron(g, restrict_to_imputation=True)
>>> poly2.contains([1.0, 1.0, 1.0])
True

tucoopy.geometry.core_set¶

Core as a polyhedral set and a set-valued wrapper.¶

Core dataclass ¶

poly property ¶

chebyshev_center ¶

check ¶

contains ¶

explain ¶

extreme_points ¶

is_empty ¶

project ¶

sample_point ¶

vertices ¶

core_polyhedron ¶

`tucoopy.geometry.core_set`¶

Core `dataclass` ¶

poly `property` ¶