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

@@ -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

.gitignore

@@ -26,4 +26,5 @@ base/data/README.md
 *.log~1
 *.log~2
 *.log~3
+build
 %batfileMERGEWITHBASE%

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

base/documentation/gh-pages/about.md

@@ -0,0 +1,3 @@
+# About this code
+
+This documentation is under construction

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
+
+
+```

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

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;
+}

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

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
+```

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. 
+:::

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.
+<div style="display: flex; justify-content: center;">
+    <iframe width="560" height="315" src="https://www.youtube.com/embed/zwHoo5zLm6g?si=_9gCkqq1ugRf2g30" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+</div>
+<br>

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
+```

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.

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.
+:::

base/documentation/gh-pages/index.md

@@ -0,0 +1,31 @@
+# Balmorel
+Balmorel is an open-source, bottom-up partial equilibrium energy system model[^1]. It has traditionally been applied to investigate decarbonisation pathways of sector-coupled energy systems[^2], infrastructure[^3], renewable fuel production[^4] and more. Results and framework has been validated against other open-source models[^5] [^6]. 
+
+A quick tutorial on how to get started can be found [here](get_started.md), and the full documentation can be found [here](https://github.com/balmorelcommunity/Balmorel/blob/master/base/documentation/TheBalmorelModelStructure-BMS301.pdf).
+
+```{toctree}
+:maxdepth: 1
+:caption: Balmorel
+:hidden:
+
+get_started
+addons
+pre_processing
+running_on_hpc
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Reference
+:hidden:
+
+about
+Full Documentation <https://github.com/balmorelcommunity/Balmorel/blob/master/base/documentation/TheBalmorelModelStructure-BMS301.pdf>
+```
+
+[^1]: Wiese, Frauke, Rasmus Bramstoft, Hardi Koduvere, Amalia Rosa Pizarro Alonso, Olexandr Balyk, Jon Gustav Kirkerud, Åsa Grytli Tveten, Torjus Folsland Bolkesjø, Marie Münster, and Hans V. Ravn. “Balmorel Open Source Energy System Model.” Energy Strategy Reviews 20 (2018): 26–34. [https://doi.org/10.1016/j.esr.2018.01.003](https://doi.org/10.1016/j.esr.2018.01.003).
+[^2]: Gea-Bermúdez, Juan, Ida Græsted Jensen, Marie Münster, Matti Koivisto, Jon Gustav Kirkerud, Yi-kuang Chen, and Hans Ravn. “The Role of Sector Coupling in the Green Transition: A Least-Cost Energy System Development in Northern-Central Europe towards 2050.” Applied Energy 289 (May 2021): 116685. [https://doi.org/10.1016/j.apenergy.2021.116685](https://doi.org/10.1016/j.apenergy.2021.116685).
+[^3]: Kountouris, Ioannis, Rasmus Bramstoft, Theis Madsen, Juan Gea-Bermúdez, Marie Münster, and Dogan Keles. “A Unified European Hydrogen Infrastructure Planning to Support the Rapid Scale-up of Hydrogen Production.” Nature Communications 15, no. 1 (June 29, 2024): 5517. [https://doi.org/10.1038/s41467-024-49867-w](https://doi.org/10.1038/s41467-024-49867-w).
+[^4]: Bramstoft, Rasmus, Amalia Pizarro-Alonso, Ida Græsted Jensen, Hans Ravn, and Marie Münster. “Modelling of Renewable Gas and Renewable Liquid Fuels in Future Integrated Energy Systems.” Applied Energy 268 (June 15, 2020): 114869. [https://doi.org/10.1016/j.apenergy.2020.114869](https://doi.org/10.1016/j.apenergy.2020.114869).
+[^5]: Ouwerkerk, Jonas van, Karlo Hainsch, Soner Candas, Christoph Muschner, Stefanie Buchholz, Stephan Günther, Hendrik Huyskens, et al. “Comparing Open Source Power System Models - A Case Study Focusing on Fundamental Modeling Parameters for the German Energy Transition.” Renewable & Sustainable Energy Reviews 161, no. 112331 (2022). [https://doi.org/10.1016/j.rser.2022.112331](https://doi.org/10.1016/j.rser.2022.112331).
+[^6]: Candas, Soner, Christoph Muschner, Stefanie Buchholz, Rasmus Bramstoft, Jonas van Ouwerkerk, Karlo Hainsch, Konstantin Löffler, et al. “Code Exposed: Review of Five Open-Source Frameworks for Modeling Renewable Energy Systems.” Renewable and Sustainable Energy Reviews 161 (June 2022): 112272. [https://doi.org/10.1016/j.rser.2022.112272](https://doi.org/10.1016/j.rser.2022.112272).

base/documentation/gh-pages/pre_processing.md

@@ -0,0 +1,7 @@
+# Pre-Processing
+
+The data format of Balmorel is .inc-files. There are different approaches to pre-processing, the simplest being creating a new .inc-file through GAMS Studio. [xls2gams](https://www.gams.com/latest/docs/T_XLS2GMS.html) Can be used to produce .inc-files from excel sheets, and for python we recommend the [IncFile class](https://balmorelcommunity.github.io/pybalmorel/autoapi/pybalmorel/classes/index.html#pybalmorel.classes.IncFile) from our [pybalmorel](https://balmorelcommunity.github.io/pybalmorel) package.
+
+```{toctree}
+:maxdepth: 1
+```

base/documentation/gh-pages/running_on_hpc.md

@@ -0,0 +1,13 @@
+# Running on HPC
+
+It will probably be necessary to run Balmorel on a high-performance computer (HPC).
+
+This section will explain how to do this on the [LSF 10 Cluster](https://www.hpc.dtu.dk/?page_id=2513) of the Technical University of Denmark, but the instructions may also be applicable to other Linux-based clusters. Note that obviously only students and employees of DTU can access this specific cluster. 
+
+```{toctree}
+:maxdepth: 1
+
+running_on_hpc/installation.md
+running_on_hpc/access.md
+running_on_hpc/submitting_a_job.md
+```