Update 02_RunningREMIND.md

tutorials/02_RunningREMIND.md

@@ -4,21 +4,21 @@ Felix Schreyer (<felix.schreyeru@pik-potsdam.de>), Lavinia Baumstark (<baumstark
 30 April, 2019
 
 - [Start running REMIND with default settings](#start-running-remind-with-default-settings)
-- [1. Your first run](#1-your-first-run)
+- [Your first run](#your-first-run)
   - [Default Configurations](#default-configurations)
   - [Accessing the HPC](#accessing-the-hpc)
-  - [HPC terminal configuration: Adjust `.profile` & `.bashrc`](#hpc-terminal-configuration-adjust-profile-bashrc)
+  - [HPC terminal configuration: Adjust `.profile` and `.bashrc`](#hpc-terminal-configuration-adjust-profile-and-bashrc)
   - [Starting the run](#starting-the-run)
   - [Restarting runs](#restarting-runs)
-- [2. What happens during a REMIND run?](#2-what-happens-during-a-remind-run)
-- [3. What happens once you start REMIND on the cluster?](#3-what-happens-once-you-start-remind-on-the-cluster)
-  - [a) renv Setup](#a-renv-setup)
-  - [b) Input Data Preparation](#b-input-data-preparation)
-  - [c) Optimization](#c-optimization)
-  - [d) Output Processing](#d-output-processing)
+- [What happens during a REMIND run?](#what-happens-during-a-remind-run)
+- [What happens once you start REMIND on the cluster?](#what-happens-once-you-start-remind-on-the-cluster)
+  - [`renv` Setup](#renv-setup)
+  - [Input Data Preparation](#input-data-preparation)
+  - [Optimization](#optimization)
+  - [Output Processing](#output-processing)
 
 
-# 1. Your first run
+# Your first run
 
 This section will explain how you start your first REMIND run on the Potsdam Institute for Climate Impact Research (PIK) High Performance Cluster (HPC). Running REMIND on other hosts is theoretically possible but works slightly different depending on input data availability and operating system configuration.
 
@@ -43,9 +43,9 @@ d. The last part includes all model parts from the core and modules.
 
 Follow the instructions [in the PIK-internal Wiki](https://gitlab.pik-potsdam.de/rse/rsewiki/-/wikis/Cluster-Access) on how to access the HPC.
 
-## HPC terminal configuration: Adjust `.profile` & `.bashrc`
+## HPC terminal configuration: Adjust `.profile` and `.bashrc`
 
-In order to ready your HPC session for REMIND operation, you'll need to have a properly configured `.profile` file in your HPC home folder. Log into the cluster, then type
+In order to ready your HPC session for REMIND operation, you'll need to have a properly configured `.profile` file in your HPC home folder. Log into the HPC, then type
 
 ```bash
 nano ~/.profile
@@ -60,7 +60,7 @@ source /p/system/modulefiles/defaults/piam/module_load_piam
 module load anaconda/2024.10
 ```
 
-Save the file and exit the editor by pressing <kbd>Ctrl</kbd> + <kbd>X</kbd> and confirm with <kbd>Enter</kbd>. Please note that `umask 0002` needs to be the first line in the `.profile`! This lines makes sure the files you create on the cluster will be writable by your coworkers. The subsequent lines load the `piam` environment, ensuring that all system libraries necessary to run REMIND are available. 
+Save the file and exit the editor by pressing <kbd>Ctrl</kbd> + <kbd>X</kbd> and confirm with <kbd>Enter</kbd>. Please note that `umask 0002` needs to be the first line in the `.profile`! This lines makes sure the files you create on the HPC will be writable by your coworkers. The subsequent lines load the `piam` environment, ensuring that all system libraries necessary to run REMIND are available. 
 
 For compatibility reasons you'll also need to add a `.bashrc` file in your home folder. It's the same procedure as with `.profile`: Open the file
 
@@ -81,7 +81,7 @@ Again save the file by pressing <kbd>Ctrl</kbd> + <kbd>X</kbd> and confirm with
 
 ## Starting the run
 
-Open a console session on the cluster and create a folder on the cluster where you want to store REMIND. It is discouraged to use the `home` directory. For your first experiments you can use a subfolder of the `/p/tmp/<PIK user name>/` directory, but keep in mind that unused files are deleted after three months.
+Open a terminal session on the HPC and create a folder where you want to store REMIND. It is discouraged to use the `home` directory. For your first experiments you can use a subfolder of the `/p/tmp/<PIK user name>/` directory, but keep in mind that unused files are deleted after three months.
 
 In case you are using console and are not familiar with shell commands, google a list of basic shell commands such as `mkdir` to create a folder or `cd /p/tmp/<PIK user name>/` to switch to your folder. Download REMIND into a directory in this folder via `cloneremind` (see tutorial [00_Git_and_GitHub_workflow](00_Git_and_GitHub_workflow.md)).
 
@@ -135,7 +135,7 @@ Rscript start.R -r
 This will use the result of the previous optimization (`fulldata.gdx`) as input for the restart. Note that this will NOT continue the run from the last CONOPT iteration (which is impossible at the moment), but simply restart the run from the last `fulldata.gdx`. Accordingly, all outputs (like `full.lst`, gdx, etc) are overwritten if you do not first make a copy by hand.
 
 
-# 2. What happens during a REMIND run?
+# What happens during a REMIND run?
 
 This section will give some technical introduction into what happens after you have started a run. It will not be a tutorial, but rather an explanation of the different parts in the modeling routine. The whole routine is illustrated in Figure 1. The core of the model is the optimization written in GAMS. However, there is some pre-processing of the input data and some post-processing of the output data using R scripts.
 
@@ -144,16 +144,16 @@ This section will give some technical introduction into what happens after you h
 REMIND modeling routine
 </p>
 
-# 3. What happens once you start REMIND on the cluster?
+# What happens once you start REMIND on the cluster?
 
 Let us go through each of the stages and briefly describe what happens:
 
-## a) renv Setup
+## `renv` Setup
 REMIND is using renv for R package library management, see [the REMIND renv tutorial](11_ManagingRenv.md) for details. When starting a run the main renv is essentially copied to the run folder which ensures that the run is always using the same package versions for reproducibility and packages cannot become corrupt because of global package updates.
 
 The R libraries required for indput data preparation and output processing (e.g. **madrat**, **mrremind** and **remind2**) are made available to the run this way.
 
-## b) Input Data Preparation
+## Input Data Preparation
 
 The optimization in REMIND requires a lot of input data. For example, the model needs to know energy production capacities per region for its initial time steps. Furthermore, it builds on GDP, population and energy demand projections that are results of other models. These kind of data are stored on the cluster in
 
@@ -172,7 +172,7 @@ cfg$inputRevision
 ```
 the name of the needed input data is constructed. It is checked whether those input data are already available. If not they are automatically downloaded from `/p/projects/rd3mod/inputdata/output/` and distributed.
 
-## c) Optimization
+## Optimization
 
 The actual REMIND is written in GAMS, a programming software to numerically solve optimization problems. The GAMS scripts are *.gms* files that you can find under the `core` (main part of the model) and the `modules` directories (subparts of the model). The general structure of the GAMS code is depicted in Figure 2. At each stage (e.g. *sets*), GAMS runs through the respective *.gms* files of the core and all chosen module realisations of that stage (`core/sets.gms` -> `modules/01_macro/sets.gms`, -> `modules/02_welfare/sets.gms` -> ...) before going to the next stage. The stages *bounds*, *presolve*, *solve* and *postsolve* are run in a loop that is followed by the final stage *output*.
 
@@ -183,7 +183,7 @@ GAMS code structure
 
 Fundamentally, we distinguish between two kinds of variables: variables (starting with *v_*) and parameters (starting with *p_*). Parameters are fixed (exogenous data in economists' lingo), while variables are free within a certain range and can be adjusted to maximize the objective function of the optimization problem (endogenous variables in economist's lingo). However, there are many constraints that fix relations between the variables and parameters. Within the remaining solution space, the optimization procedure tries to find the maximum of the objective function. The output file of the optimization is the **fulldata.gdx** which is under `output` in the folder of your REMIND run. You can open it, for instance, with GAMS IDE or load it into `R` using the command  `readGDX()` (see details below). In the file, you can find, among other things, the optimal levels of the variables (`variable.l`) and all the predefined parameter values.
 
-## d) Output Processing
+## Output Processing
 
 The output processing works with a number of R functions from the **[remind2](https://github.com/pik-piam/remind2/)** package (most of them start with `report... .R`). The wrapper function **[convGDX2MIF.R](https://github.com/pik-piam/remind2/blob/master/R/convGDX2MIF.R)** writes the most relevant output into the so-called **.mif** file. Again, it is a table that you can open in Excel for example. You find under `output` in the folder of your REMIND run as