ChemWiki - User contributions [en]

Using the cluster : tutorial, examples

2012-06-25T15:29:24Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. You should be able to start using the cluster after you get your college username and password.
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>
The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.
<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.
<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.
When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.
You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.
If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.

<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>
Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>
-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).

----
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.

If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.
To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
<h1>Your results</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.
----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

----
<h1>Using GaussView in the cluster</h1>
You should be familiar with using GaussView on your Mac. GaussView can also be used in the cluster. To open the program, start up the '''X11''' application and type 'xhost +', then press enter.
In a shell where you are logged in to the cluster, type 'module load gaussian' followed by 'gview &'.
<pre>
-bash-4.1$ module load gaussian
-bash-4.1$ gview &
[1] 9486
</pre>
----
<h3>Viewing output files in GaussView</h3>
It may be that you have written an input file in vim on the cluster and submitted it to Gaussian (as described above), but want to view only the output on GaussView. To do this, start up GaussView and open the checkpoint file created as part of your job's output. By default the 'File Type' is set to 'Gaussian Input Files'; to view your checkpoint file, change this to 'Gaussian Checkpoint Files'.
----
<h3>Doing an entire job in GaussView</h3>
Just as on the Mac, you can also do an entire job from start to finish in GaussView. The input files are created in your HOME directory, so the output files will also be put there. You can move them to your WORK directory using the 'mv' command.

----
<h1>Connecting the cluster to your Mac</h1>
You may wish to copy a file that you have saved on the cluster to your Mac, or you may wish to copy a file on your Mac to the cluster.
----
<h3>Copy a file from your Mac to your account on the cluster</h3>
This is done in a shell where you are not connected to the cluster. Use the 'scp' command, followed by the path to the file on your Mac. In the same line, login to the cluster and specify where on the cluster you would like the copy to be sent to.
<pre>
intelimac1:~/g09 username$ scp /Users/username/g09/oxygen.com/ ns4912@login.cx1.hpc.ic.ac.uk:/home/ns4912
ns4912@login.cx1.hpc.ic.ac.uk's password:
oxygen.com 100% 203 0.2KB/s 00:00
</pre>
In this example, there a file called 'oxygen.com', which is saved in a folder called g09 in the user's area on the Mac. It is going to be copied to the user's area in the HOME directory on the cluster.
After typing your command, you are prompted for your password. After entering it, the file is copied to the cluster.
This can be double-checked when you log into the cluster.
<pre>
-bash-4.1$ pwd
/home/ns4912
-bash-4.1$ ls
bin oxygen.com test
</pre>
The file 'oxygen.com' now also appears in the user's area in the HOME directory on the cluster.
----
<h3>Copy a file from your account on the cluster to your Mac</h3>
Again, this is done in a shell where you are not connected to the cluster. The 'scp' command is also used here, but the order of phrases in your command is slightly different. In the example below, we will copy a file called 'ethane.chk' from the user's area in the WORK directory on the cluster to their area on the Mac. We will then check that the file has been successfully copied.
<pre>
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public g09 scripts
Documents Movies Pictures Sites h2o.rtf work
intelimac1:~ nafisa$ scp ns4912@login.cx1.hpc.ic.ac.uk:/work/ns4912/test/ethane.chk/ /Users/username/
ns4912@login.cx1.hpc.ic.ac.uk's password:
ethane.chk 100% 768KB 768.0KB/s 00:00
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public ethane.chk h2o.rtf work
Documents Movies Pictures Sites g09 scripts
</pre>
The file has been successfully copied to the Mac.

----
<h1>More about UNIX</h1>
This website lists classic UNIX commands: [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-25T15:20:53Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>
The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.
<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.
<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.
When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.
You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.
If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.

<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>
Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>
-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).

----
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.

If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.
To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
<h1>Your results</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.
----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

----
<h1>Using GaussView in the cluster</h1>
You should be familiar with using GaussView on your Mac. GaussView can also be used in the cluster. To open the program, start up the '''X11''' application and type 'xhost +', then press enter.
In a shell where you are logged in to the cluster, type 'module load gaussian' followed by 'gview &'.
<pre>
-bash-4.1$ module load gaussian
-bash-4.1$ gview &
[1] 9486
</pre>
----
<h3>Viewing output files in GaussView</h3>
It may be that you have written an input file in vim on the cluster and submitted it to Gaussian (as described above), but want to view only the output on GaussView. To do this, start up GaussView and open the checkpoint file created as part of your job's output. By default the 'File Type' is set to 'Gaussian Input Files'; to view your checkpoint file, change this to 'Gaussian Checkpoint Files'.
----
<h3>Doing an entire job in GaussView</h3>
Just as on the Mac, you can also do an entire job from start to finish in GaussView. The input files are created in your HOME directory, so the output files will also be put there. You can move them to your WORK directory using the 'mv' command.

----
<h1>Connecting the cluster to your Mac</h1>
You may wish to copy a file that you have saved on the cluster to your Mac, or you may wish to copy a file on your Mac to the cluster.
----
<h3>Copy a file from your Mac to your account on the cluster</h3>
This is done in a shell where you are not connected to the cluster. Use the 'scp' command, followed by the path to the file on your Mac. In the same line, login to the cluster and specify where on the cluster you would like the copy to be sent to.
<pre>
intelimac1:~/g09 username$ scp /Users/username/g09/oxygen.com/ ns4912@login.cx1.hpc.ic.ac.uk:/home/ns4912
ns4912@login.cx1.hpc.ic.ac.uk's password:
oxygen.com 100% 203 0.2KB/s 00:00
</pre>
In this example, there a file called 'oxygen.com', which is saved in a folder called g09 in the user's area on the Mac. It is going to be copied to the user's area in the HOME directory on the cluster.
After typing your command, you are prompted for your password. After entering it, the file is copied to the cluster.
This can be double-checked when you log into the cluster.
<pre>
-bash-4.1$ pwd
/home/ns4912
-bash-4.1$ ls
bin oxygen.com test
</pre>
The file 'oxygen.com' now also appears in the user's area in the HOME directory on the cluster.
----
<h3>Copy a file from your account on the cluster to your Mac</h3>
Again, this is done in a shell where you are not connected to the cluster. The 'scp' command is also used here, but the order of phrases in your command is slightly different. In the example below, we will copy a file called 'ethane.chk' from the user's area in the WORK directory on the cluster to their area on the Mac. We will then check that the file has been successfully copied.
<pre>
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public g09 scripts
Documents Movies Pictures Sites h2o.rtf work
intelimac1:~ nafisa$ scp ns4912@login.cx1.hpc.ic.ac.uk:/work/ns4912/test/ethane.chk/ /Users/username/
ns4912@login.cx1.hpc.ic.ac.uk's password:
ethane.chk 100% 768KB 768.0KB/s 00:00
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public ethane.chk h2o.rtf work
Documents Movies Pictures Sites g09 scripts
</pre>
The file has been successfully copied to the Mac.

----
<h1>More about UNIX</h1>
This website lists classic UNIX commands: [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-25T15:14:20Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>
The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.
<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.
<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.
When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.
You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.
If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.

<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>
Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>
-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).

----
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.
To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
<h1>Your results</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.
----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

----
<h1>Using GaussView in the cluster</h1>
You should be familiar with using GaussView on your Mac. GaussView can also be used in the cluster. To open the program, start up the '''X11''' application and type 'xhost +', then press enter.
In a shell where you are logged in to the cluster, type 'module load gaussian' followed by 'gview &'.
<pre>
-bash-4.1$ module load gaussian
-bash-4.1$ gview &
[1] 9486
</pre>
----
<h3>Viewing output files in GaussView</h3>
It may be that you have written an input file in vim on the cluster and submitted it to Gaussian (as described above), but want to view only the output on GaussView. To do this, start up GaussView and open the checkpoint file created as part of your job's output. By default the 'File Type' is set to 'Gaussian Input Files'; to view your checkpoint file, change this to 'Gaussian Checkpoint Files'.
----
<h3>Doing an entire job in GaussView</h3>
Just as on the Mac, you can also do an entire job from start to finish in GaussView. The input files are created in your HOME directory, so the output files will also be put there. You can move them to your WORK directory using the 'mv' command.

----
<h1>Connecting the cluster to your Mac</h1>
You may wish to copy a file that you have saved on the cluster to your Mac, or you may wish to copy a file on your Mac to the cluster.
----
<h3>Copy a file from your Mac to your account on the cluster</h3>
This is done in a shell where you are not connected to the cluster. Use the 'scp' command, followed by the path to the file on your Mac. In the same line, login to the cluster and specify where on the cluster you would like the copy to be sent to.
<pre>
intelimac1:~/g09 username$ scp /Users/username/g09/oxygen.com/ ns4912@login.cx1.hpc.ic.ac.uk:/home/ns4912
ns4912@login.cx1.hpc.ic.ac.uk's password:
oxygen.com 100% 203 0.2KB/s 00:00
</pre>
In this example, there a file called 'oxygen.com', which is saved in a folder called g09 in the user's area on the Mac. It is going to be copied to the user's area in the HOME directory on the cluster.
After typing your command, you are prompted for your password. After entering it, the file is copied to the cluster.
This can be double-checked when you log into the cluster.
<pre>
-bash-4.1$ pwd
/home/ns4912
-bash-4.1$ ls
bin oxygen.com test
</pre>
The file 'oxygen.com' now also appears in the user's area in the HOME directory on the cluster.
----
<h3>Copy a file from your account on the cluster to your Mac</h3>
Again, this is done in a shell where you are not connected to the cluster. The 'scp' command is also used here, but the order of phrases in your command is slightly different. In the example below, we will copy a file called 'ethane.chk' from the user's area in the WORK directory on the cluster to their area on the Mac. We will then check that the file has been successfully copied.
<pre>
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public g09 scripts
Documents Movies Pictures Sites h2o.rtf work
intelimac1:~ nafisa$ scp ns4912@login.cx1.hpc.ic.ac.uk:/work/ns4912/test/ethane.chk/ /Users/username/
ns4912@login.cx1.hpc.ic.ac.uk's password:
ethane.chk 100% 768KB 768.0KB/s 00:00
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public ethane.chk h2o.rtf work
Documents Movies Pictures Sites g09 scripts
</pre>
The file has been successfully copied to the Mac.

----
<h1>More about UNIX</h1>
This website lists classic UNIX commands: [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-25T15:13:48Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>
The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.
<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.
<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.
When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.
You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.
If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.

<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>
Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>
-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).

----
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.
To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
<h1>Your results</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.
----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

----
<h1>Using GaussView in the cluster</h1>
You should be familiar with using GaussView on your Mac. GaussView can also be used in the cluster. To open the program, start up the '''X11''' application and type 'xhost +', then press enter.
In a shell where you are logged in to the cluster, type 'module load gaussian' followed by 'gview &'.
<pre>

-bash-4.1$ module load gaussian
-bash-4.1$ gview &
[1] 9486

</pre>
----
<h3>Viewing output files in GaussView</h3>
It may be that you have written an input file in vim on the cluster and submitted it to Gaussian (as described above), but want to view only the output on GaussView. To do this, start up GaussView and open the checkpoint file created as part of your job's output. By default the 'File Type' is set to 'Gaussian Input Files'; to view your checkpoint file, change this to 'Gaussian Checkpoint Files'.
----
<h3>Doing an entire job in GaussView</h3>
Just as on the Mac, you can also do an entire job from start to finish in GaussView. The input files are created in your HOME directory, so the output files will also be put there. You can move them to your WORK directory using the 'mv' command.

----
<h1>Connecting the cluster to your Mac</h1>
You may wish to copy a file that you have saved on the cluster to your Mac, or you may wish to copy a file on your Mac to the cluster.
----
<h3>Copy a file from your Mac to your account on the cluster</h3>
This is done in a shell where you are not connected to the cluster. Use the 'scp' command, followed by the path to the file on your Mac. In the same line, login to the cluster and specify where on the cluster you would like the copy to be sent to.
<pre>
intelimac1:~/g09 username$ scp /Users/username/g09/oxygen.com/ ns4912@login.cx1.hpc.ic.ac.uk:/home/ns4912
ns4912@login.cx1.hpc.ic.ac.uk's password:
oxygen.com 100% 203 0.2KB/s 00:00
</pre>
In this example, there a file called 'oxygen.com', which is saved in a folder called g09 in the user's area on the Mac. It is going to be copied to the user's area in the HOME directory on the cluster.
After typing your command, you are prompted for your password. After entering it, the file is copied to the cluster.
This can be double-checked when you log into the cluster.
<pre>
-bash-4.1$ pwd
/home/ns4912
-bash-4.1$ ls
bin oxygen.com test
</pre>
The file 'oxygen.com' now also appears in the user's area in the HOME directory on the cluster.
----
<h3>Copy a file from your account on the cluster to your Mac</h3>
Again, this is done in a shell where you are not connected to the cluster. The 'scp' command is also used here, but the order of phrases in your command is slightly different. In the example below, we will copy a file called 'ethane.chk' from the user's area in the WORK directory on the cluster to their area on the Mac. We will then check that the file has been successfully copied.
<pre>
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public g09 scripts
Documents Movies Pictures Sites h2o.rtf work
intelimac1:~ nafisa$ scp ns4912@login.cx1.hpc.ic.ac.uk:/work/ns4912/test/ethane.chk/ /Users/username/
ns4912@login.cx1.hpc.ic.ac.uk's password:
ethane.chk 100% 768KB 768.0KB/s 00:00
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public ethane.chk h2o.rtf work
Documents Movies Pictures Sites g09 scripts
</pre>
The file has been successfully copied to the Mac.

----
<h1>More about UNIX</h1>
This website lists classic UNIX commands: [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-25T12:03:17Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>
The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.
<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.
<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.
When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.
You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.
If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.

<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>
Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>
-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).

--------
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.
To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
<h1>Your results</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.
----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

----
<h1>Using GaussView in the cluster</h1>
----
<h3>Viewing output files in GaussView</h3>
----
<h3>Doing an entire job in GaussView</h3>
----
<h1>Connecting the cluster to your Mac</h1>
You may wish to copy a file that you have saved on the cluster to your Mac, or you may wish to copy a file on your Mac to the cluster.
----
<h3>Copy a file from your Mac to your account on the cluster</h3>
This is done in a shell where you are not connected to the cluster. Use the 'scp' command, followed by the path to the file on your Mac. In the same line, login to the cluster and specify where on the cluster you would like the copy to be sent to.
<pre>
intelimac1:~/g09 username$ scp /Users/username/g09/oxygen.com/ ns4912@login.cx1.hpc.ic.ac.uk:/home/ns4912
ns4912@login.cx1.hpc.ic.ac.uk's password:
oxygen.com 100% 203 0.2KB/s 00:00
</pre>
In this example, there a file called 'oxygen.com', which is saved in a folder called g09 in the user's area on the Mac. It is going to be copied to the user's area in the HOME directory on the cluster.
After typing your command, you are prompted for your password. After entering it, the file is copied to the cluster.
This can be double-checked when you log into the cluster.
<pre>
-bash-4.1$ pwd
/home/ns4912
-bash-4.1$ ls
bin oxygen.com test
</pre>
The file 'oxygen.com' now also appears in the user's area in the HOME directory on the cluster.
----
<h3>Copy a file from your account on the cluster to your Mac</h3>
Again, this is done in a shell where you are not connected to the cluster. The 'scp' command is also used here, but the order of phrases in your command is slightly different. In the example below, we will copy a file called 'ethane.chk' from the user's area in the WORK directory on the cluster to their area on the Mac. We will then check that the file has been successfully copied.
<pre>
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public g09 scripts
Documents Movies Pictures Sites h2o.rtf work
intelimac1:~ nafisa$ scp ns4912@login.cx1.hpc.ic.ac.uk:/work/ns4912/test/ethane.chk/ /Users/username/
ns4912@login.cx1.hpc.ic.ac.uk's password:
ethane.chk 100% 768KB 768.0KB/s 00:00
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public ethane.chk h2o.rtf work
Documents Movies Pictures Sites g09 scripts
</pre>
The file has been successfully copied to the Mac.

----
<h1>More about UNIX</h1>
This website lists classic UNIX commands: [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-21T13:53:06Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>
The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.
<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.
<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.
When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.
You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.
If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.

<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>
Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>
-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).

--------
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.
To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
<h1>Your results</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.
----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

----
<h1>Connecting the cluster to your Mac</h1>
You may wish to copy a file that you have saved on the cluster to your Mac, or you may wish to copy a file on your Mac to the cluster.
----
<h3>Copy a file from your Mac to your account on the cluster</h3>
This is done in a shell where you are not connected to the cluster. Use the 'scp' command, followed by the path to the file on your Mac. In the same line, login to the cluster and specify where on the cluster you would like the copy to be sent to.
<pre>
intelimac1:~/g09 username$ scp /Users/username/g09/oxygen.com/ ns4912@login.cx1.hpc.ic.ac.uk:/home/ns4912
ns4912@login.cx1.hpc.ic.ac.uk's password:
oxygen.com 100% 203 0.2KB/s 00:00
</pre>
In this example, there a file called 'oxygen.com', which is saved in a folder called g09 in the user's area on the Mac. It is going to be copied to the user's area in the HOME directory on the cluster.
After typing your command, you are prompted for your password. After entering it, the file is copied to the cluster.
This can be double-checked when you log into the cluster.
<pre>
-bash-4.1$ pwd
/home/ns4912
-bash-4.1$ ls
bin oxygen.com test
</pre>
The file 'oxygen.com' now also appears in the user's area in the HOME directory on the cluster.
----
<h3>Copy a file from your account on the cluster to your Mac</h3>
Again, this is done in a shell where you are not connected to the cluster. The 'scp' command is also used here, but the order of phrases in your command is slightly different. In the example below, we will copy a file called 'ethane.chk' from the user's area in the WORK directory on the cluster to their area on the Mac. We will then check that the file has been successfully copied.
<pre>
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public g09 scripts
Documents Movies Pictures Sites h2o.rtf work
intelimac1:~ nafisa$ scp ns4912@login.cx1.hpc.ic.ac.uk:/work/ns4912/test/ethane.chk/ /Users/username/
ns4912@login.cx1.hpc.ic.ac.uk's password:
ethane.chk 100% 768KB 768.0KB/s 00:00
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public ethane.chk h2o.rtf work
Documents Movies Pictures Sites g09 scripts
</pre>
The file has been successfully copied to the Mac.

----
<h1>More about UNIX</h1>
This website lists classic UNIX commands: [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-21T13:52:49Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>
The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.
<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.
<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.
When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.
You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.
If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.

<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>
Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>
-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).

--------
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.
To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
<h1>Your results</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.
----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

----
<h1>Connecting the cluster to your Mac</h1>
You may wish to copy a file that you have saved on the cluster to your Mac, or you may wish to copy a file on your Mac to the cluster.
----
<h3>Copy a file from your Mac to your account on the cluster</h3>
This is done in a shell where you are not connected to the cluster. Use the 'scp' command, followed by the path to the file on your Mac. In the same line, login to the cluster and specify where on the cluster you would like the copy to be sent to.
<pre>
intelimac1:~/g09 username$ scp /Users/username/g09/oxygen.com/ ns4912@login.cx1.hpc.ic.ac.uk:/home/ns4912
ns4912@login.cx1.hpc.ic.ac.uk's password:
oxygen.com 100% 203 0.2KB/s 00:00
</pre>
In this example, there a file called 'oxygen.com', which is saved in a folder called g09 in the user's area on the Mac. It is going to be copied to the user's area in the HOME directory on the cluster.
After typing your command, you are prompted for your password. After entering it, the file is copied to the cluster.
This can be double-checked when you log into the cluster.
<pre>
-bash-4.1$ pwd
/home/ns4912
-bash-4.1$ ls
bin oxygen.com test
</pre>
The file 'oxygen.com' now also appears in the user's area in the HOME directory on the cluster.
----
<h3>Copy a file from your account on the cluster to your Mac</h3>
Again, this is done in a shell where you are not connected to the cluster. The 'scp' command is also used here, but the order of phrases in your command is slightly different. In the example below, we will copy a file called 'ethane.chk' from the user's area in the WORK directory on the cluster to their area on the Mac. We will then check that the file has been successfully copied.
<pre>
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public g09 scripts
Documents Movies Pictures Sites h2o.rtf work
intelimac1:~ nafisa$ scp ns4912@login.cx1.hpc.ic.ac.uk:/work/ns4912/test/ethane.chk/ /Users/username/
ns4912@login.cx1.hpc.ic.ac.uk's password:
ethane.chk 100% 768KB 768.0KB/s 00:00
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public ethane.chk h2o.rtf work
Documents Movies Pictures Sites g09 scripts
</pre>
The file has been successfully copied to the Mac.

----
<h1>More about UNIX</h1>
This website lists classic UNIX commands: [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-21T13:51:50Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>
The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.
<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.
<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.
When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.
You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.
If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.

<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>
Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>
-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).

--------
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.
To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
<h1>Output file and Checkpoint file</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.
----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

----
<h1>Connecting the cluster to your Mac</h1>
You may wish to copy a file that you have saved on the cluster to your Mac, or you may wish to copy a file on your Mac to the cluster.
----
<h3>Copy a file from your Mac to your account on the cluster</h3>
This is done in a shell where you are not connected to the cluster. Use the 'scp' command, followed by the path to the file on your Mac. In the same line, login to the cluster and specify where on the cluster you would like the copy to be sent to.
<pre>
intelimac1:~/g09 username$ scp /Users/username/g09/oxygen.com/ ns4912@login.cx1.hpc.ic.ac.uk:/home/ns4912
ns4912@login.cx1.hpc.ic.ac.uk's password:
oxygen.com 100% 203 0.2KB/s 00:00
</pre>
In this example, there a file called 'oxygen.com', which is saved in a folder called g09 in the user's area on the Mac. It is going to be copied to the user's area in the HOME directory on the cluster.
After typing your command, you are prompted for your password. After entering it, the file is copied to the cluster.
This can be double-checked when you log into the cluster.
<pre>
-bash-4.1$ pwd
/home/ns4912
-bash-4.1$ ls
bin oxygen.com test
</pre>
The file 'oxygen.com' now also appears in the user's area in the HOME directory on the cluster.
----
<h3>Copy a file from your account on the cluster to your Mac</h3>
Again, this is done in a shell where you are not connected to the cluster. The 'scp' command is also used here, but the order of phrases in your command is slightly different. In the example below, we will copy a file called 'ethane.chk' from the user's area in the WORK directory on the cluster to their area on the Mac. We will then check that the file has been successfully copied.
<pre>
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public g09 scripts
Documents Movies Pictures Sites h2o.rtf work
intelimac1:~ nafisa$ scp ns4912@login.cx1.hpc.ic.ac.uk:/work/ns4912/test/ethane.chk/ /Users/username/
ns4912@login.cx1.hpc.ic.ac.uk's password:
ethane.chk 100% 768KB 768.0KB/s 00:00
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public ethane.chk h2o.rtf work
Documents Movies Pictures Sites g09 scripts
</pre>
The file has been successfully copied to the Mac.

----
<h1>More about UNIX</h1>
This website lists classic UNIX commands: [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-21T13:33:13Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>
The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.
<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.
<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.
When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.
You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.
If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.

<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>
Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>
-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).

--------
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.
To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
<h1>Output file and Checkpoint file</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.
----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

----
<h1>Following on calculations on the cluster</h1>
As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file
<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file
<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity
</pre>

4) change the command in the new input file
o you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1
</pre>

5) run the new calculation

----
<h1>Connecting the cluster to your Mac</h1>
You may wish to copy a file that you have saved on the cluster to your Mac, or you may wish to copy a file on your Mac to the cluster.
----
<h3>Copy a file from your Mac to your account on the cluster</h3>
This is done in a shell where you are not connected to the cluster. Use the 'scp' command, followed by the path to the file on your Mac. In the same line, login to the cluster and specify where on the cluster you would like the copy to be sent to.
<pre>
intelimac1:~/g09 username$ scp /Users/username/g09/oxygen.com/ ns4912@login.cx1.hpc.ic.ac.uk:/home/ns4912
ns4912@login.cx1.hpc.ic.ac.uk's password:
oxygen.com 100% 203 0.2KB/s 00:00
</pre>
In this example, there a file called 'oxygen.com', which is saved in a folder called g09 in the user's area on the Mac. It is going to be copied to the user's area in the HOME directory on the cluster.
After typing your command, you are prompted for your password. After entering it, the file is copied to the cluster.
This can be double-checked when you log into the cluster.
<pre>
-bash-4.1$ pwd
/home/ns4912
-bash-4.1$ ls
bin oxygen.com test
</pre>
The file 'oxygen.com' now also appears in the user's area in the HOME directory on the cluster.
----
<h3>Copy a file from your account on the cluster to your Mac</h3>
Again, this is done in a shell where you are not connected to the cluster. The 'scp' command is also used here, but the order of phrases in your command is slightly different. In the example below, we will copy a file called 'ethane.chk' from the user's area in the WORK directory on the cluster to their area on the Mac. We will then check that the file has been successfully copied.
<pre>
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public g09 scripts
Documents Movies Pictures Sites h2o.rtf work
intelimac1:~ nafisa$ scp ns4912@login.cx1.hpc.ic.ac.uk:/work/ns4912/test/ethane.chk/ /Users/username/
ns4912@login.cx1.hpc.ic.ac.uk's password:
ethane.chk 100% 768KB 768.0KB/s 00:00
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public ethane.chk h2o.rtf work
Documents Movies Pictures Sites g09 scripts
</pre>
The file has been successfully copied to the Mac.

----
<h1>More about UNIX</h1>
This website lists classic UNIX commands: [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-21T13:32:58Z

Ns4912:

----
<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>
The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.
<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.
<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.
When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.
You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.
If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.

<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>
Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>
-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).

--------
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.
To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
<h1>Output file and Checkpoint file</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.
----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

----
<h1>Following on calculations on the cluster</h1>
As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file
<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file
<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity
</pre>

4) change the command in the new input file
o you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1
</pre>

5) run the new calculation

----
<h1>Connecting the cluster to your Mac</h1>
You may wish to copy a file that you have saved on the cluster to your Mac, or you may wish to copy a file on your Mac to the cluster.
----
<h3>Copy a file from your Mac to your account on the cluster</h3>
This is done in a shell where you are not connected to the cluster. Use the 'scp' command, followed by the path to the file on your Mac. In the same line, login to the cluster and specify where on the cluster you would like the copy to be sent to.
<pre>
intelimac1:~/g09 username$ scp /Users/username/g09/oxygen.com/ ns4912@login.cx1.hpc.ic.ac.uk:/home/ns4912
ns4912@login.cx1.hpc.ic.ac.uk's password:
oxygen.com 100% 203 0.2KB/s 00:00
</pre>
In this example, there a file called 'oxygen.com', which is saved in a folder called g09 in the user's area on the Mac. It is going to be copied to the user's area in the HOME directory on the cluster.
After typing your command, you are prompted for your password. After entering it, the file is copied to the cluster.
This can be double-checked when you log into the cluster.
<pre>
-bash-4.1$ pwd
/home/ns4912
-bash-4.1$ ls
bin oxygen.com test
</pre>
The file 'oxygen.com' now also appears in the user's area in the HOME directory on the cluster.
----
<h3>Copy a file from your account on the cluster to your Mac</h3>
Again, this is done in a shell where you are not connected to the cluster. The 'scp' command is also used here, but the order of phrases in your command is slightly different. In the example below, we will copy a file called 'ethane.chk' from the user's area in the WORK directory on the cluster to their area on the Mac. We will then check that the file has been successfully copied.
<pre>
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public g09 scripts
Documents Movies Pictures Sites h2o.rtf work
intelimac1:~ nafisa$ scp ns4912@login.cx1.hpc.ic.ac.uk:/work/ns4912/test/ethane.chk/ /Users/username/
ns4912@login.cx1.hpc.ic.ac.uk's password:
ethane.chk 100% 768KB 768.0KB/s 00:00
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public ethane.chk h2o.rtf work
Documents Movies Pictures Sites g09 scripts
</pre>
The file has been successfully copied to the Mac.

----
<h1>More about UNIX</h1>
This website lists classic UNIX commands: [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-21T13:32:31Z

Ns4912:

Using the cluster : tutorial, examples

2012-06-21T13:24:44Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.
----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>
----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.

To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

<h1>Output file and Checkpoint file</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.

----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>
----

<h1>Following on calculations on the cluster</h1>
As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file
<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file
<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity
</pre>

4) change the command in the new input file
o you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1
</pre>

5) run the new calculation
----

<h1>Connecting the cluster to your Mac</h1>
You may wish to copy a file that you have saved on the cluster to your Mac, or you may wish to copy a file on your Mac to the cluster.
----
<h3>Copy a file from your Mac to your account on the cluster</h3>
This is done in a shell where you are not connected to the cluster. Use the 'scp' command, followed by the path to the file on your Mac. In the same line, login to the cluster and specify where on the cluster you would like the copy to be sent to.
<pre>
intelimac1:~/g09 username$ scp /Users/username/g09/oxygen.com/ ns4912@login.cx1.hpc.ic.ac.uk:/home/ns4912
ns4912@login.cx1.hpc.ic.ac.uk's password:
oxygen.com 100% 203 0.2KB/s 00:00
</pre>
In this example, there a file called 'oxygen.com', which is saved in a folder called g09 in the user's area on the Mac. It is going to be copied to the user's area in the HOME directory on the cluster.
After typing your command, you are prompted for your password. After entering it, the file is copied to the cluster.
This can be double-checked when you log into the cluster.
<pre>
-bash-4.1$ pwd
/home/ns4912
-bash-4.1$ ls
bin oxygen.com test
</pre>
The file 'oxygen.com' now also appears in the user's area in the HOME directory on the cluster.
----
<h3>Copy a file from your account on the cluster to your Mac</h3>
Again, this is done in a shell where you are not connected to the cluster. The 'scp' command is also used here, but the order of phrases in your command is slightly different. In the example below, we will copy a file called 'ethane.chk' from the user's area in the WORK directory on the cluster to their area on the Mac. We will then check that the file has been successfully copied.
<pre>
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public g09 scripts
Documents Movies Pictures Sites h2o.rtf work
intelimac1:~ nafisa$ scp ns4912@login.cx1.hpc.ic.ac.uk:/work/ns4912/test/ethane.chk/ /Users/username/
ns4912@login.cx1.hpc.ic.ac.uk's password:
ethane.chk 100% 768KB 768.0KB/s 00:00
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public ethane.chk h2o.rtf work
Documents Movies Pictures Sites g09 scripts
</pre>
The file has been successfully copied to the Mac.
--------

<h1>More about UNIX</h1>
This website lists classic UNIX commands: [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-21T13:22:44Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.
----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>
----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.

To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

<h1>Output file and Checkpoint file</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.

----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>
----

<h1>Following on calculations on the cluster</h1>
As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file
<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file
<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity
</pre>

4) change the command in the new input file
o you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1
</pre>

5) run the new calculation
----

<h1>Connecting the cluster to your Mac</h1>
You may wish to copy a file that you have saved on the cluster to your Mac, or copy a file on your Mac to the cluster.
----
<h3>Copy a file from your Mac to your account on the cluster</h3>
This is done in a shell where you are not connected to the cluster. Use the 'scp' command, followed by the path to the file on your Mac. In the same line, login to the cluster and specify where on the cluster you would like the copy to be sent to.
<pre>

intelimac1:~/g09 username$ scp /Users/username/g09/oxygen.com/ ns4912@login.cx1.hpc.ic.ac.uk:/home/ns4912
ns4912@login.cx1.hpc.ic.ac.uk's password:
oxygen.com 100% 203 0.2KB/s 00:00

</pre>
In this example, there a file called 'oxygen.com', which is saved in a folder called g09 in the user's area on the Mac. It is going to be copied to the user's area in the HOME directory on the cluster.
After typing your command, you are prompted for your password. After entering it, the file is copied to the cluster.
This can be double-checked when you log into the cluster.
<pre>

-bash-4.1$ pwd
/home/ns4912
-bash-4.1$ ls
bin oxygen.com test

</pre>
The file 'oxygen.com' now also appears in the user's area in the HOME directory on the cluster.
----
<h3>Copy a file from your account on the cluster to your Mac</h3>
Again, this is done in a shell where you are not connected to the cluster. The 'scp' command is also used here, but the order of phrases in your command is slightly different. In the example below, we will copy a file called 'ethane.chk' from the user's area in the WORK directory on the cluster to their area on the Mac. We will then check that the file has been successfully copied.
<pre>

intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public g09 scripts
Documents Movies Pictures Sites h2o.rtf work
intelimac1:~ nafisa$ scp ns4912@login.cx1.hpc.ic.ac.uk:/work/ns4912/test/ethane.chk/ /Users/username/
ns4912@login.cx1.hpc.ic.ac.uk's password:
ethane.chk 100% 768KB 768.0KB/s 00:00
intelimac1:~ nafisa$ cd /Users/username/
intelimac1:~ nafisa$ ls
Desktop Library Music Public ethane.chk h2o.rtf work
Documents Movies Pictures Sites g09 scripts
</pre>
The file has been successfully copied to the Mac.
--------

<h1>More about UNIX</h1>
This website lists classic UNIX commands: [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-21T12:34:43Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can submit big calculations more easily than you can on your Mac. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access the cluster, and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

Then type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''.
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.
----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>
----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.

To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

<h1>Output file and Checkpoint file</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.

----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created. A special jobscript file is also created which corresponds to this particular calculation. If your calculation failed, you can try to open the jobscript to see if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>
----

<h1>Following on calculations on the cluster</h1>
As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file
<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file
<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity
</pre>

4) change the command in the new input file
o you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1
</pre>

5) run the new calculation
<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really useful to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-21T12:05:30Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can more easily submit some big calculations. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access to the cluster and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

and type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.
----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>
----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).

'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
If your job is queueing for a long time, then the part of the cluster you need to use is overbooked.
The part of the cluster your job is sent to depends on the time and memory that your job requires. Each part of the cluster has a limit to the amount of calculations it can run, which is why some calculations will end up queuing for a long time. In the example above, the job was running on an area of the cluster called 'medium'.

To look at all the different parts and determine how full they are, use the '''qstat -q''' command.
<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>
From the 'Run' and 'Que' columns, we can see how many jobs each part of the cluster is running, and how many jobs each part has queuing. If your job has been sent to an area that is very full, you can try changing the time or memory you have requested for the job. By doing this and resubmitting the job, you may end up sending it to an area of the cluster that is less busy.
----
<h3>Cancel a calculation</h3>
If you wish to cancel a calculation which is running or queuing, use the 'qdel' command followed by the Job Id.
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

<h1>Output file and Checkpoint file</h1>
<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.
----
<h3>Checkpoint file</h3>
The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. This means that if you want to make the file understandable you will have to format it. It is not always necessary to look at the checkpoint file to get the information you need as the log file will contain lots of important information already. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.

----
<h3>Jobscript</h3>
When a calculation is running output and checkpoint files are created but also a special jobscript file which corresponds to this particular calculation, if your calculation failed in the beginning you can try to open the jobscript to have a look if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>
----
<h1>Following on calculations on the cluster</h1>

As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity

</pre>

4) change the command in the new input file

So you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below

<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1

</pre>

5) run the new calculation

<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really usefull to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-21T11:09:21Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can more easily submit some big calculations. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access to the cluster and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

and type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.
----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>
----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).
----
'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
You can now look at the output files to see whether your job has been successful.
----
<h1>Output file and Checkpoint file</h1>

<h3>Output file</h3>
To have a look at the output file, go to your WORK directory, and then to the folder that you have sent the output files to. You can then open the log file with vim (using ''''vi name_of_your_file.log'''').
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>
Alternatively, you can use another text editor, such as 'less' or 'more'. To use 'less', type ''''less name_of_your_file.log''''. This allows you to look at the log file one page at a time. Press the space bar to go one window forward and 'B' to go one window up.
<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>
To use 'more', type ''''more name_of_your_file.log''''. This will show you your whole log file, which you may prefer.

<h3>Checkpoint file</h3>

The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more information than you can find in your output file, but it is a binary file. As the file is a binary file, if you want to make the file understandable you will have to format it. It is not always necessary to do this. If you do want to format your checkpoint file, type 'module load gaussian' and then use the command 'formchk'.

............
If you are queueing during a long time that is because the cluster is overbooked and specially the part that you require to use.
Indeed, when you are running a calculation, depending on the time that you require, the memory... you will be affect to a part of the cluster, in my previous example I was on '''q48''', but every part has a limit of calculations that it can run, so to have a look at all the different part and if there are full or not use '''qstat -q''' command

<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>

So you can notice that '''q48''' is in fact full and that a lot of calculations are queueing.... So maybe it will be useful to try to change of part in the cluster, so as to do that you can try to change the memory used or change the time that you predict for your calculation.

<h4>Jobscript</h4>

When a calculation is running output and checkpoint files are created but also a special jobscript file which corresponds to this particular calculation, if your calculation failed in the beginning you can try to open the jobscript to have a look if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

<h3>Cancel a calculation</h3>
If you want to cancel a calculation which is running or queueing :
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
'''qdel name_of_the_file_in_the_queue'''
----

<h1>Following on calculations on the cluster</h1>

As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity

</pre>

4) change the command in the new input file

So you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below

<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1

</pre>

5) run the new calculation

<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really usefull to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-20T15:24:16Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can more easily submit some big calculations. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access to the cluster and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

and type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.
----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>
----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).
----
'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----
<h1>Submitting your calculation</h1>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
You can now look at the output files to see whether your job has been successful.
----
<h31>Output file and Checkpoint file</h1>

<h3>Output file</h3>
To have a look at the output file, go to your WORK directory. You can open the log file with vim. Alternatively, you can use another text editor, such as 'less' or 'more'. use '''vi''' or '''less''' command.
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>

'''vi''' : so as to move inside the file quickly, press '''Ctrl + f''' if you want to go forward and '''Ctrl + b''' to go back

'''less''' is an other way to open a file, with this way you can push on space to take down of one window and push B to go up.

<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>

<h3>Checkpoint file</h3>

The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more informations that you can find in your output file, but it is a binary file. That's why if you want to get some informations like concerning the orbitals (read the orbitals of your system) you have to formate the checkpoint file.

<h3>Run a calculation</h3>

<h4>QSUB</h4>
In order to run a calculation you need so an input file, and a jobscript, and so as to compute the calculation you have to submit your jobscript :

----
'''qsub jobscript_name_of_your_file'''
----

<pre>
-bash-3.00$ qsub jobscript_turorial
2760944.cx1
-bash-3.00$
</pre>

And so when you are running a calculation you can check if it is really running or not with the command '''qstat'''

<pre>
-bash-3.00$ qsub jobscript_tutorial
2760944.cx1
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2760944.cx1 jobscript_couma alasoro 0 Q q48
-bash-3.00$
</pre>

So here the calculation is queueing for the moment.

If you are queueing during a long time that is because the cluster is overbooked and specially the part that you require to use.
Indeed, when you are running a calculation, depending on the time that you require, the memory... you will be affect to a part of the cluster, in my previous example I was on '''q48''', but every part has a limit of calculations that it can run, so to have a look at all the different part and if there are full or not use '''qstat -q''' command

<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>

So you can notice that '''q48''' is in fact full and that a lot of calculations are queueing.... So maybe it will be useful to try to change of part in the cluster, so as to do that you can try to change the memory used or change the time that you predict for your calculation.

<h4>Jobscript</h4>

When a calculation is running output and checkpoint files are created but also a special jobscript file which corresponds to this particular calculation, if your calculation failed in the beginning you can try to open the jobscript to have a look if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

<h3>Cancel a calculation</h3>
If you want to cancel a calculation which is running or queueing :
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
'''qdel name_of_the_file_in_the_queue'''
----

<h1>Following on calculations on the cluster</h1>

As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity

</pre>

4) change the command in the new input file

So you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below

<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1

</pre>

5) run the new calculation

<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really usefull to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-20T15:15:24Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can more easily submit some big calculations. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access to the cluster and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

and type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.
----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
This command takes you to a specific directory, and it allows you to change that directory. You must use the path-name of the folder you wish to move to.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>
----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).
----
'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----
<h3>Submitting your calculation</h3>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
You can now look at the output files to see whether your job has been successful.
----
<h3>Output file and Checkpoint file</h3>

<h4>Output file</h4>

To have a look at the output file, use '''vi''' or '''less''' command.
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>

'''vi''' : so as to move inside the file quickly, press '''Ctrl + f''' if you want to go forward and '''Ctrl + b''' to go back

'''less''' is an other way to open a file, with this way you can push on space to take down of one window and push B to go up.

<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>

<h4>Checkpoint file</h4>

The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more informations that you can find in your output file, but it is a binary file. That's why if you want to get some informations like concerning the orbitals (read the orbitals of your system) you have to formate the checkpoint file.

<h3>Run a calculation</h3>

<h4>QSUB</h4>
In order to run a calculation you need so an input file, and a jobscript, and so as to compute the calculation you have to submit your jobscript :

----
'''qsub jobscript_name_of_your_file'''
----

<pre>
-bash-3.00$ qsub jobscript_turorial
2760944.cx1
-bash-3.00$
</pre>

And so when you are running a calculation you can check if it is really running or not with the command '''qstat'''

<pre>
-bash-3.00$ qsub jobscript_tutorial
2760944.cx1
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2760944.cx1 jobscript_couma alasoro 0 Q q48
-bash-3.00$
</pre>

So here the calculation is queueing for the moment.

If you are queueing during a long time that is because the cluster is overbooked and specially the part that you require to use.
Indeed, when you are running a calculation, depending on the time that you require, the memory... you will be affect to a part of the cluster, in my previous example I was on '''q48''', but every part has a limit of calculations that it can run, so to have a look at all the different part and if there are full or not use '''qstat -q''' command

<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>

So you can notice that '''q48''' is in fact full and that a lot of calculations are queueing.... So maybe it will be useful to try to change of part in the cluster, so as to do that you can try to change the memory used or change the time that you predict for your calculation.

<h4>Jobscript</h4>

When a calculation is running output and checkpoint files are created but also a special jobscript file which corresponds to this particular calculation, if your calculation failed in the beginning you can try to open the jobscript to have a look if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

<h3>Cancel a calculation</h3>
If you want to cancel a calculation which is running or queueing :
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
'''qdel name_of_the_file_in_the_queue'''
----

<h1>Following on calculations on the cluster</h1>

As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity

</pre>

4) change the command in the new input file

So you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below

<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1

</pre>

5) run the new calculation

<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really usefull to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-20T15:12:52Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can more easily submit some big calculations. So as soon as you can go on the cluster, learn how it works and use it!
----
<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access to the cluster and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.
----
<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

and type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.
----
<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
Changes the directory. This is specified with the path-name of the folder you wish to move to. It is used for navigating through the file-system.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]
</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>
----
<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))
----
<h3>Introduction</h3>
You most probably have performed some calculations on your Mac, so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.
----
<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>
%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0
</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.
----
<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).
----
'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----
<h3>Submitting your calculation</h3>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$
</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
You can now look at the output files to see whether your job has been successful.
----
<h3>Output file and Checkpoint file</h3>

<h4>Output file</h4>

To have a look at the output file, use '''vi''' or '''less''' command.
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>

'''vi''' : so as to move inside the file quickly, press '''Ctrl + f''' if you want to go forward and '''Ctrl + b''' to go back

'''less''' is an other way to open a file, with this way you can push on space to take down of one window and push B to go up.

<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>

<h4>Checkpoint file</h4>

The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more informations that you can find in your output file, but it is a binary file. That's why if you want to get some informations like concerning the orbitals (read the orbitals of your system) you have to formate the checkpoint file.

<h3>Run a calculation</h3>

<h4>QSUB</h4>
In order to run a calculation you need so an input file, and a jobscript, and so as to compute the calculation you have to submit your jobscript :

----
'''qsub jobscript_name_of_your_file'''
----

<pre>
-bash-3.00$ qsub jobscript_turorial
2760944.cx1
-bash-3.00$
</pre>

And so when you are running a calculation you can check if it is really running or not with the command '''qstat'''

<pre>
-bash-3.00$ qsub jobscript_tutorial
2760944.cx1
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2760944.cx1 jobscript_couma alasoro 0 Q q48
-bash-3.00$
</pre>

So here the calculation is queueing for the moment.

If you are queueing during a long time that is because the cluster is overbooked and specially the part that you require to use.
Indeed, when you are running a calculation, depending on the time that you require, the memory... you will be affect to a part of the cluster, in my previous example I was on '''q48''', but every part has a limit of calculations that it can run, so to have a look at all the different part and if there are full or not use '''qstat -q''' command

<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>

So you can notice that '''q48''' is in fact full and that a lot of calculations are queueing.... So maybe it will be useful to try to change of part in the cluster, so as to do that you can try to change the memory used or change the time that you predict for your calculation.

<h4>Jobscript</h4>

When a calculation is running output and checkpoint files are created but also a special jobscript file which corresponds to this particular calculation, if your calculation failed in the beginning you can try to open the jobscript to have a look if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

<h3>Cancel a calculation</h3>
If you want to cancel a calculation which is running or queueing :
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
'''qdel name_of_the_file_in_the_queue'''
----

<h1>Following on calculations on the cluster</h1>

As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity

</pre>

4) change the command in the new input file

So you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below

<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1

</pre>

5) run the new calculation

<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really usefull to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-20T15:08:13Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can more easily submit some big calculations. So as soon as you can go on the cluster, learn how it works and use it!

<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access to the cluster and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.

<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

and type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
Changes the directory. This is specified with the path-name of the folder you wish to move to. It is used for navigating through the file-system.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]

</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))

<h3>Introduction</h3>
You most probably have already done some calculation on your mac so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.

<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>

%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0

</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.

<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).
----
'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----

<h3>Submitting your calculation</h3>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>

-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$

</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
You can now look at the output files to see whether your job has been successful.

<h3>Output file and Checkpoint file</h3>

<h4>Output file</h4>

To have a look at the output file, use '''vi''' or '''less''' command.
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>

'''vi''' : so as to move inside the file quickly, press '''Ctrl + f''' if you want to go forward and '''Ctrl + b''' to go back

'''less''' is an other way to open a file, with this way you can push on space to take down of one window and push B to go up.

<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>

<h4>Checkpoint file</h4>

The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more informations that you can find in your output file, but it is a binary file. That's why if you want to get some informations like concerning the orbitals (read the orbitals of your system) you have to formate the checkpoint file.

<h3>Run a calculation</h3>

<h4>QSUB</h4>
In order to run a calculation you need so an input file, and a jobscript, and so as to compute the calculation you have to submit your jobscript :

----
'''qsub jobscript_name_of_your_file'''
----

<pre>
-bash-3.00$ qsub jobscript_turorial
2760944.cx1
-bash-3.00$
</pre>

And so when you are running a calculation you can check if it is really running or not with the command '''qstat'''

<pre>
-bash-3.00$ qsub jobscript_tutorial
2760944.cx1
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2760944.cx1 jobscript_couma alasoro 0 Q q48
-bash-3.00$
</pre>

So here the calculation is queueing for the moment.

If you are queueing during a long time that is because the cluster is overbooked and specially the part that you require to use.
Indeed, when you are running a calculation, depending on the time that you require, the memory... you will be affect to a part of the cluster, in my previous example I was on '''q48''', but every part has a limit of calculations that it can run, so to have a look at all the different part and if there are full or not use '''qstat -q''' command

<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>

So you can notice that '''q48''' is in fact full and that a lot of calculations are queueing.... So maybe it will be useful to try to change of part in the cluster, so as to do that you can try to change the memory used or change the time that you predict for your calculation.

<h4>Jobscript</h4>

When a calculation is running output and checkpoint files are created but also a special jobscript file which corresponds to this particular calculation, if your calculation failed in the beginning you can try to open the jobscript to have a look if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

<h3>Cancel a calculation</h3>
If you want to cancel a calculation which is running or queueing :
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
'''qdel name_of_the_file_in_the_queue'''
----

<h1>Following on calculations on the cluster</h1>

As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity

</pre>

4) change the command in the new input file

So you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below

<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1

</pre>

5) run the new calculation

<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really usefull to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-20T15:06:42Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can more easily submit some big calculations. So as soon as you can go on the cluster, learn how it works and use it!

<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access to the cluster and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.

<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

and type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
Changes the directory. This is specified with the path-name of the folder you wish to move to. It is used for navigating through the file-system.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]

</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

<h1>Preparing your first calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))

<h3>Introduction</h3>
You most probably have already done some calculation on your mac so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.

<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>

%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0

</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.

<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).
----
'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----

<h3>Submitting your calculation</h4>
After writing your input file and jobscript, you have to submit your job. To do this, open your input file, then if it is as you want it, save it and close it.
Next, type the command ''''qsub'''', followed by the full name of your jobscript file. Press enter.
<pre>
-bash-4.1$ vi ethane.com
-bash-4.1$ qsub job.sh
1478294.cx1b
</pre>
Your job should now be running. The number following your command is the Job Id.
To check the progress of your job (for example, to see whether it is already running or still queuing), use the ''''qstat'''' command.
<pre>

-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
1478294.cx1b job.sh ns4912 00:00:00 R medium
-bash-4.1$ qstat
-bash-4.1$

</pre>
The penultimate column tells us the status of the job. The 'R' in this case means the job is running. A 'Q' would mean the job is still queuing.
You can use the 'qstat' command as many times as you like to check the status of your job. When using the command does not return information on the status of your job, but instead results in a blank prompt line, it means your job has finished running.
You can now look at the output files to see whether your job has been successful.

<h3>Output file and Checkpoint file</h3>

<h4>Output file</h4>

To have a look at the output file, use '''vi''' or '''less''' command.
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>

'''vi''' : so as to move inside the file quickly, press '''Ctrl + f''' if you want to go forward and '''Ctrl + b''' to go back

'''less''' is an other way to open a file, with this way you can push on space to take down of one window and push B to go up.

<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>

<h4>Checkpoint file</h4>

The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more informations that you can find in your output file, but it is a binary file. That's why if you want to get some informations like concerning the orbitals (read the orbitals of your system) you have to formate the checkpoint file.

<h3>Run a calculation</h3>

<h4>QSUB</h4>
In order to run a calculation you need so an input file, and a jobscript, and so as to compute the calculation you have to submit your jobscript :

----
'''qsub jobscript_name_of_your_file'''
----

<pre>
-bash-3.00$ qsub jobscript_turorial
2760944.cx1
-bash-3.00$
</pre>

And so when you are running a calculation you can check if it is really running or not with the command '''qstat'''

<pre>
-bash-3.00$ qsub jobscript_tutorial
2760944.cx1
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2760944.cx1 jobscript_couma alasoro 0 Q q48
-bash-3.00$
</pre>

So here the calculation is queueing for the moment.

If you are queueing during a long time that is because the cluster is overbooked and specially the part that you require to use.
Indeed, when you are running a calculation, depending on the time that you require, the memory... you will be affect to a part of the cluster, in my previous example I was on '''q48''', but every part has a limit of calculations that it can run, so to have a look at all the different part and if there are full or not use '''qstat -q''' command

<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>

So you can notice that '''q48''' is in fact full and that a lot of calculations are queueing.... So maybe it will be useful to try to change of part in the cluster, so as to do that you can try to change the memory used or change the time that you predict for your calculation.

<h4>Jobscript</h4>

When a calculation is running output and checkpoint files are created but also a special jobscript file which corresponds to this particular calculation, if your calculation failed in the beginning you can try to open the jobscript to have a look if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

<h3>Cancel a calculation</h3>
If you want to cancel a calculation which is running or queueing :
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
'''qdel name_of_the_file_in_the_queue'''
----

<h1>Following on calculations on the cluster</h1>

As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity

</pre>

4) change the command in the new input file

So you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below

<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1

</pre>

5) run the new calculation

<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really usefull to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-20T14:37:08Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can more easily submit some big calculations. So as soon as you can go on the cluster, learn how it works and use it!

<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access to the cluster and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.

<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

and type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
Changes the directory. This is specified with the path-name of the folder you wish to move to. It is used for navigating through the file-system.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]

</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

<h1>First calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))

<h3>Introduction</h3>
You most probably have already done some calculation on your mac so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.

<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>

%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0

</pre>

<h4>Open an input file</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.

<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This is simply a file that tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<h4>Making a jobscript</h4>
Jobscript files can be written in vim. The important difference is that they are saved with the extension '.sh', not '.com' like main input files. The jobscript for the ethane optimisation job above is shown here:
<pre>

#PBS -l ncpus=1
#PBS -l mem=1500mb
#PBS -l walltime=01:30:00
#PBS -j oe

module load gaussian

g09 < /home/ns4912/test/ethane.com > /work/ns4912/test/ethane.log
</pre>
We have specified the number of processors, the memory, and the time we would like to allocate to the job. The line 'module load gaussian' tells the system to start up Gaussian.
The last line gives the version of Gaussian to be used (g09), and then it gives the location of the input file (in the HOME directory) and where we want to put the output files (in the WORK directory).
----
'''Advice Break'''

How can I predict the time of a calculation?

That's a good question but there is no magical recipe! It depends on your the size of your system, the method and basis set that you are using (a larger basis set corresponds to a calculation that will take longer), and finally it depends on the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----

<h3>Output file and Checkpoint file</h3>

<h4>Output file</h4>

To have a look at the output file, use '''vi''' or '''less''' command.
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>

'''vi''' : so as to move inside the file quickly, press '''Ctrl + f''' if you want to go forward and '''Ctrl + b''' to go back

'''less''' is an other way to open a file, with this way you can push on space to take down of one window and push B to go up.

<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>

<h4>Checkpoint file</h4>

The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more informations that you can find in your output file, but it is a binary file. That's why if you want to get some informations like concerning the orbitals (read the orbitals of your system) you have to formate the checkpoint file.

<h3>Run a calculation</h3>

<h4>QSUB</h4>
In order to run a calculation you need so an input file, and a jobscript, and so as to compute the calculation you have to submit your jobscript :

----
'''qsub jobscript_name_of_your_file'''
----

<pre>
-bash-3.00$ qsub jobscript_turorial
2760944.cx1
-bash-3.00$
</pre>

And so when you are running a calculation you can check if it is really running or not with the command '''qstat'''

<pre>
-bash-3.00$ qsub jobscript_tutorial
2760944.cx1
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2760944.cx1 jobscript_couma alasoro 0 Q q48
-bash-3.00$
</pre>

So here the calculation is queueing for the moment.

If you are queueing during a long time that is because the cluster is overbooked and specially the part that you require to use.
Indeed, when you are running a calculation, depending on the time that you require, the memory... you will be affect to a part of the cluster, in my previous example I was on '''q48''', but every part has a limit of calculations that it can run, so to have a look at all the different part and if there are full or not use '''qstat -q''' command

<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>

So you can notice that '''q48''' is in fact full and that a lot of calculations are queueing.... So maybe it will be useful to try to change of part in the cluster, so as to do that you can try to change the memory used or change the time that you predict for your calculation.

<h4>Jobscript</h4>

When a calculation is running output and checkpoint files are created but also a special jobscript file which corresponds to this particular calculation, if your calculation failed in the beginning you can try to open the jobscript to have a look if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

<h3>Cancel a calculation</h3>
If you want to cancel a calculation which is running or queueing :
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
'''qdel name_of_the_file_in_the_queue'''
----

<h1>Following on calculations on the cluster</h1>

As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity

</pre>

4) change the command in the new input file

So you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below

<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1

</pre>

5) run the new calculation

<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really usefull to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-20T14:21:08Z

Ns4912:

<h1>Connecting to the cluster</h1>
Running calculations on the cluster is quicker and you can more easily submit some big calculations. So as soon as you can go on the cluster, learn how it works and use it!

<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access to the cluster and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.

<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

and type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
Changes the directory. This is specified with the path-name of the folder you wish to move to. It is used for navigating through the file-system.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]

</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

<h1>First calculation</h1>
(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))

<h3>Introduction</h3>
You most probably have already done some calculation on your mac so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript as well as an input file. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you may find some important information if your calculation does not start.

<h3>Input</h3>
When making input files on your mac, at the very beginning of the file you may have put the 'Link 0 command', which contains information about the output file. This line always begins with a % symbol.
When making an input file on the cluster, several Link 0 commands have to be included. First, specify how much memory you want the job to take up, on the next line state how many processors you want the job to use, and then specify the location of the output checkpoint file. In the example below, we want to use 1400MB of memory and one processor. We want the output files to go to the 'test' folder in the user's WORK directory.
<pre>

%chk=mem1400MB
%nproc=1
%chk=/work/ns4912/test/ethane.chk
# opt hf/3-21g

ethane optimisation

0 1
C1
C2 C1 1.5
H1 C2 1.0 C1 109.5
H6 C1 1.0 C2 109.5 H1 180.0
H4 C1 1.0 C2 109.5 H1 300.0
H5 C1 1.0 C2 109.5 H1 60.0
H2 C2 1.0 C1 109.5 H5 180.0
H3 C2 1.0 C1 109.5 H4 180.0

</pre>

<h4>Open an input filet</h4>
To open an input file you have made already, use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

If you want to change your input file, go into insert mode, make the required changes and then go back into command mode and save the changes using '''':wq'''' as described earlier. If you want to quit and you haven't made any changes, use '''':q'''' instead. Finally, if you want to quit without saving the changes you have made, use '''':q!''''.

<h3>Jobscript</h3>
As mentioned before, to run a job on the cluster, you need a jobscript as well as an input file. This tells the cluster how to handle the job and where to put the output files. Input files - which take up relatively little space - are saved in the HOME directory. The log and checkpoint files which form the output are much larger, so they are sent to the WORK directory, which has more space. This is not done automatically - we need to tell the cluster to do this in the jobscript.

<pre>
#PBS -l ncpus=1
#PBS -l mem=1700mb
#PBS -l walltime=01:30:00
#PBS -joe

module load gaussian

g03 < /home/username/name_of_your_file.com > /work/username/name_of_your_file.log
</pre>

So ''module load gaussian'' corresponds to the software used, and ''g03'' called this specific part of the software (version of Gaussian), after this you specify the name of the file .com and .log and the localisation of those files.

And before you specified the number of processors that you require ''ncpus'', the memory ''mem'' and the estimate time of your calculation ''walltime''.

----
'''Advice Break'''

An usual question : how can I predict the time of a calculation ?

That's a good question but there is no magical recipe ! It depends on your system (small, big...), it depends on the method and basis set that you are using (bigger is the basis set and longer is the calculation...), and finally it depends of the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----

<h3>Output file and Checkpoint file</h3>

<h4>Output file</h4>

To have a look at the output file, use '''vi''' or '''less''' command.
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>

'''vi''' : so as to move inside the file quickly, press '''Ctrl + f''' if you want to go forward and '''Ctrl + b''' to go back

'''less''' is an other way to open a file, with this way you can push on space to take down of one window and push B to go up.

<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>

<h4>Checkpoint file</h4>

The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more informations that you can find in your output file, but it is a binary file. That's why if you want to get some informations like concerning the orbitals (read the orbitals of your system) you have to formate the checkpoint file.

<h3>Run a calculation</h3>

<h4>QSUB</h4>
In order to run a calculation you need so an input file, and a jobscript, and so as to compute the calculation you have to submit your jobscript :

----
'''qsub jobscript_name_of_your_file'''
----

<pre>
-bash-3.00$ qsub jobscript_turorial
2760944.cx1
-bash-3.00$
</pre>

And so when you are running a calculation you can check if it is really running or not with the command '''qstat'''

<pre>
-bash-3.00$ qsub jobscript_tutorial
2760944.cx1
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2760944.cx1 jobscript_couma alasoro 0 Q q48
-bash-3.00$
</pre>

So here the calculation is queueing for the moment.

If you are queueing during a long time that is because the cluster is overbooked and specially the part that you require to use.
Indeed, when you are running a calculation, depending on the time that you require, the memory... you will be affect to a part of the cluster, in my previous example I was on '''q48''', but every part has a limit of calculations that it can run, so to have a look at all the different part and if there are full or not use '''qstat -q''' command

<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>

So you can notice that '''q48''' is in fact full and that a lot of calculations are queueing.... So maybe it will be useful to try to change of part in the cluster, so as to do that you can try to change the memory used or change the time that you predict for your calculation.

<h4>Jobscript</h4>

When a calculation is running output and checkpoint files are created but also a special jobscript file which corresponds to this particular calculation, if your calculation failed in the beginning you can try to open the jobscript to have a look if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

<h3>Cancel a calculation</h3>
If you want to cancel a calculation which is running or queueing :
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
'''qdel name_of_the_file_in_the_queue'''
----

<h1>Following on calculations on the cluster</h1>

As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity

</pre>

4) change the command in the new input file

So you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below

<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1

</pre>

5) run the new calculation

<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really usefull to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-20T13:08:59Z

Ns4912:

<h1>Connecting to the cluster</h1>

Running calculations on the cluster is quicker and you can more easily submit some big calculations. So as soon as you can go on the cluster, learn how it works and use it!

<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access to the cluster and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.

<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

and type '''ssh -Y username@login.cx1.hpc.ic.ac.uk'''
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

<h1>First steps on the cluster</h1>
<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]
----
<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
Changes the directory. This is specified with the path-name of the folder you wish to move to. It is used for navigating through the file-system.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----
<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.
<pre>
-bash-4.1$ vi name_of_your_file.com
~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]

</pre>
Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:
<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>
To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>
Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.
<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>
If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.
<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

<h1>First calculation</h1>

(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))

<h3>Introduction</h3>
You most probably have already done some calculation on your mac so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you will find maybe some information if your calculation does not start.

<h3>Input</h3>

So as on your mac the input file contain many informations : route job, geometry, memory require... as you can see below.

[[Image:input_2.png]]

<h4>Open an input, create an input</h4>
So as to open an input file you have to use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

And in order to create a new .com file you have to ''open'' a file with '''vi''' followed by the name of the file that you want to create and it will create the file.
'''vi name_of_your_new_file'''

<h4>Save what you just changed inside your input, quit a file...</h4>
Different UNIX commands enable you to save (or not) the changes (wanted or not) that you did inside a file

'''ESC + : + wq''' enables you ta save the changes operated
<pre>
:wq
</pre>

'''ESC + : q''' enables to quit the file
<pre>
:q
</pre>

'''ESC + q + !''' enables you to quit the file without saving the different changes that you did
<pre>
:q!
</pre>

<h3>Jobscript</h3>

You have more space allocate on your WORK directory, so because the files .log and .chk are bigger than the file .com, usually we save the .log and .chk in the WORK directory and .com in the HOME directory.

A Jobscript file is like a command in order to explain where is the file that you want to compute, where you want to save the output and what kind of software you wan to use to run the calculation.

<pre>
#PBS -l ncpus=1
#PBS -l mem=1700mb
#PBS -l walltime=01:30:00
#PBS -joe

module load gaussian

g03 < /home/username/name_of_your_file.com > /work/username/name_of_your_file.log
</pre>

So ''module load gaussian'' corresponds to the software used, and ''g03'' called this specific part of the software (version of Gaussian), after this you specify the name of the file .com and .log and the localisation of those files.

And before you specified the number of processors that you require ''ncpus'', the memory ''mem'' and the estimate time of your calculation ''walltime''.

----
'''Advice Break'''

An usual question : how can I predict the time of a calculation ?

That's a good question but there is no magical recipe ! It depends on your system (small, big...), it depends on the method and basis set that you are using (bigger is the basis set and longer is the calculation...), and finally it depends of the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----

<h3>Output file and Checkpoint file</h3>

<h4>Output file</h4>

To have a look at the output file, use '''vi''' or '''less''' command.
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>

'''vi''' : so as to move inside the file quickly, press '''Ctrl + f''' if you want to go forward and '''Ctrl + b''' to go back

'''less''' is an other way to open a file, with this way you can push on space to take down of one window and push B to go up.

<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>

<h4>Checkpoint file</h4>

The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more informations that you can find in your output file, but it is a binary file. That's why if you want to get some informations like concerning the orbitals (read the orbitals of your system) you have to formate the checkpoint file.

<h3>Run a calculation</h3>

<h4>QSUB</h4>
In order to run a calculation you need so an input file, and a jobscript, and so as to compute the calculation you have to submit your jobscript :

----
'''qsub jobscript_name_of_your_file'''
----

<pre>
-bash-3.00$ qsub jobscript_turorial
2760944.cx1
-bash-3.00$
</pre>

And so when you are running a calculation you can check if it is really running or not with the command '''qstat'''

<pre>
-bash-3.00$ qsub jobscript_tutorial
2760944.cx1
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2760944.cx1 jobscript_couma alasoro 0 Q q48
-bash-3.00$
</pre>

So here the calculation is queueing for the moment.

If you are queueing during a long time that is because the cluster is overbooked and specially the part that you require to use.
Indeed, when you are running a calculation, depending on the time that you require, the memory... you will be affect to a part of the cluster, in my previous example I was on '''q48''', but every part has a limit of calculations that it can run, so to have a look at all the different part and if there are full or not use '''qstat -q''' command

<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>

So you can notice that '''q48''' is in fact full and that a lot of calculations are queueing.... So maybe it will be useful to try to change of part in the cluster, so as to do that you can try to change the memory used or change the time that you predict for your calculation.

<h4>Jobscript</h4>

When a calculation is running output and checkpoint files are created but also a special jobscript file which corresponds to this particular calculation, if your calculation failed in the beginning you can try to open the jobscript to have a look if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

<h3>Cancel a calculation</h3>
If you want to cancel a calculation which is running or queueing :
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
'''qdel name_of_the_file_in_the_queue'''
----

<h1>Following on calculations on the cluster</h1>

As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity

</pre>

4) change the command in the new input file

So you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below

<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1

</pre>

5) run the new calculation

<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really usefull to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-20T13:02:52Z

Ns4912:

<h1>Connecting to the cluster</h1>

Running calculations on the cluster is quicker and you can more easily submit some big calculations. So as soon as you can go on the cluster, learn how it works and use it!

<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access to the cluster and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.

<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

and type:
----
'''ssh -Y username@login.cx1.hpc.ic.ac.uk'''
----
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

<h1>First steps on the cluster</h1>

<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]

<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
Changes the directory. This is specified with the path-name of the folder you wish to move to. It is used for navigating through the file-system.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. In order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----

<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.

<pre>
-bash-4.1$ vi name_of_your_file.com

~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]

</pre>

Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:

<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>

To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>

Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.

<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>

If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

<h1>First calculation</h1>

(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))

<h3>Introduction</h3>
You most probably have already done some calculation on your mac so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you will find maybe some information if your calculation does not start.

<h3>Input</h3>

So as on your mac the input file contain many informations : route job, geometry, memory require... as you can see below.

[[Image:input_2.png]]

<h4>Open an input, create an input</h4>
So as to open an input file you have to use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

And in order to create a new .com file you have to ''open'' a file with '''vi''' followed by the name of the file that you want to create and it will create the file.
'''vi name_of_your_new_file'''

<h4>Save what you just changed inside your input, quit a file...</h4>
Different UNIX commands enable you to save (or not) the changes (wanted or not) that you did inside a file

'''ESC + : + wq''' enables you ta save the changes operated
<pre>
:wq
</pre>

'''ESC + : q''' enables to quit the file
<pre>
:q
</pre>

'''ESC + q + !''' enables you to quit the file without saving the different changes that you did
<pre>
:q!
</pre>

<h3>Jobscript</h3>

You have more space allocate on your WORK directory, so because the files .log and .chk are bigger than the file .com, usually we save the .log and .chk in the WORK directory and .com in the HOME directory.

A Jobscript file is like a command in order to explain where is the file that you want to compute, where you want to save the output and what kind of software you wan to use to run the calculation.

<pre>
#PBS -l ncpus=1
#PBS -l mem=1700mb
#PBS -l walltime=01:30:00
#PBS -joe

module load gaussian

g03 < /home/username/name_of_your_file.com > /work/username/name_of_your_file.log
</pre>

So ''module load gaussian'' corresponds to the software used, and ''g03'' called this specific part of the software (version of Gaussian), after this you specify the name of the file .com and .log and the localisation of those files.

And before you specified the number of processors that you require ''ncpus'', the memory ''mem'' and the estimate time of your calculation ''walltime''.

----
'''Advice Break'''

An usual question : how can I predict the time of a calculation ?

That's a good question but there is no magical recipe ! It depends on your system (small, big...), it depends on the method and basis set that you are using (bigger is the basis set and longer is the calculation...), and finally it depends of the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----

<h3>Output file and Checkpoint file</h3>

<h4>Output file</h4>

To have a look at the output file, use '''vi''' or '''less''' command.
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>

'''vi''' : so as to move inside the file quickly, press '''Ctrl + f''' if you want to go forward and '''Ctrl + b''' to go back

'''less''' is an other way to open a file, with this way you can push on space to take down of one window and push B to go up.

<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>

<h4>Checkpoint file</h4>

The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more informations that you can find in your output file, but it is a binary file. That's why if you want to get some informations like concerning the orbitals (read the orbitals of your system) you have to formate the checkpoint file.

<h3>Run a calculation</h3>

<h4>QSUB</h4>
In order to run a calculation you need so an input file, and a jobscript, and so as to compute the calculation you have to submit your jobscript :

----
'''qsub jobscript_name_of_your_file'''
----

<pre>
-bash-3.00$ qsub jobscript_turorial
2760944.cx1
-bash-3.00$
</pre>

And so when you are running a calculation you can check if it is really running or not with the command '''qstat'''

<pre>
-bash-3.00$ qsub jobscript_tutorial
2760944.cx1
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2760944.cx1 jobscript_couma alasoro 0 Q q48
-bash-3.00$
</pre>

So here the calculation is queueing for the moment.

If you are queueing during a long time that is because the cluster is overbooked and specially the part that you require to use.
Indeed, when you are running a calculation, depending on the time that you require, the memory... you will be affect to a part of the cluster, in my previous example I was on '''q48''', but every part has a limit of calculations that it can run, so to have a look at all the different part and if there are full or not use '''qstat -q''' command

<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>

So you can notice that '''q48''' is in fact full and that a lot of calculations are queueing.... So maybe it will be useful to try to change of part in the cluster, so as to do that you can try to change the memory used or change the time that you predict for your calculation.

<h4>Jobscript</h4>

When a calculation is running output and checkpoint files are created but also a special jobscript file which corresponds to this particular calculation, if your calculation failed in the beginning you can try to open the jobscript to have a look if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

<h3>Cancel a calculation</h3>
If you want to cancel a calculation which is running or queueing :
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
'''qdel name_of_the_file_in_the_queue'''
----

<h1>Following on calculations on the cluster</h1>

As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity

</pre>

4) change the command in the new input file

So you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below

<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1

</pre>

5) run the new calculation

<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really usefull to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]

Using the cluster : tutorial, examples

2012-06-20T13:00:55Z

Ns4912:

<h1>Connecting to the cluster</h1>

Running calculations on the cluster is quicker and you can more easily submit some big calculations. So as soon as you can go on the cluster, learn how it works and use it!

<h3>SSH </h3>
Secure Shell or SSH is a network protocol that allows data to be exchanged using a secure channel between two networked devices.

We use the '''ssh''' command to access to the cluster and build a connection like a safe tunnel between your mac and the cluster. Thus you can run and follow calculations on the cluster via your mac.

This can be used with a number of options (use the '''man ssh''' command to view these). One of the most useful is '''-Y''' which enables X11 forwarding, enabling graphical user interfaces (GUIs), such as nedit or xpbs, to be used.

<h3>How to use SSH protocol </h3>
To connect to the PC cluster you must have an IC college account.

When you have an IC college account, open a Terminal shell for example:

[[Image:terminal_1.png]]

and type:
----
'''ssh -Y username@login.cx1.hpc.ic.ac.uk'''
----
The username is the one given to you by Imperial College. When using this page, always substitute 'username' for your personal username.

[[Image:terminal_2.png]]

It will ask you for your password. After entering you password and pressing enter, you will be connected to the cluster.

[[Image:terminal_3.png]]

If you want to leave the cluster, just close the window.

You can connect many shells to the cluster to make different manipulations easier, and you can have Terminal and X11 connected to the cluster at the same time.

<h1>First steps on the cluster</h1>

<h3>Structure of the cluster</h3>

The cluster can be thought of as a hierarchy of directories like any UNIX system. On it your user area is divided into two sections, work and home. Input files are usually made and saved in '''home''' and output files are saved in '''work'''.

[[Image:cluster_structure2.png]]

<h3>Basic UniX commands</h3>
The cluster uses UNIX commands in order to navigate through the file system. Below you will find some basic commands that you will use often. They may often be used with a number of options. Use '''man command-name''' or '''command-name help''' for information on these options. For further information the following two links are of interest:<br>
[http://www.ee.surrey.ac.uk/Teaching/Unix/ UNIX Online Tutorials]<br>
[http://en.wikipedia.org/wiki/Unix_commands List of UNIX commands]

<h4>pwd</h4>
Displays current position in the file system.
<pre>
-bash-3.00$ pwd
/home/username
-bash-3.00$
</pre>
So, when you connect to the cluster you are in your '''HOME''' directory.

<h4>ls</h4>
Displays files and directories inside the directory you are in, which in the example here is '/home/username'.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03
-bash-3.00$
</pre>
In the /home/username directory there are different folders but if this is your first time on the cluster this is probably empty. We are going to create a folder in the next part.

<h4>mkdir</h4>
Creates a folder.
<pre>
-bash-3.00$ mkdir tutorial
-bash-3.00$
</pre>
We now have a folder named tutorial in the 'username' directory. (The path to this folder is '/home/username/tutorial').
We can check that the folder exists with the '''ls''' command.
<pre>
-bash-3.00$ ls
ONIOM2 benzene protein ONIOM
bin qst2 g03 tutorial
-bash-3.00$
</pre>

<h4>cd</h4>
Changes the directory. This is specified with the path-name of the folder you wish to move to. It is used for navigating through the file-system.

<pre>
-bash-3.00$ cd /work/username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>
Now you are in your WORK directory. Following the above steps a folder 'tutorial' can also be created here (within your username).
Note that if you are already in your WORK directory, and want to change the 'username' directory in WORK, you can simply type 'cd username/'.

<pre>
-bash-3.00$ pwd
/work
-bash-3.00$ cd username/
-bash-3.00$ pwd
/work/username
-bash-3.00$
</pre>

<h4>cd ..</h4>
Move up a level out of the folder you are in.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ cd ..
-bash-3.00$ pwd
-bash-3.00$ /home/username/
</pre>

This is useful for navigating your way around directories.

<h4>Moving between the HOME and WORK directories</h4>
You have two directories in the cluster : a '''HOME''' folder and a '''WORK''' one.

When you connect to the cluster you are directly in your '''HOME''' directory. So in order to go to your '''WORK''' directory you can use the command '''cd /work/username/'''.

You can also use the shortcut '''cd $WORK''' in order to directly get to your part of the '''WORK''' directory.

If you want to go back to your '''HOME''' directory, use '''cd $HOME''' or '''cd ~'''.
<h4>jump</h4>
Use this command to go straight from where you are in the HOME directory to the equivalent point in the WORK directory (or vice versa).

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ jump
cd /work/username/tutorial
-bash-3.00$ pwd
/work/username/tutorial
</pre>

Before moving on, try using all the commands above to make sure you are comfortable with them.
----

<h3>Making and manipulating a new text file</h3>
Hopefully you are now comfortable with moving around the directories. The next step is to make a new text file as a practise run for when you will be making input files for Gaussian.

<h4>Making a new file</h4>
First, make sure you are in the folder that you would like the file to be saved in. The text editor you will be using is called 'vim' or 'vi'. Type ''''vi name_of_your_file.com'''', then press enter. The following screen will appear.

<pre>
-bash-4.1$ vi name_of_your_file.com

~
~
~
~
~
~
~
~
~
~
~
~
~
"name_of_your_file.com" [New File]

</pre>

Vim has two modes: 'command' and 'insert'. When you create a new file, you are in command mode by default. To insert text you will need to change to insert mode by pressing ''''i''''. You will see the bottom of the screen now says -INSERT-. Type some text:

<pre>

-bash-4.1$ vi name_of_your_file.com

My first vi file
~
~
~
~
~
~

~
-- INSERT --
</pre>

To save your file, first go back into command mode by pressing the esc button, then type '''':wq'''' and press enter.

Now you have made your first text file, practise the commands below in order to become confident with manipulating your file.

<h4>cp</h4>
Copy a file.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ cp testjob_2.com testjob_3.com
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$
</pre>

Here we have made a copy of testjob_2.com, the new file testjob_3.com.

<h4>rm</h4>
Remove a file.

<pre>
-bash-3.00$ pwd
/work/username
-bash-3.00$ ls
-bash-3.00$
tutorial
-bash-3.00$ cd tutorial/
-bash-3.00$ ls
testjob_1.com testjob_2.com
-bash-3.00$ rm testjob_2.com
-bash-3.00$ ls
testjob_1.com
-bash-3.00$
</pre>

If a file is no longer needed it can be removed with this command. If you wish to remove a whole directory use '''rm-r''' before specifying its name to remove the folder and all the files inside.
When you are in the cluster and are trying to remove a file, a line will appear saying 'rm: remove regular file 'name_of_file'?' with a prompt. Type 'y' and press enter to remove the file.

<h4>mv</h4>
Move a file to another folder.

<pre>
-bash-3.00$ pwd
/home/username/tutorial
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ mv testjob_3.com /home/username/
-bash-3.00$ ls
testjob_1.com testjob_2.com testjob_3.com
-bash-3.00$ cd ..
-bash-3.00$ pwd
/home/username
-bash-3.00$ ls
testjob_3.com tutorial
-bash-3.00$
</pre>

<h1>First calculation</h1>

(This tutorial was put together when the default released version of Gaussian was Gaussian 03 / g03.
It's now Gaussian 09 / g09, so use 'g09' with 'module load gaussian' in what's below.
--[[User:Mjbear|Mjbear]] 11:56, 23 March 2011 (UTC))

<h3>Introduction</h3>
You most probably have already done some calculation on your mac so you know that in order to run a calculation you need an input file. But now the difference is that to compute this calculation you must have a jobscript. And as usual a calculation will create an output file, a .chk file and also a jobscript_ file in which you will find maybe some information if your calculation does not start.

<h3>Input</h3>

So as on your mac the input file contain many informations : route job, geometry, memory require... as you can see below.

[[Image:input_2.png]]

<h4>Open an input, create an input</h4>
So as to open an input file you have to use the UNIX command '''vi'''

'''vi name_of_your_file.com'''

And in order to create a new .com file you have to ''open'' a file with '''vi''' followed by the name of the file that you want to create and it will create the file.
'''vi name_of_your_new_file'''

<h4>Save what you just changed inside your input, quit a file...</h4>
Different UNIX commands enable you to save (or not) the changes (wanted or not) that you did inside a file

'''ESC + : + wq''' enables you ta save the changes operated
<pre>
:wq
</pre>

'''ESC + : q''' enables to quit the file
<pre>
:q
</pre>

'''ESC + q + !''' enables you to quit the file without saving the different changes that you did
<pre>
:q!
</pre>

<h3>Jobscript</h3>

You have more space allocate on your WORK directory, so because the files .log and .chk are bigger than the file .com, usually we save the .log and .chk in the WORK directory and .com in the HOME directory.

A Jobscript file is like a command in order to explain where is the file that you want to compute, where you want to save the output and what kind of software you wan to use to run the calculation.

<pre>
#PBS -l ncpus=1
#PBS -l mem=1700mb
#PBS -l walltime=01:30:00
#PBS -joe

module load gaussian

g03 < /home/username/name_of_your_file.com > /work/username/name_of_your_file.log
</pre>

So ''module load gaussian'' corresponds to the software used, and ''g03'' called this specific part of the software (version of Gaussian), after this you specify the name of the file .com and .log and the localisation of those files.

And before you specified the number of processors that you require ''ncpus'', the memory ''mem'' and the estimate time of your calculation ''walltime''.

----
'''Advice Break'''

An usual question : how can I predict the time of a calculation ?

That's a good question but there is no magical recipe ! It depends on your system (small, big...), it depends on the method and basis set that you are using (bigger is the basis set and longer is the calculation...), and finally it depends of the calculation that you would like to compute (a single point energy calculation is quicker than an optimisation with the same system).
----

<h3>Output file and Checkpoint file</h3>

<h4>Output file</h4>

To have a look at the output file, use '''vi''' or '''less''' command.
<pre>
[intellimac4:~/g03] aurelie% vi aurelie_pyridine_iefpcm_water.log
</pre>

'''vi''' : so as to move inside the file quickly, press '''Ctrl + f''' if you want to go forward and '''Ctrl + b''' to go back

'''less''' is an other way to open a file, with this way you can push on space to take down of one window and push B to go up.

<pre>
[intellimac4:~/g03] aurelie% less aurelie_pyridine_iefpcm_water.log
</pre>

<h4>Checkpoint file</h4>

The checkpoint file contains all the information concerning your system and the calculation that you computed, so it contains more informations that you can find in your output file, but it is a binary file. That's why if you want to get some informations like concerning the orbitals (read the orbitals of your system) you have to formate the checkpoint file.

<h3>Run a calculation</h3>

<h4>QSUB</h4>
In order to run a calculation you need so an input file, and a jobscript, and so as to compute the calculation you have to submit your jobscript :

----
'''qsub jobscript_name_of_your_file'''
----

<pre>
-bash-3.00$ qsub jobscript_turorial
2760944.cx1
-bash-3.00$
</pre>

And so when you are running a calculation you can check if it is really running or not with the command '''qstat'''

<pre>
-bash-3.00$ qsub jobscript_tutorial
2760944.cx1
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2760944.cx1 jobscript_couma alasoro 0 Q q48
-bash-3.00$
</pre>

So here the calculation is queueing for the moment.

If you are queueing during a long time that is because the cluster is overbooked and specially the part that you require to use.
Indeed, when you are running a calculation, depending on the time that you require, the memory... you will be affect to a part of the cluster, in my previous example I was on '''q48''', but every part has a limit of calculations that it can run, so to have a look at all the different part and if there are full or not use '''qstat -q''' command

<pre>
-bash-3.00$ qstat -q

server: cx1

Queue Memory CPU Time Walltime Node Run Que Lm State
---------------- ------ -------- -------- ---- ----- ----- ---- -----
vlong 1900mb -- 72:00:00 -- 110 26 110 E R
submit -- -- -- -- 0 0 -- E R
short 1000mb -- 01:00:00 -- 7 76 25 E R
medium 1000mb -- 04:00:00 -- 5 0 25 E R
long 1900mb -- 22:00:00 -- 69 24 60 E R
q24 3900mb -- 48:00:00 -- 0 0 0 E S
q816 244gb -- 72:00:00 -- 18 14 17 E R
monster -- -- -- -- 0 0 0 E S
bench 122gb -- 72:00:00 -- 0 0 -- E S
fixed -- -- 72:00:00 -- 0 0 -- E R
q48 61gb -- 72:00:00 -- 137 195 120 E R
pqaerostr -- -- 300:00:0 -- 10 3 -- E R
ibtest -- -- 480:00:0 -- 0 0 60 D S
tng 16gb -- 48:00:00 -- 0 0 600 E S
heplt2 -- -- -- -- 0 0 -- E R
xdbg 61gb -- 00:15:00 -- 0 0 3 E R
pqese -- -- 150:00:0 -- 12 0 -- E R
pqph -- -- 120:00:0 -- 9 0 -- E R
pqfb -- -- 120:00:0 -- 1 0 -- E R
pqms -- -- 72:00:00 -- 32 3 -- E R
slong 1900mb -- 72:00:00 -- 0 0 -- E S
pqmb -- -- 72:00:00 -- 0 0 -- E R
pqjk -- -- 200:00:0 -- 2 0 -- E R
test8 -- -- -- -- 0 0 -- E R
pqtyc -- -- 72:00:00 -- 2 0 -- E R
pqmls -- -- 72:00:00 -- 0 0 -- E R
pqeph -- -- 999:00:0 -- 123 10 -- E R
pqnh -- -- 72:00:00 -- 0 0 -- E R
chemlab1 -- -- 72:00:00 -- 1 0 -- E R
pqrevans -- -- 650:00:0 -- 6 0 -- E R
pqneuro -- -- 96:00:00 -- 18 0 -- E R
pqchemeng -- -- 72:00:00 -- 18 4 -- E R
pqciveng -- -- 999:00:0 -- 1 0 -- E R
test82 -- -- 72:00:00 -- 6 1 -- E R
pqjc1 -- -- 650:00:0 -- 1 0 -- E R
p1mem 12gb -- 72:00:00 -- 16 41 -- E R
test81 -- -- 72:00:00 -- 6 8 -- E R
pqesebot -- -- 100:00:0 -- 31 3 -- E R
pqspat -- -- 72:00:00 -- 6 0 -- E R
testnh -- -- 72:00:00 -- 0 0 -- E R
pqastro -- -- 72:00:00 -- 2 0 -- E R
pqplee -- -- 1000:00: -- 20 1 -- E R
pqplasp -- -- -- -- 0 0 -- E R
pqtzaki -- -- 96:00:00 -- 9 0 -- E R
pqexss -- -- 72:00:00 -- 2 0 -- E R
pqdd -- -- 500:00:0 -- 1 0 -- E R
----- -----
681 409
-bash-3.00$
</pre>

So you can notice that '''q48''' is in fact full and that a lot of calculations are queueing.... So maybe it will be useful to try to change of part in the cluster, so as to do that you can try to change the memory used or change the time that you predict for your calculation.

<h4>Jobscript</h4>

When a calculation is running output and checkpoint files are created but also a special jobscript file which corresponds to this particular calculation, if your calculation failed in the beginning you can try to open the jobscript to have a look if it can give you an explanation.
<pre>
-bash-3.00$ vi jobscript_tutor.o2760944
</pre>

<h3>Cancel a calculation</h3>
If you want to cancel a calculation which is running or queueing :
<pre>
-bash-3.00$ qstat
Job id Name User Time Use S Queue
---------------- ---------------- ---------------- -------- - -----
2745894.cx1 jobscript_couma alasoro 0 Q p1mem
-bash-3.00$ qdel 2745894.cx1
-bash-3.00$ qstat
-bash-3.00$
</pre>

----
'''qdel name_of_the_file_in_the_queue'''
----

<h1>Following on calculations on the cluster</h1>

As a training run the calculation of this input on the cluster
[[Media:cyclopropane_optimisation.gjf]]

When the optimisation is successful, you will need a frequency calculation in order to check if you really found a minimum, and so as to run a frequency calculation you have to keep the geometry of your optimised parameters. Thus what you always have to do in those cases is :

1) cp the input file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.com cyclopropane_optimised_frequency.com
</pre>

2) cp the checkpoint file

<pre>
-bash-3.00$ cp cyclopropane_optimisation.chk cyclopropane_optimised_frequency.chk
</pre>

3) change the name of the checkpoint file in the new input file
So you have to change the name of the checkpoint file which correspond to this new input
<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# opt=calcall b3lyp/cc-pvdz geom=connectivity

</pre>

4) change the command in the new input file

So you have to change the calculation type (opt ---> freq), but also because you want to keep the optimised geometry,contained in the checkpoint that you copied you have to specify '''geom=check''' and remove the geometry below

<pre>
%chk=/work/username/cyclopropane_optimised_frequency.chk
%mem=1200mb
%nproc=1
# freq b3lyp/cc-pvdz geom=check

cyclopropane
DFT ccpvdz b3lyp
opt + calcall

0 1

</pre>

5) run the new calculation

<h1>Connecting the cluster to your Mac</h1>
<h3>Copy a file from your mac to your account on the cluster</h3>
<p>
It is really usefull to export a file from a computer to the cluster
----
'''scp absolute_link_to_the_file_on_your_mac username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/'''
----

Example :<br/>
So send our file test2.com to the directory home on the cluster
<pre>
[intellimac4:~] aurelie% pwd
/Users/aurelie
[intellimac4:~] aurelie% cd phony
[intellimac4:~/phony] aurelie% ls
test2.com
[intellimac4:~/phony] aurelie% scp ./test2.com alasoro@login.cx1.hpc.ic.ac.uk:/home/alasoro/
alasoro@login.cx1.hpc.ic.ac.uk's password:
test2.com 100% 650 0.6KB/s 00:00
[intellimac4:~/phony] aurelie%
</pre>
So the file was good sent to the directory home.
</p>

<h3>Copy a file from your account on the cluster to your mac</h3>
<p>
Obviously you can do it in the other side.
----
'''scp username@login.cx1.hpc.ic.ac.uk:/home(or work, it depends on which directory you want to put the file)/username/ absolute_link_to_the_file_on_your_mac'''
----
</p>

<h1>More about UNIX</h1>
This website group together the most classical command of UNIX : [http://mally.stanford.edu/~sr/computing/basic-unix.html Basis UNIX commands]