Environment Modules

General Information

Overview

Environment Modules allow you to easily load and unload specific pieces of software. Unlike the previously-used mpi-selector functionality, changes made using Modules take effect in your current shell immediately (you do not have to log out and back in) as shown in the following example; changes are not persistent across future login shells, unless you put them into your "$HOME/.modules" file, as described below.

A video tutorial is now included in our Getting Started video series.


$ icc --version
icc (ICC) 12.1.4 20120410
Copyright (C) 1985-2012 Intel Corporation.  All rights reserved.

$ module unload compiler_intel/12.1.4
$ module load compiler_intel/13.0.1
$ icc --version
icc (ICC) 13.0.1 20121010
Copyright (C) 1985-2012 Intel Corporation.  All rights reserved.

Default Environment

In order to make this process easier, we have created a module called defaultenv, and have set up the system to automatically load this by default. We expect that most users will not need to change this, but syntax examples on how to change it will be shown below. As of this writing, the defaultenv module loads the default versions of the following other modules:

  • compiler_gnu
  • compiler_intel
  • compiler_pgi
  • mpi

Prerequisites, Conflicts, and Error Messages

Modules allow for the creation of relationships between modules, including prerequisites (modules that must already be loaded before this one can load), and conflicts (modules that cannot be loaded when this module loads).

Conflicts

For example, we have the MPI modules set up to conflict with one another, so that a user can only have one loaded at a time. We also have the modules for the Intel compilers conflict with each other, so a user cannot have multiple versions of the Intel compilers loaded at the same time. However, we don't have anything that prevents you from having one version of the Intel compilers, and one version of the GNU compilers, loaded at the same time.

The following example shows the error message you would receive when you try to load a conflicting module:


$ module load compiler_intel/13.0.1
compiler_intel/13.0.1(3):ERROR:150: Module 'compiler_intel/13.0.1' conflicts with the currently loaded module(s) 'compiler_intel/12.1.4'
compiler_intel/13.0.1(3):ERROR:102: Tcl command execution failed: conflict compiler_intel

Prerequisites

Normally, when one module requires another module as a prerequisite, and you try to load it anyway, you would get a message similar to the one for the conflict, as shown above. However, we have, as of this writing, chosen to automatically load the prerequisite for you instead. For example, if you load the "mpi/openmpi_1.6.3_intel-13.0.1" module, which requires "compiler_intel/13.0.1" as a prerequisite, it will make sure that the prerequisite is loaded. Note that it will have to unload any modules that conflict with the prerequisite first, and will output a message when it does, as shown in this example:


$ module load mpi/openmpi_1.6.3_intel-13.0.1
This module requires that we load the compiler_intel/13.0.1 module for you.  Loading it now.

Syntax examples

The following section demonstrates most of the operations that you will need, in order to manage modules.

Listing currently-loaded modules


$ module list
Currently Loaded Modulefiles:
  1) compiler_gnu/4.4(default)        4) mpi/openmpi_1.6.3_intel-13.0.1
  2) compiler_pgi/12.5(default)       5) defaultenv/0.1(default)
  3) compiler_intel/13.0.1

Listing all available modules


$ module avail

-------------------------------- /usr/share/Modules/modulefiles ---------------------------------
dot         module-cvs  module-info modules     null        use.own

-------------------------------------- /apps/.modulefiles ---------------------------------------
compiler_gnu/4.4(default)          defaultenv/0.1(default)
compiler_intel/12.1.4(default)     mpi/openmpi_1.6.3_gnu-4.4(default)
compiler_intel/13.0.1              mpi/openmpi_1.6.3_intel-12.1.4
compiler_pgi/12.10                 mpi/openmpi_1.6.3_intel-13.0.1
compiler_pgi/12.5(default)         mpi/openmpi_1.6.3_pgi-12.5

Get information for a specific module


$ module help compiler_intel/12.1.4

----------- Module Specific Help for 'compiler_intel/12.1.4' ---------------------------

Sets up Intel Compilers (v12.1.4) and associated tools, including Math Kernel Libraries.

Unload a currently-loaded module


$ module list
Currently Loaded Modulefiles:
  1) compiler_gnu/4.4(default)        4) mpi/openmpi_1.6.3_intel-13.0.1
  2) compiler_pgi/12.5(default)       5) defaultenv/0.1(default)
  3) compiler_intel/13.0.1
$ module unload compiler_intel
$ module list
Currently Loaded Modulefiles:
  1) compiler_gnu/4.4(default)        3) mpi/openmpi_1.6.3_intel-13.0.1
  2) compiler_pgi/12.5(default)       4) defaultenv/0.1(default)

Note that if you unload a module using the generic name (eg "compiler_intel"), it will unload the first one that it encounters in the list. If you have multiple non-conflicting modules loaded, that have the same generic name, you will want to be more specific when you unload them (eg. "module unload compiler_intel/13.0.1")

Load a module


$ module list
Currently Loaded Modulefiles:
  1) compiler_gnu/4.4(default)        3) mpi/openmpi_1.6.3_intel-13.0.1
  2) compiler_pgi/12.5(default)       4) defaultenv/0.1(default)
$ #Load whatever the default version of "compiler_intel" is:
$ module load compiler_intel
$ module list
Currently Loaded Modulefiles:
  1) compiler_gnu/4.4(default)        4) defaultenv/0.1(default)
  2) compiler_pgi/12.5(default)       5) compiler_intel/12.1.4(default)
  3) mpi/openmpi_1.6.3_intel-13.0.1
$ module unload compiler_intel
$ #Load a specific version of "compiler_intel"
$ module load compiler_intel/13.0.1
$ module list
Currently Loaded Modulefiles:
  1) compiler_gnu/4.4(default)        4) defaultenv/0.1(default)
  2) compiler_pgi/12.5(default)       5) compiler_intel/13.0.1
  3) mpi/openmpi_1.6.3_intel-13.0.1

Swapping one module for another

Note that this is the same thing as if you did a "module unload" followed by a "module load". It's just a shortcut.


$ module list
Currently Loaded Modulefiles:
  1) compiler_gnu/4.4(default)        4) defaultenv/0.1(default)
  2) compiler_pgi/12.5(default)       5) compiler_intel/12.1.4(default)
  3) mpi/openmpi_1.6.3_intel-13.0.1
$ module swap compiler_intel/12.1.4 compiler_intel/13.0.1
$ module list
Currently Loaded Modulefiles:
  1) compiler_gnu/4.4(default)        4) defaultenv/0.1(default)
  2) compiler_pgi/12.5(default)       5) compiler_intel/13.0.1
  3) mpi/openmpi_1.6.3_intel-13.0.1

Purge Modules (unload all currently-loaded modules)


$ module list
Currently Loaded Modulefiles:
  1) compiler_gnu/4.4(default)            4) mpi/openmpi_1.6.3_gnu-4.4(default)
  2) compiler_intel/12.1.4(default)       5) defaultenv/0.1(default)
  3) compiler_pgi/12.5(default)
$ module purge
$ module list
No Modulefiles Currently Loaded.

Make persistent changes 

If you want to make changes to your environment, and have the changes persist across multiple logins, etc., you can do so by modifying the file "$HOME/.modules" using your favorite text editor (vim, emacs, nano, etc.). Simply modify the the file to contain the list of commands (eg. "module unload ..." or "module load ...") that you want to occur.

For example, the following file loads the default environment, but then swaps two modules:


#%Module

module load defaultenv
module swap compiler_intel compiler_intel/13.0.1
module swap mpi mpi/openmpi_1.6.3_intel-13.0.1

Load modules inside a job script

It is possible to load and unload specific modules as a part of your job script, making the changes available within your job's environment, without making the changes persistent for all your shells. Changes made within the script will be available inside the script, but will not persist after the script completes executing, as shown in this example:


#!/bin/bash
#PBS -l nodes=2:ppn=4,walltime=30:00,pmem=2gb
#PBS -m n


module swap mpi mpi/openmpi_1.6.3_gnu-4.4

#run code that depends on the GNU-compiled version of OpenMPI

module swap mpi mpi/openmpi_1.6.3_intel-12.1.4

#run code that depends on the Intel (v12.1.4) compiled version of OpenMPI

Advanced Features

Loading your own (or group's) modules

It is possible to create your own modules, and manage them the same way as the ones that the system provides. This would be the most useful if you have many versions of software installed, and need to switch between them quickly and easily. This can also be used for software installed in a group directory as well.

The syntax on how to do this is currently beyond the scope of this document. We will attempt to place documentation on this technique here in the future, but if you wish to use this feature now, please contact us for more details.