SERGHEI-tutorial.md

@@ -25,7 +25,27 @@ SERGHEI is available at https://gitlab.com/serghei-model/serghei. You can simply
 
 ## Get source code
 
-To get the source code, open a terminal, and while in your account's home directory, simply **clone** the repository
+When you first login, your current directory is your home directory. You could get the source code and put it here, but best practice is to store it in the `project` folder. We first navigate there
+
+```
+cd /p/project/training2226
+```
+
+This is the directory where all of our project's resources should be located. It has a much larger storage quota than your home directory.
+To keep things tidy in here, first create a directory for you, with your user name. 
+
+```
+mkdir $USER
+```
+
+`mkdir` creates a new directory with the name returned by the environment variable `USER`, which returns your username. You can of course directly type your username. 
+
+Let's now move into this new directory.
+```
+cd $USER
+```
+
+To get the source code, simply **clone** the repository here
 
 `git clone https://gitlab.com/serghei-model/serghei.git`
 
@@ -35,13 +55,16 @@ To get the source code, open a terminal, and while in your account's home direct
 
 You can now navigate to the SERGHEI root directory `cd serghei`
 
-Check the path to the current directory using the `pwd` command. This should return be the absolute path to the local working copy of the repository (i.e., the `serghei` directory).
+Check the path to the current directory using the `pwd` command. This should return be the absolute path to the local working copy of the repository (i.e., the `serghei` directory). This should look something like
+```
+/p/project/training2226/username1/serghei
+```
 
 # 3. Preparing the environment
 
-## Environmental variable
+## Environment variable
 
-Create an environmental variable for the path to the local working copy of the repository
+Create an environment variable for the path to the local working copy of the repository
 
 `export SERGHEIPATH=$(pwd)`
 
@@ -49,13 +72,15 @@ This command exports the current path (which is returned by the `pwd` command) i
 
 You can check if this variable is set by running
 
-`echo $SERGHEIPATH`
+```
+echo $SERGHEIPATH
+```
 
 **Optional but convenient**
 
-A way setting this in a persisting way is to define it in your local `.bashrc` file. Edit the `.bashrc` file in your home folder
+A way setting this in a persisting way is to define it in your local `.bash_profile` file. Edit the `.bash_profile` file in your home folder
 
-`vim ~/.bashrc`
+`vim ~/.bash_profile`
 
 and include a new line which includes the path to `serghei` (which you can copy from the `pwd` output).
 
@@ -82,7 +107,7 @@ To find a module try
 
 `module spider gcc`
 
-In this way you can find the formal name of the module and the versions available in the system.
+In this way you can find the formal name of the module and the versions available in the system. You can navigate the text with the arrow keys, and also exit back to the terminal pressing `q`.
 
 To load the GCC module try
 
@@ -90,7 +115,7 @@ To load the GCC module try
 
 Try to do the same for the Parastation MPI and the Parallel NetCDF modules. Use `module spider` to find the modules, and `module load` to load them.
 
-Like the environmental variable before, the **environment** you have prepared by loading these modules will not survive when you log out or close your terminal, in which case you will have to repeat this procedure.
+Like the environment variable before, the **environment** you have prepared by loading these modules will not survive when you log out or close your terminal, in which case you will have to repeat this procedure.
 
 It is therefore practical to write a script that will make this easier. This of course already exists for SERGHEI, and you can find it in the `serghei/machines` folder. Here you will find a number of scripts which load the modules required by SERGHEI for several machines.
 
@@ -104,7 +129,7 @@ If all goes well, we now should have the environment ready. You can check which
 
 ### Getting Kokkos
 
-Kokkos is available in GitHub at [https://github.com/kokkos/kokkos.git](https://github.com/kokkos/kokkos.git). To clone the Kokkos repository, follow a analogous procedure to what was done to clone SERGHEI into your home directory.
+Kokkos is available in GitHub at [https://github.com/kokkos/kokkos.git](https://github.com/kokkos/kokkos.git). To clone the Kokkos repository, follow a analogous procedure to what was done to clone SERGHEI. Make sure you that Kokkos is cloned inside of the `serghei` directory.
 
 Usually dependencies need to be built in the system (so that they are available locally as a binary, or through a module). For SERGHEI, Kokkos does not need to be built beforehand. It will be built when we build SERGHEI, if the path to Kokkos is properly set in the next step.
 
@@ -116,7 +141,7 @@ Usually dependencies need to be built in the system (so that they are available
 cd $SERGHEIPATH/src
 ```
 
-2. Open the `Makefile`. This is a script which controls how SERGHEI is compiled. Note that there are some definitions early on. In particular `KOKKOS_PATH` and `KOKKOS_SRC_PATH` are defined as a function of `HOME`. Note that the `Makefile` assumes that `KOKKOS_PATH` will be in `HOME` path. `HOME` is an environmental variable which contain the path to your home directory. Exit the file and check what your HOME environmental variable contains.
+2. Open the `Makefile`. This is a script which controls how SERGHEI is compiled. Note that there are some definitions early on. In particular `KOKKOS_PATH` and `KOKKOS_SRC_PATH` are defined as a function of `HOME`. Note that the `Makefile` assumes that `KOKKOS_PATH` will be in `HOME` path. `HOME` is an environment variable which contain the path to your home directory. Exit the file and check what your HOME environment variable contains.
 
 3. Now we will use `make` to compile and build. Running `make` attempts to read the `Makefile`, which you can see exists in this directory. If you try to run `make` in a different directory which does not contain a `Makefile` you will get an error. `make` support parallel threads, so that the compilation is faster. For example
 
@@ -204,7 +229,7 @@ You can check if your job is in the queue, or already running, with
 squeue -u $USER
 ```
 
-which uses the `USER` environmental variable (your username effectively) to query the system for active jobs.  
+which uses the `USER` environment variable (your username effectively) to query the system for active jobs.  
 
 If things go well, you should get an output folder and inside it a `log.out` file. 
 You will also get a `slurm` job report showing everything that happened behind the scenes and not shown in the terminal while the job was launched in the compute nodes. Inspecting the contents of this file which also show if there was an error or a successful run. If you had errors, try troubleshooting through them.