Base Types and Methods

Action{T}

Alias for Union{PureAction,MixedAction{T}} where T<:Real.

ActionProfile{N,T}

Alias for Union{PureActionProfile{N,T},MixedActionProfile{N,T}}.

MixedAction{T}

Alias for Vector{T} where T<:Real.

MixedActionProfile{N,T}

Alias for NTuple{N,MixedAction{T}} where T<:Real.

PureAction

Alias for Integer.

PureActionProfile{N,T}

Alias for NTuple{N,T} where T<:PureAction.

BROptions

Struct to contain options for best_response.

Fields

• tol::Real=1e-8 : Tolerance level.
• tie_breaking::Symbol=:smallest : :smallest or :random.
• rng::AbstractRNG=GLOBAL_RNG : Random number generator.

NormalFormGame{N,T}

Type representing an N-player normal form game.

Fields

• players::NTuple{N,Player{N,T<:Real}} : Tuple of Player instances.
• nums_actions::NTuple{N,Int} : Tuple of the numbers of actions, one for each player.

NormalFormGame(players)

Constructor of an N-player NormalFormGame with a vector of N Player instances.

Arguments

• players::Vector{Player} : Vector of Player instances.

NormalFormGame(payoffs)

Construct an N-player NormalFormGame for N>=2 with an array payoffs of M=N+1 dimensions, where payoffs[a_1, a_2, ..., a_N, :] contains a profile of N payoff values.

Arguments

• payoffs::Array{T<:Real} : Array with ndims=N+1 containing payoff profiles.

NormalFormGame(payoffs)

Construct an N-player NormalFormGame with an N-dimensional array payoffs of vectors, where payoffs[a_1, a_2, ..., a_N] contains a vector of N payoff values, one for each player, for the action profile (a_1, a_2, ..., a_N).

Arguments

• payoffs::Array{AbstractVector{T<:Real}} : Array with ndims=N containing payoff profiles as vectors.

NormalFormGame(payoffs)

Construct a symmetric 2-player NormalFormGame with a square matrix.

Arguments

• payoffs::Matrix{T<:Real} : Square matrix representing each player's payoff matrix.

NormalFormGame([T=Float64], nums_actions)

Constructor of an N-player NormalFormGame, consisting of payoffs all 0.

Arguments

• T::Type : Type of payoff values; defaults to Float64 if not specified.
• nums_actions::NTuple{N,Int} : Numbers of actions of the N players.

NormalFormGame(T, g)

Convert g into a new NormalFormGame instance with eltype T.

Arguments

• T::Type
• g::NormalFormGame

Returns

• ::NormalFormGame : NormalFormGame instance with eltype T.

NormalFormGame(players)

Constructor of an N-player NormalFormGame with a tuple of N Player instances.

Arguments

• players::NTuple{N,Player} : Tuple of Player instances.

NormalFormGame(players...)

Constructor of an N-player NormalFormGame with N Player instances.

Arguments

• players::Player{N,T}... : N Player instances

Examples

# p1, p2, and p3 are all of type `Player{3,T}` for some `T`
NormalFormGame(p1, p2, p3)

Player{N,T}

Type representing a player in an N-player normal form game.

Fields

• payoff_array::Array{T<:Real} : Array representing the player's payoff function.

Player(T, player)

Convert player into a new Player instance with eltype T.

Arguments

• T::Type
• player::Player

Returns

• ::Player : Player instance with eltype T.

best_response(player, opponents_actions, options)

Return a best response action to opponents_actions with options as specified by a BROptions instance options.

best_response(player, opponents_actions, payoff_perturbation)

Return the perturbed best response to opponents_actions.

Arguments

• player::Player : Player instance.
• opponents_actions::Union{Action,ActionProfile,Nothing} : Profile of N-1 opponents' actions. If N=2, then it must be a vector of reals (in which case it is treated as the opponent's mixed action) or a scalar of integer (in which case it is treated as the opponent's pure action). If N>2, then it must be a tuple of N-1 integers (pure actions) or N-1 vectors of reals (mixed actions). (For the degenerate case N=1, it must be nothing.)
• payoff_perturbation::Vector{Float64} : Vector of length equal to the number of actions of the player containing the values ("noises") to be added to the payoffs in determining the best response.

Returns

• ::Int : Best response action.

best_response([rng=GLOBAL_RNG], player, opponents_actions;
              tie_breaking=:smallest, tol=1e-8)

Return a best response action to opponents_actions.

Arguments

• rng::AbstractRNG=GLOBAL_RNG : Random number generator; relevant only with tie_breaking=:random.
• player::Player : Player instance.
• opponents_actions::Union{Action,ActionProfile,Nothing} : Profile of N-1 opponents' actions. If N=2, then it must be a vector of reals (in which case it is treated as the opponent's mixed action) or a scalar of integer (in which case it is treated as the opponent's pure action). If N>2, then it must be a tuple of N-1 integers (pure actions) or N-1 vectors of reals (mixed actions). (For the degenerate case N=1, it must be nothing.)
• tie_breaking::Symbol : Control how to break a tie (see Returns for details).
• tol::Real : Tolerance to be used to determine best response actions.

Returns

• ::Int : If tie_breaking=:smallest, returns the best response action with the smallest index; if tie_breaking=:random, returns an action randomly chosen from the best response actions.

best_responses(player, opponents_actions; tol=1e-8)

Return all the best response actions to opponents_actions.

Arguments

• player::Player : Player instance.
• opponents_actions::Union{Action,ActionProfile,Nothing} : Profile of N-1 opponents' actions. If N=2, then it must be a vector of reals (in which case it is treated as the opponent's mixed action) or a scalar of integer (in which case it is treated as the opponent's pure action). If N>2, then it must be a tuple of N-1 integers (pure actions) or N-1 vectors of reals (mixed actions). (For the degenerate case N=1, it must be nothing.)
• tol::Real : Tolerance to be used to determine best response actions.

Returns

• best_responses::Vector{Int} : Vector containing all the best response actions.

delete_action(g, action, player_idx)

Return a new NormalFormGame instance with the action(s) specified by action deleted from the action set of the player specified by player_idx.

Arguments

• g::NormalFormGame : NormalFormGame instance.
• action::Union{PureAction, AbstractVector{<:PureAction}} : The action(s) to be deleted.
• player_idx::Integer : Index of the player to delete action(s) for.

Returns

• ::NormalFormGame : NormalFormGame instance with the action(s) deleted as specified.

delete_action(player, action[, player_idx=1])

Return a new Player instance with the action(s) specified by action deleted from the action set of the player specified by player_idx.

Arguments

• player::Player : Player instance.
• action::Union{PureAction,AbstractVector{<:PureAction}}: The action(s) to be deleted.
• player_idx::Integer : Index of the player to delete action(s) for.

Returns

• ::Player : Player instance with the action(s) deleted as specified.

Examples

julia> player = Player([3 0; 0 3; 1 1])
3×2 Player{2, Int64}:
 3  0
 0  3
 1  1

julia> delete_action(player, 3)
2×2 Player{2, Int64}:
 3  0
 0  3

julia> delete_action(player, 1, 2)
3×1 Player{2, Int64}:
 0
 3
 1

dominated_actions(player; tol=1e-8,
                  lp_solver=GameTheory.highs_optimizer_silent)

Return a vector of actions that are strictly dominated by some mixed actions.

Arguments

• player::Player : Player instance.
• tol::Real : Tolerance level used in determining domination.
• lp_solver::Union{Type{<:MathOptInterface.AbstractOptimizer},Function} : Linear programming solver to be used internally. Pass a MathOptInterface.AbstractOptimizer type (such as HiGHS.Optimizer) if no option is needed, or a function (such as GameTheory.highs_optimizer_silent) to supply options.

Returns

• out::Vector{Int} : Vector of integers representing pure actions, each of which is strictly dominated by some mixed action.

is_best_response(player, own_action, opponents_actions; tol=1e-8)

Return true if own_action is a best response to opponents_actions.

Arguments

• player::Player : Player instance.
• own_action::PureAction : Own pure action (integer).
• opponents_actions::Union{Action,ActionProfile,Nothing} : Profile of N-1 opponents' actions. If N=2, then it must be a vector of reals (in which case it is treated as the opponent's mixed action) or a scalar of integer (in which case it is treated as the opponent's pure action). If N>2, then it must be a tuple of N-1 integers (pure actions) or N-1 vectors of reals (mixed actions). (For the degenerate case N=1, it must be nothing.)
• tol::Real : Tolerance to be used to determine best response actions.

Returns

• ::Bool : True if own_action is a best response to opponents_actions; false otherwise.

is_best_response(player, own_action, opponents_actions; tol=1e-8)

Return true if own_action is a best response to opponents_actions.

Arguments

• player::Player : Player instance.
• own_action::MixedAction : Own mixed action (vector of reals).
• opponents_actions::Union{Action,ActionProfile,Nothing} : Profile of N-1 opponents' actions. If N=2, then it must be a vector of reals (in which case it is treated as the opponent's mixed action) or a scalar of integer (in which case it is treated as the opponent's pure action). If N>2, then it must be a tuple of N-1 integers (pure actions) or N-1 vectors of reals (mixed actions). (For the degenerate case N=1, it must be nothing.)
• tol::Real : Tolerance to be used to determine best response actions.

Returns

• ::Bool : True if own_action is a best response to opponents_actions; false otherwise.

is_dominated(player, action; tol=1e-8,
             lp_solver=GameTheory.highs_optimizer_silent)

Determine whether action is strictly dominated by some mixed action.

Arguments

• player::Player : Player instance.
• action::PureAction : Integer representing a pure action.
• tol::Real : Tolerance level used in determining domination.
• lp_solver : Linear programming solver to be used internally. Pass a MathOptInterface.AbstractOptimizer type (such as HiGHS.Optimizer) if no option is needed, or a function (such as GameTheory.highs_optimizer_silent) to supply options.

Returns

• ::Bool : True if action is strictly dominated by some mixed action; false otherwise.

is_nash(g, action_profile; tol=1e-8)

Return true if action_profile is a Nash equilibrium.

Arguments

• g::NormalFormGame : Instance of N-player NormalFormGame.
• action_profile::ActionProfile : Tuple of N integers (pure actions) or N vectors of reals (mixed actions).
• tol::Real : Tolerance to be used to determine best response actions.

Returns

• ::Bool

is_nash(g, action; tol=1e-8)

Return true if action is a Nash equilibrium of a trivial game with 1 player.

Arguments

• g::NormalFormGame{1} : Instance of 1-player NormalFormGame.
• action::Action : Integer (pure action) or vector of reals (mixed action).
• tol::Float64 : Tolerance to be used to determine best response actions.

Returns

• ::Bool

is_pareto_dominant(g, action_profile)

Return true if action_profile is Pareto dominant for game g.

Arguments

• g::NormalFormGame : Instance of N-player NormalFormGame.
• action_profile::PureActionProfile : Tuple of N integers (pure actions).

Returns

• ::Bool

is_pareto_efficient(g, action_profile)

Return true if action_profile is Pareto efficient for game g.

Arguments

• g::NormalFormGame : Instance of N-player NormalFormGame.
• action_profile::PureActionProfile : Tuple of N integers (pure actions).

Returns

• ::Bool

payoff_profile_array(g)

Return an N-dimensional array of vectors, whose (a_1, ..., a_N)-entry contains a vector of N payoff values, one for each player, for the action profile (a_1, ..., a_N).

Arguments

• g::NormalFormGame : N-player NormalFormGame instance.

Returns

• ::Array{Vector,N} : Array of payoff profiles.

payoff_vector(player, opponents_actions)

Return a vector of payoff values for a Player in an N>2 player game, one for each own action, given a tuple of the opponents' pure actions.

Arguments

• player::Player : Player instance.
• opponents_actions::PureActionProfile : Tuple of N-1 opponents' pure actions.

Returns

• ::Vector : Payoff vector.

payoff_vector(player, opponent_action)

Return a vector of payoff values for a Player in a trivial game with 1 player, one for each own action.

Arguments

• player::Player{1} : Player instance.
• opponent_action::Nothing

Returns

• ::Vector : Payoff vector.

payoff_vector(player, opponent_action)

Return a vector of payoff values for a Player in a 2-player game, one for each own action, given the opponent's pure action.

Arguments

• player::Player{2} : Player instance.
• opponent_action::PureAction : Opponent's pure action (integer).

Returns

• ::Vector : Payoff vector.

payoff_vector(player, opponent_action)

Return a vector of payoff values for a Player in a 2-player game, one for each own action, given the opponent's mixed action.

Arguments

• player::Player{2} : Player instance.
• opponent_action::MixedAction : Opponent's mixed action (vector of reals).

Returns

• ::Vector : Payoff vector.

payoff_vector(player, opponents_actions)

Return a vector of payoff values for a Player in an N>2 player game, one for each own action, given a tuple of the opponents' mixed actions.

Arguments

• player::Player : Player instance.
• opponents_actions::MixedActionProfile : Tuple of N-1 opponents' mixed actions.

Returns

• ::Vector : Payoff vector.

pure2mixed(num_actions, action)

Convert a pure action to the corresponding mixed action.

Arguments

• num_actions::Integer : The number of the pure actions (= the length of a mixed action).
• action::PureAction : The pure action to convert to the corresponding mixed action.

Returns

• mixed_action::Vector{Float64} : The mixed action representation of the given pure action.