Merge pull request #4 from mitchphillipson/hdf5

Documentation

README.md

@@ -1,5 +1,8 @@
 # GamsStructure.jl
 
+
+[Very terse documentation](https://windc.wisc.edu/GamsStructure_Documentation/)
+
 Current Issues:
 
 1. ~~Getting indices in parameters is very slow, like 10X slower than a regular array. I think the issue

docs/make.jl

@@ -0,0 +1,24 @@
+using Documenter,GamsStructure
+
+
+
+const _PAGES = [
+    "Introduction" => ["index.md","elements.md","sets.md","parameters.md","universe.md"],
+    #"Sets" => ["sets/regions.md","sets/products.md","sets/sectors.md","sets/final_demand.md","sets/value_added.md"],
+    #"Mappings" => ["mappings/product_aggregation.md","mappings/sector_aggregation.md","mappings/g20_regions.md"],
+]
+
+makedocs(
+    sitename="GamsStructure.jl",
+    authors="WiNDC",
+    #format = Documenter.HTML(
+    #    # See https://github.com/JuliaDocs/Documenter.jl/issues/868
+    #    prettyurls = get(ENV, "CI", nothing) == "true",
+    #    analytics = "UA-44252521-1",
+    #    collapselevel = 1,
+    #    assets = ["assets/extra_styles.css"],
+    #    sidebar_sitename = false,
+    #),
+    strict = true,
+    pages = _PAGES
+)

docs/src/elements.md

@@ -0,0 +1,6 @@
+# Elements
+
+
+```@docs
+GamsElement
+```

docs/src/index.md

@@ -0,0 +1,3 @@
+# Introduction
+
+This package is under development and some things may change. 

docs/src/parameters.md

@@ -0,0 +1,10 @@
+# Parameters
+
+```@docs
+GamsParameter
+GamsParameter(base_path::String,parm_name::Symbol,sets::Tuple{Vararg{Symbol}},GU::GamsUniverse;description = "")
+GamsParameter(base_path::String,parm_name::Symbol,sets::Tuple{Vararg{Symbol}},GU::GamsUniverse,columns::Vector{Int};description = "")
+@GamsParameters(GU,block)
+@GamsParameters(GU,base_path,block)
+domain(P::GamsParameter)
+```

docs/src/sets.md

@@ -0,0 +1,13 @@
+# Sets
+
+
+```@docs
+GamsSet
+GamsSet(e::Tuple;description = "")   
+GamsSet(x::Vector{Tuple{Symbol,String}};description = "")
+GamsSet(e::Vector{Symbol};description = "")  
+GamsSet(base_path::String,set_name::Symbol;description = "",csv_description = true,aliases = [])
+GamsDomainSet(base_path::String,parm_name::Symbol,column::Int;description = "")
+@GamsSet
+@GamsSets
+```

docs/src/universe.md

@@ -0,0 +1,8 @@
+# Gams Universe
+
+
+```@docs
+GamsUniverse
+load_universe(path::String;to_load = [],nGU::GamsUniverse = GamsUniverse(),raw_text=true)
+unload(GU::GamsUniverse,path;to_unload = [],raw_text = true)
+```

src/GamsParameter.jl

@@ -4,7 +4,6 @@
 
 Load a GamsParameter from a file. 
 """
-
 function GamsParameter(base_path::String,parm_name::Symbol,sets::Tuple{Vararg{Symbol}},GU::GamsUniverse;description = "")
     df = CSV.File("$base_path/$parm_name.csv",stringtype=String,silencewarnings=true)
     s = [GU[c] for c in sets]
@@ -51,6 +50,18 @@ function GamsParameter(base_path::String,parm_name::Symbol,sets::Tuple{Vararg{Sy
     return out
 end
 
+""" 
+    @GamsParameters(GU,block)
+
+Create many empty parameters
+
+```
+@GamsParameters(GU,begin
+    :P, (:set_1,:set_2), "Description 1"
+    :X, (:set_1,), "Description 2"
+end)
+```
+"""
 macro GamsParameters(GU,block)
     GU = esc(GU)
     if !(isa(block,Expr) && block.head == :block)
@@ -72,7 +83,19 @@ macro GamsParameters(GU,block)
     return code
 end
 
+""" 
+    @GamsParameters(GU,base_path,block)
+
+Load parameters from a file. This will search `base_path\\name.csv`.
 
+
+```
+@GamsParameters(GU,begin
+    :P, (:set_1,:set_2), "Description 1"
+    :X, (:set_1,), "Description 2"
+end)
+```
+"""
 macro GamsParameters(GU,base_path,block)
     GU = esc(GU)
     base_path = esc(base_path)
@@ -104,6 +127,12 @@ macro GamsParameters(GU,base_path,block)
     return code
 end
 
+"""
+    domain(P::GamsParameter)
+
+Return the domain of the paramter P in the form of a vector of
+symbols.
+"""
 function domain(P::GamsParameter)
     return P.sets
 end

src/GamsSet.jl

@@ -1,16 +1,33 @@
+"""
+    GamsSet(x::Tuple...;description = "")
 
-
+GamsSet constructor for a tuple of the form (name,description) which
+will be made into GamsElements
+"""
 function GamsSet(x::Tuple...;description = "")
     return GamsSet([GamsElement(a,b) for (a,b) in x],description)
 end
 
+"""
+    GamsSet(x::Vector{Tuple{Symbol,String}};description = "")
+
+GamsSet constructor for a vector of tuples of the form (name,description) which
+will be made into GamsElements
+"""
 function GamsSet(x::Vector{Tuple{Symbol,String}};description = "")
     return GamsSet([GamsElement(a,b) for (a,b) in x],description)
 end
 
+"""
+    GamsSet(e::Vector{Symbol};description = "")   
+
+GamsSet constructor for a tuple of symbols which
+will be made into GamsElements with empty description.
+"""
 function GamsSet(e::Vector{Symbol};description = "")   
     return GamsSet([GamsElement(i,"") for i∈e],description)
 end
+
 """
     GamsSet(base_path::String,set_name::Symbol;description = "",csv_description = true))
 
@@ -130,6 +147,20 @@ function Base.length(X::GamsSet)
     return length(_active_elements(X))
 end
 
+
+"""
+    @GamsSet(GU,set_name,description,block)
+
+Macro to create a GamsSet. 
+
+```
+@GamsSet(GU,:i,"example set",begin
+    element_1, "Description 1"
+    element_2, "Description 2"
+    element_3, "Description 3"
+end)
+```
+"""
 macro GamsSet(GU,set_name,description,block)
     GU = esc(GU)
     set_name = esc(set_name)
@@ -152,7 +183,18 @@ macro GamsSet(GU,set_name,description,block)
     return :(add_set($GU,$set_name,GamsSet($elements,$description)))
 end
 
+"""
+    @GamsSets(GU,base_path,block)
+
+Load a collection of sets from a file. This will search for 
+the file `base_path\\name.csv` where name is the first
+entry of each line in the block.
 
+@GamsSets(GU,"sets",begin
+    :i, "Set 1"
+    :j, "Set 2"
+end)
+"""
 macro GamsSets(GU,base_path,block)
     GU = esc(GU)
     base_path = esc(base_path)

src/GamsUniverse.jl

@@ -1,5 +1,4 @@
 
-
 function add_set(GU::GamsUniverse,set_name::Symbol,set::GamsSet)
     GU.sets[set_name] = set
 end

src/io/load.jl

@@ -1,3 +1,20 @@
+
+"""
+    load_universe(path::String;
+                  to_load = [],
+                  nGU::GamsUniverse = GamsUniverse(),
+                  raw_text=true)
+
+Load a universe from the path.
+
+`path` - Universe location
+
+`to_load` - Load specific sets and parameters
+
+`nGU` - Add sets and parameters to an existing universe
+
+`raw_text` - Denote if a universe is saved as raw_text or in a binary format.
+"""
 function load_universe(path::String;to_load = [],nGU::GamsUniverse = GamsUniverse(),raw_text=true)
 
     #nGU = GamsUniverse()

src/io/unload.jl

@@ -5,7 +5,6 @@ function unload(S::GamsSet,path,set_name)
     writedlm("$path/$set_name.csv",out,",")
 end
 
-
 function unload(GU::GamsUniverse,P::GamsParameter,path,parm_name;raw_text=true)
 
     if raw_text
@@ -32,6 +31,22 @@ function unload(GU::GamsUniverse,P::GamsParameter,path,parm_name;raw_text=true)
 end
 
 
+"""
+    unload(GU::GamsUniverse,
+           path;
+           to_unload = [],
+           raw_text = true)
+
+Save a universe from the path.
+
+`GU` - The universe to save
+
+`path` - Universe location
+
+`to_unload` - Unload specific sets and parameters
+
+`raw_text` - Denote if a universe is saved as raw_text or in a binary format.
+"""
 function unload(GU::GamsUniverse,path;to_unload = [],raw_text = true)
     info = Dict()
     info[:set] = Dict()

src/structs.jl

@@ -1,7 +1,8 @@
 """
-    GamsElement(Name, Description, active = true)
+    GamsElement(name::union{Symbol,Tuple}, description::String="", active::Bool = true)
 
 A base struct for GamsSets. Each Name will be converted to a symbol. 
+The `active` keyword denotes if the element should appear in sets.
 """
 mutable struct GamsElement
     name::Union{Symbol,Tuple}
@@ -27,7 +28,23 @@ struct GamsSet
 end
 
 
+"""
+    GamsParameter{N}(GU,sets::Tuple{Vararg{Symbol}},value::Array{Float64,N},description::String)
+
+Container to hold parameters.
+
+Parameters can be indexed either by set name
+
+P[:set_1,:set_2]
+
+or by list of element names
+
+P[[:element_1,:element_2],[:e_1,:e_2]]
+
+or a mix of both
 
+P[:set_1,[:e_1]]
+"""
 struct GamsParameter{N}
     universe
     sets::Tuple{Vararg{Symbol}}
@@ -44,6 +61,23 @@ mutable struct GamsScalar
     GamsScalar(scalar::Number;description = "") = new(scalar,description)
 end
 
+
+"""
+    GamsUniverse(sets::Dict{Symbol,GamsSet}
+                parameters::Dict{Symbol,GamsParameter}
+                scalars::Dict{Symbol,GamsScalar})
+
+Note: scalars are going to be deprecated soon.
+
+Access objects like an array,
+```
+GU[:X]
+```
+This will return the X object, either a set or parameter. The search
+order is sets first, then parameters.
+
+Print a universe to see it's members and their descriptions.
+"""
 struct GamsUniverse
     sets::Dict{Symbol,GamsSet}
     parameters::Dict{Symbol,GamsParameter}