From e9a2de01a438b23ef8123066d26a699ea502ff6b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tonn=20R=C3=BCter?= <tonnru@pik-potsdam.de>
Date: Tue, 14 Jan 2025 18:03:42 +0100
Subject: [PATCH] Updated tutorial section on .profile/.bashrc

---
 tutorials/02_RunningREMIND.md | 54 ++++++++++++++++++++++++-----------
 1 file changed, 37 insertions(+), 17 deletions(-)

diff --git a/tutorials/02_RunningREMIND.md b/tutorials/02_RunningREMIND.md
index f94acc5bb..5952e1431 100644
--- a/tutorials/02_RunningREMIND.md
+++ b/tutorials/02_RunningREMIND.md
@@ -1,13 +1,13 @@
 Start running REMIND with default settings
 ================
-Felix Schreyer (<felix.schreyeru@pik-potsdam.de>), Lavinia Baumstark (<baumstark@pik-potsdam.de>), David Klein (<dklein@pik-potsdam.de>)
+Felix Schreyer (<felix.schreyeru@pik-potsdam.de>), Lavinia Baumstark (<baumstark@pik-potsdam.de>), David Klein (<dklein@pik-potsdam.de>), Tonn Rüter (<tonn.rueter@pik-potsdam.de>)
 30 April, 2019
 
 - [Start running REMIND with default settings](#start-running-remind-with-default-settings)
 - [1. Your first run](#1-your-first-run)
   - [Default Configurations](#default-configurations)
-  - [Accessing the cluster](#accessing-the-cluster)
-  - [Adjust the .profile](#adjust-the-profile)
+  - [Accessing the HPC](#accessing-the-cluster)
+  - [HPC terminal configuration: Adjust `.profile` & `.bashrc`](#adjust-the-profile)
   - [Starting the run](#starting-the-run)
   - [Restarting runs](#restarting-runs)
 - [2. What happens during a REMIND run?](#2-what-happens-during-a-remind-run)
@@ -20,7 +20,7 @@ Felix Schreyer (<felix.schreyeru@pik-potsdam.de>), Lavinia Baumstark (<baumstark
 
 # 1. Your first run
 
-This section will explain how you start your first REMIND run on PIK's cluster (starting REMIND on other machines is theoretically possible but works slightly different depending on input data availability and operating system configuration).
+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.
 
 ## Default Configurations
 
@@ -39,31 +39,51 @@ c. The FLAGS section contains compilation flags (setGlobals) for further configu
 
 d. The last part includes all model parts from the core and modules.
 
-## Accessing the cluster
+## Accessing the HPC
 
-As normal runs with REMIND take quite a while (from a couple of hours to several days), you normally don't want to run them locally (i.e., on your own machine) but on the cluster provided by the IT-services. The first step is to access the cluster. In general, there are three ways how to access the cluster:
+Follow the instructions [in the PIK-internal Wiki](https://gitlab.pik-potsdam.de/rse/rsewiki/-/wikis/Cluster-Access) on how to access the HPC.
 
-1. The main tool to work on the cluster is the console. This is provided by PuTTY (for most Windows users) or simply a terminal (other operating systems)
-2. WinSCP allows you to access files and do file operations 
-3. Windows Explorer, click on network drive (only possible if you are in PIK LAN), same as WinSCP
+## HPC terminal configuration: Adjust `.profile` & `.bashrc`
 
-They all have their upsides and downsides. Don't worry! If they are new to you, you will figure out what is best for which kind of task after some time and get more familiar just by your practice. Using either the console or the network drive in Windows Explorer, the first step is:
+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
 
-## Adjust the .profile
+```bash
+nano ~/.profile
+```
 
-First, log onto the cluster via WinSCP and open the file `/home/username/.profile` in a text editor. Add these two lines and save the file.
+Add these lines in the text editor:
 
-``` bash
-module load piam
+```bash
 umask 0002
+
+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. 
+
+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
+
+```bash
+nano ~/.bashrc
+```
+
+and add `umask 0002` as the first line. A typical `.bashrc` file might look like
+
+```bash
+umask 0002 # Must be the first line
+
+# Additional typical .bashrc configurations like aliases must come after
+alias ll="ls -la"
 ```
-The first line loads the `piam` environment once you log onto the cluster via console the next time. This environment will enable you to manage the runs that you do on the cluster. The second line makes sure the files you create on the cluster will be writable by your coworkers. Next, you need to specify the kind of run you would like to do.
+
+Again save the file by pressing <kbd>Ctrl</kbd> + <kbd>X</kbd> and confirm with <kbd>Enter</kbd>.
 
 ## 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 recommended not to use the `home` directory. For your first experiments you can use a subfolder of the `/p/tmp/YourPIKName/` directory (only stored for 3 months).
+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.
 
-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/YourPIKName/` 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)).
+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)).
 
 Go to your REMIND main folder (i.e. it contains subfolders such as `config`, `core`, and `modules`) and start a REMIND run by typing: