On computational clusters it is very common to find users with code that depends on a particular version of a compiler or library. The effort required to convert the code to use a different version can be significant. To overcome this problem we install multiple versions of each compiler, library or application, and let each user choose the most suitable version. Environment Modules offer a simple means of customising your environment to access the required versions of installed software.

How do I discover what software is available?

[z1234567@katana ~]$ module avail 
 
-------------------------- /share/apps/modules/intel ---------------------------
intel/11.1.080(default)  intel/12.1.7.367  intel/13.0.1.117  intel/13.1.0.146
 
--------------------------- /share/apps/modules/pgi ----------------------------
pgi/13.7
 
-------------------------- /share/apps/modules/matlab --------------------------
matlab/2007b          matlab/2010b          matlab/2012a(default)
matlab/2008b          matlab/2011a          matlab/2012b
matlab/2009b          matlab/2011b          matlab/2013a

What can I do if the software that I want to use is not on the list?

If you require software installed on the cluster then email the IT Service Centre (ITServiceCentre@unsw.edu.au) detailing the software that you would like installed and that you would like to have it installed on Katana.

How do I add a particular version of software to my environment?

[z1234567@katana ~]$ module add matlab/2011b

How do I remove a particular version of software from my environment?

[z1234567@katana ~]$ module rm matlab/2011b

Which versions of software am I currently using?

[z1234567@katana ~]$ module list
Currently Loaded Modulefiles:
  1) intel/13.1.0.146   2) matlab/2013a

How do I find out more about a particular piece of software?

You can find out more about a piece of software by using the module help command. For example:

[z1234567@katana ~]# module help mrbayes
 
----------- Module Specific Help for 'mrbayes/3.2.2' --------------
 
MrBayes 3.2.2 is installed in /share/apps/mrbayes/3.2.2
 
This module was complied against beagle/2.1.2 and openmpi/1.6.4 with MPI support.
 
More information about the commands made available by this module is available
at http://mrbayes.sourceforge.net

How do I remove all software from my environment?

[z1234567@katana ~]$ module purge

How do I switch between particular versions of software?

[z1234567@katana ~]$ module switch matlab/2013a matlab/2012b

What does it mean if a version of software is marked as default?

This means that if the version number is omitted from the module add command then the default version will be selected. For example, the following command will load the default environment module for MATLAB, i.e. 2012a.

[z1234567@katana ~]$ module add matlab

Choosing the default software version can be useful when you are not restricted to a particular version and you always want to use the most recent version. This is possible because the default version will be updated whenever new versions of the software are installed.

How can I find out what paths and other environment variables a module uses?

You can use the module show command to list the changes that the module makes to the environment variables. For example

[z1234567@katana ~]$ module show nag/CLL6A23DGL
-------------------------------------------------------------------
/share/apps/modules/other/nag/CLL6A23DGL:
 
module-whatis    NAG C Library cll6a23dgl 
prepend-path     LD_LIBRARY_PATH /share/apps/nag/cll6a23dgl/lib:/share/apps/nag/cll6a23dgl/acml 
prepend-path     LIBRARY_PATH /share/apps/nag/cll6a23dgl/lib:/share/apps/nag/cll6a23dgl/acml 
prepend-path     CPATH /share/apps/nag/cll6a23dgl/include 
setenv           NAG_KUSARI_FILE /share/apps/nag/license.dat 
-------------------------------------------------------------------
[z1234567@katana ~]$ module show matlab
-------------------------------------------------------------------
/share/apps/modules/matlab/matlab/2012a:
 
module-whatis    MATLAB 2012a 
conflict         matlab 
prepend-path     PATH /share/apps/matlab/2012a/bin 
prepend-path     XAPPLRESDIR /share/apps/matlab/2012a/X11/app-defaults 
-------------------------------------------------------------------

Why does the cluster forget my choice of modules?

Environment modules only affect the particular session in which they are loaded. Loading a module in one SSH session will not affect any other SSH session or even any jobs submitted from that session. Modules must be loaded in every session where they will be used.

How can I invoke my module commands automatically?

Every time you log into the cluster or submit a job the commands in your $HOME/.bashrc file will be executed. It can be very convenient to save your environment module commands in this file. Open $HOME/.bashrc in a text editor and add your environment module commands to the section corresponding to the cluster you are using. For example:

 
katana*|kc*)
    # Global definitions
    if [ -f /etc/bashrc ]; then
        . /etc/bashrc
    fi
 
    # Local definitions
    module add intel
    module add matlab
    ;;

Note that different modules will be available on different clusters.

Module commands can also be included in job scripts. This approach is useful for preserving the required environment for each job and insulating jobs from any changes to your $HOME/.bashrc. For example:

#!/bin/bash
 
#PBS -l nodes=1:ppn=1
#PBS -l vmem=4gb
#PBS -j oe
 
module purge
module add intel/13.1.0.146
 
cd ${PBS_O_WORKDIR}
 
./myprog