Skip to content

Using modules

HPC cluster systems typically have a large number of software packages installed. Often there will be several versions provided for a package where it will be necessary for a user to choose between them. Equally, two different packages may clash with each other: for example, the commands for Intel MPI and Open MPI would overlap if simultaneously installed.

On Apocrita we use the modules package to manage the user environment for the installed packages. This makes it simple to use different packages or switch between versions of the same package without conflicts. Use the module or ml command to manage your Apocrita environment.

To get a list of available packages, use one of the following:

module avail

ml av

To load a module into your environment to start using an application, use one of the following:

module load <package>

ml <package>

replacing <package> with the relevant module name. For example, to load Matlab, use one of the following:

module load matlab

ml matlab

To get a list of currently loaded modules, use one of the following:

module list

ml

To unload a specific module, use one of the following:

module unload <package>

ml unload <package>

replacing <package> with the relevant module name. For example, to unload Matlab, use one of the following:

module unload matlab

ml unload matlab

To unload all loaded modules, use one of the following:

module purge

ml purge

Customised Environments

While we encourage users to customise their Apocrita environment to make their workflow easier, please be aware that customisations which change the user's environment for example by setting variables in the ~/.bash_profile file, or by using python's pip to create a ~/.local folder, may cause problems with modules which can be difficult to troubleshoot.

Loading a module can result in a message being displayed, such as warnings about a module's behaviour or other modules being loaded to satisfy dependencies. Examples of these are given in the following sections.

To suppress these messages, the -s option can be used with the module command:

$ module load use.dev
------------------------------------------------------------------------------
Loading Development Modules

The modules in the development environment are for testing purposes only.
Modules may be removed without prior warning.
Please do not use these modules for production jobs.

------------------------------------------------------------------------------

$ module purge
$ module -s load use.dev
$

Suppressing module output

Suppressing output from the module commands can make output from your job scripts tidier, but it can potentially hide important diagnostic information about your work. Be sure to display the output from module commands when performing unfamiliar work, when looking at potential problems or seeking help from others.

Default versions

Environment modules also support the concept of default versions. The default version, where it exists, is shown in the output of module avail. For example, module load matlab will load matlab/2021a, since it is marked as default. If you wish to load the 2017a version then you will need to specify module load matlab/2017a. For example:

$ module avail matlab
---------------- /share/apps/environmentmodules/centos7/general ----------------
matlab/2016a  matlab/2018a  matlab/2020a
matlab/2017a  matlab/2019a  matlab/2021a(default)

$ module load matlab
$ module list
Currently Loaded Modulefiles:
 1) matlab/2021a(default)

$ module purge
$ module load matlab/2017a
$ module list
Currently Loaded Modulefiles:
 1) matlab/2017a

Sometimes we stick with an older version as the default, since a lot of people may still be using that version, and will require checking of scripts and communication to all users of the package. For popular packages, we rarely make the newest version the default one, due to the potential for introduction of incompatibilities or inconsistent results.

Dependencies

Some of the software provided by a module may in turn depend on software provided by another module. For example, an FFTW implementation offering MPI support will require a suitable MPI package. These cases may be handled by module dependencies. In this example, the module fftw/3.3.8-openmpi depends on the MPI implementation provided by the module openmpi/3.0.0-gcc. On Apocrita, the module system is set up to load dependent modules automatically rather than requiring users to satisfy the dependencies first. We see that loading this FFTW module also loads the Open MPI module:

$ module load fftw/3.3.8-openmpi
Loading fftw/3.3.8-openmpi
  Loading requirement: openmpi/3.0.0-gcc gcc/7.1.0

$ module list
Currently Loaded Modulefiles:
 1) openmpi/3.0.0-gcc(default)   2) gcc/7.1.0(default)   3) fftw/3.3.8-openmpi

Here we see that the GCC module gcc/7.1.0 has also been loaded.

Conflicts

When two packages may cause problems when both made accessible, their modules will conflict with each other. This means that they cannot both be loaded. In particular, different versions of the same module may not be used at the same time:

$ module load intel/2018.1
$ module load intel/2018.3
Loading intel/2018.3
  ERROR: intel/2018.3 cannot be loaded due to a conflict.
    HINT: Might try "module unload intel/2018.1" first.

Some modules may load dependent modules and these dependencies may cause a conflict like:

$ module load openmpi/3.0.0-gcc namd/2.12-openmpi
Loading openmpi/2.1.0-gcc
  ERROR: openmpi/2.1.0-gcc cannot be loaded due to a conflict.
    HINT: Might try "module unload openmpi/3.0.0-gcc" first.

Loading namd/2.12-openmpi
  ERROR: namd/2.12-openmpi cannot be loaded due to missing prereq.
    HINT: the following module must be loaded first: openmpi/2.1.0-gcc

If you require the use of a specific version which conflicts with another module's dependency please send us an email at its-research-support@qmul.ac.uk.

Development versions

When requesting a new version or software package you may be asked to test a development version before it is released. These test installations will be made available through development modules.

To access development modules you can load the use.dev module:

$ module load use.dev
$ module avail
---------------- /share/apps/environmentmodules/dev ----------------
test/2.1.2      testing/2.3

$ module load test/2.1.2

On acceptance, the module will be moved to the production module set and the use.dev module will no longer be required to access it.

Deprecated modules

Once a software package has been made available with a module in the production module set, it will generally remain available for future use. However, in some circumstances, such as those related to security or performance problems, it may be necessary for modules to be deprecated ahead of eventual removal. A deprecated module will lose its default visibility and we recommend no further use of the module.

Deprecated modules, and installations, will usually have an alternative module available and in the first instance we recommend considering using this. Contact us if you experience problems using an alternative module.

To gain access to modules which have been deprecated you can load the use.deprecated module. For example, the deprecated module openmpi/2.0.2-gcc may be loaded by module load use.deprecated openmpi/2.0.2-gcc/.

Private modules

It is possible to have your own module files to enable you to install and manage specific versions of software without affecting existing installations.

This is mostly useful when you have very specific needs that will not be shared with other users.

Similarly to development modules, these private modules may be accessed by loading the module use.own.

Basic setup

Private modules are defined within modulefiles stored in ~/privatemodules. If this directory does not exist, it is created when the use.own module is loaded.

This example uses a python install done under ~/privatemodules/python/3.4.3

If your own installation is in a different directory the paths will need to be modified.

To setup a module you'll need to do the following:

# Make "privatemodules" directory in your home directory using either
mkdir ~/privatemodules
# or
module load use.own

# using an editor (vim in this case) create a module file called "test_module"
vim ~/privatemodules/test_module

Module Files

Modulefiles handle the path adjustments required for an application to work, the full syntax is defined in the MODULEFILE(4) man page. This can be read with

man 4 modulefile

The basics are covered by this example modulefile for python 3.4.3:

#%Module########################################################################
#
# python 3.4.3 module file

proc ModulesHelp { } {
    puts stderr "\tAdds python 3.4.3 to your environment"
}

module-whatis "Loads Python 3.4.3"

prepend-path PATH ~/privatemodules/python/3.4.3/bin
prepend-path LD_LIBRARY_PATH ~/privatemodules/python/3.4.3/lib
prepend-path C_INCLUDE_PATH ~/privatemodules/python/3.4.3/include
prepend-path PKG_CONFIG_PATH ~/privatemodules/python/3.4.3/lib/pkgconfig
prepend-path MANPATH ~/privatemodules/python/3.4.3/share/man
prepend-path PYTHONPATH ~/privatemodules/python/3.4.3/lib/python3.4.3

Usage

Once a module is configured in a modulefile and the software has been installed you can use private modules with the following commands:

$ module load use.own
$ module load test_module

$ which python
/data/home/abc123/privatemodules/python/3.4.3/bin/python