Difference between revisions of "Environment Modules"

From bwHPC Wiki
Jump to: navigation, search
(→‎Automatic Loading)
(→‎Software job examples added echo and comment to omit that users are copying "/")
 
(93 intermediate revisions by 9 users not shown)
Line 1: Line 1:
−
{| style="border-style: solid; border-width: 1px"
  
−
! Navigation: [[BwHPC_Best_Practice_Repository|bwHPC BPR]] / [[BwUniCluster_User_Guide|bwUniCluster]]
 
−
|}
  
   
  +
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.
   
  +
= Basic Usage =
−
The usage of compilers, libraries and software packages requires by default users to set up
 
  +
== General Documentation on the Modules Environment Software ==
−
manually their session environment.
  
   
  +
We will provide an overview of the most important commands in the next sections.
−
The bwHPC clusters (such as '''''bwUniCluster''''') provide users the possibility to load and unload '''complete environments'''
  
−
for compilers, libraries and software packages by single commands. Because of the
 
−
convenient modularity this software is called ''Environment Modules''.
  
   
  +
For your reference on what is not covered here, the full documentation written by the software developers is available on the cluster via the commands:
   
  +
<code>module help</code>
   
  +
<code>man module</code>
−
= Environment Modules =
 
   
  +
Online documentation of the project is available on the [https://lmod.readthedocs.io/en/latest/ Environment Modules Website].
−
The ''Environment Modules'' software enables dynamic modification of your environment by the
 
−
use of so-called ''modulefiles''. A ''modulefile'' contains information to configure the shell
 
−
for an application. Typically, a modulefile contains instructions that alter or set shell
 
−
environment variables, such as PATH and MANPATH, to enable access to various installed
 
−
software.
 
   
  +
== Module categories, versions and defaults ==
−
One of the key features of using the ''Environment Modules'' software is to allow multiple versions of the same software to be used in your environment in a controlled manner.
 
  +
The bwHPC clusters categorize ''Modules'', each software can exist in different versions:
−
For example, two different versions of the Intel C compiler can be installed on the system at the same time - the version used is based upon which Intel C compiler modulefile is loaded.
  
   
  +
category/softwarename/version
−
The software stack of bwHPC clusters provides a number of modulefiles. You can also
 
  +
For instance the Intel compiler X.Y belongs to the category of compilers, therefore the
−
create your own modulefiles. ''Modulefiles'' may be shared by many users on a system, and
 
  +
modulefile ''X.Y'' is placed under the category ''compiler'' and ''intel''.
−
users may have their own collection of modulefiles to supplement or replace the shared
 
  +
<br>
−
modulefiles.
  
  +
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:
  +
category/softwarename
   
  +
e.g. if mathematica is installed, it is in the module
−
A modulefile does not provide configuration of your environment until it is explicitly loaded,
 
−
i.e., the specific modulefile for a software product or application must be loaded in your environment before the configuration information in the modulefile is effective. For instance
 
−
loading the default Intel C and Fortran compiler you must execute:
  
−
<pre>
  
−
$ module load compiler/intel
  
−
</pre>
  
   
  +
math/mathematica
   
  +
Currently all bwHPC software packages are assigned to the following ''Module'' categories:
−
== Modulefile Help ==
  
−  
−
For help on how to use the ''Environment Modules'' software, i.e., the command ''module'',
 
−
execute:
  
−
<pre>
  
−
$ module help
  
−
</pre>
  
−
or
 
−
<pre>
  
−
$ man module
  
−
</pre>
  
−  
−
For help on particular version of modulefiles, e.g. Intel compiler version 12.1, execute:
  
−
<pre>
  
−
$ module help compiler/intel/12.1
  
−
</pre>
  
   
  +
<code> bio cae chem compiler devel lib math mpi numlib phys system vis </code>
   
  +
<!--
−
== Display all available modulefiles ==
  
  +
[[:Category:Biology_software|bio]]
  +
[[:Category:Engineering_software|cae]]
  +
[[:Category:Chemistry_software|chem]]
  +
[[:Category:Compiler_software|compiler]]
  +
[[:Category:Debugger_software|devel]]
  +
[[:Category:Mathematics_software|math]]
  +
mpi
  +
[[:Category:Numerical libraries|numlib]]
  +
[[:Category:Physics software|phys]]
  +
[[:Category:System software|system]]
  +
[[:Category:Visualization|vis]]
  +
-->
   
  +
== Display and search available Modules ==
−
Available modulefiles are ''modulefiles'' that can be load by the user. A modulefile must be loaded before it provides changes to your environment, as described in the introduction to this
 
−
section. You can display all available modulefiles on the system by executing:
 +
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:
 
<pre>
  
<pre>
 
$ module avail
  
$ module avail
 
</pre>
  
</pre>
  +
−
The short form the command is:
  
  +
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:
 
<pre>
  
<pre>
−
$ module av
 +
$ module avail compiler/
  +
$ module avail compiler/gnu
 
</pre>
  
</pre>
   
  +
== module help ==
−
Available modulefiles can be also displayed in modes:
  
  +
A help message for a specific ''Module'' can be displayed with ''''module help category/softwarename/version''''.
−
* each modulefile per one line
  
  +
<br>
  +
The help message usually contains additional information about the software and points to the software website and documentation.
 
<pre>
  
<pre>
−
$ module -t avail
 +
$ 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 ...]
 
</pre>
  
</pre>
  +
−
* long
  
  +
  +
== Loading Modules and Check they are loaded ==
  +
To load a software ''Module'' and display all loaded modules:
 
<pre>
  
<pre>
−
$ module -l avail
 +
$ module list
  +
No Modulefiles Currently Loaded.
  +
$ module load system/example/1.0
  +
$ module list
  +
Currently Loaded Modulefiles:
  +
1) system/example/1.0
 
</pre>
  
</pre>
   
   
  +
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.
−
== Modulefile categories, versions and defaults ==
  
  +
  +
== Software job examples ==
  +
bwHPC provides example job scripts for most installed software modules.
   
  +
For a Software ''Module'' with the sofware called '''SOMESOFTWARE''', you can find the example directory by:
−
The bwHPC clusters (such as '''''bwUniCluster''''') traditionally provide a large variety of
 
−
software and software versions. Therefore modulefiles are divided in category folders
 
−
containing subfolders of modulefiles containing modulefile versions, and must be addressed
  
−
as follows:
  
 
<pre>
  
<pre>
  +
$ cd $SOMESOFTWARE_EXA_DIR
−
category/modulefile_name/version
  
−
</pre>
 +
</pre>
  +
−
For instance the Intel compiler 12.1 belongs to the category of compilers, therefore the
 
  +
Copy the whole example folder to your $HOME directory, so you can edit those job examples:
−
modulefile ''12.1'' is placed under the category ''compiler'' and ''intel''.
  
   
−
In case of multiple software versions, one version will be always defined as the '''default'''
 
−
version. Modulefiles of such default software can be addressed by omitting the version number:
  
 
<pre>
  
<pre>
  +
$ cd
−
category/modulefile_name
  
  +
$ mkdir softwarename_examples
  +
$ echo $SOMESOFTWARE_EXA_DIR
  +
# Please do not proceed if the command above does not provide any text !
  +
# Otherwise you will start to copy all system data (the directory "/").
  +
$ cp -r $SOMESOFTWARE_EXA_DIR/ softwarename_examples/
  +
 
</pre>
  
</pre>
   
  +
If your specific software isn't installed, there is a dummy software example module "system/example" present on all clusters. For this module, the process looks like this:
   
−
== Loading Modulefiles ==
  
−
You can load a modulefile in to your environment to enable easier access to software that
 
−
you want to use by executing:
  
 
<pre>
  
<pre>
  +
# Load the example module
−
$ module load category/modulefile_name/version
  
  +
$ module load system/example/1.0
−
</pre>
  
−
or
  
−
<pre>
  
−
$ module add category/modulefile_name/version
  
−
</pre>
  
−
Loading a modulefile in this manner affects your environment for the current session only.
  
   
  +
# Run example in a temporary directory
  +
$ mkdir tmp_example_dir
  +
$ cp -r $EXAMPLE_EXA_DIR/ softwarename_examples/
  +
$ cd tmp_example_dir/bwhpc-examples
   
  +
# Example jobscript for clusters using the SLURM batch system
−
=== Modulefile conflicts ===
  
  +
sbatch examples-1.0.slurm
−
By default you can not load different versions of same software modulefile in same session. Loading for example Intel compiler version 13.1 while Intel compiler version 12.1 is loaded results in error message as follows:
  
  +
# Example jobscript for clusters using PBS
−
<source lang="bash">
  
  +
qsub examples-1.0.pbs
−
ERROR:150: Module 'compiler/intel/13.1' conflicts with the currently loaded module(s) 'compiler/intel/12.1'
  
−
</source>
  
−
The solution is [[#Unloading Modulefiles|unloading]] or switching modulefiles.
  
   
  +
# Print the results
  +
cat examples_result.txt
  +
</pre>
  +
----
   
  +
= Additional Usage Recommendations =
   
−
=== Automatic Loading ===
 +
=== 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:
−
If you frequently use one or more modulefiles that are not loaded when you log in to
 
−
the system, you can set up your environment to automatically load those modulefiles for
 
−
you. A method for doing this is to modify your shell startup script to include instructions to
 
−
load the modulefile automatically.
  
−  
−
For example, if you want to automatically load the Intel 12.1 modulefile when you log
 
−
in, edit your shell startup script to include the following instructions. This example assumes
 
−
that you use bash as your login shell. Edit the <tt>$HOME/.bashrc</tt> file as follows:
  
−
{| style="width: 100%; border:1px solid #e7aa01; background:#e7d9b4;border-spacing: 2px;"
  
−
| style="width:280px; text-align:center; white-space:nowrap; color:#000;" |
  
 
<source lang="bash">
  
<source lang="bash">
  +
Module 'compiler/intel/X' conflicts with the currently loaded module(s) 'compiler/intel/Y'
−
## if the ’module’ command is defined, $MODULESHOME will be set
  
−
if [ -n "$MODULESHOME" ]; then
  
−
module load compiler/intel/12.1
  
−
fi
  
 
</source>
  
</source>
  +
The solution is [[#Unloading Modules|unloading]] or switching ''Modules''.
  +
  +
=== 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.
  +
<br>
  +
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:
  +
{| width=600px class="wikitable"
  +
|-
  +
! Variable
  +
! Pointing to
  +
|-
  +
| $SWN_HOME
  +
| Root directory of the software package
  +
|-
  +
| $SWN_DOC_DIR
  +
| Documentation
  +
|-
  +
| $SWN_EXA_DIR
  +
| Examples
  +
|-
  +
| $SWN_BPR_URL
  +
| URL of software's Wiki article
  +
|-
  +
| and many many more...
  +
| &nbsp;
 
|}
  
|}
  +
with SWN being the place holder of the software ''Module'' name.
−
From now on, whenever you log in, the Intel 12.1 compiler modulefile is automatically
 
  +
<br>
−
loaded in your environment.
  
  +
All the changes to the current shell session to be invoked by loading the ''Module'' can be reviewed using ''''module show category/softwarename/version''''.
  +
<br>
  +
<pre>
  +
$ 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
−
=== Modulefiles depending on Modulefiles ===
  
  +
$EXAMPLE_BIN_DIR
−
Some software depends on libraries to be loaded to the user environment. Therefore the
  
  +
Upon loading the module, the binaries are added to PATH.
−
corresponding modulefile of the software must be loaded together with the modulefiles of
 
−
the libraries.
 
   
  +
* Further documentation for using the example can be found in
−
By default such software modulefiles try to load required modulefile and modulefile versions automatically. However, automatic loading might fail if a different version of that required modulefile
 
  +
https://wiki.bwhpc.de/e/Environment_Modules
−
is already loaded (cf. [[#Modulefile conflicts|modulefile conflicts]]).
  
   
  +
* Examples are located at:
  +
$EXAMPLE_EXA_DIR
  +
]])
   
−
== Unloading Modulefiles ==
  
−
To unload or to remove a modulefile execute:
  
−
<pre>
  
−
$ module unload category/modulefile_name/version
  
 
</pre>
  
</pre>
  +
−
or
  
  +
=== 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
  +
the libraries.
  +
<br>
  +
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|Loading conflicts]]).
  +
<br>
  +
  +
== Unloading Modules ==
  +
To unload or to remove a software ''Module'' execute:
 
<pre>
  
<pre>
−
$ module remove category/modulefile_name/version
 +
$ module unload category/softwarename/version
 
</pre>
  
</pre>
−
Unloading a modulefile that is loaded by default makes it inactive for the current session only - it will be reloaded the next time you log in.
  
   
  +
=== Unloading all loaded modules ===
−  
  +
In order to remove all previously loaded software modules from your environment issue the command 'module purge'.
−
== Display your loaded Modulefiles ==
  
  +
<br>
−
All modulefiles that are currently loaded for you can be displayed by the
  
−
command:
  
 
<pre>
  
<pre>
 
$ module list
  
$ 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.
  +
$
 
</pre>
  
</pre>
−
You only have to load further modulefiles, if you want to use additional software
  
−
packages or to change the version of an already loaded software.
  
   
  +
== Other Module commands ==
−  
  +
=== module whatis ===
−
----
  
  +
A short description for a specific ''Module'' can be displayed with ''''module whatis category/softwarename/version''''
−
[[Category:bwHPC|User Environment]]
  
  +
<pre>
−
[[Category:bwUniCluster|Environment Modules]]
  
  +
$ module whatis system/example/1.0
  +
system/example/1.0 : A generic module containing a working bwhpc-examples job.
  +
</pre>

Latest revision as of 10:24, 25 March 2024

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

1.1 General Documentation on the Modules Environment Software

We will provide an overview of the most important commands in the next sections.

For your reference on what is not covered here, the full documentation written by the software developers is available on the cluster via the commands:

module help

man module

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: 

category/softwarename/version

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: 

category/softwarename

e.g. if mathematica is installed, it is in the module 

math/mathematica

Currently all bwHPC software packages are assigned to the following Module categories:

bio cae chem compiler devel lib math mpi numlib phys system vis


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.

For a Software Module with the sofware called SOMESOFTWARE, you can find the example directory by: 

$ cd  $SOMESOFTWARE_EXA_DIR

Copy the whole example folder to your $HOME directory, so you can edit those job examples: 

$ cd
$ mkdir softwarename_examples
$ echo $SOMESOFTWARE_EXA_DIR
# Please do not proceed if the command above does not provide any text !
# Otherwise you will start to copy all system data (the directory "/").
$ cp -r $SOMESOFTWARE_EXA_DIR/ softwarename_examples/

If your specific software isn't installed, there is a dummy software example module "system/example" present on all clusters. For this module, the process looks like this: 

# Load the example module
$ module load system/example/1.0

# Run example in a temporary directory
$ mkdir tmp_example_dir
$ cp -r $EXAMPLE_EXA_DIR/ softwarename_examples/
$ cd tmp_example_dir/bwhpc-examples

# Example jobscript for clusters using the SLURM batch system
sbatch examples-1.0.slurm
# Example jobscript for clusters using PBS
qsub 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:

Variable Pointing to
$SWN_HOME Root directory of the software package
$SWN_DOC_DIR Documentation
$SWN_EXA_DIR Examples
$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 the libraries.
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.
Retrieved from "https://wiki.bwhpc.de/wiki/index.php?title=Environment_Modules&oldid=12670"