From 11776a84b729b0c8886151bb841637a03db79280 Mon Sep 17 00:00:00 2001
From: Mathias Berg Rosendal <77012503+Mathias157@users.noreply.github.com>
Date: Thu, 19 Sep 2024 10:26:54 +0200
Subject: [PATCH] Created a quick get started tutorial using sphinx and GitHub
actions (#27)
* Implemented tutorial format
* Fixed wrong .yml path
* Wrong build command fixed
* Ample installation instructions
* Added section on HPC running
* Added installation instructions
* Grammar
* Correct path
* Fixed headers and made a succesful admonition
* Grammar
* Itemisation doesn't need spaces between them
* Access documentation
* Some grammar
* More installation instructions and project setup
* Wrote scenario setup
* Explained the scenario structure logic
* Added addons page
* Started running Balmorel page
* Fixed links
* Made a working test_run scenario
* Finished running Balmorel section
* There's now a minimal get started / 'hello world' guide for installing and running Balmorel, related to issue #25
* Corrected version and added general description
* Added output analysis video
* Added PuTTY login example
* Made explanation for accessing WinSCP
* Minimal guide to submitting jobs to the HPC finalised, related to issue #25
* Wrong wording
* Added some notes on how to check the log
* A link to the full documentation is made, which resolves #25
* Made copy button for code snippets
* Trying to generate code snippets copy button again
* Removed packages that did not exist, and trying with conda install copy button
* Fixed copy button not appearing - needed to add is as extension in conf.py
* Transferred the github action to master
* Fixed some grammar error and added CLI description
---
.github/workflows/sphinx.yml | 40 ++++++++++++
.gitignore | 1 +
base/documentation/gh-pages/README.md | 49 +++++++++++++++
base/documentation/gh-pages/about.md | 3 +
base/documentation/gh-pages/addons.md | 9 +++
base/documentation/gh-pages/conf.py | 32 ++++++++++
.../gh-pages/css/css_options.css | 18 ++++++
.../gh-pages/docs_environment.yml | 10 +++
base/documentation/gh-pages/get_started.md | 13 ++++
.../gh-pages/get_started/installation.md | 20 ++++++
.../gh-pages/get_started/outputs.md | 11 ++++
.../gh-pages/get_started/running_balmorel.md | 20 ++++++
.../gh-pages/get_started/scenario_setup.md | 56 +++++++++++++++++
.../gh-pages/get_started/structure.md | 25 ++++++++
.../gh-pages/img/GAMS_Studio_Setup.jpg | Bin 0 -> 61968 bytes
.../gh-pages/img/putty_login.jpg | Bin 0 -> 75622 bytes
.../gh-pages/img/winscp_login.jpg | Bin 0 -> 49699 bytes
base/documentation/gh-pages/index.md | 31 ++++++++++
base/documentation/gh-pages/pre_processing.md | 7 +++
base/documentation/gh-pages/running_on_hpc.md | 13 ++++
.../gh-pages/running_on_hpc/access.md | 43 +++++++++++++
.../gh-pages/running_on_hpc/installation.md | 9 +++
.../running_on_hpc/submitting_a_job.md | 57 ++++++++++++++++++
23 files changed, 467 insertions(+)
create mode 100644 .github/workflows/sphinx.yml
create mode 100644 base/documentation/gh-pages/README.md
create mode 100644 base/documentation/gh-pages/about.md
create mode 100644 base/documentation/gh-pages/addons.md
create mode 100644 base/documentation/gh-pages/conf.py
create mode 100644 base/documentation/gh-pages/css/css_options.css
create mode 100644 base/documentation/gh-pages/docs_environment.yml
create mode 100644 base/documentation/gh-pages/get_started.md
create mode 100644 base/documentation/gh-pages/get_started/installation.md
create mode 100644 base/documentation/gh-pages/get_started/outputs.md
create mode 100644 base/documentation/gh-pages/get_started/running_balmorel.md
create mode 100644 base/documentation/gh-pages/get_started/scenario_setup.md
create mode 100644 base/documentation/gh-pages/get_started/structure.md
create mode 100644 base/documentation/gh-pages/img/GAMS_Studio_Setup.jpg
create mode 100644 base/documentation/gh-pages/img/putty_login.jpg
create mode 100644 base/documentation/gh-pages/img/winscp_login.jpg
create mode 100644 base/documentation/gh-pages/index.md
create mode 100644 base/documentation/gh-pages/pre_processing.md
create mode 100644 base/documentation/gh-pages/running_on_hpc.md
create mode 100644 base/documentation/gh-pages/running_on_hpc/access.md
create mode 100644 base/documentation/gh-pages/running_on_hpc/installation.md
create mode 100644 base/documentation/gh-pages/running_on_hpc/submitting_a_job.md
diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml
new file mode 100644
index 00000000..a2a93385
--- /dev/null
+++ b/.github/workflows/sphinx.yml
@@ -0,0 +1,40 @@
+name: Build documentation
+on:
+ push:
+ branches: [ master ]
+ pull_request:
+ branches: [ master ]
+
+permissions:
+ contents: write
+
+jobs:
+ docs:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - uses: mamba-org/setup-micromamba@v1
+ with:
+ micromamba-version: '1.5.8-0' # any version from https://github.com/mamba-org/micromamba-releases
+ environment-file: base/documentation/gh-pages/docs_environment.yml
+ init-shell: bash
+ cache-environment: true
+ post-cleanup: 'all'
+ generate-run-shell: false
+
+ - name: Sphinx build
+ run: |
+ sphinx-build base/documentation/gh-pages _build
+ shell: bash -el {0}
+
+ - name: Deploy to GitHub Pages
+ uses: peaceiris/actions-gh-pages@v4
+ if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+ with:
+ publish_branch: gh-pages
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: _build/
+ force_orphan: true
diff --git a/.gitignore b/.gitignore
index 4d4eb265..3d84ee95 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,4 +26,5 @@ base/data/README.md
*.log~1
*.log~2
*.log~3
+build
%batfileMERGEWITHBASE%
\ No newline at end of file
diff --git a/base/documentation/gh-pages/README.md b/base/documentation/gh-pages/README.md
new file mode 100644
index 00000000..95d775c9
--- /dev/null
+++ b/base/documentation/gh-pages/README.md
@@ -0,0 +1,49 @@
+# GitHub Pages Tutorial: A Quick Start Guide for Balmorel
+
+This folder contain all necessary files for developing the Balmorel GitHub pages.
+
+
+## Purpose
+
+On the short-term: to make it easier getting started with Balmorel.
+
+On the long-term: interlink development of Balmorel with development of documentation. I.e., by tracking markdown documents within the Balmorel repository, the process of editing documentation becomes identical to the process of editing Balmorel source code.
+
+
+## Requirements
+
+The documentation can be tested on a local machine by running:
+```bash
+sphinx-build base/documentation/gh-pages build
+```
+Then, build/index.html can be opened by, e.g., VS Code's "Go Live" extension and the website can be browsed.
+
+This requires the following python packages:
+```yaml
+name: docs_building
+channels:
+ - conda-forge
+dependencies:
+ - python=3.12
+ - myst-parser
+ - sphinx
+ - sphinx-rtd-theme
+ - sphinx-autoapi
+```
+
+## Installation instructions
+
+For more information on how to manage and install virtual python environments check out [this resource](https://docs.python.org/3/library/venv.html), or if you are a conda user, [this resource](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).
+
+The correct virtual environment can be installed using the [provided .yaml file](base/documentation/gh-pages/docs_environment.yml) that is equal to the environments above.
+
+## Example
+
+
+## Authors
+
+Mathias Berg Rosendal
+
+## Contribution guide
+
+Similar to developing Balmorel - create your own branch, remember to commit all small changes and create a pull request to master when a feature or tutorial section is done
\ No newline at end of file
diff --git a/base/documentation/gh-pages/about.md b/base/documentation/gh-pages/about.md
new file mode 100644
index 00000000..1aae90ae
--- /dev/null
+++ b/base/documentation/gh-pages/about.md
@@ -0,0 +1,3 @@
+# About this code
+
+This documentation is under construction
diff --git a/base/documentation/gh-pages/addons.md b/base/documentation/gh-pages/addons.md
new file mode 100644
index 00000000..09cabe64
--- /dev/null
+++ b/base/documentation/gh-pages/addons.md
@@ -0,0 +1,9 @@
+# Addons
+
+Addons are modular additions to the Balmorel framework that can be turned on and off in the balopt.opt file. E.g., the hydrogen addon adds energy balance equations for hydrogen, demand for hydrogen, hydrogen conversion, transmission and storage technologies etc.
+
+```{toctree}
+:maxdepth: 1
+
+
+```
\ No newline at end of file
diff --git a/base/documentation/gh-pages/conf.py b/base/documentation/gh-pages/conf.py
new file mode 100644
index 00000000..7648a801
--- /dev/null
+++ b/base/documentation/gh-pages/conf.py
@@ -0,0 +1,32 @@
+project = "Balmorel"
+copyright = "2024, Mathias Berg Rosendal"
+author = "Mathias Berg Rosendal"
+release = "5.0"
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".testenv", ".testenv/**", "README.md"]
+
+conf_py_path = "/base/documentation/gh-pages" # with leading and trailing slash
+
+html_static_path = ["css"]
+
+# General configurations
+extensions = [
+ "myst_parser", # in order to use markdown
+ 'sphinx_copybutton',
+ # "autoapi.extension", # in order to use markdown
+]
+
+# search this directory for Python files
+# autoapi_dirs = ["../src/pybalmorel"]
+
+# ignore this file when generating API documentation
+# autoapi_ignore = ["*/conf.py"]
+
+myst_enable_extensions = [
+ "colon_fence", # ::: can be used instead of ``` for better rendering
+]
+
+html_theme = "sphinx_rtd_theme"
+
+def setup(app):
+ app.add_css_file('css_options.css') # may also be an URL
\ No newline at end of file
diff --git a/base/documentation/gh-pages/css/css_options.css b/base/documentation/gh-pages/css/css_options.css
new file mode 100644
index 00000000..d111b7f2
--- /dev/null
+++ b/base/documentation/gh-pages/css/css_options.css
@@ -0,0 +1,18 @@
+/* Changing the ugly purple visited colour to remain blue or white for all links */
+/* Cross references turns grayblue */
+a[class="reference internal"]:visited {
+ color: #6a8392;
+}
+a[class="reference external"]:visited {
+ color: #6a8392;
+}
+
+/* Toctree remains white */
+div[class="wy-side-scroll"] li[class='toctree-l1'] a:visited {
+ color: white;
+}
+
+/* Home icon turns grayblue */
+ul[class="wy-breadcrumbs"] a:visited {
+ color: #6a8392;
+}
\ No newline at end of file
diff --git a/base/documentation/gh-pages/docs_environment.yml b/base/documentation/gh-pages/docs_environment.yml
new file mode 100644
index 00000000..8f8ecc07
--- /dev/null
+++ b/base/documentation/gh-pages/docs_environment.yml
@@ -0,0 +1,10 @@
+name: docs_building
+channels:
+ - conda-forge
+dependencies:
+ - python=3.12
+ - myst-parser
+ - sphinx
+ - sphinx-rtd-theme
+ - sphinx-autoapi
+ - sphinx-copybutton
\ No newline at end of file
diff --git a/base/documentation/gh-pages/get_started.md b/base/documentation/gh-pages/get_started.md
new file mode 100644
index 00000000..14e08833
--- /dev/null
+++ b/base/documentation/gh-pages/get_started.md
@@ -0,0 +1,13 @@
+# Get Started
+
+The intention of this tutorial is to teach the user how to install and run Balmorel, using a small test case.
+
+```{toctree}
+:maxdepth: 1
+
+get_started/installation.md
+get_started/structure.md
+get_started/scenario_setup.md
+get_started/running_balmorel.md
+get_started/outputs.md
+```
\ No newline at end of file
diff --git a/base/documentation/gh-pages/get_started/installation.md b/base/documentation/gh-pages/get_started/installation.md
new file mode 100644
index 00000000..278709a8
--- /dev/null
+++ b/base/documentation/gh-pages/get_started/installation.md
@@ -0,0 +1,20 @@
+# Installation
+A [GAMS](https://gams.com/) installation and license is required to run Balmorel. We also recommend installing [git](https://git-scm.com/) to do version control on your Balmorel project.
+
+A small demo can be run without a GAMS license in the [balmorel-demo](https://github.com/balmorelcommunity/Balmorel/tree/balmorel-demo) branch.
+
+## Downloading Balmorel Framework and Data
+The Balmorel framework can be downloaded from [GitHub](https://github.com/balmorelcommunity/Balmorel) as a .zip file by pressing Code -> Download ZIP.
+The corresponding data is in another [GitHub repository](https://github.com/balmorelcommunity/Balmorel_data), and can also be downloaded as a .zip. Place the Balmorel_data folder in Balmorel/base and rename it to "data".
+
+This installation can also be done using git commands in a command line interface:
+```console
+git clone https://github.com/balmorelcommunity/Balmorel.git
+cd Balmorel/base
+git clone https://github.com/balmorelcommunity/Balmorel_data.git
+```
+Remember to rename Balmorel_data to data inside Balmorel/base.
+
+:::{tip}
+If you use [VS Code](https://code.visualstudio.com/?wt.mc_id=DX_841432) with git, this specific placing of the data repository Balmorel_data inside the framework repository Balmorel/base folder will enable you to simultaneously keep track of changes to both the Balmorel framework and data in your workspace.
+:::
\ No newline at end of file
diff --git a/base/documentation/gh-pages/get_started/outputs.md b/base/documentation/gh-pages/get_started/outputs.md
new file mode 100644
index 00000000..ef323286
--- /dev/null
+++ b/base/documentation/gh-pages/get_started/outputs.md
@@ -0,0 +1,11 @@
+# Outputs
+
+The main outputs after a succesful Balmorel execution are **all_endofmodel.gdx** and **MainResults.gdx**. **all_endofmodel.gdx** contains *everything*, from sets, parameters, decision variable levels, etc. **MainResults.gdx** is post-processed outputs that are readable to a human energy system analyst.
+
+We recommend the [interactive bar plotting tool](https://balmorelcommunity.github.io/pybalmorel/autoapi/pybalmorel/classes/index.html#pybalmorel.classes.MainResults.interactive_bar_chart) from the [pybalmorel](https://balmorelcommunity.github.io/pybalmorel/) package for quick inspections. You will also find functions for [plotting maps of transmission capacities](https://balmorelcommunity.github.io/pybalmorel/autoapi/pybalmorel/classes/index.html#pybalmorel.classes.MainResults.plot_map) and [production profiles](https://balmorelcommunity.github.io/pybalmorel/autoapi/pybalmorel/classes/index.html#pybalmorel.classes.MainResults.plot_profile). See examples [here](https://github.com/balmorelcommunity/pybalmorel/blob/master/examples/PostProcessing.ipynb).
+
+The video below gives some tips on typical plots and practical guidance on analysing results using GAMS, excel or python.
+
+
+
+
diff --git a/base/documentation/gh-pages/get_started/running_balmorel.md b/base/documentation/gh-pages/get_started/running_balmorel.md
new file mode 100644
index 00000000..aabbc517
--- /dev/null
+++ b/base/documentation/gh-pages/get_started/running_balmorel.md
@@ -0,0 +1,20 @@
+# Running Balmorel
+
+To setup Balmorel in GAMS Studio, you can drag and drop the Balmorel.gms into GAMS Studio to create a correctly setup project. It is important to ensure that the working directory is in your/path/to/Balmorel/test_run/model, as illustrated in [the Figure](#GAMS_Studio_Setup) below.
+
+:::{figure} ../img/GAMS_Studio_Setup.jpg
+:name: GAMS_Studio_Setup
+:alt: How to check the working directory of your GAMS project
+:width: 100%
+:align: center
+Check your working directory by opening View/Project Explorer, and then press the gear icon ⚙️ next to "Balmorel".
+:::
+
+Make sure that Balmorel/test_run/model/Balmorel.gms is the main file and press the green run button ▶️. Balmorel should now optimise model year 2030, 2040, 2050 for Denmark and Norway using the previously specificed timesteps.
+
+## Command-Line Interface
+Balmorel can also be run using GAMS' command-line interface (CLI). You will need to use this when [running on a HPC](../running_on_hpc.md). The commands below change directory to the relevant scenario/model folder (assuming that your command prompt is already inside the Balmorel folder) and executes Balmorel.
+```console
+cd test_run/model
+gams Balmorel
+```
diff --git a/base/documentation/gh-pages/get_started/scenario_setup.md b/base/documentation/gh-pages/get_started/scenario_setup.md
new file mode 100644
index 00000000..e2baafa3
--- /dev/null
+++ b/base/documentation/gh-pages/get_started/scenario_setup.md
@@ -0,0 +1,56 @@
+# Scenario Setup
+Lets start by learning how to execute Balmorel using a small test scenario. Create a new folder in the level of the base folder, a new data and model folder inside of this and copy and paste the Balmorel.gms and cplex.op4 folder from base/model. If you want to call this scenario "test_run" the folder structure should now look like the following:
+```bash
+Balmorel
+├── base
+├── test_run
+│ ├── data
+│ └── model
+│ ├── cplex.op4
+│ └── Balmorel.gms
+└── simex
+```
+
+This is how to setup different scenarios in Balmorel. The framework will first attempt to look for files in the test_run, and then in the base folder if the required file did not exist. This means you do not have to copy paste all of the data in base/data everytime you make a new scenario, but can simply add the *changed* data. We will do this below.
+
+## Prepare Scenario Data
+Lets decrease the temporal and spatial resolution significantly, so Balmorel will solve within one or two minutes and we can verify our setup. We can do this by creating new [Y.inc](#y-inc), [S.inc](#s-inc), [T.inc](#t-inc) and [C.inc](#c-inc) files in test_run/data. In GAMS Studio, press File/New..., find the test_run/data folder and save as type "GAMS Include files (*.inc)". Copy and paste the contents from each of the snippets below:
+
+### Y.inc
+```gams
+SET Y(YYY) "Years in the simulation"
+/
+2030, 2040, 2050
+/;
+```
+This will select model years 2030, 2040 and 2050.
+
+### S.inc
+```gams
+SET S(SSS) 'Seasons in the simulation'
+/
+S14
+/;
+```
+This corresponds to selecting week 14 in a year.
+
+### T.inc
+```gams
+SET T(TTT) 'Time periods within a season in the simulation'
+/
+T001, T005, T009, T013, T017, T021
+/;
+```
+This corresponds to selecting hours 00:00, 04:00, 08:00, 12:00, 16:00 and 20:00 on a monday.
+
+### C.inc
+```gams
+SET C(CCC) 'Countries in the simulation'
+/
+NORWAY
+DENMARK
+/;
+```
+This selects countries Norway and Denmark (which consist of respectively 5 and 2 electricity and hydrogen nodes, corresponding to the bidding zones of Norway and Denmark).
+
+We are now ready to run Balmorel, see the next page.
\ No newline at end of file
diff --git a/base/documentation/gh-pages/get_started/structure.md b/base/documentation/gh-pages/get_started/structure.md
new file mode 100644
index 00000000..310da490
--- /dev/null
+++ b/base/documentation/gh-pages/get_started/structure.md
@@ -0,0 +1,25 @@
+# Structure
+
+When you clone or download Balmorel from GitHub, you will see the following folder structure:
+```bash
+Balmorel
+├── base
+│ ├── addons
+│ ├── auxils
+│ ├── bui
+│ ├── data
+│ ├── documentation
+│ ├── logerror
+│ ├── model
+│ │ ├── cplex.op4
+│ │ ├── balopt.opt
+│ │ └── Balmorel.gms
+│ └── output
+└── simex
+```
+For now, it will be sufficient to focus on the base/model folder and the Balmorel.gms, balopt.inc and cplex.op4 files.
+It is good practice to keep files in the base folder unchanged, unless you want a consistent change in data (base/data) or in the equations of the [addons](../addons.md) (base/addons). The addons folder contain modules that can be turned of and on in balopt.inc, Balmorel.gms is the file to execute to run Balmorel and cplex.op4 contain important solver options. We will use these files to execute Balmorel on the next page.
+
+:::{warning}
+Do not rename the base folder! The code of Balmorel needs to be able to locate the base/addons and base/data folders or it will generate errors.
+:::
diff --git a/base/documentation/gh-pages/img/GAMS_Studio_Setup.jpg b/base/documentation/gh-pages/img/GAMS_Studio_Setup.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..6b1ff361a961921c044e11bd9184cde169b2006a
GIT binary patch
literal 61968
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