You are here

Setting up your environment with modules

The default user environment on WestGrid systems varies from system to system according to the available hardware and software, and the local administrator's policies and opinions as to how much should be left to be customized by the individual user.  (There is an effort underway to provide a more unified environment across WestGrid, as systems purchased under WestGrid II are brought online.)  On most WestGrid systems, a command called module is provided to assist users to override the defaults. One uses the module command to load or unload modules (configuration files that typically specify such things as the PATH, MANPATH and LD_LIBRARY_PATH). The most common use of the module command is to select a particular compiler version, but, there may also be instances in which it is used to select among MPI distributions, or set environment variables needed to use particular application software.

Basics of module usage are covered here.  More details are available at the Environment Modules Project web site, or on some systems by typing man module.

Available modules

Several of the module-related commands allow you to determine what modules have been installed on a particular system.  Usually modules are installed by a system administrator, but, you can install your own also.

To see a list of available modules, type:

module avail

To see a list of available modules and a short description, type:

module whatis

To see currently loaded modules, type:

module list

For more information on a particular module, specify the name of the module after module help:

module help module_name

For more more detailed information on a particular module, type:

module show module_name

 For example, here is the output of these commands on Matrix, at the time of writing:

m129: module list
Currently Loaded Modulefiles:
  1) mpi/hp/default   2) pgi/8.0-1        3) hptc

m129: module help pgi/8.0-1
----------- Module Specific Help for 'pgi/8.0-1' ------------------
        Changes the PGI home directory to Target linux86-64 Version 8.0-1

m129: module show pgi/8.0-1
-------------------------------------------------------------------
/opt/modules/modulefiles/pgi/8.0-1:
module-whatis    Changes the PGI home directory to linux86-64 8.0-1
setenv           PGI /usr/apps/PGI-8.0-1
setenv           CC /usr/apps/PGI-8.0-1/linux86-64/8.0-1/bin/pgcc
setenv           FC /usr/apps/PGI-8.0-1/linux86-64/8.0-1/bin/pgf90
setenv           F90 /usr/apps/PGI-8.0-1/linux86-64/8.0-1/bin/pgf90
setenv           F77 /usr/apps/PGI-8.0-1/linux86-64/8.0-1/bin/pgf77
setenv           CPP /usr/apps/PGI-8.0-1/linux86-64/8.0-1/bin/pgcpp
setenv           CXX /usr/apps/PGI-8.0-1/linux86-64/8.0-1/bin/pgcpp
prepend-path     PATH /usr/apps/PGI-8.0-1/linux86-64/8.0-1/bin
prepend-path     MANPATH /usr/apps/PGI-8.0-1/linux86-64/8.0-1/man
prepend-path     LD_LIBRARY_PATH /usr/apps/PGI-8.0-1/linux86-64/8.0-1/lib:/usr/apps/PGI-8.0-1/linux86-64/8.0-1/libso
-------------------------------------------------------------------

Manipulating the environment with modules

Once you know the name of a module and have an idea about what it does, you can use the module load command to use that module:

module load module_name

In most cases, if you are using the module command to switch compilers, or versions of a software package, you will want to remove variables associated with the previous version, using the module unload command, before loading the new version.  This minimizes the possibility of conflict.

Here is an example, again on Matrix, in which an older version of the PGI compiler, 7.2-4 is selected to override the default (8.0-1).  On Matrix, the PGI-8.0-1 bin directory is defined in the default command PATH, so compiler commands such as pgcc and pgf95 will be version 8.0-1 of those commands.

m129: echo $PATH
/opt/hptc/bin:/usr/kerberos/bin:/usr/apps/java/bin:/usr/local/globus/bin:/usr/local/globus/sbin:
/usr/apps/PGI-8.0-1/linux86-64/8.0-1/bin:/opt/hpmpi/bin:...

m129: pgcc -V
pgcc 8.0-1 64-bit target on x86-64 Linux -tp k8-64

Now, unload the pgi/8.0-1 module and check to confirm that the PGI compiler is no longer on the command PATH:

m129: module unload pgi/8.0-1

m129: module list
Currently Loaded Modulefiles:
  1) mpi/hp/default   2) hptc
m129: echo $PATH
/opt/hptc/bin:/usr/kerberos/bin:/usr/apps/java/bin:/usr/local/globus/bin:/usr/local/globus/sbin:
/opt/hpmpi/bin:...

m129: pgcc -V
-bash: pgcc: command not found

Next, load the pgi/7.2-4 module (one of the options shown with module list) and verify that the pgcc command gives the correct version:

m129: module load pgi/7.2-4


m129: pgcc -V
pgcc 7.2-4 64-bit target on x86-64 Linux -tp k8-64

m129: echo $PATH
/usr/apps/PGI-7.2-4/linux86-64/7.2/bin:/opt/hptc/bin:/usr/kerberos/bin:/usr/apps/java/bin:/usr/local/globus/bin:
/usr/local/globus/sbin:/opt/hpmpi/bin:...

Finally, reload the original compiler.

m129: module unload pgi/7.2-4


m129: module load pgi/8.0-1

m129: echo $PATH
/usr/apps/PGI-8.0-1/linux86-64/8.0-1/bin:/opt/hptc/bin:/usr/kerberos/bin:/usr/apps/java/bin:/usr/local/globus/bin:
/usr/local/globus/sbin:/opt/hpmpi/bin:...

m129: module list
Currently Loaded Modulefiles:
  1) mpi/hp/default   2) hptc             3) pgi/8.0-1

Comparing the default PATH and module list output to that obtained after unloading and reloading the pgi/8.0-1 module, one sees that there is a change in the order of directories in the PATH and in the order of the modules listed.  This implies that the environment has not been restored exactly to its original state.  You may have to log out and log back in again to revert to the default state if that exact environment is needed.

Modules in batch scripts

Modules may also be needed in batch scripts, for example to ensure that specific run-time libraries are used.  However, the user environment for a batch job is not typically the same as for an interactive session on the login node.  To be sure that your environment is set up the way you expect, you might like to include commands such as the following in your batch scripts:

env
module list