tac.platform.game package¶

Submodules¶

tac.platform.game.base module¶

This module contains all the classes to represent the TAC game.

Classes:

GameConfiguration: a class to hold the configuration of a game. Immutable.
Game: the class that manages an instance of a game (e.g. validate and settling transactions).
AgentState: a class to hold the current state of an agent.
GoodState: a class to hold the current state of a good.
WorldState represent the state of the world from the perspective of the agent.

class tac.platform.game.base.GameConfiguration(version_id: str, nb_agents: int, nb_goods: int, tx_fee: float, agent_pbk_to_name: Dict[str, str], good_pbk_to_name: Dict[str, str])¶

Bases: object

Class containing the game configuration of a TAC instance.

property agent_names¶: List of agent names.

property agent_pbk_to_name¶: Map agent public keys to names.

property agent_pbks¶: List of agent public keys.

classmethod from_dict(d: Dict[str, Any]) → tac.platform.game.base.GameConfiguration¶: Instantiate an object from the dictionary.

property good_names¶: List of good names.

property good_pbk_to_name¶: Map good public keys to names.

property good_pbks¶: List of good public keys.

property nb_agents¶: Agent number of a TAC instance.

property nb_goods¶: Good number of a TAC instance.

to_dict() → Dict[str, Any]¶: Get a dictionary from the object.

property tx_fee¶: Transaction fee for the TAC instance.

property version_id¶: Agent number of a TAC instance.

class tac.platform.game.base.GameData(sender: str, money: float, endowment: List[int], utility_params: List[float], nb_agents: int, nb_goods: int, tx_fee: float, agent_pbk_to_name: Dict[str, str], good_pbk_to_name: Dict[str, str], version_id: str)¶

Bases: object

Convenience representation of the game data.

class tac.platform.game.base.GamePhase¶

Bases: enum.Enum

This class defines the TAC game stages.

GAME = 'game'¶

GAME_SETUP = 'game_setup'¶

POST_GAME = 'post_game'¶

PRE_GAME = 'pre_game'¶

class tac.platform.game.base.GoodState(price: float)¶

Bases: object

Represent the state of a good during the game.

class tac.platform.game.base.Transaction(transaction_id: str, is_sender_buyer: bool, counterparty: str, amount: float, quantities_by_good_pbk: Dict[str, int], sender: str)¶

Bases: object

Convenience representation of a transaction.

property buyer_pbk¶: Get the publick key of the buyer.

classmethod from_dict(d: Dict[str, Any]) → tac.platform.game.base.Transaction¶: Return a class instance from a dictionary.

classmethod from_message(message: aea.protocols.tac.message.TACMessage, sender: str) → tac.platform.game.base.Transaction¶

Create a transaction from a proposal.

Parameters: message – the message
Returns: Transaction

classmethod from_proposal(proposal: aea.protocols.oef.models.Description, transaction_id: str, is_sender_buyer: bool, counterparty: str, sender: str) → tac.platform.game.base.Transaction¶

Create a transaction from a proposal.

Parameters

proposal – the proposal
transaction_id – the transaction id
is_sender_buyer – whether the sender is the buyer
counterparty – the counterparty public key
sender – the sender public key

Returns

Transaction

matches(other: tac.platform.game.base.Transaction) → bool¶

Check if the transaction matches with another (mirroring) transaction.

Two transaction requests do match if: - the transaction id is the same; - one of them is from a buyer and the other one is from a seller - the counterparty and the origin field are consistent. - the amount and the quantities are equal.

Parameters: other – the other transaction to match.
Returns: True if the two

property seller_pbk¶: Get the publick key of the seller.

property sender¶: Get the sender public key.

to_dict() → Dict[str, Any]¶: From object to dictionary.

tac.platform.game.helpers module¶

This module contains helpers for game.

tac.platform.game.helpers.determine_scaling_factor(money_endowment: int) → float¶

Compute the scaling factor based on the money amount.

Parameters: money_endowment – the endowment of money for the agent
Returns: the scaling factor

tac.platform.game.helpers.generate_equilibrium_prices_and_holdings(endowments: List[List[int]], utility_function_params: List[List[float]], money_endowment: float, scaling_factor: float, quantity_shift: int = 1) → Tuple[List[float], List[List[float]], List[float]]¶

Compute the competitive equilibrium prices and allocation.

Parameters

endowments – endowments of the agents
utility_function_params – utility function params of the agents (already scaled)
money_endowment – money endowment per agent.
scaling_factor – a scaling factor for all the utility params generated.
quantity_shift – a factor to shift the quantities in the utility function (to ensure the natural logarithm can be used on the entire range of quantities)

Returns

the lists of equilibrium prices, equilibrium good holdings and equilibrium money holdings

tac.platform.game.helpers.generate_good_endowments(nb_goods: int, nb_agents: int, base_amount: int, uniform_lower_bound_factor: int, uniform_upper_bound_factor: int) → List[List[int]]¶

Compute good endowments per agent. That is, a matrix of shape (nb_agents, nb_goods).

Parameters

nb_goods – the number of goods.
nb_agents – the number of agents.
base_amount – the base amount of instances per good
uniform_lower_bound_factor – the lower bound of the uniform distribution for the sampling of the good instance number.
uniform_upper_bound_factor – the upper bound of the uniform distribution for the sampling of the good instance number.

Returns

the endowments matrix.

tac.platform.game.helpers.generate_money_endowments(nb_agents: int, money_endowment: int) → List[float]¶

Compute the initial money amounts for each agent.

Parameters

nb_agents – number of agents.
money_endowment – money endowment per agent.

Returns

the list of initial money amounts.

tac.platform.game.helpers.generate_utility_params(nb_agents: int, nb_goods: int, scaling_factor: float) → List[List[float]]¶

Compute the preference matrix. That is, a generic element e_ij is the utility of good j for agent i.

Parameters

nb_agents – the number of agents.
nb_goods – the number of goods.
scaling_factor – a scaling factor for all the utility params generated.

Returns

the preference matrix.

tac.platform.game.helpers.logarithmic_utility(utility_function_params: List[float], good_bundle: List[int], quantity_shift: int = 1) → float¶

Compute agent’s utility given her utility function params and a good bundle.

Parameters

utility_function_params – utility function params of the agent
good_bundle – a bundle of goods with the quantity for each good
quantity_shift – a factor to shift the quantities in the utility function (to ensure the natural logarithm can be used on the entire range of quantities)

Returns

utility value

tac.platform.game.helpers.make_agent_name(agent_id: int, is_world_modeling: bool, nb_agents: int) → str¶

Make the name for baseline agents from an integer identifier.

E.g.:

>>> make_agent_name(2, False, 10)
'tac_agent_2'
>>> make_agent_name(2, False, 100)
'tac_agent_02'
>>> make_agent_name(2, False, 101)
'tac_agent_002'

Parameters

agent_id – the agent id.
is_world_modeling – the boolean indicated whether the baseline agent models the world around her or not.
nb_agents – the overall number of agents.

Returns

the formatted name.

Returns

the string associated to the integer id.

tac.platform.game.helpers.marginal_utility(utility_function_params: List[float], current_holdings: List[int], delta_holdings: List[int]) → float¶

Compute agent’s utility given her utility function params and a good bundle.

Parameters

utility_function_params – utility function params of the agent
current_holdings – a list of goods with the quantity for each good
delta_holdings – a list of goods with the quantity for each good (can be positive or negative)

Returns

utility difference between new and current utility

tac.platform.game.stats module¶

This module contains a class to query statistics about a game.

class tac.platform.game.stats.GameStats(game: tac.agents.controller.base.states.Game)¶

Bases: object

A class to query statistics about a game.

adjusted_score() → Tuple[List[str], numpy.ndarray]¶

Compute the adjusted score of each agent.

Returns: a matrix of shape (1, nb_agents), where every column i contains the score of the agent.

balance_history() → Tuple[List[str], numpy.ndarray]¶: Get the balance history.

eq_vs_current_score() → Tuple[List[str], numpy.ndarray]¶

Compute the equilibrium score of each agent and display it together with the current score.

Returns: a matrix of shape (2, nb_agents), where every column i contains the scores of the agent.

eq_vs_mean_price() → Tuple[List[str], numpy.ndarray]¶

Compute the mean price of each good and display it together with the equilibrium price.

Returns: a matrix of shape (2, nb_goods), where every column i contains the prices of the good.

classmethod from_json(d: Dict[str, Any])¶: Read from json.

get_eq_scores() → Dict[str, float]¶

Get the equilibrium score for all agents.

Returns: dictionary mapping agent name to equilibrium score.

get_initial_scores() → Dict[str, float]¶

Get the initial score for all agents.

Returns: dictionary mapping agent name to initial score.

holdings_history()¶

Compute the history of holdings.

Returns: a matrix of shape (nb_transactions, nb_agents, nb_goods). i=0 is the initial endowment matrix.

price_history() → numpy.ndarray¶: Get the price history.

score_history() → Tuple[List[str], numpy.ndarray]¶

Compute the history of the scores for every agent.

To do so, we need to simulate the game again, by settling transactions one by one and get the scores after every transaction.

Returns: a matrix of shape (nb_transactions + 1, nb_agents), where every row i contains the scores after transaction i (i=0 is a row with the initial scores.)

tx_counts() → Dict[str, Dict[str, int]]¶: Get the tx counts.

tx_prices() → Dict[str, List[float]]¶: Get the tx counts.

Module contents¶

Contains the game specific modules.

tac.platform.game package¶

Submodules¶

tac.platform.game.base module¶

tac.platform.game.helpers module¶

tac.platform.game.stats module¶

Module contents¶

Table of Contents

Related Topics