Modules Environment

Tip

If you are already somewhat familiar with modules from your home system you may get more from this page if you first read our page on the available software stacks. However, if you are not very familiar with modules it may be best to first read this page, then the one on the software stacks and then re-read this page as you will get more information out of it.

Software modules allow you to control which software and versions are available in your environment. Modules contain the necessary information to allow you to run a particular application or provide you access to a particular library so that

different versions of a software package can be provided
you can easily switch to different versions without having to explicitly specify different paths
you don't have to deal with dependent modules, they are loaded at the same time as the software

Almost all compute clusters use software modules. Currently there are three competing implementations, so you may not be familiar with Lmod already. And even if you are already familiar with Lmod from your home cluster we still encourage you to read through this page as not all sites promote the same Lmod features.

Which module system am I using?

There are currently three different popular implementations of modules:

Environment Modules version 3.X which uses modules written in Tcl but itself is written in C. This version is no longer maintained, but is one of the systems offered on Cray systems.
Environment Modules version 4.X and 5.X which is a continuation of the Tcl modules but now entirely written in Tcl itself. It is developed at CEA in France.
Lmod uses module files written in Lua and itself is also written in Lua. It is compatible with many Tcl module files (from both versions of Environment Modules) through an automatic translation layer. Lmod is developed at TACC.

You can see which version of modules your home cluster is using by executing

module --version

at the command prompt. For the old environment modules, the output will start with VERSION=3.2.11 or something similar, for the new Environment Modules it will report as Modules Release 4.X or Modules Release 5.x or something similar, and for Lmod it will explicitly say Modules based on Lua.

The `module` command

Modules are managed by the module command:

module <sub-command> <module-name>

where the sub-command indicates the operation you want to perform. The sub-command is followed by the name of the module on which you want to perform the operation.

Sub-command	Description
`spider`	Search for modules and display help
`keyword`, `key`	Search for modules based on keywords
`avail`, `av`	List available modules
`whatis`	Display short information about modules
`help`	Print the help message of a module
`list`	List the currently modules loaded
`load`, `add`	Load a module
`unload`	Remove a module from your environment
`purge`	Unload all modules from your environment
`show`	Show the commands in the module's definition file

Finding modules

Lmod is a hierarchical module system. It distinguishes between installed modules and available modules. Installed modules are all modules that are installed on the system. Available modules are all modules that can be loaded directly at that time without first loading other modules. The available modules are often only a subset of the installed modules. However, Lmod can tell you for each installed module what steps you have to take to also make it available so that you can load it. This is why the commands for finding modules are so important.

Some modules may also provide multiple software packages or extensions. Lmod can also search for these but this feature.

Not fully supported on LUMI

The LMOD feature to search for, e.g., Python packages inside a module or other software in a module is not fully exploited on LUMI as the output of some module commands becomes very long and ways to disabling that output do not work properly in the current version of Lmod on LUMI. This is due to two bugs, one of which is present even in newer versions of Lmod as of November 2021.

module spider

The basic command to search for software on LUMI is module spider. It has three levels, producing different outputs:

module spider without further arguments will produce a list of all installed software and show some basic information about those packages. Some packages may have an (E) behind their name and will appear in blue (in the default colour scheme) which means that they are part of a different package. The following levels of module spider will then tell you how to find which module(s) to load.

Note that module spider will also search in packages that are hidden from being displayed. These packages can be loaded and used. However we hide them either because they are not useful to regular users or because we think that they will rarely or never be directly loaded by a user and want to avoid overloading the module display.
module spider <name of package> will search for the specific package. This can be the name of a module, but it will also search some other information that can be included in the modules. The search is also case-insensitive. E.g.,
```
module spider GNUplot
```
will show something along the lines of
```
------------------------------------------------------------------
  gnuplot:
------------------------------------------------------------------
    Description:
      Gnuplot is a portable command-line driven graphing utility

     Versions:
        gnuplot/5.4.2-cpeCray-21.08
        gnuplot/5.4.2-cpeGNU-21.08
```
so even though the capitalisation of the name was wrong, it can tell us that there are two versions of gnuplot. The cpeGNU-21.08 and cpeCray-21.08 tell that the difference is the compiler that was used to install gnuplot, being the GNU compiler (PrgEnv-gnu) and the Cray compiler (PrgEnv-cray) respectively.

Similarly,
```
module spider CMake
```
returns output similar to
```
---------------------------------------------------------------------
  CMake: CMake/3.21.2 (E)
---------------------------------------------------------------------
    This extension is provided by the following modules. To access the
extension you must load one of the following modules. Note that any
module names in parentheses show the module location in the software
hierarchy.

       buildtools/21.08 (LUMI/21.08 partition/L)
       buildtools/21.08 (LUMI/21.08 partition/G)
       buildtools/21.08 (LUMI/21.08 partition/D)
       buildtools/21.08 (LUMI/21.08 partition/C)
       buildtools/21.08 (CrayEnv)

Names marked by a trailing (E) are extensions provided by another module.
```
This tells that there is no CMake module on the system but that CMake (version 3.21.2) is provided by a module called buildtools/21.08 which is not readily available but requires loading any of the sets of modules between the parentheses, which in fact point to the different software stacks and node types on the system.

Information on LUMI software stacks?

For more information on the software stacks on LUMI, head to the Software stacks page.

Known issue

We have run into cases where this list is incomplete. It seems that Lmod sometimes fails to find all possible combinations to make a particular module available.

In some cases, if there is no ambiguity, module spider will actually already produce help about the package.

module spider <module name>/<version> will show more help information about the package, including information on which other modules need to be loaded to be able to load the package. E.g.,

module spider git/2.33.1

will return

-------------------------------------------------------------------
  git: git/2.33.1
-------------------------------------------------------------------
   Description:
     Git is a free and open source distributed version control
     system

   You will need to load all module(s) on any one of the lines below
   before the "git/2.33.1" module is available to load.

     CrayEnv
     LUMI/21.08  partition/C
     LUMI/21.08  partition/D
     LUMI/21.08  partition/G
     LUMI/21.08  partition/L

   Help:

(abbreviated output). Note that it also tells you which other modules need to be loaded. You need to choose the line which is appropriate for you and load all modules on that line, not the whole list of in this case 9 modules.

module keyword

Another search command that is sometimes useful is module keyword. It really just searches for the given word in the short descriptions that are included in most module files and in the name of the module. The output is not always complete since not all modules may have a complete enough short description.

Consider we are looking for a library or package that supports MP3 audio encoding.

module keyword mp3

will return something along the lines of

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

The following modules match your search criteria: "mp3"
----------------------------------------------------------------

  LAME: LAME/3.100-cpeCray-21.08, LAME/3.100-cpeGNU-21.08
    LAME is a high quality MPEG Audio Layer III (mp3) encoder

though the output will depend on the version of Lmod. This may not be the most useful example on a supercomputer, but the library is in fact needed to be able to install some other packages even though the sound function is not immediately useful.

Know issue: Irrelevant output

At the moment of writing of this documentation page, this command actually returns a lot more output, referring to completely irrelevant extensions. This is a bug in the HPE-Cray-provided version of Lmod

module avail

The module avail command is used to show only available modules, i.e., modules that can be loaded directly without first loading other modules. It can be used in two ways:

Without a further argument it will show an often lengthy list of all available modules. Some modules will be marked with (D) which means that they are the default module that would be loaded should you load the module using only its name.
With the name of a module (or a part of the name) it will show all modules that match that (part of) a name. E.g.,
```
module avail gnuplot
```
will show something along the lines of
```
------ EasyBuild managed software for software stack LUMI/21.08 on LUMI-L ------
   gnuplot/5.4.2-cpeCray-21.08    gnuplot/5.4.2-cpeGNU-21.08 (D)

  Where:
   D:  Default Module
    (output abbreviated).
```
but
```
module avail gnu
```
will show you an often lengthy list that contains all packages with gnu (case insensitive) in their name or version.

Getting help

One way to get help on a particular module has already been discussed on this page: module spider <name>/<version> will produce help about the package as soon as it can unambiguously determine the package. It is the only command that can produce help for all installed packages. The next two commands can only produce help about available packages.

A second command is module whatis with the name or name and version of a module. It will show the brief description of the module that is included in most modules on the system. If the full version of the module is not given, it will display the information for the default version of that module.

The third command is module help. Without any further argument it will display some brief help about the module command. However, when used as module help <name> or module help <name>/<version> it will produce help for either the default version of the package (if the version is not specified) or the indicated version.

Loading and unloading modules

Loading and unloading modules in Lmod is very similar to other module systems. Also node that only available modules can be loaded with the commands below. Some installed modules may only become available after first loading other modules as discussed above.

To load a module, use the module load command. For example, to load the Cray FFTW library, use:

$ module load cray-fftw

This command will load the default version of the module. If the software you loaded has dependencies, they will be loaded in your environment at the same time.

To load a specific version of the module you need to specify it after the name of the module.

$ module load cray-fftw/3.3.8.11

In order to unload a module from your environment, use the unload sub-command followed by the name of the module you want to remove.

$ module unload cray-fftw

In most cases multiple module load or module unload commands can be combined in a single module load or module unload command. One exception to this is any sequence of loads or unloads involving the cpe module from the Cray Programming Environment as loading or unloading of this module only takes full effect at the next module command.

You can also remove all loaded modules from your environment by using the purge sub-command.

$ module purge

In Lmod, some modules can be declared as sticky modules by the sysadmins. These modules will not be removed by module purge and will produce an error message when you try to unload them with module unload. On LUMI this is the case for the modules that activate a software stack so that it is possible to unload all modules that are loaded in the stack without deactivating the stack. Sticky modules can still be unloaded or purged by adding the --force option, e.g.,

module --force unload LUMI
module --force purge

Note the position of the --force argument.

It is also possible to see the Lmod commands that are executed when loading a module using module show. E.g.,

module load CrayEnv
module show cray-fftw

will show

-------------------------------------------------------------------------------------------------------
   /opt/cray/pe/lmod/modulefiles/cpu/x86-rome/1.0/cray-fftw/3.3.8.10.lua:
-------------------------------------------------------------------------------------------------------
help([[Release info:  /opt/cray/pe/fftw/3.3.8.10/release_info]])
help([[Documentation: `man intro_fftw3`]])
whatis("FFTW 3.3.8.10 - Fastest Fourier Transform in the West")
setenv("FFTW_VERSION","3.3.8.10")
setenv("CRAY_FFTW_VERSION","3.3.8.10")
setenv("FFTW_DIR","/opt/cray/pe/fftw/3.3.8.10/x86_rome/lib")
setenv("FFTW_INC","/opt/cray/pe/fftw/3.3.8.10/x86_rome/include")
setenv("PE_FFTW_PKGCONFIG_VARIABLES","PE_FFTW_OMP_REQUIRES_@openmp@")
setenv("PE_FFTW_OMP_REQUIRES"," ")
setenv("PE_FFTW_OMP_REQUIRES_openmp","_mp")
setenv("PE_FFTW_PKGCONFIG_LIBS","fftw3f_mpi:libfftw3f_threads:fftw3f:fftw3_mpi:libfftw3_threads:fftw3")
prepend_path("PKG_CONFIG_PATH","/opt/cray/pe/fftw/3.3.8.10/x86_rome/lib/pkgconfig")
prepend_path("PATH","/opt/cray/pe/fftw/3.3.8.10/x86_rome/bin")
prepend_path("MANPATH","/opt/cray/pe/fftw/3.3.8.10/share/man")
prepend_path("CRAY_LD_LIBRARY_PATH","/opt/cray/pe/fftw/3.3.8.10/x86_rome/lib")
prepend_path("PE_PKGCONFIG_PRODUCTS","PE_FFTW")

The interesting lines are the setenv lines which tell which environment variables will be set and the prepend_path lines which tell which directories will be added to certain PATH-style variables.

Saving your environment

Sometimes, if you frequently use multiple modules together, it might be useful to save your environment as a module collection. However, you should do so only if you fully understand how Lmod works and what is saved as saving environments is rather fragile in Lmod. E.g., in the LUMI software stack, saving a collection on the login nodes may not give you the right binaries when working on one of the types of compute nodes, even though tha application modules have the same name and version. Also, when saving a collection of modules, the full pathname to each of the module files is saved so the stored collection will break if modules have to be moved.

A collection can be created using save sub-command.

module save <collection-name>

Your saved collections can be listed using the savelist sub-command.

module savelist

But, of course, the main interest of a collection is that you can load all the modules it contains in one command. This is done using the restore sub-command.

module restore <collection-name>

More options to manage collections of modules can be found by running module help or in the Lmod User Manual. Note, however, that the latter may contain options or commands that do not yet work on the version of Lmod supported on LUMI.

Create and use your own modules

When you install software yourself, it may make life easier if you make it available through a module. Some software for HPC systems will also produce modules during the installation process, e.g., the Intel oneAPI compilers.

Lmod supports most Tcl-based module files written for the various versions of Environment Modules. It also has its own format for module files, which are Lua programs though with a restricted set of Lua functions available. More information on developing module files is available in the Lmod documentation. Note, however, that that documentation is for the latest version of Lmod and not all features may be supported on the version of Lmod that is installed on LUMI.

Tip: Study an existing module file

If you want to study an existing module file then module show <modulename> will also show you where to find the module file.

Adding directories to the search path for modules is done with

module use <directory>

Conversely, removing a directory is done with

module unuse <directory>

Removing a directory from the module search path will also unload the modules that are loaded from that directory.

For advanced users: Resetting the MODULEPATH

The search path for modules is stored in the environment variable MODULEPATH. Adding directories to the search path by manipulating MODULEPATH is possible. However overwriting the variable and removing directories can have nasty side effects and bring the internal data structures of Lmod in an inconsistent state, e.g., because there may now be modules loaded from directories that are not in the MODULEPATH.

If you want to overwrite MODULEPATH, e.g., to build your own private environment fully independent from those that LUMI offers, you also need to re-initialise Lmod by running

source /usr/share/lmod/lmod/init/bash