Native GT

Ver. 1.0.1 (2023-12-27)

This module provides model classes for tasks related to a Native Game Theory.

class mlpro.gt.native.basics.GTStrategy(p_player_id=0, p_strategy_space: Set = None, p_values: ndarray = None)

Bases: Action

A class representing a strategy for a player in game theory. Objects of this class representations of (multi-)players. Every element of the internal list is related to a player, and its partial subsection. Strategy values for the first player can be added while object instantiation. Strategy values of further player can be added by using method self.add_elem().

Parameters:

• p_player_id – Unique id of (first) player to be added

• p_strategy_space (Set) – Strategy space of (first) player to be added. Default = None.

• p_values (np.ndarray) – Strategy values of (first) player to be added. Default = None.

C_TYPE = 'GT Strategy'

get_player_ids() → list

A method to get the ids of (multi-)players that have been added to this class.

Returns:

A list of players’ ids.

Return type:

list

class mlpro.gt.native.basics.GTFunction(p_func_type: int, p_dim_elems: list = None, p_num_coalisions: int = None, p_logging=True)

Bases: Persistent

A class representing a mapping functionality between strategies and payoffs in two possible forms, such as payoff matrices or transfer functions.

Parameters:

• p_func_type (int) – Type of functions, either C_FUNC_PAYOFF_MATRIX or C_FUNC_TRANSFER_FCTS.

• p_dim_elems (list) – The dimension of payoff matrix. For transfer function, this can be avoided. Default = None.

• p_num_coalisions (int) – Number of coalisions. For transfer function, this can be avoided. Default = None.

• p_logging – Log level (see constants C_LOG_*). Default: Log.C_LOG_ALL.

C_TYPE = 'GT Function'

C_FUNC_PAYOFF_MATRIX = 0

C_FUNC_TRANSFER_FCTS = 1

C_FUNCTION_TYPE = None

_setup_mapping_matrix() → ndarray

A method to setup the mapping of the payoff matrix between strategies and payoffs. This is only applicable for C_FUNC_PAYOFF_MATRIX. This method needs to be redefined based on the setup of the game.

Returns:

Resulted mapping.

Return type:

np.ndarray

_setup_payoff_matrix()

A method to setup payoff matrices. This is only applicable for C_FUNC_PAYOFF_MATRIX. This method needs to be redefined based on the setup of the game.

_add_payoff_matrix(p_idx: int, p_payoff_matrix: ndarray)

A method to add a payoff matrix to the GTFunction class. This method is called during the redifinition of _setup_payoff_matrix(). This is only applicable for C_FUNC_PAYOFF_MATRIX.

Parameters:

• p_idx (int) – Id of the payoff matrix in the same order as the index of the players’ ids in the list.

• p_payoff_matrix (np.ndarray) – Defined payoff matrix.

_setup_transfer_functions()

A method to setup transfer functions. This is only applicable for C_FUNC_TRANSFER_FCTS. This method needs to be redefined based on the setup of the game.

_add_transfer_function(p_idx: int, p_transfer_fct: TransferFunction)

A method to add a transfer function to the GTFunction class. This method is called during the redifinition of _setup_transfer_functions(). This is only applicable for C_FUNC_TRANSFER_FCTS.

Parameters:

• p_idx (int) – Id of the payoff matrix in the same order as the index of the players’ ids in the list.

• p_transfer_fct (TransferFunction) – Defined transfer function.

best_response(p_element_id: str) → float

A method to measure the highest possible payoff of a player/coalition in the related payoff map.

Parameters:

p_element_id (str) – Id of a specific player/coalition.

Returns:

The highest possible payoff of a player/coalition.

Return type:

float

zero_sum() → bool

A method to check whether the game is a zero sum game by considering the payoff maps.

Returns:

True means it is a zero sum game, otherwise no.

Return type:

bool

class mlpro.gt.native.basics.GTPayoffMatrix(p_function: GTFunction = None, p_player_ids: list = None, p_logging=True)

Bases: TStamp, Persistent

A class representing a payoff matrix for a set of players in game theory, where it includes GTFunction that has a mapping functionality.

Parameters:

• p_function (GTFunction, optional) – Defined GTFunction for mapping functionality. The default is None.

• p_player_ids (list, optional) – List of players ids. The default is None.

• p_logging – Logging functionality. The default is Log.C_LOG_ALL.

C_TYPE = 'GT Payoff Matrix'

get_payoff(p_strategies: GTStrategy, p_element_id: str) → float

A method to get the payoff for a player/coalition with respect to the selected strategies.

Parameters:

• p_strategies (GTStrategy) – Selected strategies by all players/coalitions.

• p_element_id (str) – ID of a specific player/coalition.

Returns:

Payoff value.

Return type:

float

call_mapping(p_input: str, p_strategies: GTStrategy) → float

A method to run the mapping from the payoff matrix.

Parameters:

• p_input (str) – inputs of the payoff matrix.

• p_strategies (GTStrategy) – Selected strategies by all players/coalitions.

Returns:

Payoff of the player/coalition.

Return type:

float

_call_mapping(p_input: str, p_strategies: GTStrategy) → float

If the payoff matrix does not use the standardized matrix by MLPro-GT. This method can be used by redefining it.

Parameters:

• p_input (str) – inputs of the payoff matrix.

• p_strategies (GTStrategy) – Selected strategies by all players/coalitions.

Returns:

Payoff of the player/coalition.

Return type:

float

best_response_value(p_strategies: GTStrategy, p_element_id: str) → float

A method to calculate the gap between the payoff of the taken strategy to the best response value.

Parameters:

• p_strategies (GTStrategy) – Selected strategies by all players/coalitions.

• p_element_id (str) – Id of a specific player/coalition.

Returns:

Current payoff - payoff from best response.

Return type:

float

_call_best_response(p_element_id: str) → float

If the payoff matrix does not use the standardized matrix by MLPro-GT. This method can be used to get the best response value by redefining it.

Parameters:

p_element_id (str) – Id of a specific player/coalition.

Returns:

The highest possible payoff of a player/coalition.

Return type:

float

zero_sum() → bool

A method to check whether the game is a zero sum game by considering the payoff maps.

Returns:

True means it is a zero sum game, otherwise no.

Return type:

bool

_call_zero_sum() → bool

If the payoff matrix does not use the standardized matrix by MLPro-GT. This method can be used to get the detect zero sum games by redefining it.

Returns:

True means it is a zero sum game, otherwise no.

Return type:

bool

class mlpro.gt.native.basics.GTSolver(p_strategy_space: MSpace, p_id=None, p_visualize: bool = False, p_logging=True, **p_param)

Bases: Task, ScientificObject

A class representing a solver (policy) in game theory.

Parameters:

• p_strategy_space (MSpace) – Strategy space of (first) player to be added. Default = None.

• p_id – Id of a player. The default is None.

• p_visualize (bool, optional) – Allowing visualization. The default is False.

• p_logging – Logging setup. The default is Log.C_LOG_ALL.

• **p_param – additional parameters related to the policy.

C_TYPE = 'GT Solver'

C_NAME = '????'

C_SCIREF_TYPE = None

_init_hyperparam(**p_param)

Implementation specific hyperparameters can be added here. Please follow these steps: a) Add each hyperparameter as an object of type HyperParam to the internal hyperparameter

space object self._hyperparam_space

2. Create hyperparameter tuple and bind to self._hyperparam_tuple

3. Set default value for each hyperparameter

Parameters:

p_param (Dict) – Further model specific hyperparameters, that are passed through constructor.

_setup_solver()

A method to setup a solver. This needs to be redefined based on each policy, but remains optional.

get_hyperparam() → HyperParamTuple

Returns the internal hyperparameter tuple to get access to single values.

get_strategy_space() → MSpace

A method to get the strategy space of a solver.

Returns:

Strategy space.

Return type:

MSpace

set_random_seed(p_seed=None)

Resets the internal random generator using the given seed.

Parameters:

p_seed – Seeding.

compute_strategy(p_payoff: GTPayoffMatrix) → GTStrategy

A method to compute a strategy from the solver.

Parameters:

p_payoff (GTPayoffMatrix) – Payoff matrix of a specific player.

Returns:

The computed strategy.

Return type:

GTStrategy

_compute_strategy(p_payoff: GTPayoffMatrix) → GTStrategy

A method to compute a strategy from the solver. This method needs to be redefined.

Parameters:

p_payoff (GTPayoffMatrix) – Payoff matrix of a specific player.

Returns:

The computed strategy.

Return type:

GTStrategy

class mlpro.gt.native.basics.GTPlayer(p_solver: list | GTSolver, p_name='', p_visualize: bool = False, p_logging=True, p_random_solver: bool = False, **p_param)

Bases: GTSolver

A class representing a player in game theory with at least one specific defined solver.

Parameters:

• p_solver (Union[list, GTSolver]) – A list of solvers or a solver.

• p_name – Name of the player. The default is ‘’.

• p_visualize (bool, optional) – Allowing visualization. The default is False.

• p_logging – Logging setup. The default is Log.C_LOG_ALL.

• p_random_solver (bool, optional) – Allowing random solver. The default is False.

• **p_param – Additional parameters for the player.

C_TYPE = 'GT Player'

C_NAME = ''

_init_hyperparam(**p_param)

A method to initiate the related hyperparameters.

Parameters:

**p_param – Additional parameters for the player.

switch_logging(p_logging)

A metod to swith logging setup

Parameters:

p_logging – Loggin setup.

set_log_level(p_level)

A method to set the logging level

Parameters:

p_level – Logging level.

get_strategy_space() → MSpace

A method to get the strategy space of a player.

Returns:

Strategy space.

Return type:

MSpace

set_random_seed(p_seed=None)

Resets the internal random generator using the given seed.

Parameters:

p_seed – Seeding.

compute_strategy(p_payoff: GTPayoffMatrix) → GTStrategy

A method to compute a strategy from the solver.

Parameters:

p_payoff (GTPayoffMatrix) – Payoff matrix of a specific player.

Returns:

The computed strategy.

Return type:

GTStrategy

get_solver() → GTSolver

A method to get the solver of the player.

Returns:

Solver.

Return type:

GTSolver

switch_solver()

A method to switch the solver, if the player has multiple solvers.

class mlpro.gt.native.basics.GTCoalition(p_name: str = ' ', p_coalition_type=None, p_logging=True)

Bases: GTPlayer

A class representing a colation in game theory that contains a set of players or at least one player.

Parameters:

• p_name (str, optional) – Name of a coalition. The default is “ “.

• p_coalition_type – Type of coalitions. The default is None.

• p_logging – Logging setup. The default is Log.C_LOG_ALL.

C_TYPE = 'GT Coalition'

C_NAME = ''

C_COALITION_STRATEGY = None

C_COALITION_MEAN = 0

C_COALITION_SUM = 1

C_COALITION_MIN = 2

C_COALITION_MAX = 3

C_COALITION_MEDIAN = 4

C_COALITION_MODE = 5

C_COALITION_CUSTOM = 6

switch_logging(p_logging) → None

A metod to swith logging setup

Parameters:

p_logging – Loggin setup.

switch_adaptivity(p_ada: bool)

A method to switch adaptivity. In native GT, this is not necessary.

Parameters:

p_ada (bool) – adaptivity.

set_log_level(p_level)

A method to set the logging level

Parameters:

p_level – Logging level.

add_player(p_player: GTPlayer)

A method to add a player to the coalition.

Parameters:

p_player (GTPlayer) – A GT player.

get_players() → list

A method to get a list of players in the coaltiion.

Returns:

List of GT Players.

Return type:

list

get_players_ids() → list

A method to get the players’ ids in the coalition.

Returns:

List of ids.

Return type:

list

get_player(p_player_id) → GTPlayer

A method to get the object of a specific player.

Parameters:

p_player_id – Id of a player.

Returns:

Object of the player.

Return type:

GTPlayer

get_coalition_strategy() → int

A methof to get the coalition strategy.

Returns:

Coalition strategy.

Return type:

int

set_random_seed(p_seed=None)

Resets the internal random generator using the given seed.

Parameters:

p_seed – Seeding.

get_strategy_space() → ESpace

A method to get the strategy space of the coalition.

Returns:

Strategy space.

Return type:

ESpace

compute_strategy(p_payoff: GTPayoffMatrix) → GTStrategy

A method to compute a combined strategy from the players in the coalition.

Parameters:

p_payoff (GTPayoffMatrix) – Payoff matrix of the coalition.

Returns:

The computed strategy.

Return type:

GTStrategy

_custom_coalition_strategy(p_payoff: GTPayoffMatrix) → GTStrategy

A method for customizing the coalition strategy.

Parameters:

p_payoff (GTPayoffMatrix) – The payoff matrix of the coalition.

class mlpro.gt.native.basics.GTCompetition(p_name: str = ' ', p_logging=True)

Bases: GTCoalition

A class representing a competition in game theory that contains a set of coalitions. This suits for a competitive game.

Parameters:

• p_name (str, optional) – Name of the competition. The default is “ “.

• p_logging – Logging setup. The default is Log.C_LOG_ALL.

Return type:

None.

C_TYPE = 'GT Competition'

C_NAME = ''

switch_logging(p_logging) → None

A metod to swith logging setup

Parameters:

p_logging – Loggin setup.

set_log_level(p_level)

A method to set the logging level

Parameters:

p_level – Logging level.

add_coalition(p_coalition: GTCoalition)

A method to add a coaltion to the competition.

Parameters:

p_coalition (GTCoalition) – A coalition.

get_coalitions() → list

A method to get the list of coalitions in the competition.

Returns:

List of coalitions.

Return type:

list

get_coalitions_ids() → list

A method to get the list of coalitions’ ids in the competition.

Returns:

List of coalitions’ ids.

Return type:

list

get_coalition(p_coalition_id) → GTCoalition

A method to get the object of a specific coalition.

Parameters:

p_coalition_id – Coalition id.

Returns:

Coalition object.

Return type:

GTCoalition

get_players() → list

A method to get the list of players in the competition.

Returns:

List of players.

Return type:

list

get_players_ids() → list

A method to get the list of players’ ids in the competition.

Returns:

List of players’ ids.

Return type:

list

get_player(p_player_id) → GTPlayer

A method to get the object of a player.

Parameters:

p_player_id – Player id.

Returns:

Object of the player.

Return type:

GTPlayer

set_random_seed(p_seed=None)

Resets the internal random generator using the given seed.

Parameters:

p_seed – Seeding.

compute_strategy(p_payoff: GTPayoffMatrix) → GTStrategy

A method to compute the strategy of each coaltiion.

Parameters:

p_payoff (GTPayoffMatrix) – Payoff matrices.

Returns:

The computed strategy.

Return type:

GTStrategy

get_strategy_space() → ESpace

A method to get the strategy space of the competition.

Returns:

Strategy space.

Return type:

ESpace

class mlpro.gt.native.basics.GTDataStoring(p_space: Set = None)

Bases: DataStoring

A method for data storing of the game.

Parameters:

p_space (Set, optional) – Spaces. The default is None.

C_VAR0 = 'Trial'

C_VAR_CYCLE = 'Cycle'

C_VAR_DAY = 'Day'

C_VAR_SEC = 'Second'

C_VAR_MICROSEC = 'Microsecond'

get_variables()

A method to get variables.

get_space()

A method to get space..

add_trial(p_trial_id)

A method to add a trial id into the data storing.

Parameters:

p_trial_id – Trial id.

memorize_row(p_cycle_id, p_tstamp: timedelta, p_data)

A method to add data to the data storing

Parameters:

• p_cycle_id – Cyle id.

• p_tstamp (timedelta) – Time stamp.

• p_data – Data to be stored.

class mlpro.gt.native.basics.GTGame(p_mode=0, p_ada=False, p_cycle_limit=1, p_visualize: bool = False, p_logging=True)

Bases: Scenario

A class representing a game in game theory.

Parameters:

• p_mode – Operation mode. See bf.ops.Mode.C_VALID_MODES for valid values. Default = Mode.C_MODE_SIM.

• p_ada – Boolean switch for adaptivity. In the native GT, this is always switched off. The default is False.

• p_cycle_limit – Maximum number of cycles.. The default is 1.

• p_visualize (bool, optional) – Boolean switch for visualisation. The default is False.

• p_logging – Log level (see constants of class Log). The default is Log.C_LOG_ALL.

C_TYPE = 'GT Game'

C_NAME = ''

C_LATENCY = datetime.timedelta(seconds=1)

_setup(p_mode, p_ada: bool, p_visualize: bool, p_logging) → Model

Custom setup of GT Game. Payoff matrix has to be defined here as self._payoff.

Parameters:

• p_mode – Operation mode. See Mode.C_VALID_MODES for valid values. Default = Mode.C_MODE_SIM

• p_ada (bool) – Boolean switch for adaptivity.

• p_visualize (bool) – Boolean switch for visualisation.

• p_logging – Log level (see constants of class Log).

Returns:

player – GTPlayer model (object of type GTPlayer, GTCoalition or GTCompetition).

Return type:

GTPlayer

_run_cycle()

A method to run a cycle in the defined game

Return type:

False, False, False, False

_get_evaluation(p_coalition_id: str, p_coalition: GTCoalition) → float | list

A method to get the evaluation of a coalition in the form of payoff matrix.

Parameters:

• p_coalition_id (str) – Coalition id.

• p_coalition (GTCoalition) – Coalition object.

Returns:

Payoff of the respective coalition.

Return type:

Union[float,list]

connect_data_logger(p_ds_strategies: GTDataStoring = None, p_ds_payoffs: GTDataStoring = None)

A method to connect connect with the data logger from GTDataStoring.

Parameters:

• p_ds_strategies (GTDataStoring, optional) – Object of GTDataStoring of strategies. The default is None.

• p_ds_payoffs (GTDataStoring, optional) – Object of GTDataStoring of payoffs. The default is None.

is_zerosum() → bool

A method to identify whether it is a zero-sum game.

Returns:

True means zero-sum game, otherwise not.

Return type:

bool

_is_bestresponse(p_coalition_id: str, p_coalition: GTCoalition) → float

A method to identify whether the best response value of a coaltion.

Parameters:

• p_coalition_id (str) – Coalition id.

• p_coalition (GTCoalition) – Coalition object.

Returns:

The best response value.

Return type:

float

get_latency() → timedelta

A method to get the latency of the game

Returns:

Latency.

Return type:

timedelta

class mlpro.gt.native.basics.GTTrainingResults(p_scenario: GTGame, p_run: int, p_cycle_id: int, p_logging='W')

Bases: TrainingResults

Results of a native GT training.

Parameters:

• p_scenario (GTScenario) – Related native GT scenario.

• p_run (int) – Run id.

• p_cycle_id (int) – Id of first cycle of this run.

• p_logging – Log level (see constants of class Log). Default: Log.C_LOG_ALL

C_NAME = 'GT Training Results'

C_FNAME_COAL_STRATEGIES = 'stategies'

C_FNAME_COAL_PAYOFFS = 'payoffs'

save(p_path, p_filename='summary.csv') → bool

A method to save the training results

Parameters:

• p_path – Saving path.

• p_filename – Name and format of the file. The default is ‘summary.csv’.

Returns:

True means successful, otherwise failed.

Return type:

bool

class mlpro.gt.native.basics.GTTraining(**p_kwargs)

Bases: Training

Template class for a GT training.

Parameters:

• p_game_cls – Name of GT game class, compatible to/inherited from class GTGame.

• p_cycle_limit (int) – Maximum number of training cycles (0=no limit). Default = 0.

• p_adaptation_limit (int) – Maximum number of adaptations (0=no limit). Default = 0.

• p_hpt (HyperParamTuner) – Optional hyperparameter tuner (see class HyperParamTuner). Default = None.

• p_hpt_trials (int) – Optional number of hyperparameter tuning trials. Default = 0.

• p_path (str) – Optional destination path to store training data. Default = None.

• p_visualize (bool) – Boolean switch for visualisation. Default = False.

• p_logging – Log level (see constants of class Log). Default = Log.C_LOG_WE.

• p_collect_strategy – Collect data of selected strategies. Default = False.

• p_collect_payoff – Collect data of obtained payoffs. Default = False.

• p_init_seed – Seeding. Default = 0.

C_TYPE = 'GT Training'

C_NAME = 'Native GT Training'

C_CLS_RESULTS

alias of GTTrainingResults

_init_results() → GTTrainingResults

A method to initialise data storing functionality.

Returns:

Object of GTTrainingResults.

Return type:

GTTrainingResults

_init_trial()

A method to initialise a trial.

_close_trial()

A method to close/stop a trial.

_run_cycle() → bool

A method to run a cycle.

Returns:

False.

Return type:

bool