deploy: d89f89e

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: b3ee2d639a3243268a63e9222e7c6371
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/about.md.txt

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

_sources/addons.md.txt

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

_sources/get_started.md.txt

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

_sources/get_started/installation.md.txt

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

_sources/get_started/outputs.md.txt

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

_sources/get_started/running_balmorel.md.txt

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

_sources/get_started/scenario_setup.md.txt

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

_sources/get_started/structure.md.txt

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

_sources/index.md.txt

@@ -0,0 +1,32 @@
+# 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
+versions
+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).

_sources/pre_processing.md.txt

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

_sources/running_on_hpc.md.txt

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

_sources/running_on_hpc/access.md.txt

@@ -0,0 +1,43 @@
+# Accessing the Cluster
+
+A general guide for accessing the DTU clusters through the so-called login nodes can be found [here](https://www.hpc.dtu.dk/?page_id=2501). We go through examples using PuTTY for accessing these nodes below.
+
+Note that you should not transfer large files via the login nodes (e.g. login.gbar.dtu.dk), but through the transfer nodes (e.g. transfer.gbar.dtu.dk). A [general guide](https://www.hpc.dtu.dk/?page_id=4377) exists for transferring files to and from the cluster, and we provided an example of how to access the transfer node using WinSCP below. 
+
+:::{warning}
+- Remember to be on a DTU network, either by physically being at DTU or through a VPN, such as [Cisco VPN](https://itswiki.compute.dtu.dk/index.php/Cisco_VPN).
+- Do not transfer large files or run resource intensive programs directly on the login nodes!<br>
+See [WinSCP Example](#winscp-example) for how to transfer large files and [Job Submission](submitting_a_job.md) for submitting resource intensive programs.
+:::
+
+## PuTTY Example
+
+We will use PuTTY to explain how to submit jobs. When starting PuTTY, a graphical user interface (GUI) appears as illustrated in the [Figure](putty_login) below.
+:::{figure} ../img/putty_login.jpg 
+:name: putty_login
+:alt: Logging into PuTTY
+:width: 70% 
+:align: center
+The graphical user interface that appears when starting up PuTTY. 
+:::
+Type login.gbar.dtu.dk as the host-name and enter. This results in a command prompt that asks for your username, see the [code snippet](putty_login_cli) below. Write your DTU initials or student number. This is followed by a password prompt. Note that it does not show your password as you type it for security purposes, but your keystrokes are being registered. Type your DTU password confidently and press enter. You can also (in Windows) copy your password and paste it into the password prompt with shift + enter (not ctrl + V).
+
+
+:::{code-block} console
+:name: putty_login_cli
+:caption: The prompts appearing after entering the PuTTY setup. 
+login as: user_name
+[email protected]'s password:
+:::
+
+
+## WinSCP Example
+
+When you open WinSCP, the GUI illustrated in the [Figure](winscp_login) below will appear. Type your user name followed by @transfer.gbar.dtu.dk in the "Host name" form and press enter. Once again, you will need to write your DTU password. You will then enter the main WinSCP GUI, where you can browse local files in the left window and HPC files in the right window. Files can be transferred by dragging and dropping between the two windows.
+:::{figure} ../img/winscp_login.jpg 
+:name: winscp_login
+:alt: Logging into PuTTY
+:width: 100% 
+:align: center
+The graphical user interface that appears when starting up WinSCP. 
+:::

_sources/running_on_hpc/installation.md.txt

@@ -0,0 +1,9 @@
+# Installation
+
+We will describe how to transfer files through [WinSCP](https://winscp.net/eng/index.php) and submit jobs through [PuTTY](https://putty.org/), but it is possible to access the clusters in many ways, such as through [Visual Studio Code](https://code.visualstudio.com/docs/remote/ssh) or [ThinLinc](https://www.gbar.dtu.dk/index.php/faq/43-thinlinc).
+
+:::{admonition} Software Requirements 
+- Download and install [WinSCP](https://winscp.net/eng/index.php) for transferring files to the HPC.
+- Download and install [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) for submitting jobs.
+- Download and install [Cisco VPN](https://itswiki.compute.dtu.dk/index.php/Cisco_VPN) to access DTU network from home.
+:::