Difference between revisions of "HowTo:Setup"

From CAC Wiki
Jump to: navigation, search
(Created page with "= How to Set Up a Unix Shell = This is an introduction to setting up your account on our systems. When first logging in, you are presented with a default set-up that enables...")
 
(Running pre-installed software)
 
(14 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
This is an introduction to setting up your account on our systems. When first logging in, you are presented with a default set-up that enables the use of basic system commands, simple compilers, and access to the scheduler. This help file is meant to explain how to modify that default.
 
This is an introduction to setting up your account on our systems. When first logging in, you are presented with a default set-up that enables the use of basic system commands, simple compilers, and access to the scheduler. This help file is meant to explain how to modify that default.
  
 +
{|  style="border-spacing: 8px;"
 +
| valign="top" width="50%" style="padding:1em; border:1px solid #aaaaaa; background-color:#e1eaf1; border-radius:7px" |
 
== Shells ==
 
== Shells ==
 +
 
A shell is a command line interface that lets users issue commands to the operating system. It contains the basic Unix commands, as well as many more adcanced ones. The default '''shell''' for a Linux system is '''bash''' ("Bourne again" shell). There are others:
 
A shell is a command line interface that lets users issue commands to the operating system. It contains the basic Unix commands, as well as many more adcanced ones. The default '''shell''' for a Linux system is '''bash''' ("Bourne again" shell). There are others:
  
Line 15: Line 18:
 
Some people prefer '''csh''' best because it is simple and its syntax is similar to the C programming language (thus the name). We discourage its use ([http://cfajohnson.com/shell/?2011-11-30_why_not_csh see this for reasons]).
 
Some people prefer '''csh''' best because it is simple and its syntax is similar to the C programming language (thus the name). We discourage its use ([http://cfajohnson.com/shell/?2011-11-30_why_not_csh see this for reasons]).
  
'''ksh''' offers some extended features compared with csh. As an example, you can recall commands that you typed previously. With ksh, this is usually done by pressing the "escape" key, and scrolling through previous commands with arrow keys. However, its syntax is rather different, so that csh commands can usually not be issued to ksh.
+
'''ksh''' offers some extended features but is rarely used these days as it is similar to bash but offers less features.
  
Choosing a login shell is largely a matter of taste. '''We recommend bash''' as this is the most commonly used shell, especially for Linux systems.  It is probably fair to point out that [http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/ many people do not find csh a good choice].
+
Some programs require a specific shell to run. You can always call a shell by typing <pre>/usr/bin/name_of_shell</pre> where name_of_shell might be csh, tcsh, ksh, bash or sh (the latter is another standard shell that is often used for scripts). You may have to maintain set-up files for the shells you use, even if they are not your login shell.
 
+
Some programs require a specific shell to run. You can always call a shell by typing "/usr/bin/name_of_shell", where name_of_shell might be csh, tcsh, ksh, bash or sh (the latter is another standard shell that is often used for scripts). Make sure you maintain setup files for the shells you use, even if they are not your login shell.
+
  
 
In scripts, shells are usually called with a "hash-bang" sequence, that looks like:   
 
In scripts, shells are usually called with a "hash-bang" sequence, that looks like:   
  
: #!/bin/csh
+
<pre>#!/bin/bash</pre>
  
in the first line. In such cases, it can happen that environment variables, such as PATH get reset to some default. This is why it is a good idea to start csh scripts with
+
in the first line. In such cases, it can happen that environment variables, such as PATH get reset to some default. This is why it may be necessary to use the -f option: <pre>#!/bin/csh -f</pre> which avoids sourcing in the set-up files, leading to consistent behaviour for different users.
  
: #!/bin/csh -f
+
All shells are documented in the man pages: type <pre>man name_of_shell</pre> to get more information than you'd care to know. Here are links for pretty complete documentation for the shells online:
 
+
The -f option avoids sourcing in the .cshrc file, leading to consistent behaviour of the script for different users (with different .cshrc files).
+
 
+
All shells are documented in the man pages: type
+
 
+
: man name_of_shell
+
 
+
to get more information than you'd care to know. Here are links for pretty complete documentation for the shells online:
+
  
 
* [http://www.gnu.org/software/bash/manual/ bash]
 
* [http://www.gnu.org/software/bash/manual/ bash]
Line 41: Line 34:
 
* [http://www.kitebird.com/csh-tcsh-book/csh-intro.pdf csh]
 
* [http://www.kitebird.com/csh-tcsh-book/csh-intro.pdf csh]
  
==How do I setup my shell ?==
+
In the following section, we assume a '''bash''' shell.
  
To a large degree, your shell is set up using a tool called '''usepackage'''. This allows you to replace the setting of several environment variables, and the execution of setup scripts by a simple command of the form
+
== Setting up a shell ==
  
: use package
+
We are using a system called '''usepackage''' to setup the shell. This allows replacing the setting of several environment variables, and the execution of set-up scripts by simple commands of the form <pre>use package</pre> where ''package'' stands for a pre-defined application or feature that is to be included. We discuss the use of use in the next section.
  
where package stands for a pre-defined application or feature that you want to include in your setup. We discuss the use of use in the next section.
+
There are several '''set-up files''' in your home directory:
 +
* '''.bashrc''' is "sourced in" every time a bash shell is invoked.
 +
* '''.bash_profile''' applies only to login shells, i.e. when you access the system from outside.
  
On a lower level, there are several setup files in your home directory. Depending on the shell you use, these files differ in their structure and command syntax. If you are a new user of our systems, the system will copy a set of default files into your home directory. If you need setup files for a shell other than your login shell, or you are not a new user, but want to set yourself up from scratch, the default files can be found in ''/etc/skel''. Check out the ''README'' file in that directory.
+
The setup files are mainly used to set '''environment variables''' such as PATH, and to execute a few commands when the shell is started. Note that all shells first execute a default set-up script, and therefore have default values for the most common variables. You can check the current values of all environment variables by typing <pre>env</pre>
 +
|}
  
* For '''csh''' there are two basic setup files: '''.cshrc''' and '''.login'''. The former gets "sourced" (i.e. applied to the shell) every time you call a shell, while the latter only applies to login shells. Due to the leading "." these files are not visible if you type "ls"; you will have to type "ls -la" to see them. Editing this file lets you change the basic behavior of your shell. If you don't have any setup files in your account, our system will apply a simple default setup that lets you access system functions, compile code, run parallel programs, and use our scheduling software. Note that there may be other setup files. csh sources the .login file when you log in, and the .logout file when you log out. All these files reside in your home directory.
+
{|  style="border-spacing: 8px;"
* For '''ksh''' the main setup file is called '''.profile'''. It is also "invisible". If you don't have it in your directory, your shell will still be set up "reasonably" by our system. You can also obtain a default .profile from /etc/skel.
+
| valign="top" width="50%" style="padding:1em; border:1px solid #aaaaaa; background-color:#f7f7f7; border-radius:7px" |
* Since '''bash''' uses a similar scripting syntax as ksh, it can execute '''.profile''' on login as well. Other setup files for bash are '''.bashrc''' and '''.bash_profile''' which have a similar function for bash as .cshrc and .login do for csh. For details about which files are sourced in which order, consult the man pages: "man bash" or equivalent. As for the other shells, bash setup files may be obtained from /etc/skel.
+
== usepackage and the ''use'' command ==
  
The setup files are mainly used to set environment variables such as PATH, and to execute a few commands when the shell is started. Note that all shells first execute a default setup script, and therefore have default values for the most common variables. You can check the current values of all environment variables by typing
+
Most set-ups involve the setting of environment variables. These are variables that are used by your shell to determine its desired behaviour. Other set-up operations may include the execution of scripts. To simplify this task, our system supplies the '''use''' command. Instead of setting each variable and execute each script separately, everything is "lumped in" to the command <pre>use package_name</pre> where "package_name" stands for an application or functionality that you want to include.  
  
: env
+
A list of possible package_names can be obtained by typing <pre>use -l</pre>
  
== How do I use "use"? ==
+
Here is an example: To be able to use the electronic-structure software Gaussian, you need to execute ("source in") a lengthy set-up script, and set a few environment variable, e.g. to tell the system where to place temporary files:
  
Most setup consists of the setting of environment variables. These are variables that are used by your shell to determine its desired behavior. Other setup operations might include the execution of scripts. To simplify this task, our system supplies the '''use''' command. The manual setting of environment variables (such as PATH, for instance) is replaced by typing:
+
<pre>
 +
export g09root = "/opt/gaussian/g09e1"
 +
. /opt/gaussian/g09e1/g09/bsd/g09.profile
 +
export GAUSS_SCRDIR = "/scratch/$LOGNAME"
 +
</pre>
  
: use package_name
+
These commands can be replaced by <pre>use g09</pre> and the above commands are stored in a file <pre>/opt/usepackage/etc/usepackage.conf</pre>
  
where "package_name" stands for an application or functionality that you want to include in your setup. A list of possible package_names can be obtained by typing:
+
The use command also works inside of your login set-up file, i.e. .bash_profile, so you won't have to retype it every time you log in. By default, users are supplied with a basic set-up that corresponds to <pre>use standard-user-settings</pre> and includes access to most system functions, scheduler, and some compilers.
  
: use -l
+
Note: New shells do not always know about the use command. In that case you either have to set up that shell "manually", or teach it about use. This can be done with a single line: <pre>. /opt/usepackage/share/usepackage/use.bsh</pre>
  
Here is an example:
+
Note that it is rarely necessary to make invoked shells aware of use, as they inherit the setup of the invoking (login) shell.
  
In order for you to be able to use the programs in the "Blastwave" distribution, you would need to add the /opt/csw/bin directory to your PATH variable, the /opt/csw/share/man directory to your MANPATH variable, and the /opt/csw/share/info directory to your INFOPATH variable. Instead of doing this, you can also just type
+
== Manual Set-Up ==
  
: use blastwave
+
You can of course apply settings directly without using "use".
  
Note that "Blastwave" is included in the default user setup, and is used here only as an example.
+
One of the most important environment variables is '''PATH''', which tells the system where to look for the commands you issue. You may want to make your shell aware of some directories with system commands and shell commands in them.  
  
The use command will also work inside of your login setup file, e.g. .login for a csh. This makes it possible to apply the setting permanently, and you won't have to retype the use command every time you log in (which would defeat the purpose). By default, users are supplied with a reasonable setup that corresponds to
+
Another environment variable that is often useful is '''MANPATH'''. This is for the Unix manual pages, and tells the system where to look for online-documentation.
 
+
: use standard-user-settings
+
 
+
and includes access to most system functions, Cluster Tools, Grid Engine, Sun Studio compilers, and a few "extras".
+
  
However, if you invoke a shell from the command prompt or by executing a script, the new shell will not know about the usecommand. You either have to setup that shell "manually", or source a file to teach the shell about use. This can be done with a single line:
+
Yet another one is '''LD_LIBRARY_PATH''', which is sometimes used by applications to find dynamic runtime libraries. If you experience problems with missing libraries, try playing with LD_LIBRARY_PATH, otherwise it's best left unset.
  
 +
The command to set an EV is the binary operator '='. This is often followed by the '''export''' command, which makes the variable part of the environment:
 
<pre>
 
<pre>
source /opt/usepackage/share/usepackage/use.csh (for csh, tcsh, etc.)
+
VARIABLE=VALUE
. /opt/usepackage/share/usepackage/use.ksh (for sh, ksh, etc.)
+
export VARIABLE
. /opt/usepackage/share/usepackage/use.bsh (for bash)
+
 
</pre>
 
</pre>
  
Note that it is rarely necessary to make invoked shells aware of use, as they inherit the setup of the invoking (login) shell.
+
Note that it is possible to place "export" in front of the variable assignment instead of issuing two separate commands:<pre>export VARIABLE=VALUE</pre>
  
==How do I do this manually?==
+
To access the value of a environment variable, place a "$" in front of it. For example you want to see which value your variable PATH has, type <pre>echo $PATH </pre> where "echo" is a standard Unix command, and "$PATH" returns the value of PATH. The following command will append something to a previously defined variable:
  
If you don't want to use "use", you can of course apply the settings directly. This means essentially setting a few basic environment variables, the most important of which is '''PATH''', which tells the system where to look for the commands that you issue or for the files that are used while executing something within a shell. You want to make your shell aware of some directories with system commands and shell commands in them.
+
<pre>export PATH=$PATH":/yet/another/directory</pre>
  
Another environment variable that is often useful is '''MANPATH'''. This is for the Unix manual pages, and tells the system where to look for online-documentation.
+
Here, "PATH" is the variable and "$PATH" is its present value.
  
Yet another one is '''LD_LIBRARY_PATH''', which is sometimes used by applications to find dynamic runtime libraries. The variable tells the runtime environment where to look for these, and your program might not run if LD_LIBRARY_PATH is not set correctly. If you experience problems with missing runtime libraries, try playing with LD_LIBRARY_PATH, otherwise it's best left unset.
+
Sometimes a variable needs to be reset for a specific application. It is then best to write a shell script that sets the variables and starts the application, rather than setting the variables globally in your start-up files. In this example:
  
For a '''csh''', the the command to set environment variables is '''setenv''':
+
<pre>OMP_NUM_THREADS=8 omp_program</pre>
  
: setenv VARIABLE VALUE
+
The variable OMP_NUM_THREADS (which determines how many threads are being used) is set '''only''' for this specific run of the multi-threaded program omp_program.
  
where VARIABLE is the name of the environment variable, and VALUE is the value it is set to. This might be a number, or a string, in which case it should be enclosed by double quotes.
+
You can consult the configuration files of "usepackage" /opt/usepackage/etc/usepackage.conf to find out which setting you need to apply to run a specific software or access certain features. The syntax in that file is not hard to read, for instance the entry
 
+
For '''ksh''' or '''bash''' the command is just the binary operator '=', often followed by the '''export''' command, which makes the variable part of the environment:
+
 
+
: VARIABLE=VALUE
+
: export VARIABLE
+
 
+
Note that for '''bash''' it is possible to place "export" in front of the variable assignment instead of issuing two separate commands:
+
 
+
: export VARIABLE=VALUE
+
 
+
To access the value of a environment variable, you have to type a "$" in front of it. For example you want to see which value your variable PATH has, you type:
+
 
+
: echo $PATH
+
 
+
where "echo" is just a standard Unix command, and "$PATH" returns the value of PATH. The following command will append something to a previously defined variable (bash):
+
 
+
: export PATH=$PATH":/yet/another/directory"
+
 
+
Here, "PATH" denotes the variable and "$PATH" denotes its present value.
+
 
+
Sometimes a variable needs to be reset for a specific application. It is then best to write a shell script that sets the variables and starts the application, rather than setting the variables globally in your startup files.
+
 
+
You can consult the configuration files of "usepackage" to find out which setting you need to apply to run a specific software or access certain features. The configuration is in /opt/usepackage/etc/usepackage.conf
+
 
+
The syntax in that file is not hard to read, for instance the entry
+
  
 
<pre>
 
<pre>
>> blastwave : "Blastwave Solaris Packages" <<
+
>> g09 : "Gaussian 09 Update E.01" <<
blastwave :  
+
g09 : g09root = "/opt/gaussian/g09e1",
PATH += /opt/csw/bin,
+
      <[ . /opt/gaussian/g09e1/g09/bsd/g09.profile ]>,
MANPATH += /opt/csw/share/man,
+
      GAUSS_SCRDIR = "/scratch/$LOGNAME";
INFOPATH += /opt/csw/share/info ;
+
 
</pre>
 
</pre>
  
tells us what directories to prepend to the environment variables PATH, MANPATH, and INFOPATH, respectively if we want to use "Blastwave".
+
is responsible for the settings in the "Gaussian" example in the previous section.
 
+
|}
==How do I run pre-installed software ?==
+
{|  style="border-spacing: 8px;"
 +
| valign="top" width="50%" style="padding:1em; border:1px solid #aaaaaa; background-color:#e1eaf1; border-radius:7px" |
 +
== Running pre-installed software ==
  
A lot of software is pre-installed on our clusters. Some of this software requires specific license agreements, other programs are freely accessible. With the use command, most of them can be set up with a single line such as "use fluent" in your shell's startup file. If the software you want to run is not included in our usepackage list, please contact us, and we can include it. If you are using very specific software that is not accessed by other users, you might have to do the setup manually.
+
A lot of software is pre-installed on our clusters. Some of this software requires specific license agreements, other programs are freely accessible. With the use command, most of them can be set up with a single line such as "use fluent" in your shell's start-up file. If the software you want to run is not included in our usepackage list, please contact us, and we can include it. If you are using very specific software that is not accessed by other users, you might have to do the setup manually.
  
 
Here is a few steps to follow in that case.
 
Here is a few steps to follow in that case.
  
 
* Check out the '''documentation''' for the specific program, including users' manuals and home pages.
 
* Check out the '''documentation''' for the specific program, including users' manuals and home pages.
* Inform yourself about '''licensing'''. Some software requires each individual user to hold a license, some is covered by a collective license agreement, some does not require a license at all. For example, the finite-element structural code "Abaqus" is only accessible to users who work at an institution that is covered by a local license, whereas the license agreement for the electronic-structure code "Gaussian" covers all our HPCVL users. Finally, code such as "Gamess" (another quantum-chemistry program) are free to use by all users, although the distributor encourages registration.
+
* Inform yourself about '''licensing'''. Some software requires each individual user to hold a license, some is covered by a collective license agreement, some does not require a license at all. For example, the finite-element structural code "Abaqus" is only accessible to users who work at an institution that is covered by a local license, whereas the license agreement for the electronic-structure code "Gaussian" covers all of our users. Finally, code such as "Gamess" (another quantum-chemistry program) are free to use by all users, although the distributor encourages registration.
 
* Set the proper '''environment variables'''. This can usually be done in your shell setup files, since you'll be running the same code on most occasions you log on. These variables might include the PATH, but also variables specific for the program in question. Which ones to set you will be able to find out in most cases from the program documentation. Remember that this is only necessary if no entry exists in the "usepackage" configuration file, which can be checked by running "use -l".
 
* Set the proper '''environment variables'''. This can usually be done in your shell setup files, since you'll be running the same code on most occasions you log on. These variables might include the PATH, but also variables specific for the program in question. Which ones to set you will be able to find out in most cases from the program documentation. Remember that this is only necessary if no entry exists in the "usepackage" configuration file, which can be checked by running "use -l".
  
Line 160: Line 132:
 
You can learn more about parallel code by having a look at our [[FAQ:Parallel|Parallel Programming FAQ]]. We also have a bit more specific information about  parallel programming tools, namely [[FAQ:OpenMP|OpenMP compiler directives]] and the [[FAQ:MPI|Message Passing Interface (MPI)]].
 
You can learn more about parallel code by having a look at our [[FAQ:Parallel|Parallel Programming FAQ]]. We also have a bit more specific information about  parallel programming tools, namely [[FAQ:OpenMP|OpenMP compiler directives]] and the [[FAQ:MPI|Message Passing Interface (MPI)]].
  
==How do I get my terminal to work with this system ?==
+
== Help ==
 
+
If you have questions that you can't resolve by checking documentation, [mailto:cac.help@queensu.ca email to cac.help@queensu.ca].
In most cases your terminal settings are automatically selected and work "as is".
+
|}
 
+
In some cases when the machine used to connect to our machines is non-standard, an environment variable has to be set to tell our system what kind of terminal you are using. This variable is TERM. For instance, if you log in from a non-standard terminal type such as "vt220" you may have to type (bash):
+
 
+
: export TERM=vt100
+
 
+
If you are always logging in from the same terminal, you might as well put this into your setup file. In most cases you don't have to issue this at all because the system figures it out by itself.
+
 
+
If you want to run graphics applications that create windows on your desktop you will on rare occasions have to set another environment variable called "DISPLAY". That is done like:
+
 
+
: DISPLAY=ip_address:disp_num; export DISPLAY
+
 
+
for the others. ip_address stands for the IP address of your terminal or desktop, and disp_num is its "display number" (which is usually 0). If you don't know it, you can usually find it by typing "who am i" on sfnode0. Setting this environment variable will then display any newly called interfaces on your terminal. Or will it? ... Not quite. First you have to issue a command "xhost" on your local machine (usually a desktop). Typing "xhost sflogin0.hpcvl.queensu.ca" on your terminal enables you to receive displays from this remote machine. Now you're ready.
+
 
+
Note that the above procedure of setting the DISPLAY environment variable can most often be avoided by configuring your connection software (see next section about ssh clients) to enable "X11 forwarding".
+
 
+
==Still doesn't work. Where can I get help ?==
+
 
+
If you have questions that you can't resolve by checking documentation, [mailto:help@hpcvl.org email to help@hpcvl.org] or [[Contacts:UserSupport|contact one of our user support people]] directly.
+

Latest revision as of 13:44, 31 March 2017

How to Set Up a Unix Shell

This is an introduction to setting up your account on our systems. When first logging in, you are presented with a default set-up that enables the use of basic system commands, simple compilers, and access to the scheduler. This help file is meant to explain how to modify that default.

Shells

A shell is a command line interface that lets users issue commands to the operating system. It contains the basic Unix commands, as well as many more adcanced ones. The default shell for a Linux system is bash ("Bourne again" shell). There are others:

  • csh (C shell)
  • ksh (Korn shell)

They differ in their "feel" and how they handle system commands. ksh and bash largely understand each other's command syntax. csh is somewhat different.

bash is a "GNU" shell that uses features from the older shells csh and ksh. It is quite popular because it offers many convenient features, such as command and file-name completion by pressing the "Tab"-key. Its scripting syntax is almost identical to the one of ksh, which enables you to use ksh set-up files.

Some people prefer csh best because it is simple and its syntax is similar to the C programming language (thus the name). We discourage its use (see this for reasons).

ksh offers some extended features but is rarely used these days as it is similar to bash but offers less features.

Some programs require a specific shell to run. You can always call a shell by typing
/usr/bin/name_of_shell
where name_of_shell might be csh, tcsh, ksh, bash or sh (the latter is another standard shell that is often used for scripts). You may have to maintain set-up files for the shells you use, even if they are not your login shell.

In scripts, shells are usually called with a "hash-bang" sequence, that looks like:

#!/bin/bash
in the first line. In such cases, it can happen that environment variables, such as PATH get reset to some default. This is why it may be necessary to use the -f option:
#!/bin/csh -f
which avoids sourcing in the set-up files, leading to consistent behaviour for different users. All shells are documented in the man pages: type
man name_of_shell
to get more information than you'd care to know. Here are links for pretty complete documentation for the shells online:

In the following section, we assume a bash shell.

Setting up a shell

We are using a system called usepackage to setup the shell. This allows replacing the setting of several environment variables, and the execution of set-up scripts by simple commands of the form
use package
where package stands for a pre-defined application or feature that is to be included. We discuss the use of use in the next section.

There are several set-up files in your home directory:

  • .bashrc is "sourced in" every time a bash shell is invoked.
  • .bash_profile applies only to login shells, i.e. when you access the system from outside.
The setup files are mainly used to set environment variables such as PATH, and to execute a few commands when the shell is started. Note that all shells first execute a default set-up script, and therefore have default values for the most common variables. You can check the current values of all environment variables by typing
env

usepackage and the use command

Most set-ups involve the setting of environment variables. These are variables that are used by your shell to determine its desired behaviour. Other set-up operations may include the execution of scripts. To simplify this task, our system supplies the use command. Instead of setting each variable and execute each script separately, everything is "lumped in" to the command
use package_name
where "package_name" stands for an application or functionality that you want to include. A list of possible package_names can be obtained by typing
use -l

Here is an example: To be able to use the electronic-structure software Gaussian, you need to execute ("source in") a lengthy set-up script, and set a few environment variable, e.g. to tell the system where to place temporary files:

export g09root = "/opt/gaussian/g09e1"
. /opt/gaussian/g09e1/g09/bsd/g09.profile
export GAUSS_SCRDIR = "/scratch/$LOGNAME"
These commands can be replaced by
use g09
and the above commands are stored in a file
/opt/usepackage/etc/usepackage.conf
The use command also works inside of your login set-up file, i.e. .bash_profile, so you won't have to retype it every time you log in. By default, users are supplied with a basic set-up that corresponds to
use standard-user-settings
and includes access to most system functions, scheduler, and some compilers. Note: New shells do not always know about the use command. In that case you either have to set up that shell "manually", or teach it about use. This can be done with a single line:
. /opt/usepackage/share/usepackage/use.bsh

Note that it is rarely necessary to make invoked shells aware of use, as they inherit the setup of the invoking (login) shell.

Manual Set-Up

You can of course apply settings directly without using "use".

One of the most important environment variables is PATH, which tells the system where to look for the commands you issue. You may want to make your shell aware of some directories with system commands and shell commands in them.

Another environment variable that is often useful is MANPATH. This is for the Unix manual pages, and tells the system where to look for online-documentation.

Yet another one is LD_LIBRARY_PATH, which is sometimes used by applications to find dynamic runtime libraries. If you experience problems with missing libraries, try playing with LD_LIBRARY_PATH, otherwise it's best left unset.

The command to set an EV is the binary operator '='. This is often followed by the export command, which makes the variable part of the environment:

VARIABLE=VALUE
export VARIABLE
Note that it is possible to place "export" in front of the variable assignment instead of issuing two separate commands:
export VARIABLE=VALUE
To access the value of a environment variable, place a "$" in front of it. For example you want to see which value your variable PATH has, type
echo $PATH 
where "echo" is a standard Unix command, and "$PATH" returns the value of PATH. The following command will append something to a previously defined variable:
export PATH=$PATH":/yet/another/directory

Here, "PATH" is the variable and "$PATH" is its present value.

Sometimes a variable needs to be reset for a specific application. It is then best to write a shell script that sets the variables and starts the application, rather than setting the variables globally in your start-up files. In this example:

OMP_NUM_THREADS=8 omp_program

The variable OMP_NUM_THREADS (which determines how many threads are being used) is set only for this specific run of the multi-threaded program omp_program.

You can consult the configuration files of "usepackage" /opt/usepackage/etc/usepackage.conf to find out which setting you need to apply to run a specific software or access certain features. The syntax in that file is not hard to read, for instance the entry

>> g09 : "Gaussian 09 Update E.01" <<
g09 : g09root = "/opt/gaussian/g09e1",
      <[ . /opt/gaussian/g09e1/g09/bsd/g09.profile ]>,
      GAUSS_SCRDIR = "/scratch/$LOGNAME";

is responsible for the settings in the "Gaussian" example in the previous section.

Running pre-installed software

A lot of software is pre-installed on our clusters. Some of this software requires specific license agreements, other programs are freely accessible. With the use command, most of them can be set up with a single line such as "use fluent" in your shell's start-up file. If the software you want to run is not included in our usepackage list, please contact us, and we can include it. If you are using very specific software that is not accessed by other users, you might have to do the setup manually.

Here is a few steps to follow in that case.

  • Check out the documentation for the specific program, including users' manuals and home pages.
  • Inform yourself about licensing. Some software requires each individual user to hold a license, some is covered by a collective license agreement, some does not require a license at all. For example, the finite-element structural code "Abaqus" is only accessible to users who work at an institution that is covered by a local license, whereas the license agreement for the electronic-structure code "Gaussian" covers all of our users. Finally, code such as "Gamess" (another quantum-chemistry program) are free to use by all users, although the distributor encourages registration.
  • Set the proper environment variables. This can usually be done in your shell setup files, since you'll be running the same code on most occasions you log on. These variables might include the PATH, but also variables specific for the program in question. Which ones to set you will be able to find out in most cases from the program documentation. Remember that this is only necessary if no entry exists in the "usepackage" configuration file, which can be checked by running "use -l".

How do I run parallel code ?

That depends on how the code is "parallelized":

  • If it was "multi-threaded" by the compiler (automatic or via compiler directives), it is usually enough to set the environment variable PARALLEL or OMP_NUM_THREADS to the number of threads that should be used.
  • If it is MPI code, a special parallel runtime environment has to be used. The command there is mpirun, which has command-line options that let you tell how many and which processors to use. This command is part of the Cluster Tools parallel runtime environment. Cluster Tools involves a good deal of commands that let you modify the condition under which your program runs. The settings for these are included in our default setup.

You can learn more about parallel code by having a look at our Parallel Programming FAQ. We also have a bit more specific information about parallel programming tools, namely OpenMP compiler directives and the Message Passing Interface (MPI).

Help

If you have questions that you can't resolve by checking documentation, email to cac.help@queensu.ca.