Utilities

NormalFormGame([T], p)

Construct a NormalFormGame (of eltype T if specified) from a PayoffVector p.

Examples

julia> nums_actions = (3, 2);

julia> payoffs = collect(1:12);

julia> @show payoffs;
payoffs = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]

julia> p = GameTheory.GAMPayoffVector(nums_actions, payoffs);

julia> NormalFormGame(p)
3×2 NormalFormGame{2, Int64}:
 (1, 7)  (4, 10)
 (2, 8)  (5, 11)
 (3, 9)  (6, 12)

julia> p = GameTheory.NFGPayoffVector(nums_actions, payoffs);

julia> NormalFormGame(p)
3×2 NormalFormGame{2, Int64}:
 (1, 2)  (7, 8)
 (3, 4)  (9, 10)
 (5, 6)  (11, 12)

gam_string(g)

Return the GameTracer .gam representation of the game g as a string. See write_gam for the requirement on the element type of g.

Arguments

• g::Union{NormalFormGame,PayoffVector} : Game to write.

Returns

• ::String : The .gam representation of g.

Examples

julia> g = NormalFormGame(Player([3 1; 0 4; 2 5]), Player([2 6 1; 3 0 4]));

julia> gam_string(g)
"2\n3 2\n\n3 0 2 1 4 5 2 6 1 3 0 4\n"

julia> print(gam_string(g))
2
3 2

3 0 2 1 4 5 2 6 1 3 0 4

nfg_string(g)

Return the Gambit .nfg representation of the game g as a string. See write_nfg for the requirement on the element type of g.

Arguments

• g::Union{NormalFormGame,PayoffVector} : Game to write.

Returns

• ::String : The .nfg representation of g.

Examples

julia> g = NormalFormGame(Player([3 1; 0 4; 2 5]), Player([2 6 1; 3 0 4]));

julia> print(nfg_string(g))
NFG 1 R "" { "1" "2" } { 3 2 }

3 2 0 6 2 1 1 3 4 0 5 4

parse_gam([T], text)

Parse the string text in the GameTracer .gam format and return the game as a NormalFormGame. See read_gam for the meaning of T and for reading from a stream or a file.

Arguments

• T::Type : Element type of the payoffs, where T<:Real. If omitted, Int when every payoff in text is written as an integer (BigInt if one does not fit in Int), Rational{BigInt} when the others are written as rationals n/d, and Float64 otherwise.
• text::AbstractString : String in the .gam format.

Returns

• ::NormalFormGame{N,T} : The game described by text.

Examples

julia> s = """
       2
       3 2

       3 2 0 3 5 6 3 2 3 2 6 1
       """;

julia> parse_gam(s)
3×2 NormalFormGame{2, Int64}:
 (3, 3)  (3, 2)
 (2, 2)  (5, 6)
 (0, 3)  (6, 1)

julia> parse_gam(Float64, s)
3×2 NormalFormGame{2, Float64}:
 (3.0, 3.0)  (3.0, 2.0)
 (2.0, 2.0)  (5.0, 6.0)
 (0.0, 3.0)  (6.0, 1.0)

parse_nfg([T], text)

Parse the string text in the Gambit .nfg format and return the game as a NormalFormGame. See read_nfg for the meaning of T and for reading from a stream or a file.

Arguments

• T::Type : Element type of the payoffs, where T<:Real. If omitted, it is determined as in read_nfg.
• text::AbstractString : String in the .nfg format.

Returns

• ::NormalFormGame{N,T} : The game described by text.

Examples

julia> s = """
       NFG 1 R "" { "1" "2" } { 3 2 }

       3 2 0 6 2 1 1 3 4 0 5 4
       """;

julia> parse_nfg(s)
3×2 NormalFormGame{2, Int64}:
 (3, 2)  (1, 3)
 (0, 6)  (4, 0)
 (2, 1)  (5, 4)

read_gam([T], io)
read_gam([T], path)

Read a normal form game in the GameTracer .gam format from the stream io or the file at path, and return it as a NormalFormGame. See GAMPayoffVector for the ordering of the payoffs in the format, and parse_gam for reading from a string.

Arguments

• T::Type : Element type of the payoffs, where T<:Real. If omitted, Int when every payoff in the input is written as an integer (BigInt if one does not fit in Int), Rational{BigInt} when the others are written as rationals n/d, and Float64 otherwise.
• io::IO : Input stream.
• path::AbstractString : Path to the file to read.

Returns

• ::NormalFormGame{N,T} : The game described by the input.

Examples

julia> g = NormalFormGame(Player([3 1; 0 4; 2 5]), Player([2 6 1; 3 0 4]));

julia> path = tempname();

julia> write_gam(path, g)

julia> read_gam(path)
3×2 NormalFormGame{2, Int64}:
 (3, 2)  (1, 3)
 (0, 6)  (4, 0)
 (2, 1)  (5, 4)

julia> read_gam(Float64, path)
3×2 NormalFormGame{2, Float64}:
 (3.0, 2.0)  (1.0, 3.0)
 (0.0, 6.0)  (4.0, 0.0)
 (2.0, 1.0)  (5.0, 4.0)

A file at a URL can be read with read_gam(Downloads.download(url)).

read_nfg([T], io)
read_nfg([T], path)

Read a normal form game in the Gambit .nfg format from the stream io or the file at path, and return it as a NormalFormGame. Both the payoff version and the outcome version of the format are read; the title, the names of the players, of the actions, and of the outcomes, and the comment are ignored. See ProfileMajor for the ordering of the payoffs in the format, and parse_nfg for reading from a string.

Arguments

• T::Type : Element type of the payoffs, where T<:Real. If omitted, Int when every payoff in the input is written as an integer (BigInt if one does not fit in Int), Rational{BigInt} when the others are written as rationals n/d, and Float64 otherwise.
• io::IO : Input stream.
• path::AbstractString : Path to the file to read.

Returns

• ::NormalFormGame{N,T} : The game described by the input.

Examples

julia> g = NormalFormGame(Player([3 1; 0 4; 2 5]), Player([2 6 1; 3 0 4]));

julia> path = tempname();

julia> write_nfg(path, g)

julia> read_nfg(path)
3×2 NormalFormGame{2, Int64}:
 (3, 2)  (1, 3)
 (0, 6)  (4, 0)
 (2, 1)  (5, 4)

julia> read_nfg(Float64, path)
3×2 NormalFormGame{2, Float64}:
 (3.0, 2.0)  (1.0, 3.0)
 (0.0, 6.0)  (4.0, 0.0)
 (2.0, 1.0)  (5.0, 4.0)

A file at a URL can be read with read_nfg(Downloads.download(url)).

write_gam(io, g)
write_gam(path, g)

Write the game g to the stream io or the file at path in the GameTracer .gam format. Each payoff is written with print, a Rational as n/d; hence the element type of g must be an Integer, an AbstractFloat, or a Rational type; convert first otherwise, e.g. with NormalFormGame(Float64, g). See gam_string for writing to a string.

Arguments

• io::IO : Output stream.
• path::AbstractString : Path to the file to write; an existing file is overwritten.
• g::Union{NormalFormGame,PayoffVector} : Game to write. A PayoffVector of any layout is accepted; one that is not player-major is converted first.

Examples

julia> g = NormalFormGame(Player([3 1; 0 4; 2 5]), Player([2 6 1; 3 0 4]));

julia> write_gam(stdout, g)
2
3 2

3 0 2 1 4 5 2 6 1 3 0 4

julia> write_gam("game.gam", g)

write_nfg(io, g)
write_nfg(path, g)

Write the game g to the stream io or the file at path in the payoff version of the Gambit .nfg format, with an empty title and the players named "1", ..., "N". Each payoff is written with print, a Rational as n/d; hence the element type of g must be an Integer, an AbstractFloat, or a Rational type. See nfg_string for writing to a string.

Arguments

• io::IO : Output stream.
• path::AbstractString : Path to the file to write; an existing file is overwritten.
• g::Union{NormalFormGame,PayoffVector} : Game to write. A PayoffVector of any layout is accepted; one that is not profile-major is converted first.

Examples

julia> g = NormalFormGame(Player([3 1; 0 4; 2 5]), Player([2 6 1; 3 0 4]));

julia> write_nfg(stdout, g)
NFG 1 R "" { "1" "2" } { 3 2 }

3 2 0 6 2 1 1 3 4 0 5 4

julia> write_nfg("game.nfg", g)

GAMPayoffVector{N,T}

Alias for PayoffVector{PlayerMajor,N,T}: payoff values are ordered as in the GameTracer .gam format:

1. Player-major blocks: player 1, ..., player N.
2. Within each block, action profiles are ordered with player 1 varying fastest, then player 2, ..., player N (i.e., column-major order).

NFGPayoffVector{N,T}

Alias for PayoffVector{ProfileMajor,N,T}: payoff values are ordered as in the Gambit .nfg format:

1. Profile-major blocks: action profiles are ordered with player 1 varying fastest, then player 2, ..., player N (i.e., column-major order).
2. Within each block, the payoffs to player 1, ..., player N.

PayoffLayout

Abstract supertype of the singleton types that specify the ordering of the payoff values in a PayoffVector.

PayoffVector{L,N,T}

Intermediate representation that stores the payoffs of an N-player game in a single flat vector of eltype T, ordered according to the layout L<:PayoffLayout. See GAMPayoffVector and NFGPayoffVector for the two layouts available.

Viewed as a prod(nums_actions) × N matrix whose [a, i] entry is the payoff to player i at the a-th action profile in column-major order, payoffs is that matrix vectorized in column-major order for PlayerMajor, and in row-major order for ProfileMajor.

Fields

• nums_actions::NTuple{N,Int} : Tuple of the numbers of actions, one for each player.
• payoffs::Vector{T} : Vector storing payoffs in the order specified by L.

PayoffVector{L}([T], p)

Construct a PayoffVector of layout L (and of eltype T if specified) from a PayoffVector p of possibly another layout. The payoffs are copied.

Examples

julia> p = GameTheory.GAMPayoffVector((3, 2), collect(1:12));

julia> p_nfg = GameTheory.NFGPayoffVector(p);

julia> @show p_nfg.payoffs;
p_nfg.payoffs = [1, 7, 2, 8, 3, 9, 4, 10, 5, 11, 6, 12]

PayoffVector{L}([T], g)

Construct a PayoffVector of layout L (and of eltype T if specified) from a NormalFormGame g. GAMPayoffVector([T], g) and NFGPayoffVector([T], g) are the versions for the two layouts.

Examples

julia> player1 = Player([1 4; 2 5; 3 6]);

julia> player2 = Player([7 8 9; 10 11 12]);

julia> g = NormalFormGame(player1, player2)
3×2 NormalFormGame{2, Int64}:
 (1, 7)  (4, 10)
 (2, 8)  (5, 11)
 (3, 9)  (6, 12)

julia> p = GameTheory.GAMPayoffVector(g);

julia> @show p.payoffs;
p.payoffs = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]

julia> p = GameTheory.NFGPayoffVector(g);

julia> @show p.payoffs;
p.payoffs = [1, 7, 2, 8, 3, 9, 4, 10, 5, 11, 6, 12]

PlayerMajor <: PayoffLayout

Player-major ordering, as in the GameTracer .gam format: all the payoffs of player 1 come first, then those of player 2, and so on. Within each block, action profiles are ordered with player 1 varying fastest, then player 2, ..., player N (i.e., column-major order).

ProfileMajor <: PayoffLayout

Profile-major ordering, as in the Gambit .nfg format: the payoffs of players 1, ..., N at the first action profile come first, then those at the second action profile, and so on. Action profiles are ordered with player 1 varying fastest, then player 2, ..., player N (i.e., column-major order).

_player_block(p, i)

Return a view of p.payoffs holding the payoffs to player i, as an N-dim array indexed by the action profile (a_1, ..., a_N). This is the only place where the layout L matters; no copy is made.

clp_optimizer_silent()

Function that returns a Clp.Optimizer instance in silent mode.