tucoopy.geometry.projection¶
Coordinate conversions and projections for visualization.¶
This module contains helpers that map allocations x in the imputation hyperplane to convenient 2D/3D coordinates:
- barycentric coordinates on the imputation simplex (
n=3), - 2D/3D embeddings used by the static Matplotlib visualizations in
tucoopy.viz.
Notes
These helpers are intentionally simple and aimed at visualization and diagnostics. They are not intended as general-purpose dimensionality reduction tools.
Examples:
Convert a point in the imputation set to barycentric coordinates (n=3):
>>> from tucoopy import Game
>>> from tucoopy.geometry.projection import allocation_to_barycentric_imputation
>>> g = Game.from_coalitions(n_players=3, values={
... 0: 0.0,
... 1: 1.0, 2: 1.0, 4: 1.0,
... 3: 2.0, 5: 2.0, 6: 2.0,
... 7: 4.0,
... })
>>> b = allocation_to_barycentric_imputation(g, [1.0, 1.0, 2.0])
>>> (len(b), round(sum(b), 12))
(3, 1.0)
allocation_to_barycentric_imputation ¶
allocation_to_barycentric_imputation(
game, x, *, tol=DEFAULT_IMPUTATION_SAMPLE_TOL
)
Convert an allocation to barycentric coordinates of the imputation simplex.
Background
The imputation set of a TU game can be written as a shifted simplex:
where
- \(l_i = v(\{i\})\) are the individual rationality lower bounds,
- \(r = v(N) - \sum_i l_i\) is the remaining distributable surplus,
- \(b \in \mathbb{R}^n\) satisfies
$$ \sum_i b_i = 1, \qquad b_i \ge 0. $$
The vector \(b\) is a set of barycentric coordinates inside the standard simplex, representing the position of \(x\) relative to the imputation simplex.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
game | GameProtocol | TU game. | required |
x | list[float] | Allocation vector (length | required |
tol | float | Numerical tolerance for detecting degenerate simplices. | DEFAULT_IMPUTATION_SAMPLE_TOL |
Returns:
| Type | Description |
|---|---|
list[float] | Barycentric coordinates |
Raises:
| Type | Description |
|---|---|
InvalidGameError | If the imputation simplex is empty or degenerate (\(v(N) - \sum_i v(\{i\}) \le 0\)). |
Notes
These coordinates are the natural input for geometric visualizations of allocations in 2D (n=3) and 3D (n=4).
Examples:
>>> b = allocation_to_barycentric_imputation(g, [1.0, 1.0, 1.0])
>>> sum(b)
1.0
project_allocation ¶
project_allocation(game, x, *, space='imputation_simplex')
Project an allocation to Euclidean coordinates for visualization.
Background
For small games, the imputation set is a simplex that can be embedded in low-dimensional Euclidean space:
- For
n=3, the imputation simplex is a triangle in 2D. - For
n=4, the imputation simplex is a tetrahedron in 3D.
This function:
- Converts the allocation to barycentric coordinates in the imputation simplex.
- Maps these barycentric coordinates to Cartesian coordinates using canonical simplex embeddings.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
game | GameProtocol | TU game. | required |
x | list[float] | Allocation vector in the imputation set. | required |
space | Literal['imputation_simplex'] | Currently only | 'imputation_simplex' |
Returns:
| Type | Description |
|---|---|
list[float] | 2D coordinates (for n=3) or 3D coordinates (for n=4). |
Raises:
| Type | Description |
|---|---|
InvalidParameterError | If the space is unknown. |
NotSupportedError | If the number of players is not supported for this projection. |
Notes
This is intended for geometric plotting of solution concepts such as:
- Core
- Epsilon-core
- Least-core
- Kernel / Pre-kernel
- Nucleolus
- Tau value
Examples:
>>> project_allocation(g, [1.0, 1.0, 1.0])
[x_coord, y_coord]