Merge branch 'master' of https://github.com/xsdk-project/HandsOnLessons

Author: markcmiller86

lessons/atpesc-instructions.md

@@ -1,17 +1,19 @@
 
 # Instructions for Numerical Package Hands-on
 
+ATPESC participants will work in groups of 2 for hands-on exercises.  Forming groups of 2 helps us to cut in half the number of IT issues that may arise during hands-on exercises.  Moreover, [pair programming](https://en.wikipedia.org/wiki/Pair_programming) (the practice of having two people work together on one machine, each taking turns between typing and commenting) results in real-time code review, which [research has shown](http://www.sciencedirect.com/science/article/pii/S0950584909000123) results in higher productivity. If you are not using an OSX or Linux laptop, it would be best to try to pair with someone who is.  
+
 ## Basic Instructions
 
-Hands-on exercises are primarily run on cooley cluster at ALCF. Please do the following initial setup
+Hands-on exercises are primarily run on the [Cooley](https://www.alcf.anl.gov/user-guides/cooley) cluster at ALCF. Please do the following initial setup.
 
- - login to cooley
+ - Login to Cooley
 ```
 ssh -C -X -Y username@cooley.alcf.anl.gov
 ```
    - `-C` means to use compression
    - `-X` means to forward X11, `-Y` means _trusted_ X11 forwarding
- - setup software environment on cooley by adding the following to  _~/.soft.cooley_ (preferably before `@default` line)
+ - Setup software environment on Cooley by adding the following to  _~/.soft.cooley_ (preferably before `@default` line)
 ```
 +mvapich2
 +gcc-4.8.1
@@ -20,16 +22,16 @@ PATH+=/projects/ATPESC2017/NumericalPackages/spack/bin
 MPIEXEC_OMPI=/projects/ATPESC2017/NumericalPackages/spack/opt/spack/linux-rhel6-x86_64/gcc-4.8.1/openmpi-2.1.1-5b4k4f3vzgwz5qmektcqja2av4c4bjrg/bin/mpiexec
 MPIEXEC=/soft/libraries/mpi/mvapich2/gcc/bin/mpiexec
 ```
-  - run the following command to make the above change to _~/.soft.cooley_ effective
+  - Run the following command to make the above change to _~/.soft.cooley_ effective.
 ```
 resoft
 ```
-  - obtain 3 compute nodes in _interactive_ (`-I`) mode to run the hands on exercises by running the following `qsub` command...
+  - Obtain 2 compute nodes in _interactive_ (`-I`) mode to run the hands on exercises by running the following `qsub` command...
 ```
-qsub -I -n 3 -t 720 -A ATPESC2017
+qsub -I -n 2 -t 720 -A ATPESC2017
 ```
      - **Note**: Once the allocation has started, you will be logged into
-       the reserved nodes and see a new prompt with a differnt hostname such as
+       the reserved nodes and see a new prompt with a different hostname such as
        `cc122`.
      - The allocation should remain _reserved_ for the whole day. However,
        you can delete it simply by logging out of the interactive shell it put you in.
@@ -47,7 +49,7 @@ Some of the hands-on exercises have optional visualization instructions
 and use a variety of visualization tools.
 
 Getting a room of more than 70 people with different laptops working with
-remote visualization from cooley is not something either our tight agenda or
+remote visualization from Cooley is not something either our tight agenda or
 our staff are prepared to support. In addition, where necessary, the hands-on
 leader(s) will demonstrate the use of some tools and learners can follow 
 along at those points.
@@ -67,15 +69,15 @@ exercises.
     paraview, VisIt and glvis.
 
 We have a devloped a script (to be run on your laptop) that can help with
-setting up a VNC connection to cooley. It can work on MacOS, and with some
-Linux VNC clients (vinagre, vncviewer). However the script is fragile and
-might not work with everyones setup - hence this is optional. This script
-will do several things
+setting up a VNC connection to Cooley. It can work on MacOS, and with some
+Linux VNC clients (vinagre, vncviewer). However, the script is fragile and
+might not work with everyone's setup - hence this is optional. This script
+will do several things:
 
- - Logs you into cooley once with your token
- - Sets up SSH Control Master so you only have to log into cooley with your token once for the whole day and password-less will work thereafter
- - Reserves 3 nodes for 12h on cooley.
- - Sets up a VNC connection to those nodes
+ - Log you into cooley once with your token.
+ - Set up SSH Control Master so you have to log into Cooley with your token only once for the whole day and password-less will work thereafter.
+ - Reserve 3 nodes for 12h on Cooley.
+ - Set up a VNC connection to those nodes.
 
    Mac and Linux users are welcome download and run this script to
    setup a VNC connection. Doing so will permit quick use of tools
@@ -106,16 +108,16 @@ Now, try running the script
 ```
 
 ### Notes
-  - If allocating nodes via this script - please deallocate nodes that you might have previously allocated
+  - If allocating nodes via this script, please deallocate nodes that you might have previously allocated
     by simply logging out of the interactive allocation.
 
 ### Troubleshooting
-  - If you have a different preferred Linux VNC client - you should be able to use it to connect to the VNC connection that is already setup by this script. For example,
+  - If you have a different preferred Linux VNC client, you should be able to use it to connect to the VNC connection that is already setup by this script. For example,
 ```
 krdc vnc://localhost:22590
 ```
   - When rerunning the script - if the ssh command to setup VNC tunnel fails - you
-    might have to kill the _ssh control master_ process and restart again. Its easiest
+    might have to kill the _ssh control master_ process and restart again. It's easiest
     to simply find all ssh logins to cooley and kill them
 ```
 $ ps -ef | grep cooley