Documentation

Version: 1.0.0

Historical documentation: 1.0.0

Useful links: Source Repository | Issue Tracker & Support | Contact & Mailing List

Objects

GameParameters

class karma_game_library.entities.game_parameters.GameParameters(num_agents: int, num_participants: int, num_types: int, num_urgencies: int, num_outcomes: int, num_average_karma: int, map_type_temp_preference: Dict[int, float], lst_init_types: List[int], lst_init_urgencies: List[int], lst_init_karmas: List[int], func_cost: Callable, func_outcome: Callable, func_payment: Callable, func_urgency_transition: Callable, func_overflow_distribution: Callable, func_karma_redistribution: Callable)

A class to encapsulate all parameters necessary to describe a Karma game for policy computation and simulation purposes. It is used when instantiating StateDistribution and Policy objects, as well as it is used for Simulator and Optimizer.

__init__(num_agents: int, num_participants: int, num_types: int, num_urgencies: int, num_outcomes: int, num_average_karma: int, map_type_temp_preference: Dict[int, float], lst_init_types: List[int], lst_init_urgencies: List[int], lst_init_karmas: List[int], func_cost: Callable, func_outcome: Callable, func_payment: Callable, func_urgency_transition: Callable, func_overflow_distribution: Callable, func_karma_redistribution: Callable)

This constructor initializes the GameParameters instance and checks the validity of the given parameters.

Parameters:

• num_agents (int) – The number agents in the population (the population size).

• num_participants (int) – The number of agents that participate in an interaction.

• num_types (int) – The finite number of possible agent types.

• num_urgencies (int) – The finite number of possible agent urgencies.

• num_outcomes (int) – The finite number of possible outcomes for a participant.

• num_average_karma (int) – The initial state is focussed on num_average_karma. The average Karma will remain constant.

• map_type_temp_preference (Dict[int, float]: [type] -> [temporal preference]) – This map maps the given agent type to a temporal preference between 0.0 and 1.0.

• lst_init_types (List[int]) – This list of integers represents the list of agent types. The agent types (temporal preferences) cannot change over time.

• lst_init_urgencies (List[int]) – This list of integers represents the list of initial agent urgencies.

• lst_init_karmas (List[int]) – This list of integers represents the list of initial agents’ karma balances.

• func_cost (Callable, (urgency, outcome) -> (cost)) – This function takes the urgency and outcome of a participant and returns the costs that result of to it. The cost should be a positive number as the software framework works with negative costs.

• func_outcome (Callable, (lst_actions) -> (outcomes)) – This function takes the interaction participant actions and returns an integers representing the interaction outcome. The outcomes is a vector of outcomes for each participant.

• func_payment (Callable, (actions, outcomes) -> (payments, karma_overflow)) – This function takes the participants actions and interaction outcomes and returns the lists of payments and karma_overflow. Note, payments are added to the karma balances of participants. Note2: This function cannot be probabilistic!

• func_urgency_transition (Callable, (atype, urgency, outcome, set_urgencies) -> (urgency_next)) – This function takes an agent type, urgency, and outcome, and returns the next agent urgency. This enables the user to model the urgency_next in dependence of outcome. The outcome is encoded as follows: -1 means the agent didnt participate an interaction this epoch, otherwise it is the max outcome of all interactions from this epoch the agent participated. One could model the urgency transition with type specific finite state machines for instance.

• func_overflow_distribution (Callable, (pop_karmas, karma_overflow) -> (pop_karmas_next)) – This function takes the population karma balances, and the payment overflow, and distributes it across the population.

• func_karma_redistribution (Callable, (pop_karmas) -> (pop_karmas_next)) – This function takes the population (represented by karma balances) and returns a list of integers representing the new karma balances of agents after redistribution.

Raises:

Exception – In case the input parameters are not plausible a specific exception will be raised.

Return type:

None

static load(source_file: str)

This function loads the GameParameters from a file.

Parameters:

source_file (str) – The file to load the GameParameters from.

Returns:

parameters – A GameParameters instance.

Return type:

GameParameters

static save(parameters: GameParameters, target_file: str)

This function stores the GameParameters to a file.

Parameters:

• parameters (GameParameters) – A GameParameters instance.

• target_file (str) – The file to store the GameParameters.

Return type:

None

StateDistribution

class karma_game_library.StateDistribution(game_parameters: GameParameters)

A class to represent the state distribution of a Karma system. This means, the share of the population, that has a specific type, specific urgency, and a specific karma balance. All shares together add up to 1.0.

dist_matrix

The social state distribution matrix. Each value represents the share of the population, that has a specific type, specific urgency, and a specific karma balance. All shares together add up to 1.0. Note, that the share for the last karma balance index represents agents with a karma balance of exactly this value or higher.

Type:

np.array, indexes: [type][urgency][karma_balance]

__init__(game_parameters: GameParameters)

This constructor initializes the state distribution instance. The distribution matrix will be initialized to an even distribution.

Parameters:

game_parameters (GameParameters) – The game parameters for the simulator.

Raises:

Exception – In case the input parameters are not plausible a specific exception will be raised.

Return type:

None.

autocorrect()

This function corrects the state_distribution after changes by the user. This involves normalizing the matrix, so that all shares add up to 1.0, and transforming the distribution so that the average karma balance is preserved as constant.

Parameters:

None –

Returns:

changed – Whether the state_distribution was changed by the function or not.

Return type:

bool

copy_social_state_distribution(other_social_state)

This function copies the dist_matrix from other_social_state into this instances dist_matrix.

Parameters:

other_social_state_distribution (StateDistribution) – Another social state distribution from which the content shall be copied into this instance.

Raises:

Exception – In case the StateDistribution other_social_state_distribution is invalid a specific exception will be raised.

Return type:

None

get_average_karma()

Returns the average amount of Karma.

Returns:

average – The empirical, average amount of Karma.

Return type:

float

get_limited_dist_matrix(limit: int)

This function returns a karma balance limited state_distribution. If the limit is larger than the _num_state_karmas, the additional fields are added up with zeros. If the limit is smaller, then the state distribution is aggregated, meaning that the share for the returned distribution for karma=limit-1 represents the share of all balances with karmas>=limit-1.

Parameters:

limit (int) – The limit for the limited distribution matrix.

Returns:

limited_dist_matrix – The limited distribution matrix.

Return type:

np.array

load(source_file: str)

This function loads the state distribution from a file into this instance.

Parameters:

source_file (str) – The file where to load the state distribution from.

Return type:

None

save(target_file: str)

This function saves the state distribution to a file.

Parameters:

target_file (str) – The file where to store the state distribution.

Return type:

None

validate()

This function validates whether the social state distribution is valid. This means, that all shares add up to 1.0, and that the average karma balance is preserved as constant.

Parameters:

None –

Returns:

valid – Whether the policy is valid or not.

Return type:

bool

Policy

class karma_game_library.Policy(game_parameters: GameParameters, initialization: str = 'even')

A class to represent the agent policy, meaning for a specific type and urgency the 2D probability matrix of karma balances (columns) and actions taken (rows). The type and urgency specific 2D probability matrix will add up to 1.0 for each column (for one given karma balance, the sum of probabilities of different actions sum up to 1.0).

prob_matrix

The probability matrix. Each value represents the probability, that an agent of a specific type and a specific urgency with a specific karma balance will choose a specific action. The probability matrix will add up to 1.0 for each column (for one given karma balance, the sum of probabilities of different actions sum up to 1.0).

Type:

np.array, indexes: [type][urgency][karma_balance][action]

map_possible_actions

This map maps the given karma balance to a list of possible actions during an interaction.

Type:

Dict[int,List[int]], [karma] -> [list of actions]

__init__(game_parameters: GameParameters, initialization: str = 'even')

This constructor initializes the Policy instance. The probability matrix will be initialized to an even distribution.

Parameters:

• game_parameters (GameParameters) – The game parameters for the simulator.

• initialization (str) – Optional. The initialization of the policy. There are three possible options: “even”, “bottom”, “top”. Default value is “even” (recommended).

Raises:

Exception – In case the input parameters are not plausible a specific exception will be raised.

Return type:

None.

autocorrect()

This function corrects the prob_matrix after changes by the user. This involves (i) eliminating illegal actions for specific karma balances as defined during initialization by map_possible_actions (setting their probability to zero), and (ii) normalizing the columns, so that the type and urgency specific 2D probability matrix will add up to 1.0 for each column.

Parameters:

None –

Returns:

changed – Whether the prob_matrix was changed by the function or not.

Return type:

bool

copy_policy(other_policy)

This function copies the prob_matrix from other_policy into this instances prob_matrix.

Parameters:

other_policy (Policy) – Another policy from which the content shall be copied into this instance.

Raises:

Exception – In case the Policy other_policy is invalid a specific exception will be raised.

Return type:

None

load(source_file: str)

This function loads the policy from a file.

Parameters:

source_file (str) – The file where to load the policy from.

Return type:

None

save(target_file: str)

This function saves the policy to a file.

Parameters:

target_file (str) – The file where to store the policy.

Return type:

None

validate()

This function validates whether the policy is valid. This means, that for each type and urgency specific 2D probability matrix, the columns add up to 1.0 (for one given karma balance, the sum of probabilities of different actions sum up to 1.0). Moreover, it checks whether all actions are valid (one cannot bid more in an auction then one has karma). If the outcome of the validation is negative you could try to call function autocorrect().

Parameters:

None –

Returns:

valid – Whether the policy is valid or not.

Return type:

bool

Algorithms

Simulator

class karma_game_library.Simulator(game_parameters: GameParameters, state: StateDistribution, steady_state_init: bool = True)

A class to provide entities and functionality to perform the simulation of a Karma game.

epoch_counter

The current epoch of the game (starts counting from zero).

Type:

int

last_participants

List of participating agents from last interaction.

Type:

List[int]

last_actions

List of participant actions from last interaction.

Type:

List[int]

last_outcome

List of outcomes from last interaction.

Type:

List[int]

all_epoch_participants

List of participants during all interactions of the current epoch.

Type:

List[int]

all_epoch_outcomes

List of the maximum of outcomes during all interactions of the current epoch for the participants in all_epoch_participants.

Type:

List[int]

__init__(game_parameters: GameParameters, state: StateDistribution, steady_state_init: bool = True)

This constructor initializes the internal variables of the simulator according to the simulation_parameters by calling the function reset().

Parameters:

• game_parameters (GameParameters) – The game parameters for the simulator.

• steady_state_init (bool) – Optional, Default: True. This will define whether population initialization for the simulation is as given by the initial parameters for the optimization (lst_init_types, lst_init_urgencies, lst_init_karmas), or the steady state computed by the optimizer will be used.

Return type:

None

begin_epoch()

This function begins the next epoch of the game.

Parameters:

None –

Raises:

Exception – In case the previous epoch was not closed. In case the karma overflow is not empty due to invalid functions func_payment, func_overflow_distribution or func_karma_redistribution.

Return type:

None

close_epoch()

This function closes / ends the current epoch of the game. This includes the distribution of karma overflow, and the redistribution of karma balances.

Parameters:

None –

Raises:

Exception – In case there is no open epoch started yet. In case the karma overflow is not empty due to invalid functions func_payment, func_overflow_distribution or func_karma_redistribution. In case the total amount of karma did not stay constant due to invalid functions func_payment, func_overflow_distribution or func_karma_redistribution.

Returns:

epoch_counter – The increment epoch_counter after playing the epoch.

Return type:

int

get_agent_information(agent_idx: int, arr: bool = True)

This function returns the information of an agent.

Parameters:

• agent_idx (int) – The agent index in the population.

• arr (bool) – Whether an array shall be returned, or a tuple of values. Default is True.

Returns:

• arr (np.array) – The agent information as a 1x5 array, where each column is represented by following enumeration: TYPE_COL = 0, URGENCY_COL = 1, KARMA_COL = 2, CUM_COST_COL = 3, ENCOUNTERS_COL = 4.

• type (int) – (if parameter ‘arr’ set to False)

• urgency (int) – (if parameter ‘arr’ set to False)

• karma (int) – (if parameter ‘arr’ set to False)

• cum_cost (float) – (if parameter ‘arr’ set to False)

• encounters (int) – (if parameter ‘arr’ set to False)

get_agent_population()

This function returns the complete population, meaning the information of all agents. Each column is represented by following enumeration: TYPE_COL = 0, URGENCY_COL = 1, KARMA_COL = 2, CUM_COST_COL = 3, ENCOUNTERS_COL = 4.

Parameters:

None –

Returns:

population – The agent information as a [num_agent x 5] array, where each column is represented by following enumeration: TYPE_COL = 0, URGENCY_COL = 1, KARMA_COL = 2, CUM_COST_COL = 3, ENCOUNTERS_COL = 4.

Return type:

np.array

get_karma_distribution()

This function returns the Karma distribution of the population.

Parameters:

None –

Returns:

distribution – This distribution represents the relative share of the population that owns a specific amount of Karma. The distribution is calculated for all karmas in parameters._num_state_karmas. The last value of the distribution thus represents the share of agents with a karma balance of num_state_karmas-1 or higher.

Return type:

np.array

get_population_cumulative_costs()

This function returns the cumulative, and discounted costs for each agent of the population. Discounting takes place for each encounter and not for each epoch!

Parameters:

None –

Returns:

pop_costs – This array represents the cumulative, discounted costs for each agent of the population.

Return type:

np.array

get_population_encounters()

This function returns the number of encounters (being a participant in an interaction) for each agent of the population.

Parameters:

None –

Returns:

pop_encounters – This represents the number of encounters for each agent during the game.

Return type:

np.array

get_state_transition_counts(participants_only: bool = True)

This function returns the state transition counts. This means the times an agent reached state X (urgency, karma) from the original state Y (urgency, karma).

Parameters:

participants_only (bool) – Optional. Default=True. This defines, whether the state transition distribution of all agents, or just of the agents that participated during an epoch shall be considered.

Returns:

distribution – This distribution is a four dimensional matrix with following indexes: [urgency_next][karma_next][urgency_before][karma_before]

Return type:

np.array

get_total_cumulative_costs()

This function returns the total cumulative, and discounted costs as sum of the cumulative, discounted costs over all agents. Discounting takes place for each encounter and not for each epoch!

Parameters:

None –

Returns:

costs – This cost is the sum of all cumulative, discounted costs over all agents.

Return type:

float

get_total_encounters()

This function returns the total number of encounters (participations in interactions) as sum over all agents of the population.

Parameters:

None –

Returns:

encounters – This represents the number of total encounters during the game.

Return type:

int

peer_selection_random(excluded_indexes: List[int] = None)

This function simulates the random peer selection, which is the random selection of num_participants from a population of num_agents.

Parameters:

excluded_indexes (List[int]) – Optional. Default is None. If defined, certain agents can be excluded from the peer_selection process.

Returns:

participants – The agent indexes of the participants of the interaction.

Return type:

List[int]

peer_selection_random_exclusive_peer_groups(n_groups: int)

This function simulates the random peer selection, which is the random selection of num_participants from a population of num_agents. This is repeated for n_pairs times, and returns a list of participants lists. This function produces exclusive peer groups, meaning that it is not possible that one agent participates in more than one interaction.

Parameters:

n_groups (int) – Number of participant groups that shall be returned.

Returns:

lst_participants – The list of participant lists (agent indexes of the participants) of the interactions.

Return type:

List[List[int]]

peer_selection_random_non_exclusive_peer_groups(n_groups: int)

This function simulates the random peer selection, which is the random selection of num_participants from a population of num_agents. This is repeated for n_pairs times, and returns a list of participants lists. This function produces non-exclusive peer groups, meaning that it is possible that one agent participates in more than one interaction.

Parameters:

n_groups (int) – Number of participant groups that shall be returned.

Returns:

lst_participants – The list of participant lists (agent indexes of the participants) of the interactions.

Return type:

List[List[int]]

peer_selection_whole_population()

This function simulates the peer selection of all agents interacting with each other at the same time.

Parameters:

None –

Returns:

participants – The agent indexes of the participants of the interaction.

Return type:

List[int]

play_interaction(policy: Policy, participants: List[int])

This function performs one interaction, consisting out of decision making, outcome determinantion and transaction (of costs, urgencies, and karma balances exclusive overflow distribution and karma redistribution).

Parameters:

• policy (Policy) – The Karma policy that should be used to play in this interaction.

• participants (List[int]) – The list of participants of this interaction.

Raises:

Exception – In case the policy is invalid, an exception will be raised.

Return type:

None

reset(state: StateDistribution, steady_state_init: bool = True)

This function resets all internal variables of the simulator so that a restart of the simulation from the beginning is possible.

Parameters:

• state (StateDistribution) – The state distribution, that is used to reset the population in case steady_state_init is set to True.

• steady_state_init (bool) – Optional, Default: True. This will define whether population initialization for the simulation is as given by the initial parameters for the optimization (lst_init_types, lst_init_urgencies, lst_init_karmas), or the steady state computed by the optimizer will be used.

Return type:

None

Optimizer

class karma_game_library.Optimizer(game_parameters: GameParameters, hyper_lambda: float, hyper_dt: float, hyper_nu: float, func_prob_outcome: Callable, func_prob_karma_transition: Callable, func_prob_urgency_transition: Callable)

A class to provide functionality to iteratively optimize the agent policy.

hyper_lambda

Exponential scaling factor for policy perturbation.

Type:

float

hyper_dt

Stepwidth for state updates. Only values between 0.0 and 1.0 allowed.

Type:

float

hyper_nu

Stepwidth for policy updates. Only values between 0.0 and 1.0 allowed.

Type:

float

func_prob_outcome

This function returns the probability for the outcome given the actions.

Type:

Callable, (outcome, actions) -> (probability)

func_prob_karma_transition

This function returns the probability of karma_next given a prior karma, actions and outcome.

Type:

Callable, (karma_next, karma, actions, outcome) -> (probability)

func_prob_urgency_transition

This function returns the probability of urgency_next given a prior urgency and outcome and type.

Type:

Callable, (urgency_next, urgency, outcome, atype, set_urgencies) -> (probability)

v

“Distribution of agents’ actions” Intermediate result, returns probability of an action.

Type:

np.array [action]

gamma

“Probability of interaction outcome given bid” Intermediate result, returns the probability of an outcome given the action.

Type:

np.array [outcome][action]

kappa

“Probabilistic karma transition function” Intermediate result, returns the probability of karma_next given the prior karma, action and outcome.

Type:

np.array [karma_next][karma][action][outcome]

xi

“Immediate reward function” Intermediate result, returns the expected immediate reward (negative cost) for an participant with specific urgency, and action.

Type:

np.array [urgency][action]

rho

“Probabilistic state transition function” Intermediate result, returns the probability that participant of type ends up in next state urgency_next and karma_next given a prior urgency and karma and action.

Type:

np.array [type][urgency_next][karma_next][urgency][karma][action]

R

“Expected immediate reward” Imme result, returns the expected immediate reward (negative cost) for an participant of a specific type, urgency, karma.

Type:

np.array [type][urgency][karma]

P

“State transition probabilities” Intermediate result, returns the probability of an agent of specific type to end up in next state urgency_next, karma_next given his prior state urgency, karma

Type:

np.array [type][urgency_next][karma_next][urgency][karma]

V

“Expected infinite horizon reward” Intermediate result, returns the expected inifinite horizon reward (negative cost) for an agent of specific type, urgency, karma.

Type:

np.array [type][urgency][karma]

Q

“Single-stage deviation reward (from current policy)” Intermediate result, returns the expected reward (negative cost) for an participant with specific type, urgency, karma and action.

Type:

np.array [type][urgency][karma][action]

pi_pbp

“Perturbed best response policy” Intermediate result, represents a modified, potentially better policy.

Type:

np.array [type][urgency][karma][bid]

delta_state

The amount the state changed when compared to previous iteration. Can be used as an indicator for convergence.

Type:

float

delta_policy

The amount the policy changed when compared to previous iteration. Can be used as an indicator for convergence.

Type:

float

__init__(game_parameters: GameParameters, hyper_lambda: float, hyper_dt: float, hyper_nu: float, func_prob_outcome: Callable, func_prob_karma_transition: Callable, func_prob_urgency_transition: Callable)

This constructor initializes the PolicyOptimizer.

Parameters:

• game_parameters (GameParameters) – The simulation parameters.

• hyper_lambda (float) – Exponential scaling factor for policy perturbation.

• hyper_dt (float) – Stepwidth for state updates. Only values between 0.0 and 1.0 allowed.

• hyper_nu (float) – Stepwidth for policy updates. Only values between 0.0 and 1.0 allowed.

• func_prob_outcome (Callable, (outcome, actions) -> (probability)) – This function returns the probability for the outcome given the actions.

• func_prob_karma_transition (Callable, (outcome, actions) -> (probability)) – This function returns the probability of karma_next given a prior karma, actions and outcome.

• func_prob_urgency_transition (Callable, (urgency_next, urgency, outcome, atype, set_urgencies) -> (probability)) – This function returns the probability of urgency_next given a prior urgency and outcome.

Raises:

Exception – In case the input parameters are not plausible a specific exception will be raised.

Return type:

None.

compute_iteration(state: StateDistribution, policy: Policy)

This function updates the social state distribution and policy probability matrix according to an optimization algorithm. This algorithm is iterative, and shall be repeated iteratively until state and policy converge to a stationary Nash equilibrium.

Parameters:

• state (StateDistribution) – The social state distribution that should be optimized.

• policy (Policy) – The policy that should be optimized.

Raises:

Exception – In case the policy or state are invalid, an exception will be raised.

Returns:

• delta_state (float) – The absolute change to the state (can be used as an indicator for convergence).

• delta_policy (float) – The absolute change to the policy (can be used as an indicator for convergence).

Modelling Templates

Game Logic Functions

Cost

karma_game_library.templates.cost.cost.default(urgency: int, outcome: int) → float

The default cost function. Outcome=0 means resource not received, therefore costs created. Cost = urgency_level (urgency_level=0 has no costs)

Outcome

karma_game_library.templates.outcome.outcome.highest_bid(actions: List[int]) → List[int]

The highest bid (action) wins. Tiebreaker: random.

karma_game_library.templates.outcome.outcome.second_highest_bid(actions: List[int]) → List[int]

The second highest bid (action) wins. Tiebreaker: random.

Payment

karma_game_library.templates.payment.payment.bid_difference_to_peer(actions: List[int], outcomes: List[int]) → List[int]

The winner pays the difference of highest and second highest bid to the other peer. Only for Karma Games with exactly two participants per interaction.

karma_game_library.templates.payment.payment.bid_difference_to_society(actions: List[int], outcomes: List[int]) → List[int]

The winner pays the difference of highest and second highest bid to the society (Karma overflow).

karma_game_library.templates.payment.payment.highest_bid_to_peer(actions: List[int], outcomes: List[int]) → List[int]

The highest bid (action) is paid by the winner to the other peer. Only for Karma Games with exactly two participants per interaction.

karma_game_library.templates.payment.payment.highest_bid_to_society(actions: List[int], outcomes: List[int]) → List[int]

The highest bid (action) is paid by the winner to the society (Karma overflow).

karma_game_library.templates.payment.payment.one_to_peer(actions: List[int], outcomes: List[int]) → List[int]

The winner pays exactly one Karma unit to the other peer. Only for Karma Games with exactly two participants per interaction.

karma_game_library.templates.payment.payment.one_to_society(actions: List[int], outcomes: List[int]) → List[int]

The winner pays exactly one Karma unit to the society (Karma overflow).

karma_game_library.templates.payment.payment.second_highest_bid_to_peer(actions: List[int], outcomes: List[int]) → List[int]

The second highest bid (action) is paid by the winner to the other peer. Only for Karma Games with exactly two participants per interaction.

karma_game_library.templates.payment.payment.second_highest_bid_to_society(actions: List[int], outcomes: List[int]) → List[int]

The second highest bid (action) is paid by the winner to the society (Karma overflow).

Urgency Transition

karma_game_library.templates.urgency_transition.urgency_transition.random(atype: int, urgency: int, outcome: int, set_urgencies: Set) → int

This function transitions randomly from one urgency level to the next. This happens independent from agent type, urgency level, and outcome.

Overflow Distribution

karma_game_library.templates.overflow_distribution.overflow_distribution.none(pop_karmas: List[int], overflow: int) → List[int]

This function does not distribute any karma overflow.

karma_game_library.templates.overflow_distribution.overflow_distribution.random_group_each_one(pop_karmas: List[int], overflow: int) → List[int]

This function distributes the Karma overflow randomly two n agents, where each agent receives one unit of Karma.

karma_game_library.templates.overflow_distribution.overflow_distribution.random_individual_all(pop_karmas: List[int], overflow: int) → List[int]

This function distributes the whole Karma overflow to one randomly chosen individual.

Karma Redistribution

karma_game_library.templates.karma_redistribution.karma_redistribution.none(pop_karmas: List[int]) → List[int]

This function does not redistribute Karma.

Probabilistic Functions

Outcome

karma_game_library.templates.p_outcome.p_outcome.highest_bid(outcome: int, actions: List[int]) → float

The highest bid (action) wins. Tiebreaker: random.

karma_game_library.templates.p_outcome.p_outcome.second_highest_bid(outcome: int, actions: List[int]) → float

The second highest bid (action) wins. Tiebreaker: random.

Karma Transition

karma_game_library.templates.p_karma_transition.p_karma_transition.highest_bid_to_peer_no_redistribution(karma_next: int, karma: int, action: int, outcome: int, state_mat: ndarray[Any, dtype[ScalarType]], policy_mat: ndarray[Any, dtype[ScalarType]], game_parameters, gamma_mat: ndarray[Any, dtype[ScalarType]], v_mat: ndarray[Any, dtype[ScalarType]]) → float

This function returns the probability to reach a karma_next balance given a karma, action and outcome for the case that the highest bidding peer wins, pays the bid to the peer, and there is no Karma redistribution.

karma_game_library.templates.p_karma_transition.p_karma_transition.highest_bid_to_society_no_redistribution(karma_next: int, karma: int, action: int, outcome: int, state_mat: ndarray[Any, dtype[ScalarType]], policy_mat: ndarray[Any, dtype[ScalarType]], game_parameters, gamma_mat: ndarray[Any, dtype[ScalarType]], v_mat: ndarray[Any, dtype[ScalarType]]) → float

This function returns the probability to reach a karma_next balance given a karma, action and outcome for the case that the highest bidding peer wins, pays the bid to the society (Karma overflow), and there is no Karma redistribution.

Urgency Transition

karma_game_library.templates.p_urgency_transition.p_urgency_transition.random(urgency_next: int, urgency: int, outcome: int, atype: int, set_urgencies: Set) → float

This function assumes that the transition probability from one urgency level to another is random. It is completely independent from the agent type, urgency, and interaction outcome.

Visualization Utilities

karma_game_library.utils.visualizer.draw_distribution_bar(set_karmas: Set[int], values: Iterable[float], std_errs: Iterable[float] = None, bins: int = None)

This function draws a bar chart from a given vector of values using matplotlib.pyplot.

Parameters:

• set_karmas (Set[int]) – The set_policy_karmas.

• values (Iterable[float]) – The values to plot.

• std_errs (Iterable[float]) – Optional parameter, representing standard errors.

• bins (int) – Optional parameter, Default: None. If provided, only ‘bins’ ticks are displayed on the x axis.

Return type:

None

karma_game_library.utils.visualizer.draw_distribution_from_simulator(simulator, game_parameters, column: int, mode: str, bins: int = 15)

This function draw the interaction distribution from a given state distribution for a specific agent type. The karma distribution shows the average across all urgencies, if the urgency level is unspecified (None).

Parameters:

• simulator (Simulator) – The state distribution to draw from.

• game_parameters (GameParameters) – The game parameters used.

• column (int) – The column from the agent population. Each column is represented by following enumeration: TYPE_COL = 0, URGENCY_COL = 1, KARMA_COL = 2, CUM_COST_COL = 3, ENCOUNTERS_COL = 4.

• mode (str) – Which mode for the distribution. Possible options are: ‘unique’ to display how often all unique elements of the population occur; ‘histogram’ to display how often values occur in predefined bins.

• bins (int) – Optional. Default=15. This defines how many bins are used for the mode ‘histogram’.

Return type:

None

karma_game_library.utils.visualizer.draw_heatmap(matrix: ndarray[Any, dtype[ScalarType]], labels_x: List[str], labels_y: List[str], cmap: str = 'Blues', bins: int = None)

This function draws a heatmap from a given matrix of values using matplotlib.pyplot.

Parameters:

• matrix (npt.NDArray) – The matrix to be drawn.

• labels_x (List[str]) – The list of labels for the abscissa.

• labels_y (List[str]) – The list of labels for the ordinate.

• cmap (str) – Optional parameter, representing the colormap. Default is ‘Blues’.

Return type:

None

karma_game_library.utils.visualizer.draw_karma_distribution_from_simulator(simulator, game_parameters, bins: int = None)

This function draw the Karma distribution from a given state distribution for a specific agent type. The karma distribution shows the average across all urgencies, if the urgency level is unspecified (None).

Parameters:

• simulator (Simulator) – The state distribution to draw from.

• game_parameters (GameParameters) – The game parameters used.

• bins (int) – Optional parameter, Default: None. If provided, only ‘bins’ ticks are displayed on the x axis.

Return type:

None

karma_game_library.utils.visualizer.draw_karma_distribution_from_state(state, game_parameters, limit: int = None, atype: int = None, urgency: int = None, bins: int = None)

This function draw the Karma distirbution from a given state distribution for a specific agent type. The karma distribution shows the average across all urgencies, if the urgency level is unspecified (None).

Parameters:

• state (StateDistribution) – The state distribution to draw from.

• game_parameters (GameParameters) – The game parameters used.

• limit (int) – Optional. Default is None. If not defined, the full distribution is displayed, otherwise only until the limit. The last bar will then represent the karma balances greater or equal that value.

• atype (int) – Optional. Default is None. If not defined, the average across all types is displayed, otherwise for the agent type specifically.

• urgency (int) – Optional. Default is None. If not defined, the average across all urgencies is displayed, otherwise for the urgency level specifically.

• bins (int) – Optional parameter, Default: None. If provided, only ‘bins’ ticks are displayed on the x axis.

Return type:

None

karma_game_library.utils.visualizer.draw_karma_transition_heatmap_from_simulator(simulator, game_parameters)

This function draws a karma transition heatmap from a given state transition matrix of a simulation as average over types and urgencies using matplotlib.pyplot.

Parameters:

• simulator (Simulator) – The state_transition_distribution from a KarmaSimulationInstance.

• game_parameters (The game parameters) – The set_state_karmas.

Return type:

None

karma_game_library.utils.visualizer.draw_specific_policy(policy, game_parameters, atype, urgency, bins: int = None)

This function draws the probability of certain actions according to karma balances as heatmap for a specific type and urgency using matplotlib.pyplot.

Parameters:

• policy (Policy) – The policy used in simulation.

• game_parameters (GameParameters) –

• atype (int) – The specific agent type.

• urgency (int) – The specific agent urgency.

• bins (int) – Optional parameter, Default: None. If provided, only ‘bins’ ticks are displayed on the x axis.

Return type:

None

karma_game_library.utils.visualizer.render_gif_animation(lst_image_files: List[str], target_file: str, speed: int = 100, first_last_slow: bool = True)

This function reads static images from a list of image files, and stores all of them in an GIF animation.

Parameters:

• lst_image_files (List[str]) – A list with image files that shall be connected to a GIF animation.

• target_file (str) – The target file to store the GIF into.

• speed (int) – Optional, Defualt: 100. The time per image. The slower the faster the animation.

• first_last_slow (bool) – Optional, Default : True. This will repeat the first and the last image for ten times, so the animation does not directly run.

Return type:

None

Indices and tables

• Index

• Search Page