Squashed commit of the following:

commit 398321e
Author: Bruno Machado Pacheco <mpacheco.bruno@gmail.com>
Date:   Thu Feb 20 22:57:56 2025 +0000

    add tests for the new player write/read methods

commit 6a26ab4
Author: Bruno Machado Pacheco <mpacheco.bruno@gmail.com>
Date:   Thu Feb 20 22:55:10 2025 +0000

    found a bug in JuMP mof reading with start values

commit 8d6f9ca
Author: Bruno Machado Pacheco <mpacheco.bruno@gmail.com>
Date:   Thu Feb 20 22:12:03 2025 +0000

    implement player serialization and storage

commit 30262b8
Author: Bruno Machado Pacheco <mpacheco.bruno@gmail.com>
Date:   Thu Feb 20 21:26:34 2025 +0000

    refactor player as a parametric type of its payoff

Author: brunompacheco

Project.toml

@@ -5,6 +5,7 @@ version = "0.1.0"
 
 [deps]
 IterTools = "c8e1da08-722c-5040-9ed9-7db0dc04731e"
+JSON3 = "0f8b85d8-7281-11e9-16c2-39a750bddbf1"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 NormalGames = "4dc104ef-1e0c-4a09-93ea-14ddc8e86204"
 
@@ -13,6 +14,7 @@ NormalGames = {path = "Normal-form-games"}
 
 [compat]
 IterTools = "1.10.0"
+JSON3 = "1.14.1"
 JuMP = "1.23.6"
 Test = "1.11.0"
 

src/Game/Player.jl

@@ -1,53 +1,53 @@
-using JuMP
+using JuMP, JSON3
 
 abstract type AbstractPlayer end
 
 "A player in an IPG."
-struct Player <: AbstractPlayer
+struct Player{Payoff<:AbstractPayoff} <: AbstractPlayer
     "Strategy space."
     Xp::Model
     "Payoff function."
-    Πp::AbstractPayoff
+    Πp::Payoff
     "Player's index."
     p::Integer  # TODO: this could be Any, to allow for more general collections, e.g, string names
     # TODO: maybe I could just index everything relevant as a Dict{Player, T}?
 end
 "Initialize player with empty strategy space."
-function Player(Πp::AbstractPayoff, p::Integer)
-    return Player(Model(), Πp, p)
+function Player(Πp::Payoff, p::Integer) where Payoff <: AbstractPayoff
+    return Player{Payoff}(Model(), Πp, p)
 end
 
 "Check whether an optimizer has already been set for player."
-function has_optimizer(player::Player)
+function has_optimizer(player::AbstractPlayer)
     return ~(backend(player.Xp).state == JuMP.MOIU.NO_OPTIMIZER)
 end
 
 "Define the optimizer for player."
-function set_optimizer(player::Player, optimizer_factory)
+function set_optimizer(player::AbstractPlayer, optimizer_factory)
     JuMP.set_optimizer(player.Xp, optimizer_factory)
 end
 
 "Compute the utility that `player_p` receives from `player_k` when they play, resp., `xp` and `xk`."
-function bilateral_payoff(player_p::Player, xp::Vector{<:Union{Real,VariableRef}}, player_k::Player, xk::Vector{<:Real})
+function bilateral_payoff(player_p::Player{QuadraticPayoff}, xp::Vector{<:Union{Real,VariableRef}}, player_k::Player{QuadraticPayoff}, xk::Vector{<:Real})
     return bilateral_payoff(player_p.Πp, player_p.p, xp, player_k.p, xk)
 end
 "Compute the utility that `player_p` receives from `player_k` when they play, resp., `xp` and `σk`."
-function bilateral_payoff(player_p::Player, xp::Vector{<:Union{Real,VariableRef}}, player_k::Player, σk::DiscreteMixedStrategy)
+function bilateral_payoff(player_p::Player{QuadraticPayoff}, xp::Vector{<:Union{Real,VariableRef}}, player_k::Player{QuadraticPayoff}, σk::DiscreteMixedStrategy)
     return expected_value(xk -> bilateral_payoff(player_p.Πp, player_p.p, xp, player_k.p, xk), σk)
 end
 
 "Compute the payoff of player `player` given pure strategy profile `x`."
-function payoff(player::Player, x::Vector{<:Vector{<:Real}})
+function payoff(player::AbstractPlayer, x::Vector{<:Vector{<:Real}})
     return payoff(player.Πp, x, player.p)
 end
 "Compute the payoff of player `player` given mixed strategy profile `σ`."
-function payoff(player::Player, σ::Vector{DiscreteMixedStrategy})
+function payoff(player::AbstractPlayer, σ::Vector{DiscreteMixedStrategy})
     _payoff = x -> payoff(player, x)
     return expected_value(_payoff, σ)
 end
 
 "Compute `player`'s best response to the mixed strategy profile `σp`."
-function best_response(player::Player, σ::Vector{DiscreteMixedStrategy})
+function best_response(player::Player{QuadraticPayoff}, σ::Vector{DiscreteMixedStrategy})
     xp = all_variables(player.Xp)
 
     # TODO: No idea why this doesn't work
@@ -68,7 +68,7 @@ function best_response(player::Player, σ::Vector{DiscreteMixedStrategy})
 end
 
 "Solve the feasibility problem for a player, returning a feasible strategy."
-function find_feasible_pure_strategy(player::Player)
+function find_feasible_pure_strategy(player::AbstractPlayer)
     @objective(player.Xp, JuMP.MOI.FEASIBILITY_SENSE, 0)
 
     set_silent(player.Xp)
@@ -78,6 +78,47 @@ function find_feasible_pure_strategy(player::Player)
 end
 
 "Solve the feasibility problem of all players, returning a feasible profile."
-function find_feasible_pure_profile(players::Vector{Player})
+function find_feasible_pure_profile(players::Vector{<:AbstractPlayer})
     return [find_feasible_pure_strategy(player) for player in players]
-end
+end
+
+function save(player::Player{QuadraticPayoff}, filename::String)
+    # we need to ensure that the file is stored as a json, so we can add the payoff information
+    JuMP.write_to_file(player.Xp, filename; format = JuMP.MOI.FileFormats.FORMAT_MOF)
+
+    # TODO: this could be refactored as a payoff JSON-serialization method
+    # see https://quinnj.github.io/JSON3.jl/stable/#Struct-API
+    mof_json = JSON3.read(read(filename, String))
+    mof_json = copy(mof_json)  # JSON type is immutable
+
+    mof_json[:IPG__player_index] = player.p
+    mof_json[:IPG__payoff] = Dict(
+        :cp => player.Πp.cp,
+        :Qp => player.Πp.Qp,
+        # JSON3 cannot store matrices, it stores them as a flat vector
+        :Qp_shapes => [size(Qpk) for Qpk in player.Πp.Qp],
+    )
+
+    open(filename, "w") do file
+        JSON3.write(file, mof_json)
+    end
+end
+
+function load(filename::String)::Player{QuadraticPayoff}
+    Xp = JuMP.read_from_file(filename; format = JuMP.MOI.FileFormats.FORMAT_MOF)
+    
+    # see https://github.com/jump-dev/JuMP.jl/issues/3946
+    set_start_value.(all_variables(Xp), start_value.(all_variables(Xp)))
+
+    mof_json = JSON3.read(read(filename, String))
+
+    player_index = mof_json[:IPG__player_index]
+    payoff_data = mof_json[:IPG__payoff]
+    cp = copy(payoff_data[:cp])
+    flat_Qp = copy(payoff_data[:Qp])
+    Qp_shapes = copy(payoff_data[:Qp_shapes])
+
+    Qp = [reshape(flat_Qpk, Tuple(Qpk_shape)) for (flat_Qpk, Qpk_shape) in zip(flat_Qp, Qp_shapes)]
+
+    return Player{QuadraticPayoff}(Xp, QuadraticPayoff(cp, Qp), player_index)
+end

src/SGM/DeviationReaction.jl

@@ -1,6 +1,6 @@
 
 "Find a deviation from mixed profile `σ`."
-function find_deviation_best_response(players::Vector{Player}, σ::Vector{DiscreteMixedStrategy}; player_order=nothing, dev_tol=1e-3)::Tuple{Float64,Int64,Union{Nothing,Vector{Float64}}}
+function find_deviation_best_response(players::Vector{<:AbstractPlayer}, σ::Vector{DiscreteMixedStrategy}; player_order=nothing, dev_tol=1e-3)::Tuple{Float64,Int64,Union{Nothing,Vector{Float64}}}
     if isnothing(player_order)
         player_order = 1:length(players)
     end

src/SGM/Initialization.jl

@@ -1,5 +1,5 @@
 
-function initialize_strategies_feasibility(players::Vector{Player})
+function initialize_strategies_feasibility(players::Vector{<:AbstractPlayer})
     S_X = [Vector{Vector{Float64}}() for _ in players]
     for player in players
         xp_init = start_value.(all_variables(player.Xp))
@@ -16,7 +16,7 @@ function initialize_strategies_feasibility(players::Vector{Player})
     return S_X
 end
 
-function initialize_strategies_player_alone(players::Vector{Player})
+function initialize_strategies_player_alone(players::Vector{<:AbstractPlayer})
     S_X = [Vector{Vector{Float64}}() for _ in players]
 
     # mixed profile that simulates players being alone (all others play 0)

src/SGM/PlayerOrder.jl

@@ -1,21 +1,21 @@
 
-function get_player_order_fixed(players::Vector{Player}, iter::Integer, Σ_S::Vector{Vector{DiscreteMixedStrategy}}, payoff_improvements::Vector{<:Tuple{<:Integer,<:Real}})
+function get_player_order_fixed(players::Vector{<:AbstractPlayer}, iter::Integer, Σ_S::Vector{Vector{DiscreteMixedStrategy}}, payoff_improvements::Vector{<:Tuple{<:Integer,<:Real}})
     return keys(players)
 end
 
-function get_player_order_fixed_ascending(players::Vector{Player}, iter::Integer, Σ_S::Vector{Vector{DiscreteMixedStrategy}}, payoff_improvements::Vector{<:Tuple{<:Integer,<:Real}})
+function get_player_order_fixed_ascending(players::Vector{<:AbstractPlayer}, iter::Integer, Σ_S::Vector{Vector{DiscreteMixedStrategy}}, payoff_improvements::Vector{<:Tuple{<:Integer,<:Real}})
     return sort(keys(players))
 end
 
-function get_player_order_fixed_descending(players::Vector{Player}, iter::Integer, Σ_S::Vector{Vector{DiscreteMixedStrategy}}, payoff_improvements::Vector{<:Tuple{<:Integer,<:Real}})
+function get_player_order_fixed_descending(players::Vector{<:AbstractPlayer}, iter::Integer, Σ_S::Vector{Vector{DiscreteMixedStrategy}}, payoff_improvements::Vector{<:Tuple{<:Integer,<:Real}})
     return reverse(sort(keys(players)))
 end
 
-function get_player_order_random(players::Vector{Player}, iter::Integer, Σ_S::Vector{Vector{DiscreteMixedStrategy}}, payoff_improvements::Vector{<:Tuple{<:Integer,<:Real}})
+function get_player_order_random(players::Vector{<:AbstractPlayer}, iter::Integer, Σ_S::Vector{Vector{DiscreteMixedStrategy}}, payoff_improvements::Vector{<:Tuple{<:Integer,<:Real}})
     return shuffle(keys(players))
 end
 
-function get_player_order_by_last_deviation(players::Vector{Player}, iter::Integer, Σ_S::Vector{Vector{DiscreteMixedStrategy}}, payoff_improvements::Vector{<:Tuple{<:Integer,<:Real}})
+function get_player_order_by_last_deviation(players::Vector{<:AbstractPlayer}, iter::Integer, Σ_S::Vector{Vector{DiscreteMixedStrategy}}, payoff_improvements::Vector{<:Tuple{<:Integer,<:Real}})
     iterations_since_last_deviation = Dict(player.p => length(payoff_improvements) for player in players)
 
     for i in 0:length(payoff_improvements)-1

src/SGM/SGM.jl

@@ -4,7 +4,7 @@ include("PlayerOrder.jl")
 include("DeviationReaction.jl")
 include("Initialization.jl")
 
-function SGM(players::Vector{Player}, optimizer_factory; max_iter=100, dev_tol=1e-3)
+function SGM(players::Vector{<:AbstractPlayer}, optimizer_factory; max_iter=100, dev_tol=1e-3)
     # set `optimizer_factory` the optimizer for each player that doesn't have one yet
     for player in players
         # check whether an optimizer has already been set to player

src/SGM/SampledGame/SampledGame.jl

@@ -1,6 +1,6 @@
 
 "Compute polymatrix for normal form game from sample of strategies."
-function get_polymatrix(players::Vector{Player}, S_X::Vector{<:Vector{<:Vector{<:Real}}})
+function get_polymatrix(players::Vector{<:AbstractPlayer}, S_X::Vector{<:Vector{<:Vector{<:Real}}})
     polymatrix = Dict{Tuple{Integer, Integer}, Matrix{Float64}}()
 
     # compute utility of each player `p` using strategy `i_p` against player `k` using strategy `i_k`
@@ -32,14 +32,14 @@ mutable struct SampledGame
     S_X::Vector{Vector{Vector{Float64}}}  # sample of strategies (finite subset of the strategy space X)
     normal_game::NormalGames.NormalGame
 end
-function SampledGame(players::Vector{Player}, S_X::Vector{<:Vector{<:Vector{<:Real}}})
+function SampledGame(players::Vector{<:AbstractPlayer}, S_X::Vector{<:Vector{<:Vector{<:Real}}})
     payoff_polymatrix = get_polymatrix(players, S_X)
     normal_game = NormalGames.NormalGame(length(players), length.(S_X), payoff_polymatrix)
 
     return SampledGame(S_X, normal_game)
 end
 
-function add_new_strategy!(sampled_game::SampledGame, players::Vector{Player}, new_xp::Vector{<:Real}, p::Integer)
+function add_new_strategy!(sampled_game::SampledGame, players::Vector{<:AbstractPlayer}, new_xp::Vector{<:Real}, p::Integer)
     # first part is easy, just add the new strategy to the set
     push!(sampled_game.S_X[p], new_xp)
 

test/runtests.jl

@@ -13,6 +13,43 @@ using Test
         @test expected_value(sum, σp) == 1.0
     end
 
+    @testset "Player serialization" begin
+        using JuMP, SCIP
+
+        X1 = Model()
+        @variable(X1, x1, start=10.0)
+        @constraint(X1, x1 >= 0)
+
+        player = Player(X1, QuadraticPayoff(0, [2, 1]), 1)
+
+        filename = "test_player.json"
+        IPG.save(player, filename)
+        loaded_player = IPG.load(filename)
+
+        @test loaded_player.p == player.p
+        @test loaded_player.Πp.cp == player.Πp.cp
+        @test loaded_player.Πp.Qp == player.Πp.Qp
+
+        # test strategy space
+        X1 = player.Xp
+        loaded_X1 = loaded_player.Xp
+
+        set_optimizer(X1, SCIP.Optimizer)
+        set_optimizer(loaded_X1, SCIP.Optimizer)
+
+        set_silent(X1)
+        optimize!(X1)
+
+        set_silent(loaded_X1)
+        optimize!(loaded_X1)
+
+        @test value.(all_variables(X1)) == value.(all_variables(loaded_X1))
+        @test objective_value(X1) == objective_value(loaded_X1)
+
+        # cleanup
+        rm(filename)
+    end
+
     @testset "Example 5.3" begin
         using SCIP