Pular para conteúdo

tucoopy.solutions.solve

Solution dispatcher.

This module provides solve, a single entry point that dispatches to the individual solution concept implementations under tucoopy.solutions.

SolveResult dataclass

Result container for solution methods.

Attributes:

Name Type Description
method str

Name of the solution method used.
x list[float]

Payoff vector (allocation/imputation) returned by the method.
meta dict[str, object] | None

Optional metadata returned by the solver, such as: - LP iterations, - epsilon values, - solver diagnostics, - structural information.
Notes

This lightweight container standardizes the output of all solution methods exposed through solve, enabling uniform downstream processing, logging, or visualization.

solve 

solve(game, *, method='shapley', **kwargs)

Unified dispatcher for cooperative game solution concepts.

This function provides a single entry point to compute a wide range of point solutions (allocations/imputations) for TU cooperative games.

The desired method is selected by name, and any additional keyword arguments required by the method can be passed through **kwargs.

Parameters:

Name Type Description Default
game GameProtocol

TU cooperative game.

 required
method Method

Name of the solution concept to compute. Supported values include:

  • "shapley", "shapley_sample"
  • "banzhaf", "normalized_banzhaf"
  • "nucleolus", "prenucleolus"
  • "modiclus"
  • "tau"
  • "gately"
  • "myerson"
  • "owen"
 "shapley"
**kwargs Any

Additional arguments forwarded to the specific solver. Examples:

  • myerson: edges=[(u,v), ...], max_players, require_complete
  • owen: unions=[[...], ...], max_players, require_complete
 {}

Returns:

Type Description
SolveResult

Container with the solution vector and optional metadata.

Raises:

Type Description
InvalidParameterError

If the method name is unknown or required parameters are missing/invalid.
Notes
  • This function does not implement the algorithms itself; it dispatches to the appropriate module under tucoopy.solutions.
  • The goal is to offer a stable, high-level API for experimentation, scripting, and integration with analysis/visualization tools.
  • Metadata returned in SolveResult.meta may include solver diagnostics, LP iteration counts, or epsilon values for geometric methods.

Examples:

>>> res = solve(g, method="shapley")
>>> res.x

>>> res = solve(g, method="nucleolus")
>>> res.meta["lp_rounds"]

>>> res = solve(g, method="myerson", edges=[(0,1), (1,2)])
>>> res.x