From 99ba76344ea6a5a413da6301a27109ad7dfb5390 Mon Sep 17 00:00:00 2001 From: mitchphillipson <mitch.phillipson@gmail.com> Date: Tue, 9 May 2023 10:33:09 -0500 Subject: [PATCH] Documentation --- README.md | 3 +++ docs/make.jl | 24 +++++++++++++++++++++++ docs/src/elements.md | 6 ++++++ docs/src/index.md | 3 +++ docs/src/parameters.md | 10 ++++++++++ docs/src/sets.md | 13 +++++++++++++ docs/src/universe.md | 8 ++++++++ src/GamsParameter.jl | 31 ++++++++++++++++++++++++++++- src/GamsSet.jl | 44 +++++++++++++++++++++++++++++++++++++++++- src/GamsUniverse.jl | 1 - src/io/load.jl | 17 ++++++++++++++++ src/io/unload.jl | 17 +++++++++++++++- src/structs.jl | 36 +++++++++++++++++++++++++++++++++- 13 files changed, 208 insertions(+), 5 deletions(-) create mode 100644 docs/make.jl create mode 100644 docs/src/elements.md create mode 100644 docs/src/index.md create mode 100644 docs/src/parameters.md create mode 100644 docs/src/sets.md create mode 100644 docs/src/universe.md diff --git a/README.md b/README.md index 29ec34c..4f7be80 100644 --- a/README.md +++ b/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 diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..5ece52b --- /dev/null +++ b/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 +) \ No newline at end of file diff --git a/docs/src/elements.md b/docs/src/elements.md new file mode 100644 index 0000000..76bd3eb --- /dev/null +++ b/docs/src/elements.md @@ -0,0 +1,6 @@ +# Elements + + +```@docs +GamsElement +``` \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..b484387 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,3 @@ +# Introduction + +This package is under development and some things may change. \ No newline at end of file diff --git a/docs/src/parameters.md b/docs/src/parameters.md new file mode 100644 index 0000000..b7cc5d2 --- /dev/null +++ b/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) +``` \ No newline at end of file diff --git a/docs/src/sets.md b/docs/src/sets.md new file mode 100644 index 0000000..c9ede36 --- /dev/null +++ b/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 +``` diff --git a/docs/src/universe.md b/docs/src/universe.md new file mode 100644 index 0000000..5b4f5e1 --- /dev/null +++ b/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) +``` \ No newline at end of file diff --git a/src/GamsParameter.jl b/src/GamsParameter.jl index 0022985..fcacc2c 100644 --- a/src/GamsParameter.jl +++ b/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 diff --git a/src/GamsSet.jl b/src/GamsSet.jl index d95fd8d..578b239 100644 --- a/src/GamsSet.jl +++ b/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) diff --git a/src/GamsUniverse.jl b/src/GamsUniverse.jl index f3d16da..308f2f7 100644 --- a/src/GamsUniverse.jl +++ b/src/GamsUniverse.jl @@ -1,5 +1,4 @@ - function add_set(GU::GamsUniverse,set_name::Symbol,set::GamsSet) GU.sets[set_name] = set end diff --git a/src/io/load.jl b/src/io/load.jl index ac28513..9dc7b01 100644 --- a/src/io/load.jl +++ b/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() diff --git a/src/io/unload.jl b/src/io/unload.jl index dd0a734..c0c0d68 100644 --- a/src/io/unload.jl +++ b/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() diff --git a/src/structs.jl b/src/structs.jl index 108f856..6a40624 100644 --- a/src/structs.jl +++ b/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}