commonpower.extensions.cost_allocation.BaseShapleySimulator

class BaseShapleySimulator(sys: System, community_controller: OptimalController, horizon: timedelta = datetime.timedelta(days=1), dt: timedelta = datetime.timedelta(seconds=3600), n_sample_coalitions: int = 100, seed: int | None = None)[source]

Bases: object

Base Shapley simulator class, providing internal logic.

Simulator that simulates one (possibly) imperfect knowledge system and computes Shapley values. The given system is a template representing the entire energy community (grand coalition). For the simulation of coalitions, the template system is cloned and rearranged accordingly.

Parameters:

  • sys (System) – (Template) system to simulate. Must contain exactly one top-level EnergyCommunity node.

  • community_controller (OptimalController) – (Template) controller for the community.

  • horizon (timedelta, optional) – Forecast horizon. Defaults to timedelta(days=1).

  • dt (timedelta, optional) – Sample time aka frequency. Defaults to timedelta(minutes=60).

  • n_sample_coalitions (int, optional) – Number of coalitions to sample. Defaults to 100.

  • seed (int, optional) – Seed for the coalition sampling. Defaults to None.

Methods

simulate

Simulate the system and compute Shapley values.
_get_coalitions(grand_coalition: List[int]) → List[List[int]][source]

Genenerate sub-coalitions of the grand coalition efficiently. Utilizes self.seed and returns self.n_sample_coalitions coalitions.

Parameters:

grand_coalition (List[int]) – Grand coalition of players.

Returns:

List[List[int]] – List of coalitions.

_get_coalitions_for_i(coalitions: List[List[int]], grand_coalition: List[int], i: int) → List[List[int]][source]

Get all coalitions without player i, including the empty coalition. For any set of players, we return only one ordered coalition.

Parameters:

  • coalitions (List[List[int]]) – Sampled coalitions.

  • grand_coalition (List[int]) – Grand coalition of players.

  • i (int) – Index of player.

Returns:

List[List[int]] – List of ordered coalitions without player i.

_get_cost_for_coalition(sys: System, coalition: List[int], sim_steps: int, fixed_start: datetime) → tuple[float, DeploymentRunner][source]

Simulate a coalition and return the total cost. The computed cost includes the “value” of the terminal state, which is computed as perfect knowledge cost over the horizon from the terminal time step. This makes different trajectory costs more comparable. The template system is cloned, and rearanged to represent the coalition.

Parameters:

  • sys (System) – (Template) system to simulate.

  • coalition (List[int]) – Indices of the coalition members.

  • sim_steps (int) – Number of simulation steps.

  • fixed_start (datetime) – Start time of the simulation.

Returns:

tuple[float, DeploymentRunner] – Total cost of the coalition, deployment runner of the coalition.

_get_grand_coalition() → List[int][source]

Get the indices of the grand coalition.

Returns:

List[int] – Grand coalition indices.

_get_shapleys(sys: System, sim_steps: int, fixed_start: datetime) → tuple[List[float], dict, dict][source]

Compute Shapley values for the given system. (1) We sample coalitions from the powerset of the grand coalition. (2) For each player i, we compute the marginal contribution of i to each coalition. (3) We average the marginal contributions over all coalitions to get the Shapley value for i.

We reuse the costs of previously simulated coalitions during the process. We apply a normalization step to ensure efficiency, i.e., the sum of Shapley values equals the cost of the grand coalition.

Parameters:

  • sys (System) – (Template) system to simulate.

  • sim_steps (int) – Number of simulation steps.

  • fixed_start (datetime) – Start time of the simulation.

Returns:

tuple[List[float], dict, dict] – Shapley values, costs of coalitions, deployment runners of coalitions.

_get_sub_coalition(sys: System, community: EnergyCommunity, coalition: List[int]) → None[source]

Rearange the system to represent the given coalition. (1) Prune the community. (2) Add the pruned nodes to the system.

Parameters:

  • sys (System) – Reference to the system.

  • community (EnergyCommunity) – Reference to the community.

  • coalition (List[int]) – Indices of the coalition members.

simulate(sim_steps: int, fixed_start: datetime, **kwargs) → ShapleySimulationResult[source]

Simulate the system and compute Shapley values. Must be implemented by subclasses.

Parameters:

  • sim_steps (int) – Number of simulation steps.

  • fixed_start (datetime) – Start time of the simulation.

Raises:

NotImplementedError – Must be implemented by subclasses.