Software on the bwHPC Clusters is provided as Software Environment Modules, or short Modules.
Modules make it possible to have different versions of a software installed at a the same time. The complete environments for the software package, compilers and libraries and needed by this specific version is then loaded by a single command. This happens usually in the beginning of the jobscript.
- 1 Basic Usage
- 2 Additional Usage Recommendations
1 Basic Usage
1.1 General Documentation on the Modules Environment Software
The documentation written by the software developers is available on the cluster via the commands:
Online documentation of the project is available on the Environment Modules Website.
1.2 Module categories, versions and defaults
The bwHPC clusters categorize Modules, each software can exist in different versions:
For instance the Intel compiler X.Y belongs to the category of compilers, therefore the
modulefile X.Y is placed under the category compiler and intel.
In case of multiple software versions, one version will be always defined as the default version. The Module of the default can be addressed by simply omitting the version number:
e.g. if mathematica is installed, it is in the module
Currently all bwHPC software packages are assigned to the following Module categories:
1.3 Display and search available Modules
Available Modules are modulefiles that can be loaded by the user. A Module must be loaded before it provides changes to your environment. You can display all available Modules on the system by executing:
$ module avail
You can selectively list software in one of those categories using, e.g. for the category "compiler", or just all versions of a certain module:
$ module avail compiler/ $ module avail compiler/gnu
1.4 module help
A help message for a specific Module can be displayed with 'module help category/softwarename/version'.
The help message usually contains additional information about the software and points to the software website and documentation.
$ module help system/example/1.0 ----------------- Module Specific Help for "system/example/1.0" --------------------------- "This module provides a bwhpc-examples job that works on every cluster. [... rest of the output is omitted in the Wiki for clarity ...]
1.5 Loading Modules and Check they are loaded
To load a software Module and display all loaded modules:
$ module list No Modulefiles Currently Loaded. $ module load system/example/1.0 $ module list Currently Loaded Modulefiles: 1) system/example/1.0
Module make software available only in your current shell. Whenever you login in, you have to load the software again. Please don not auto-load modules in .bashrc on login, this can lead to problems with other modules you may load later.
1.6 Software job examples
bwHPC provides example job scripts for most installed software modules.
It uses a variable named $SWN_EXA_DIR for a Module called SWN. To copy the whole example folder to your $HOME directory, so you can edit those job examples.
A small example module installed on bwUniCluster and each bwForCluster illustrates that. The following code snippet shows you can run the bwhpc-example.
# Load the example module $ module load system/example/1.0 # Run example in a temporary directory $ mkdir tmp_example_dir && cd tmp_example_dir # Example jobscript for clusters using the SLURM batch system sbatch $EXAMPLE_EXA_DIR/examples-1.0.slurm # Example jobscript for clusters using PBS qsub $EXAMPLE_EXA_DIR/examples-1.0.pbs # Print the results cat examples_result.txt
2 Additional Usage Recommendations
2.1 Loading conflicts
By default you can not load different versions of same software Module in same session. Loading for example Intel compiler version X while Intel compiler version Y is loaded results in error message as follows:
Module 'compiler/intel/X' conflicts with the currently loaded module(s) 'compiler/intel/Y'
The solution is unloading or switching Modules.
2.2 Showing the changes introduced by a Module
Loading a Module will change the environment of the current shell session. For instance the $PATH variable will be expanded by the software's binary directory. Other Module variables may even change the behavior of the current shell session or the software program(s) in a more drastic way.
Loaded Modules may also invoke an additional set of environment variables, which e.g. point to directories or destinations of documentation and examples. Their nomenclature is systematic:
|$SWN_HOME||Root directory of the software package|
|$SWN_BPR_URL||URL of software's Wiki article|
|and many many more...|
with SWN being the place holder of the software Module name.
All the changes to the current shell session to be invoked by loading the Module can be reviewed using 'module show category/softwarename/version'.
$ module show system/example/1.0 --------------------------------------------------------------------------------------------------- /opt/bwhpc/common/modulefiles/Core/system/example/1.0.lua: --------------------------------------------------------------------------------------------------- whatis("A generic module containing a working bwhpc-examples job.") setenv("EXAMPLE_VERSION","1.0") setenv("EXAMPLE_HOME","/opt/bwhpc/common/system/example/1.0") setenv("EXAMPLE_BIN_DIR","/opt/bwhpc/common/system/example/1.0/bin") setenv("EXAMPLE_EXA_DIR","/opt/bwhpc/common/system/example/1.0/bwhpc-examples") prepend_path("PATH","/opt/bwhpc/common/system/example/1.0/bin") help([["This module provides a bwhpc-examples job that works on every cluster. The module is used as example in the bwHPC-Wiki and therefore should be installed on every cluster, such that users can try the commands out. * The executable of this module can be found in the folder $EXAMPLE_BIN_DIR Upon loading the module, the binaries are added to PATH. * Further documentation for using the example can be found in https://wiki.bwhpc.de/e/Environment_Modules * Examples are located at: $EXAMPLE_EXA_DIR ]])
2.3 Modules depending on Modules
Some program Modules depend on libraries to be loaded to the user environment. Therefore the
corresponding Modules of the software must be loaded together with the Modules of
By default such software Modules try to load required Modules and corresponding versions automatically. However, automatic loading might fail if a different version of that required Module is already loaded (cf. Loading conflicts).
2.4 Unloading Modules
To unload or to remove a software Module execute:
$ module unload category/softwarename/version
2.4.1 Unloading all loaded modules
In order to remove all previously loaded software modules from your environment issue the command 'module purge'.
$ module list Currently Loaded Modulefiles: 1) devel/gdb/7.7 2) compiler/intel/14.0 3) mpi/openmpi/1.8-intel-14.0(default) $ $ module purge $ module list No Modulefiles Currently Loaded. $
2.5 Other Module commands
2.5.1 module whatis
A short description for a specific Module can be displayed with 'module whatis category/softwarename/version'
$ module whatis system/example/1.0 system/example/1.0 : A generic module containing a working bwhpc-examples job.