Merge 2b6a444 into 7ffab27

docs/README.md

@@ -17,9 +17,9 @@ There are three parts to generate the documentation.
 ### auto_doc_gen.jl
 
 Main part of documentation generation. It reads `src/Games.jl` to find
-out all the source files, and then write markdown files for each with
-the structure instructed by `docs/build/Structure`, which will be utilized
-by "Documenter.jl" later.
+out all the source files (include the ones used in submodules), and then
+write markdown files for each by the structure instructed by 
+`docs/build/Structure`, which will be utilized by "Documenter.jl" later.
 
 Note that the pattern of each page can be modified by changing the
 strings in `auto_doc_gen.jl` called `file_page` and `section_page`.
@@ -34,9 +34,10 @@ You may modify `Structure` to arrange the structure of the website to be generat
 For example:
 
 ```
-Order: Base Types and Methods, Computing Nash Equilibria, Repeated Games
-Base Types and Methods: normal_form_game, random
-Computing Nash Equilibria: pure_nash
+Order: Base Types and Methods, Game Generators, Computing Nash Equilibria, Repeated Games
+Base Types and Methods: normal_form_game
+Game Generators: random, generators/bimatrix_generators
+Computing Nash Equilibria: pure_nash, support_enumeration
 Repeated Games: repeated_game_util, repeated_game
 ```
 
@@ -45,8 +46,13 @@ generate a single page, or the name of the section you want to create. In the fo
 you need to declare which files are included in each section. Note that you should not
 put a comma or dot at the end of each line.
 
-It is not necessary to declare the structure of every file included in the Module.
-A separate single page will be generated for each file not mentioned in `Structure` automatically.
+It is not necessary to declare the structure of every file included in the main module.
+A separate single page will be generated for each file not mentioned in `Structure`
+automatically.
+
+However, you must specify the structure for files in each submodule. If you want to let
+a submodule to be a seperate section, please state this in `Structure`, with the submodule
+name as the section name.
 
 #### Homepage
 

docs/auto_doc_gen.jl

@@ -31,16 +31,34 @@ open(joinpath(path, "docs/Structure")) do f
     end
 end
 
+modules = String["Games"]
 # find all files used in Games.jl
 re = r"include\(\"(.*)\.jl\"\)"
 files = String[]
 
 open(joinpath(path, "src/Games.jl")) do f
     for match in eachmatch(re, readstring(f))
-        push!(files, match.captures[1])
+        # check if it is a submodule
+        if contains(match.captures[1], "/")
+            submodule_path = match.captures[1]
+            submodule_dir, submodule_name = split(submodule_path, "/")
+            # add submodule name to modules
+            push!(modules, "Games.$submodule_name")
+            # find all files used in submodules
+            open(joinpath(path, "src/$submodule_path.jl")) do f_submodule
+                for match_sub in eachmatch(re, readstring(f_submodule))
+                    file = match_sub.captures[1]
+                    push!(files, "$submodule_dir/$file")
+                end
+            end
+        else
+            push!(files, match.captures[1])
+        end
     end
 end
 
+module_names = join(modules, ", ")
+
 files_names = Dict{String, String}(
                 file => replace(join(map(ucfirst, split(file, "_")), " "),
                                 "Util",
@@ -53,7 +71,7 @@ if !ispath(joinpath(path, "docs/src/lib"))
     mkpath(joinpath(path, "docs/src/lib"))
 end
 
-# write .md for files not in section
+# write .md for files in main modules not in section
 for file in files
     if file in vcat(values(sections)...)
         continue
@@ -71,15 +89,15 @@ This is documentation for `$file.jl`.
 ## Exported
 
 ```@autodocs
-Modules = [Games]
+Modules = [$module_names]
 Pages   = ["$file.jl"]
 Private = false
 ```
 
 ## Internal
 
 ```@autodocs
-Modules = [Games]
+Modules = [$module_names]
 Pages   = ["$file.jl"]
 Public = false
 ```
@@ -99,19 +117,23 @@ for section_name in sections_names
     section_name_lower = replace(lowercase(section_name), " ", "_")
     section_file_list = join(map(i -> string("\"", i, ".jl\""),
                              section_files), ", ")
+    # include "Games.jl" in "Base Types and Methods"
+    if section_name == "Base Types and Methods"
+        section_file_list = string("\"Games.jl\", ", section_file_list)
+    end
     section_page = """
 # [$section_name](@id $section_name_lower)
 
 ## Exported
 ```@autodocs
-Modules = [Games]
+Modules = [$module_names]
 Pages   = [$section_file_list]
 Private = false
 ```
 
 ## Internal
 ```@autodocs
-Modules = [Games]
+Modules = [$module_names]
 Pages   = [$section_file_list]
 Public = false
 ```
@@ -126,7 +148,7 @@ index = """
 # Index
 
 ```@index
-modules = [Games]
+Modules = [$module_names]
 ```
 """
 

src/normal_form_game.jl

@@ -338,7 +338,7 @@ end
 """
     NormalFormGame{N,T}
 
-Class representing an N-player normal form game.
+Type representing an N-player normal form game.
 
 # Fields
 
@@ -359,7 +359,7 @@ function NormalFormGame(::Tuple{})  # To resolve definition ambiguity
 end
 
 """
-    NormalFormGame(T, nums_actions)
+    NormalFormGame([T=Float64], nums_actions)
 
 Constructor of an N-player NormalFormGame, consisting of payoffs all 0.
 
@@ -383,7 +383,7 @@ NormalFormGame(nums_actions::NTuple{N,Int}) where {N} =
 """
     NormalFormGame(players)
 
-Constructor of an N-player NormalFormGame.
+Constructor of an N-player NormalFormGame with a tuple of N Player instances.
 
 # Arguments
 
@@ -407,7 +407,7 @@ end
 """
     NormalFormGame(players)
 
-Constructor of an N-player NormalFormGame.
+Constructor of an N-player NormalFormGame with a vector of N Player instances.
 
 # Arguments
 
@@ -419,7 +419,7 @@ NormalFormGame(players::Vector{Player{N,T}}) where {N,T} =
 """
     NormalFormGame(players...)
 
-Constructor of an N-player NormalFormGame.
+Constructor of an N-player NormalFormGame with N Player instances.
 
 # Arguments
 

src/pure_nash.jl

@@ -12,11 +12,10 @@ will change in the future.
 
 - `nfg::NormalFormGame`: Instance of N-player NormalFormGame.
 - `ntofind::Inf`: Maximal number of pure nash action Nash
-  Equilibria to be found; default is `Inf`.
+  equilibria to be found; default is `Inf`.
 
 # Returns
-- `ne::Vector{NTuple{na,Int}}`: Vector of pure action Nash
-  Equilibria. `na` is the number of players.
+- `ne::Vector{NTuple{N,Int}}`: Vector of pure action Nash equilibria.
 """
 function pure_nash(nfg::NormalFormGame; ntofind=Inf)
     # Get number of players and their actions

src/repeated_game.jl

@@ -12,7 +12,7 @@ games, but could be extended to do more with some effort.
 """
     RepeatedGame{N,T}
 
-Class representing an N-player repeated game.
+Type representing an N-player repeated game.
 
 # Fields
 
@@ -26,6 +26,11 @@ struct RepeatedGame{N, T<:Real}
 end
 
 # Type alias for 2 player game
+"""
+    RepGame2
+
+Type representing a 2-player repeated game; alias for `RepeatedGame{2}`.
+"""
 const RepGame2 = RepeatedGame{2}
 
 #
@@ -55,6 +60,15 @@ RepeatedGame(p1::Player, p2::Player, delta::Float64) =
     unpack(rpd)
 
 Helper function that unpacks the elements of a repeated game.
+
+# Arguments
+
+- `rpd::RepeatedGame` : The repeated game.
+
+# Returns
+
+- `::Tuple{::NormalFormGame, ::Float64}` : A tuple containing the stage game
+  and the delta.
 """
 unpack(rpd::RepeatedGame) = (rpd.sg, rpd.delta)
 
@@ -86,6 +100,15 @@ best_dev_payoff_2(rpd::RepGame2, a1::Int) =
 Places `npts` equally spaced points along the 2 dimensional circle and returns
 the points with x coordinates in first column and y coordinates in second
 column.
+
+# Arguments
+
+- `npts::Int` : Number of points to be placed.
+
+# Returns
+
+- `pts::Array{Float64}(npts, 2)` : The array containing the coordinates of the
+  points.
 """
 function unitcircle(npts::Int)
     # Want our points placed on [0, 2π]
@@ -116,10 +139,10 @@ approximation of the convex value set of a 2 player repeated game.
 
 # Returns
 
-- `C::Array{Float64}(nH, 1)` : The array containing the hyperplane levels.
-- `H::Array{Float64}(nH, 2)` : The array containing the subgradients.
-- `Z::Array{Float64}(nH, 2)` : The array containing the extreme points of the
-  value set.
+- `C::Array{Float64}` : Array of length `nH` containing the hyperplane levels.
+- `H::Array{Float64}` : Array of shape `(nH, 2)` containing the subgradients.
+- `Z::Array{Float64}` : Array of shape `(nH, 2)` containing the extreme
+  points of the value set.
 """
 function initialize_sg_hpl(nH::Int, o::Vector{Float64}, r::Float64)
     # First create unit circle
@@ -155,10 +178,10 @@ an appropriate origin and radius.
 
 # Returns
 
-- `C::Array{Float64}(nH, 1)` : The array containing the hyperplane levels.
-- `H::Array{Float64}(nH, 2)` : The array containing the subgradients.
-- `Z::Array{Float64}(nH, 2)` : The array containing the extreme points of the
-  value set.
+- `C::Array{Float64}` : Array of length `nH` containing the hyperplane levels.
+- `H::Array{Float64}` : Array of shape `(nH, 2)` containing the subgradients.
+- `Z::Array{Float64}` : Array of shape `(nH, 2)` containing the extreme
+  points of the value set.
 """
 function initialize_sg_hpl(rpd::RepeatedGame, nH::Int)
     # Choose the origin to be mean of max and min payoffs
@@ -188,12 +211,12 @@ Initialize matrices for the linear programming problems.
 
 # Returns
 
-- `c::Array{Float64}(nH, 1)` : Vector used to determine which subgradient is
-  being used.
-- `A::Array{Float64}(nH, 2)` : Matrix with nH set constraints and to be filled
-  with 2 additional incentive compatibility constraints.
-- `b::Array{Float64}(nH, 1)` : Vector to be filled with the values for the
-  constraints.
+- `c::Array{Float64}` : Array of length `nH` used to determine which
+  subgradient should be used.
+- `A::Array{Float64}` : Array of shape `(nH, 2)` with nH set constraints and to
+  be filled with 2 additional incentive compatibility constraints.
+- `b::Array{Float64}` : Array of length `nH` to be filled with the values for
+  the constraints.
 """
 function initialize_LP_matrices(rpd::RepGame2, H)
     # Need total number of subgradients
@@ -224,14 +247,13 @@ Given a constraint w ∈ W, this finds the worst possible payoff for agent i.
 # Arugments
 
 - `rpd::RepGame2` : Two player repeated game.
-- `H::Array{Float64, 2}` : The subgradients used to approximate the value set.
-- `C::Array{Float64, 1}` : The array containing the hyperplane levels.
+- `H::Matrix{Float64}` : The subgradients used to approximate the value set.
+- `C::Vector{Float64}` : The array containing the hyperplane levels.
 - `i::Int` : The player of interest.
 - `lp_solver` : Allows users to choose a particular solver for linear
    programming problems. Options include ClpSolver(), CbcSolver(),
    GLPKSolverLP() and GurobiSolver(). By default, it choooses ClpSolver().
 
-
 # Returns
 
 - `out::Float64` : Worst possible payoff for player i.
@@ -293,7 +315,7 @@ outer hyperplane approximation described by Judd, Yeltekin, Conklin 2002.
 - `plib`: Allows users to choose a particular package for the geometry
   computations.
   (See [Polyhedra.jl](https://github.com/JuliaPolyhedra/Polyhedra.jl)
-  docs for more info). By default, it chooses to use SimplePolyhedraLibrary.
+  docs for more info). By default, it chooses to use `SimplePolyhedraLibrary`.
 - `lp_solver` : Allows users to choose a particular solver for linear
    programming problems. Options include ClpSolver(), CbcSolver(),
    GLPKSolverLP() and GurobiSolver(). By default, it choooses ClpSolver().

src/support_enumeration.jl

@@ -30,8 +30,8 @@ minus 1 such pairs. This should thus be used only for small games.
 
 # Returns
 
-- `::Vector{Tuple{Vector{Real}, Vector{Real}}}`: Mixed-action
-  Nash equilibria that are found.
+- `::Vector{NTuple{2,Vector{Real}}}`: Mixed-action Nash equilibria that are
+  found.
 """
 function support_enumeration(g::NormalFormGame{2})
 
@@ -79,13 +79,13 @@ Main body of `support_enumeration_task`.
 # Arguments
 
 - `c::Channel`: Channel to be binded with the support enumeration task.
-- `payoff_matrices::NTuple{2, Matrix{T}}`: Payoff matrices of player 1 and
-  player 2. T<:Real.
+- `payoff_matrices::NTuple{2,Matrix{T}}`: Payoff matrices of player 1 and
+  player 2, where `T<:Real`.
 
 # Puts
 
-- `Tuple{Vector{S},Vector{S}}`: Tuple of Nash equilibrium mixed actions.
-  `S` is Float if `T` is Int or Float, and Rational if `T` is Rational.
+- `NTuple{2,Vector{S}}`: Tuple of Nash equilibrium mixed actions, where `S` is
+  Float if `T` is Int or Float, and Rational if `T` is Rational.
 """
 function _support_enumeration_producer(c::Channel,
                                        payoff_matrices
@@ -127,8 +127,7 @@ function _support_enumeration_producer(c::Channel,
 end
 
 """
-    _indiff_mixed_action!(A, b, out, payoff_matrix,
-                          own_supp, opp_supp)
+    _indiff_mixed_action!(A, b, out, payoff_matrix, own_supp, opp_supp)
 
 Given a player's payoff matrix `payoff_matrix`, an array `own_supp`
 of this player's actions, and an array `opp_supp` of the opponent's
@@ -142,10 +141,10 @@ steps.
 
 # Arguments
 
-- `A::Matrix{T}`: Matrix used in intermediate steps. T<:Real.
-- `b::Vector{T}`: Vector used in intermediate steps. T<:Real.
+- `A::Matrix{T}`: Matrix used in intermediate steps, where `T<:Real`.
+- `b::Vector{T}`: Vector used in intermediate steps, where `T<:Real`.
 - `out::Vector{T}`: Vector to store the nonzero values of the
-  desired mixed action. T<:Real.
+  desired mixed action, where `T<:Real`.
 - `payoff_matrix::Matrix`: The player's payoff matrix.
 - `own_supp::Vector{Int}`: Vector containing the player's action indices.
 - `opp_supp::Vector{Int}`: Vector containing the opponent's action indices.
@@ -241,7 +240,7 @@ of the elements. `a` is modified in place.
 
 # Returns
 
-- `:::Vector{Int}`: Next k-array of `a`.
+- `::Vector{Int}`: Next k-array of `a`.
 
 # Examples