Computing Environment

The UNIX shell is the interface to the UNIX operating system. The HPC cluster allows use of the enhanced Bourne shell bash, the enhanced C shell tcsh, and the enhanced Korn shell zsh. IT will primarily support bash, the default shell.

For most Linux systems, the sh shell is the bash shell and the csh shell is the tcsh shell. The remainder of this document will use only bash commands.

Environment variables store dynamic system values that affect the user environment. For example, the PATH environment variable tells the operating system where to look for executables. Many UNIX commands and tools, such as the compilers, debuggers, profilers, editors, and applications with graphical user interfaces, often look at environment variables for information they need to function. The man pages for these programs typically have an ENVIRONMENT VARIABLES section with a list of variable names which tells how the program uses the values.

This is why we encourage users to use VALET to modify your environment versus explicitly setting environment variables.

In bash, a variable must be exported to be used as an environment variable. By convention, environment variables are all uppercase. You can display a list of currently set environment variables by typing

    env

The echo and export commands will display and set environment variables.

You can display specific environment variables by typing

For example,

    echo $HOME
    export FFLAGS='-g -Wall'

The variable FFLAGS will have the value '-g -Wall' in the shell and exported to programs run from this shell.

This section uses the wiki's documentation conventions.

All UNIX systems set up a default environment and provide users with the ability to execute additional UNIX commands to alter the environment. These commands are automatically sourced (executed) by your shell and define the normal and environmental variables, command aliases, and functions you need. Additionally, there is a final system-wide startup file that automatically makes global environment changes that IT sets for all users.

You can modify the default environment by adding lines at the end of the ~/.bash_profile file and the ~/.bashrc file. These modifications affect shells started on the login node and the compute nodes. In general we recommend that you should not modify these files especially when software documentation refers to changing the PATH environment variable, instead use VALET to load the software.

• The ~/.bash_profile file's commands are executed once at login. Add commands to this file to set your login environment and to run startup programs.
• The ~/.bashrc file's commands are executed by each new shell you start (spawn). Add lines to this file to create aliases and bash functions. Commands such as xterm and workgroup automatically start a new shell and execute commands in the ~/.bashrc file. The salloc command starts a shell on a compute node and will execute the ~/.bashrc file from your home directory, but it does not execute the commands in the ~/.bash_profile file.

You may modify the IT-supplied ~/.bash_udit file to be able to use several IT-supplied aliases (commands) and environment settings related to your workgroup and work directory . Edit .bash_udit and follow the directions in the file to activate these options. This is the ONLY way you should set your default workgroup at login. DO NOT add the workgroup command to your .bashrc or .bash_profile as this will likely prevent you from logging in and will cause file transfer programs like WinSCP, sftp or Fetch to break.

Exiting the login session or typing the logout command executes your ~/.bash_logout file and terminates your session. Add commands to ~/.bash_logout that you want to execute at logout.

To restore the .bash_profile, .bashrc, .bash_udit and .bash_logout files in your home directory to their original state, type:

    cp /opt/shared/templates/homedir/.bash* $HOME

There are some key environment variables that are set for you, and are important for your work on any cluster. They are used to find directories for your projects. These environment variables are set on initial connection to a cluster, and will be changed if you

• set your workgroup (cluster group investing-entity name) with the workgroup command,
• change to your project directory with the cd command,
• connect to the compute node with salloc (or sbatch) command.

The system's initialization scripts set the values of some environment variables to help use the filesystems.

To use the compute nodes for a particular investing-entity cluster group (workgroup), you need to use the workgroup command.

For example,

    workgroup –g it_css

starts a new shell for the workgroup it_css, and sets the environment variables:

When you first connect to the login node, all your commands are executed from your home directory. Most of your work will be done in your private group work directory. The workgroup command has an option to start you in the private group work directory. For example,

    workgroup -cg it_css

will spawn a new shell in the workgroup directory for it_css.

You can always use the cd bash command.

For example,

    cd project/fuelcell
    cd /lustre/scratch/traine/project/fuelcell
    cd $WORKDIR/project/fuelcell

The first is using a path name relative to the current working directory (implied ./). The second to use the full path ($WOKDIR always begins with a /) In all cases the directory is changed, and the $PWD environment variable is set:

To run a job on the compute nodes, you must submit your job script using sbatch or start an interactive session using salloc. In both cases, you will be connected to one of your investing-entity's compute nodes with a clean environment. Do not rely on the environment you set on the login node. The variables USER, HOME, WORKGROUP, WORKDIR, and PWD are all set on the compute node to match the ones you had on the login node, but two variables are set to node-specific values:

An empty directory is created by the SLURM job scheduler that is associated with your job and defined as TMPDIR. This is a safe place to store temporary files that will not interfere with other jobs and tasks you or other members of your group may be executing. This directory is automatically emptied on normal termination of your job. This way the usage on the node scratch filesystem will not grow over time.

This section uses the wiki's documentation conventions.

The UD-developed VALET system facilitates your use of compilers, libraries, programming tools and application software. It provides a uniform mechanism for setting up a package's required UNIX environment. VALET is a recursive acronym for VALET Automates Linux Environment Tasks. It provides functionality similar to the Modules package used at other HPC sites.

VALET commands set the basic environment for software. This may include the PATH, MANPATH, INFOPATH, LDPATH, LIBPATH and LD_LIBRARY_PATH environment variables, compiler flags, software directory locations, and license paths. This reduces the need for you to set them or update them yourself when changes are made to system and application software. For example, you might find several versions for a single package name, such as Mathematica/8 and Mathematica/8.0.4. You can even apply VALET commands to packages that you install or alter its actions by customizing VALET's configuration files. Type man valet for instructions or see the VALET software documentation for complete details.

The table below shows the basic informational commands for VALET. In subsequent sections, VALET commands are illustrated in the contexts of application development (e.g., compiling, using libraries) and running IT-installed applications.

Users can maintain their own work directories ($WORKDIR) apart from the common work directory of the workgroup. It is also possible to make VALET software to look into this user level work directory. Users can now add ~/.workdirs.yaml to override what gets set for $WORKDIR for workgroups to which they are members. Detailed explanation follows.

[traine@login00 ~]$ workdir -g it_css
/work/it_css
 
[traine@login00 ~]$ echo "it_css: /work/it_css/users/traine" > ~/.workdirs.yaml
 
[traine@login00 ~]$ workdir -g it_css
/work/it_css/users/traine

Now inside the new work directory, users can create sw/valet directory to add valet packages

[traine@login00 ~]$ ls -l /work/it_css/users/traine/sw/valet
total 11
-rw-r--r-- 1 frey it_nss 480 Sep 21 16:06 wrf.vpkg_yaml

From this point, valet looks at this directory for possible valet packages and also the $WORKDIR after changing to workgroup will point to the path overridden in workdirs.yaml file.

traine@login00 ~]$ workgroup -g it_css
 
[(it_css:traine)@login00 ~]$ echo $WORKDIR
/work/it_css/users/traine
 
[(it_css:traine)@login00 ~]$ vpkg_info wrf
[wrf] {
  contexts: all
  actions: {
    WRF_PREFIX=${VALET_PATH_PREFIX} (contexts: development)
  }
  https://www.mmm.ucar.edu/weather-research-and-forecasting-model
  A next-generation mesoscale numerical weather prediction system
  prefix: /opt/shared/wrf
  source file: /work/it_css/users/traine/sw/valet/wrf.vpkg_yaml
  default version: wrf/3.8.1:intel
  versions: {
    [wrf/3.8.1:intel] {
      contexts: all
      dependencies: {
        hdf5/1.8.20:openmpi,intel
        netcdf/4.1.3:intel
      }
      default configuration, Intel compilers and MPI
      prefix: /opt/shared/wrf/3.8.1-intel
      standard paths: {
        bin: /opt/shared/wrf/3.8.1-intel/bin
      }
    }
  }
}

To revert back to the defaults:

[(it_css:traine)@login00 ~]$ exit
exit
 
[traine@login00 ~]$ rm ~/.workdirs.yaml 
 
traine@login00 ~]$ workgroup -g it_css
 
[(it_css:traine)@login00 ~]$ echo $WORKDIR
/work/it_css