Documentation (#62)

* paper draft * Paper draft * Update paper/paper.md Co-Authored-By: Holger Teichgraeber <[email protected]> * Update paper/paper.md Co-Authored-By: Holger Teichgraeber <[email protected]> * Update paper/paper.md Co-Authored-By: Holger Teichgraeber <[email protected]> * change requests added * constraints, julia-ref * Integrate anyMOD.jls * Missing word included * Review suggestions sjpfenninger * Feedback sjpfenninger * testing docs * Fix tiny typos in `paper.md` * Fix year for `Weibezahn:2019` reference * Documentation and minor corrections * testing dev * Clp dependency and Readme * julia 1.4 * no Clp constraint Co-authored-by: Holger Teichgraeber <[email protected]> Co-authored-by: YoungFaithful <[email protected]> Co-authored-by: Ali Ramadhan <[email protected]>
YoungFaithful · Jun 13, 2020 · f2fe4bb · f2fe4bb
1 parent b8d45dd
commit f2fe4bb
Show file tree

Hide file tree

Showing 16 changed files with 408 additions and 86 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -13,12 +13,19 @@ after_success:
 
 jobs:
  include:
- - stage: "Testing"
+ - stage: "Testing version 1.0"
  julia: 1.0
  os: linux
  script:
  - julia --project=test/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
- - julia --project=test/ test/cep.jl
+ - julia --project=test/ test/runtests.jl
+ after_success:
+ - stage: "Testing version 1.4"
+ julia: 1.4
+ os: linux
+ script:
+ - julia --project=test/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+ - julia --project=test/ test/runtests.jl
  after_success:
  - stage: "Documentation"
  julia: 1.0

diff --git a/README.md b/README.md
@@ -4,39 +4,39 @@
 [![](https://img.shields.io/badge/docs-dev-blue.svg)](https://YoungFaithful.github.io/CapacityExpansion.jl/dev)
 [![Build Status](https://travis-ci.com/YoungFaithful/CapacityExpansion.jl.svg?branch=master)](https://travis-ci.com/YoungFaithful/CapacityExpansion.jl)
 
-[CapacityExpansion](https://github.com/YoungFaithful/CapacityExpansion.jl) is a [julia](https://www.juliaopt.com) implementation of an input-data-scaling capacity expansion modeling framework.
+[CapacityExpansion](https://github.com/YoungFaithful/CapacityExpansion.jl) is a [julia](https://julialang.org/) implementation of an input-data-scaling capacity expansion modeling framework.
 
-The main purpose of the package is providing an extensible, simple-to-use generation and transmission capacity extension model that allows to address a diverse set of research questions in the area of energy systems planning. The secondary purposes are:
+The main purpose of the package is providing an extensible, simple-to-use generation and transmission capacity expansion model that allows to address a diverse set of research questions in the area of energy systems planning. The secondary purposes are:
 1) Providing a simple process to integrate (clustered) time-series input data, geographical input data, cost input data, and technology input data.
 2) Providing a model configuration, a modular model setup and model optimization.
 3) Providing an interface between the optimization result and further analysis.
 
 Please refer to the [documentation](https://YoungFaithful.github.io/CapacityExpansion.jl/stable) for details on how to use this software.
 
-|Model Information |  |
-|---------------------|-----------------------------------------------------------------------------------|
-|Model class  | Capacity Expansion Problem |
-|Model type | Optimization, Linear optimization model input-data depending energy system  |
-|Carriers  | Electricity, Hydrogen, ... |
-|Technologies  | dispatchable and non-dispatchable Generation, Conversion, Storage (seasonal), Transmission  |
-|Decisions    | investment and dispatch |
-|Objective | Total system cost |
-|Variables  | Cost, Capacities, Generation, Storage, Lost-Load, Lost-Emissions |
+| Model Information |  |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| Model class | Capacity Expansion Problem  |
+| Model type | Optimization, Linear optimization model input-data depending energy system  |
+| Carriers | Electricity, Hydrogen, ...  |
+| Technologies | dispatchable and non-dispatchable Generation, Conversion, Storage (seasonal), Transmission |
+| Decisions | investment and dispatch  |
+| Objective | Total system cost |
+| Variables  | Cost, Capacities, Generation, Storage, Lost-Load, Lost-Emissions |
 
-|Input Data Depending | Provided Input Data  |
-|---------------------|------------------------------------------------------------------------------------|
-|Regions   | California, USA (single and multi-node) and Germany, Europe (single and multi-node)|
-|Geographic Resolution| aggregated regions     |
-|Time resolution   | hourly   |
-|Network coverage  | transmission, DCOPF load flow   |
+| Input Data Depending  | Provided Input Data  |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| Regions  | California, USA (single and multi-node) and Germany, Europe (single and multi-node) |
+| Geographic Resolution | aggregated regions   |
+| Time resolution  | hourly   |
+| Network coverage  | transmission, DCOPF load flow   |
 
 The package uses [TimeSeriesClustering](https://github.com/holgerteichgraeber/TimeSeriesClustering.jl) as a basis for its time-series aggregation.
 
 This package is developed by Elias Kuepper [@YoungFaithful](https://github.com/youngfaithful) and Holger Teichgraeber [@holgerteichgraeber](https://github.com/holgerteichgraeber).
 
 ## Installation
 This package runs under julia v1.0 and higher.
-It depends on:
+It depends on multiple packages, which are also listed in the [`Project.toml`](https://github.com/YoungFaithful/CapacityExpansion.jl/blob/master/Project.toml). The packages are automatically installed by the julia package manager:
 - `JuMP.jl` - for the modeling environment
 - `CSV.jl` - for handling of `.csv`-Files
 - `DataFrames.jl` - for handling of tables
@@ -45,13 +45,24 @@ It depends on:
 - `FileIO` - for file accessing
 - `TimeSeriesClustering.jl` - for time-series data
 
+You can install `CapacityExpansion` using the package mode:
+```julia
+]
+add CapacityExpansion
+```
+or using the `Pkg.add` function:
 ```julia
 using Pkg
 Pkg.add("CapacityExpansion")
 ```
 
 A solver is required to run an optimization as explained in section [Solver](https://youngfaithful.github.io/CapacityExpansion.jl/stable/opt_cep/#Solver-1).
-Install e.g.:
+Install e.g. `Clp` using the package mode:
+```julia
+]
+add Clp
+```
+or using the `Pkg.add` function:
 ```julia
 using Pkg
 Pkg.add("Clp")
@@ -72,3 +83,12 @@ cep_data = load_cep_data_provided("GER_1")
 # run a simple
 run_opt(ts_input_data,cep_data,optimizer)
 ```
+
+## Testing
+The model is being tested against a capacity expansion model presented in the paper [`On representation of temporal variability in electricity capacity
+planning models` by Merrick 2016](http:https://dx.doi.org/10.1016/j.eneco.2016.08.001). The model additionally tests itself against previously calculated data to detect new errors.
+
+## Links
+- [Documentation of the stable version](https://YoungFaithful.github.io/CapacityExpansion.jl/stable)
+- [Documentation of the development version](https://YoungFaithful.github.io/CapacityExpansion.jl/dev)
+- [Contributing guidelines](https://github.com/YoungFaithful/CapacityExpansion.jl/blob/master/CONTRIBUTING.md)
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -2,3 +2,7 @@
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Clp = "e2554f3b-3117-50c0-817c-e040a3ddf72d"
+
+[compat]
+Documenter = "^0.24.0"
+Plots = "^0.27.0"
diff --git a/docs/make.jl b/docs/make.jl
@@ -2,27 +2,41 @@ using Documenter
 using Plots
 using CapacityExpansion
 
-makedocs(sitename="CapacityExpansion.jl",
+makedocs(
+ sitename = "CapacityExpansion.jl",
  authors = "Elias Kuepper, and Holger Teichgraeber",
  pages = [
  "Introduction" => "index.md",
  "Quickstart" => "quickstart.md",
  "Workflow" => "workflow.md",
- "Data" => ["preparing_clust_data.md", "preparing_opt_cep_data.md", "csv_structure.md", "README_GER_18.md", "README_GER_1.md", "README_CA_14.md", "README_CA_1.md", "README_TX_1.md"],
- "Optimization" => ["opt_cep.md","results_opt.md", "opt_cep_examples.md"],
+ "Data" => [
+ "preparing_clust_data.md",
+ "preparing_opt_cep_data.md",
+ "csv_structure.md",
+ "README_GER_18.md",
+ "README_GER_1.md",
+ "README_CA_14.md",
+ "README_CA_1.md",
+ "README_TX_1.md",
+ ],
+ "Optimization" => ["opt_cep.md", "results_opt.md", "opt_cep_examples.md"],
  "Teaching" => ["teaching.md", "homework.md"],
+ "Testing" => "testing.md",
+ ],
+ format = Documenter.HTML(
+ assets = [
+ asset("assets/cep_text.svg", class = :ico, islocal = true),
+ asset("assets/opt_cep.svg", class = :ico, islocal = true),
+ asset("assets/workflow.svg", class = :ico, islocal = true),
+ asset("assets/GER_1.svg", class = :ico, islocal = true),
+ asset("assets/GER_18.svg", class = :ico, islocal = true),
+ asset("assets/CA_1.svg", class = :ico, islocal = true),
+ asset("assets/CA_14.svg", class = :ico, islocal = true),
+ asset("assets/opt_cep_cap_plot.svg", class = :ico, islocal = true),
+ asset("assets/preparing_clust_data_load.svg", class = :ico, islocal = true),
+ asset("assets/preparing_clust_data_agg.svg", class = :ico, islocal = true),
  ],
- format = Documenter.HTML(assets = [
- "assets/clust_for_opt_text.svg",
- "assets/opt_cep.svg",
- "assets/workflow.svg",
- "assets/GER_1.svg",
- "assets/GER_18.svg",
- "assets/CA_1.svg",
- "assets/CA_14.svg",
- "assets/opt_cep_cap_plot",
- "assets/preparing_clust_data_load",
- "assets/preparing_clust_data_agg"])
- )
+ ),
+)
 
-deploydocs(repo = "github.com/YoungFaithful/CapacityExpansion.jl.git", devbranch="dev")
+deploydocs(repo = "github.com/YoungFaithful/CapacityExpansion.jl.git", devbranch = "dev")
diff --git a/docs/src/README_TX_1.md b/docs/src/README_TX_1.md
@@ -11,6 +11,6 @@ Implemented with PV-price 0.5 $/W
 ##Other
 Alternatively for price of 1.0$/W edit .csv files and replace costs with:
 - fix: 4.776E+3 $/MW cap: 1.032E+6 $/MW
-Assuptions for transformation:
-- demand mulitiplied with 1.48
-- solar devided by 1000
+Assumptions for transformation:
+- demand multiplied with 1.48
+- solar divided by 1000
diff --git a/docs/src/csv_structure.md b/docs/src/csv_structure.md
@@ -3,7 +3,8 @@
 - Timestep (input data) - h
 - Power - MW
 - Energy - MWh
-- length - km
+- Length - km
+- Weight - kg
 
 ## Provided Data
 The package provides data for:
@@ -69,16 +70,16 @@ The package provides data for:
 `techs.yml` needs to have the following structure:
 - `tech_groups`: defines parent groups for techs or other tech_groups
 - `techs`: defines the technologies, the elements are used to declare the dimension `tech`
-We allow technologies to have parents to reduce unnecessary and mistake enabling repitions within the `techs.yml`-file. The information of the single techs is combined with the information provided from their parent tech_groups. One technology can have multiple tech_groups, if the parant has a parant. The combined information must contain:
+We allow technologies to have parents to reduce unnecessary and mistake enabling repetitions within the `techs.yml`-file. The information of the single techs is combined with the information provided from their parent tech_groups. One technology can have multiple tech_groups, if the parent has a parent. The combined information must contain:
 - `name`: A detailed description of the technology
 - `tech_group`: a technology-group that the technology belongs to. Groups can be: `demand`, `generation`, `dispatchable_generation`, `non_dispatchable_generation`, `storage`, `conversion`, `transmission`
 - `plant_lifetime`: the physical expected lifetime of this technologies plant [a]
 - `financial_lifetime`: financial time to break even [a]
 - `discount_rate`: discount rate for technology [a]
 - `structure`: `node` or `line` depending on the structure of the technology
 - `unit`: the unit that the capacity of the technology scales with. It can be `power`[MW] or `energy`[MWh]
-- `input`: the input can be a `carrier` like e.g. electricity `carrier: electricity, a `timeseries` like e.g. `timeseries: demand_electricity`, or a `fuel` like e.g. `fuel: gas`
-The information can conatin:
+- `input`: the input can be a `carrier` like e.g. electricity, a `timeseries` like e.g. `timeseries: demand_electricity`, or a `fuel` like e.g. `fuel: gas`
+The information can contain:
 - `constraints`: like an `efficiency` like e.g. `efficiency: 0.53` or `cap_eq` (e.g. discharge capacity is same as charge capacity) `cap_eq: bat_in`
 
 ### lines.csv
@@ -90,5 +91,5 @@ The information can conatin:
 
 |`line`|`node_start`|`node_end`|`reactance`|`resistance`|`power_ex`|`power_lim`|`voltage`|`circuits`|`length`|
 |-------|------------|----------|-----------|------------|----------|-----------|---------|----------|--------|
-|[line...]|`node` - line starts| `node` - line ends| reactance| resistance| exisitng capacity in MW | capacity limit in MW| voltage or description| number of circuits included| length in km|
+|[line...]|`node` - line starts| `node` - line ends| reactance| resistance| existing capacity in MW | capacity limit in MW| voltage or description| number of circuits included| length in km|
 |...| ...| ...|...| ...|...| ...| ...|...| ...|