Refactor docs structure. Not deploying yet.

Example_Systems/SmallNewEngland/OneZone/Run.jl

@@ -1,3 +1,3 @@
 using GenX
 
-run_genx_case!(dirname(@__FILE__))
+run_genx_case!(dirname(@__FILE__))

docs/Project.toml

@@ -1,4 +1,5 @@
 [deps]
+DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 GenX = "5d317b1e-30ec-4ed6-a8ce-8d2d88d7cfac"
-DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"

docs/make.jl

@@ -1,8 +1,4 @@
-push!(LOAD_PATH,"../src/")
-#=cd("../")
-include(joinpath(pwd(), "package_activate.jl"))
-genx_path = joinpath(pwd(), "src")
-push!(LOAD_PATH, genx_path)=#
+push!(LOAD_PATH, "../src/")
 import DataStructures: OrderedDict
 using GenX
 using Documenter
@@ -13,18 +9,38 @@ push!(LOAD_PATH, genx_docpath)
 pages = OrderedDict(
     "Welcome Page" => [
         "GenX: Introduction" => "index.md",
-        "Running GenX Cases" => "how_to_run_genx.md",
-        "Multi-Stage Capacity Expansion Planning with GenX" => "multi_stage_genx.md",
+        "Installation Guide" => "installation.md",
         "Limitation of GenX" => "limitations_genx.md",
         "Third Party Extensions" => "third_party_genx.md"
     ],
+    "Getting Started" => [
+        "Running GenX" => "examples_casestudies.md",
+        "Commertial solvers" => "commercial_solvers.md",
+    ],
+    "User Guide" => [
+        "Overall workflow" => "workflow.md",
+        "Model Configuration" => "model_configuration.md",
+        "Solver Configuration" => "solver_configuration.md",
+        "Model Inputs" => "model_input.md",
+        "TDR Inputs" => "TDR_input.md",
+        "Running the TDR" => "running_TDR.md",
+        "MGA package" => "generate_alternatives.md",
+        "Multi-stage Model" => "multi_stage_input.md",
+        "Method of Morris Inputs" => "methodofmorris_input.md",
+        "Running the Model" => "running_model.md",
+        "Model Outputs" => "model_output.md",
+    ],
     "Model Concept and Overview" => [
         "Model Introduction" => "model_introduction.md",
         "Notation" => "model_notation.md",
         "Objective Function" => "objective_function.md",
-        "Power Balance" => "power_balance.md"
+        "Power Balance" => "power_balance.md",
+        "Slack Variables for Policies" => "slack_variables_overview.md",
+        "Maintenance" => "maintenance_overview.md",
+        "Time Domain Reduction" => "TDR_overview.md",
+        "Multi-Stage Modeling" => "multi_stage_overview.md",
     ],
-    "Model Function Reference" => [
+    "Reference" => [
         "Core" => "core.md",
         "Resources" => [
             "Curtailable Variable Renewable" => "curtailable_variable_renewable.md",
@@ -50,48 +66,50 @@ pages = OrderedDict(
                 "Thermal No Commit" => "thermal_no_commit.md"
             ],
             "Hydrogen Electrolyzers" => "electrolyzers.md",
+            "Retrofit" => "retrofit.md",
+            "Resources API" => "resources.md",
             "Scheduled maintenance for various resources" => "maintenance.md",
         ],
-        "Multi_stage" => [
-                "Configure multi-stage inputs" => "configure_multi_stage_inputs.md",
-                "Model multi stage: Dual Dynamic Programming Algorithm" => "dual_dynamic_programming.md",
-        ],
         "Policies" => "policies.md",
-        "Slack Variables for Policies" => "slack_variables_overview.md",
-    ],
-    "Methods" => "methods.md",
-    "Solver Configurations" => "solver_configuration.md",
-    "Solving the Model" => "solve_model.md",
-    "Model Inputs/Outputs Documentation" => [
-        "Single-stage Model" => "data_documentation.md",
-        "Multi-stage Model" => "multi_stage_model_overview.md",
+        "Solver Configurations" => "solver_configuration_api.md",
+        "Inputs Functions" => "load_inputs.md",
+        "Utility Functions" => "utility_functions.md",
+        "TDR" => "TDR.md",
+        "Multi-stage" => [
+            "Configure multi-stage inputs" => "configure_multi_stage_inputs.md",
+            "Model multi stage: Dual Dynamic Programming Algorithm" => "dual_dynamic_programming.md",
+            "Endogenous Retirement" => "endogenous_retirement.md",
+        ],
+        "Public API" => "public_api.md",
+        "Solving the Model" => "solve_model.md",
+        "Outputs Functions" => "write_outputs.md",
+        "Modeling to Generate Alternatives" => "mga.md",
+        "Method of Morris" => "methodofmorris.md",
     ],
-    "GenX Inputs Functions" => "load_inputs.md",
-    "GenX Outputs Functions" =>"write_outputs.md",
-    "Additional Features" => "additional_features.md",
     "Third Party Extensions" => "additional_third_party_extensions.md",
-    #"Unit Testing (Under Development)" => "unit_testing.md"
+    # "Unit Testing (Under Development)" => "unit_testing.md"
 )
 makedocs(;
     modules=[GenX],
     authors="Jesse Jenkins, Nestor Sepulveda, Dharik Mallapragada, Aaron Schwartz, Neha Patankar, Qingyu Xu, Jack Morris, Sambuddha Chakrabarti",
-    #repo="https://github.com/sambuddhac/GenX.jl/blob/{commit}{path}#{line}",
     sitename="GenX",
     format=Documenter.HTML(;
         prettyurls=get(ENV, "CI", "false") == "true",
-        canonical="https://genxproject.github.io/GenX/stable",
+        canonical="https://github.com/lbonaldo/GenX/stable",
         assets=String[],
+        collapselevel=1
     ),
     pages=[p for p in pages]
+    # warnonly=true
 )
 
-deploydocs(;
-    repo="github.com/GenXProject/GenX.git",
-    target = "build",
-    branch = "gh-pages",
-    devbranch = "main",
-    devurl = "dev",
-    push_preview=true,
-    versions = ["stable" => "v^", "v#.#"],
-    forcepush = false,
-)
+# deploydocs(;
+#     repo="github.com/GenXProject/GenX.git",
+#     target = "build",
+#     branch = "gh-pages",
+#     devbranch = "main",
+#     devurl = "dev",
+#     push_preview=true,
+#     versions = ["stable" => "v^", "v#.#"],
+#     forcepush = false,
+# )

docs/src/TDR.md

@@ -0,0 +1,11 @@
+# Time Domain Reduction (TDR)
+
+```@autodocs
+Modules = [GenX]
+Pages = ["time_domain_reduction.jl"]
+Order = [:type, :function]
+```
+
+```@docs
+GenX.run_timedomainreduction!
+```

docs/src/TDR_input.md

@@ -0,0 +1,24 @@
+# Time-domain reduction
+
+Modeling grid operations for each hour of the year can be computationally expensive for models with many zones and resources. Time-domain reduction is often employed in capacity expansion models as a way to balance model spatial and temporal resolution as well as representation of dispatch, while ensuring reasonable computational times. GenX allows the option of performing time-domain reduction on the user supplied time-series input data to produce a representative time series at the desired level of temporal resolution. The below table summarizes the list of parameters to be specified by the user to perform the time domain reduction implemented in GenX. These parameters are passed to GenX via the YAML file `time_domain_reduction_settings.yml`.
+
+**Structure of the time\_domain\_reduction.yml file**
+
+|**Key** | **Description**|
+| :------------ | :-----------|
+|Timesteps\_per\_period | The number of timesteps (e.g., hours) in each representative period (i.e. 168 for weeks, 24 for days, 72 for three-day periods, etc).|
+|UseExtremePeriods | 1 = Include outliers (by performance or demand/resource extreme) as their own representative extreme periods. This setting automatically includes periods based on criteria outlined in the dictionary `ExtremePeriods`. Extreme periods can be selected based on following criteria applied to demand profiles or solar and wind capacity factors profiles, at either the zonal or system level. A) absolute (timestep with min/max value) statistic (minimum, maximum) and B) integral (period with min/max summed value) statistic (minimum, maximum). For example, the user could want the hour with the most demand across the whole system to be included among the extreme periods. They would select Demand, System, Absolute, and Max.|
+||0 = Do not include extreme periods.|
+|ExtremePeriods | If **UseExtremePeriods = 1**, use this dictionary to select which types of extreme periods to use. Select by profile type (Demand, PV, or Wind), geography (Zone or System), grouping by timestep or by period (Absolute or Integral), and statistic (Maximum or Minimum).|
+|ClusterMethod |Either `kmeans` or `kmedoids`, the method used to cluster periods and determine each time step's representative period.|
+|ScalingMethod |Either `N` or `S`, the decision to normalize ([0,1]) or standardize (mean 0, variance 1) the input data prior to clustering.|
+|MinPeriods |The minimum number of representative periods used to represent the input data. If using UseExtremePeriods, this must be greater or equal to the number of selected extreme periods. If `IterativelyAddPeriods` is off, this will be the total number of representative periods.|
+|MaxPeriods| The maximum number of representative periods - both clustered and extreme - that may be used to represent the input data.|
+|IterativelyAddPeriods |1 = Add representative periods until the error threshold between input data and represented data is met or the maximum number of representative periods is reached.|
+||0 = Use only the minimum number of representative periods. This minimum value includes the selected extreme periods if `UseExtremePeriods` is on.|
+|Threshold |Iterative period addition will end if the period farthest from its representative period (as measured using Euclidean distance) is within this percentage of the total possible error (for normalization) or 95% of the total possible error (± 2 σ for standardization). E.g., for a threshold of 0.01, each period must be within 1% of the spread of possible error before the clustering iterations will terminate (or until the maximum is reached).|
+|IterateMethod | Either ‘cluster' (Default) or ‘extreme', whether to increment the number of clusters to the kmeans/kmedoids method or to set aside the worst-fitting periods as a new extreme periods.|
+|nReps |Default = 200, the number of kmeans/kmedoids repetitions at the same setting.|
+|DemandWeight| Default = 1, a multiplier on demand columns to optionally prioritize better fits for demand profiles over resource capacity factor or fuel price profiles.|
+|WeightTotal |Default = 8760, the sum to which the relative weights of representative periods will be scaled.|
+|ClusterFuelPrices| Either 1 or 0, whether or not to use the fuel price time series in `Fuels_data.csv` in the clustering process. If 'no', this function will still write `Fuels_data.csv` in the TimeDomainReductionFolder with reshaped fuel prices based on the number and size of the representative periods but will not use the fuel price time series for selection of representative periods.|

docs/src/TDR_overview.md

@@ -0,0 +1,13 @@
+# Time Domain Reduction (TDR)
+
+Rather than modeling and optimizing power grid operations at a high temporal resolution (e.g., hourly, over a full year) while evaluating new capacity investments, which can be computationally expensive for large-scale studies with several resources, it may be useful to consider a reduced temporal resolution to model annual grid operations.
+Such a time-domain reduction is often employed in capacity expansion models as a way to balance model spatial and temporal resolution as well as representation of dispatch, while ensuring reasonable computational times.
+The time-domain reduction method provided allows the user to automate these features while specifying the various parameters of the time-domain reduction 'clustering' algorithm to be used in formulating the resulting optimization model.
+
+### Running a case with Time Domain Reduction
+
+There are two ways to run a case with a reduced (e.g. less than full-year) temporal resolution.
+1. Let GenX perform the time domain reduction before optimizing.
+2. Bring your own clustered data
+
+It's also possible for GenX perform clustering separately from the optimization task. Check out the [Running the TDR](@ref) section for more information. 

docs/src/commercial_solvers.md

@@ -0,0 +1,23 @@
+## Using commercial solvers: Gurobi or CPLEX
+
+If you want to use the commercial solvers Gurobi or CPLEX:
+
+- Make sure you have a valid license and the actual solvers for either of Gurobi or CPLEX installed on your machine
+- Add Gurobi or CPLEX to the Julia Project.
+
+```
+$ julia --project=/home/youruser/GenX
+
+julia> <press close-bracket ] to access the package manager>
+(GenX) pkg> add Gurobi
+-or-
+(GenX) pkg> add CPLEX
+```
+```@meta
+#TODO: Add instructions for adding Gurobi or CPLEX to the Julia Project with the new PR. 
+```
+
+- Set the appropriate solver in the genx_settings.yml file of your case
+
+!!! warning "Warning"
+    Note that if you have not already installed the required Julia packages or you do not have a valid Gurobi license on your host machine, you will receive an error message and Run.jl will not run to completion.

docs/src/configure_multi_stage_inputs.md

@@ -1,4 +1,4 @@
-# configure multi stage inputs
+# Configure multi stage inputs
 ```@autodocs
 Modules = [GenX]
 Pages = ["configure_multi_stage_inputs.jl"]