Differences

This shows you the differences between two versions of the page.

--- services:modules [2019/07/25 09:32]
giunta [Introduction]
+++ services:modules [2019/07/25 14:34] (current)
giunta [Tips for graphical login]
@@ Line 5: / Line 5: @@
 ===== Usage =====
-The workstations have a variety of compilers, libraries, and other bits of software installed. Some of it exists in multiple versions, and, for example, you may wish to switch between compilers for testing or you may wish to select a specific revision of Matlab.
-The purpose of the module package is to simplify this for you.
+The module command sets the appropriate environment variable independent of the user’s shell. A user can list the modules loaded by:
-On all workstations the modules package is available as standard; it provides for the dynamic modification of the user's environment via modulefiles.
+  $ module list
-Each modulefile contains the information needed to configure the shell for an application; the environment can be modified on a per-module basis using the module command which interprets modulefiles. Typically modulefiles instruct the module command to alter or set shell environment variables such as PATH, MANPATH, etc.
+To find out what modules are available to be loaded a user can do:
-The modulefiles are added to and removed from the current environment by the user. The environment changes contained in a modulefile can be summarized through the ''module'' command as well. If no arguments are given, a summary of the module usage and sub-commands are shown:
+  $ module avail
-<xterm>
+To load packages a user simply does:
-[user@workstation ~]# **module**
-Modules Release Tcl x.x.x ($RCSfile: modulecmd.tcl,v $ $Revision: x.xxx $)
-	Copyright GNU GPL v2 1991
-Usage: module [ switches ] [ command ]
-Switches:
-	-t		terse format avail and list
-	-l		long format avail and list
-Commands:
-	list         |  add|load            modulefile [modulefile ...]
-	purge        |  rm|unload           modulefile [modulefile ...]
-	reload       |  switch|swap        [oldmodulefile] newmodulefile
-	             |  display|show        modulefile [modulefile ...]
-	             |  avail              [modulefile [modulefile ...]]
-	             |  whatis             [modulefile [modulefile ...]]
-	             |  help               [modulefile [modulefile ...]]
-	             |  path                modulefile
-	             |  paths               modulefile
-	             |  use                 dir [dir ...]
-	             |  unuse               dir [dir ...]
-	             |  source              scriptfile
-	             |  apropos|keyword     string
-	             |
-	initlist     |  initadd             modulefile
-	initclear    |  initprepend         modulefile
-		     |  initrm              modulefile
-</xterm>
-===== Sub-Commands =====
-==== avail ====
-With the subcommand ''avail'' you get available list of module files (versions or names may change):
-<xterm>
+  $ module load package1 package2 ...
-[user@workstation ~]# **module avail**
------------- /u/shared/programs/noarch/common/modulefiles ------------
-mathematica/6.0.2(default) mkl/10.0.2.018(default)
-mathematica/6.0.1          mkl/9.0.1
------------- /u/shared/programs/x86_64/common/modulefiles ------------
-cce/10.1.013(default)   intel/10.1.013(default) pgi/7.1-6(default)
-cce/9.0.1               intel/9.1               pgi/6.1
-fce/10.1.013(default)   maple/11(default)       sm/2.4.34(default)
-fce/9.1                 maple/10                sm/2.2.3
-idbe/10.1.013(default)  matlab/2007b(default)
-idbe/9.1                matlab/2007a
-</xterm>
-The notation for the modulefilename is ''"name of the application/version and description"''.
+To unload packages a user does:
-==== load ====
+  $ module unload package1 package2 ...
-To use a particular module, run ''module load modulename''. You don't need to list the full name of the module, as listed in ''module avail'' output, if you only use the first component, it will choose the latest version for you. (It actually chooses the last item alphabetically.)
-<xterm>
+A user might wish to change from one compiler to another:
-[user@workstation ~]# **module load cce**
-</xterm>
-==== list ====
+  $ module swap gnu intel
-This lists all modules which are currently loaded into the users' environment (versions or names may change).
-<xterm>
+The above command is short for:
-[user@workstation ~]# **module list**
-Currently Loaded Modulefiles:
-) cce/10.1.013
-</xterm>
-==== unload ====
+  $ module unload gnu
-Use this command to unload one or more of the loaded module files (seen in ''list'' before).
+  $ module load intel
-<xterm>
+A user may wish to go back to an initial set of modules:
-[user@workstation ~]# **module unload cce**
-</xterm>
-==== whatis ====
+  $ module restore
-If a module looks interesting, use this command to display the information contained within the given module file (versions or names may change).
-<xterm>
+This command will also unload all currently loaded modules, including the sticky ones, and then load the user's default collection. See [[services:modules#user_collections|User Collections]] for more details.
-[user@workstation ~]# **module whatis cce**
------------ /u/shared/programs/noarch/common/modulefiles -------------
------------ /u/shared/programs/x86_64/common/modulefiles -------------
-        cce/10.1.013: loads the Intel(R) C++ Compiler 10.1.013
-</xterm>
-==== display ====
+If a module is not available then an error message is produced:
-Use this command to see exactly what a given modulefile will do to your environment, such as what will be added to the PATH, MANPATH, etc. environment variables.
-<xterm>
+  $ module load packageXYZ
-[user@workstation ~]# **module display cce**
+  Warning: Failed to load: packageXYZ
--------------------------------------------------------------------
-/u/shared/programs/x86_64/common/modulefiles/cce/10.1.013:
-module-whatis	loads the Intel(R) C++ Compiler 10.1.013
+Modulefiles can contain help messages. To access a modulefile’s help do:
-prepend-path	PATH	/u/shared/programs/x86_64/common/intel/cce/10.1.013/bin
-prepend-path	LD_LIBRARY_PATH	/u/shared/programs/x86_64/common/intel/cce/10.1.013/lib
-prepend-path	MANPATH	/u/shared/programs/x86_64/common/intel/cce/10.1.013/man
-prepend-path	INTEL_LICENSE_FILE	/u/shared/licenses/intel
--------------------------------------------------------------------
-</xterm>
-===== Using modules in batch =====
+  $ module help packageName
-To automatically load modules when you log in to a system, put the ''module load modulename'' command in your shell's startup script.
-For example:
+To get a list of all the commands that module knows about do:
-  * if your shell is ''bash'', put the command in your ''~/.bashrc''
+  $ module help
-  * if your shell is ''csh'', put it in your ''~/.cshrc''.
-If you change shells in your batch script you may need to explicitly load the modules environment (if your script does not use modules commands, there is, of course, no need to do this) by adding as the first line of your ''bash'' script:
+The module avail command has search capabilities:
+  $ module avail cc
+will list for any modulefile where the name contains the string “cc”.
+Modulefiles can have a description section known as “whatis”. It is accessed by:
 <code>
-. /etc/profile.d/modules.sh
+$ module whatis gnu8/8.3.0
+gnu8/8.3.0          : Name: GNU Compiler Collection
+gnu8/8.3.0          : Version: 8.3.0
+gnu8/8.3.0          : Category: compiler, runtime support
+gnu8/8.3.0          : Description: GNU Compiler Family (C/C++/Fortran for x86_64)
+gnu8/8.3.0          : URL: http://gcc.gnu.org/
 </code>
-or in case your script is ''csh'' derived:
+Finally, there is a keyword search tool:
+  $ module keyword word1 word2 ...
+This will search any help message or whatis description for the word(s) given on the command line.
+Another way to search for modules is with the ''module spider''command. This command searches the entire list of possible modules. The difference between ''module avail'' and ''module spider'' is explained in the [[services:modules#module_hierarchy|Module Hierarchy]] and [[services:modules#searching_for_modules|Searching for Modules]] section:
+  $ module spider
+===== Specifying modules to load =====
+Modules are a way to ask for a certain version of a package. For example we have more versions of git (say versions 2.9.3 and 2.18). So a user may load:
+  $ module load git
+or:
+  $ module load git/2.9.3
+In the second case, //module// will load git version 2.9.3 where as in the first case //module// will load the default version of git, the last one (in this case version 2.18).
+===== Module Hierarchy =====
+Libraries built with one compiler need to be linked with applications with the same compiler version. If sites are going to provide libraries, then there will be more than one version of the library, one for each compiler version. Therefore, whether it is the //Boost library// or an //mpi library//, there are multiple versions.
+There are two main choices for system administrators. For the //XYZ library// compiled with either the //Intel compiler// or the //GNU compiler//, there could be the //xyz-intel// modulefile and the //xyz-gnu// module file. This gets much more complicated when there are multiple versions of the //XYZ library// and different //compilers//. How does one label the various versions of the library and the compiler? Even if one makes sense of the version labeling, when a user changes compilers, the user will have to remember to unload the //intel// and the //xyz-intel// modulefiles when changing to //gnu// and //xyz-gnu//. If users have mismatched modules, their programs are going to fail in very mysterious ways.
+A much saner strategy is to use a module hierarchy. Each compiler module adds to the ''MODULEPATH'' a compiler version modulefile directory. Only modulefiles that exist in that directory are packages that have been built with that compiler. When a user loads a particular compiler, **that user only sees modulefile(s) that are valid for that compiler**.
+Similarly, applications that use libraries depending on MPI implementations must be built with the same compiler - MPI pairing. This leads to modulefile hierarchy. Therefore, as users start with the minimum set of loaded modules, all they will see are compilers, not any of the packages that depend on a compiler. Once they load a compiler they will see the modules that depend on that compiler. After choosing an MPI implementation, the modules that depend on that compiler-MPI pairing will be available. One of the nice features of //module// is that it handles the hierarchy easily. If a user swaps compilers, then //module// automatically unloads any modules that depends on the old compiler and reloads those modules that are dependent on the new compiler.
 <code>
-source /etc/profile.d/modules.csh
+$ module list
+Currently Loaded Modules:
+) gnu8/8.3.0   2) hdf5/1.10.5
+$ module swap gnu intel
+Due to MODULEPATH changes, the following have been reloaded:
+) hdf5/1.10.5
 </code>
+If a modulefile is not available with the new compiler, then the module is marked as inactive. Every time MODULEPATH changes, //module// attempts to reload any inactive modules.
+===== Searching For Modules =====
+When a user enters:
+  $ module avail
+//module// reports only the modules that are in the current ''MODULEPATH''. Those are the only modules that the user can load. If there is a //modulefile hierarchy//, then a package the user wants may be available but not with the current compiler version. //module// offers a new command:
+  $ module spider
+which lists all possible modules and not just the modules that can be seen in the current ''MODULEPATH''. This command has three modes. The first mode is:
+<code>
+$ module spider
+...
+  boost: boost/1.70.0
+    Boost free peer-reviewed portable C++ source libraries
+  cmake: cmake/3.14.3
+    CMake is an open-source, cross-platform family of tools designed to build, test and package software.
+  cuda: cuda/9.0, cuda/9.1, cuda/10.0, cuda/10.1
+    NVIDIA CUDA Toolkit 10.0 Patch 1 / cuDNN 7.4.2.24
+...
+</code>
+This is a compact listing of all the possible modules on the system. The second mode describes a particular module:
+<code>
+$ module spider boost
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+  boost:
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    Description:
+      Boost free peer-reviewed portable C++ source libraries
+     Versions:
+        boost/1.70.0
+</code>
+The third mode reports on a particular module version and where it can be found:
+<code>
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+  boost: boost/1.70.0
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    Description:
+      Boost free peer-reviewed portable C++ source libraries
+    You will need to load all module(s) on any one of the lines below before the "boost/1.70.0" module is available to load.
+      gnu8/8.3.0  mvapich2/2.3.1
+      gnu8/8.3.0  openmpi3/3.1.4
+      intel/19.0.4.243  mvapich2/2.3.1
+      intel/19.0.4.243  openmpi3/3.1.4
+</code>
+===== Controlling Modules During Login =====
+<note warning>Automatically loaded modules may have a negative effect on GNOME graphical login</note>
+Users can automatically load a standard set of modules when log in, adding module commands to their //personal startup files//. To add module commands to users’ startup scripts, Bash users need to place the following in their ''~/.bashrc'' file:
+<code>
+if [ -z "$BASHRC_READ" ]; then
+   export BASHRC_READ=1
+   # Place any module commands here
+   # module load git
+fi
+</code>
+By wrapping the module command in an //if// test, the module commands need only be read in once. Any sub-shell will inherit the ''PATH'' and other environment variables automatically.
+Csh users need specify the module commands in their ''~/.cshrc'' file:
+<code>
+if ( ! $?CSHRC_READ ) then
+   setenv CSHRC_READ 1
+   # Place any module command here
+   # module load git
+endif
+</code>
+If users have created at least a default collection (see [[services:modules#user_collections|User Collections]] for more details), they can replace all ''module load ...'' commands with a single ''module restore''. Bash users need to place the following in their ''~/.bashrc'' file:
+<code>
+if [ -z "$BASHRC_READ" ]; then
+   export BASHRC_READ=1
+   module --initial_load --no_redirect restore
+else
+   module refresh
+fi
+</code>
+Csh users need specify the ''module restore'' command in their ''~/.cshrc'' file:
+<code>
+if ( ! $?CSHRC_READ ) then
+   setenv CSHRC_READ 1
+  module --initial_load restore
+else
+  module refresh
+endif
+</code>
+==== Tips for graphical login ====
+When using automatically loaded modules, a possible solution to avoid problems on GNOME login could be testing ''TERM'' environment variable. In this way, only when users open a graphical terminal (e.g., GNOME Terminal), modules will be loaded. On SISSA linux workstations, //GNOME Terminal// sets it as ''xterm-256color''. Bash users may add a test on ''TERM'' variable in their ''~/.bashrc'':
+<code>
+if [ "$TERM" == "xterm-256color" -a -z "$BASHRC_READ" ]; then
+   export BASHRC_READ=1
+   # Place any module commands here
+   # module load git
+fi
+</code>
+Csh users need to add in their ''~/.cshrc'' file:
+<code>
+if ( "$TERM" == "xterm-256color" && ! $?CSHRC_READ ) then
+   setenv CSHRC_READ 1
+   # Place any module command here
+   # module load git
+endif
+</code>
+===== User Collections =====
+Users can defined //lists// (collections) of modules to load with a single command. To define the //default// collection, users have to load the desired modules, for example:
+<code>
+$ module load cuda/9.0
+$ module load intel/19.0.4.243
+$ module load hdf5/1.10.5
+</code>
+and then issue:
+  $ module save
+This creates a file called ''~/.lmod.d/default'' which has the list of desired modules. Once this is set-up, a user can issue:
+  $ module restore
+and only the desired modules will be loaded.
+If a user doesn’t have a default collection, an error message is produced.
+Users can have as many collections as they like. They can save to a named collection with:
+  $ module save <collection_name>
+and restore that named collection with:
+  $ module restore <collection_name>
+A user can print the contents of a collection with:
+  $ module describe <collection_name>
+A user can list the collections they have with:
+  $ module savelist
+Finally a user can disable a collection with:
+  $ module disable <collection_name>
+If no //collection_name// is given then the //default// is disabled. Note that the collection is not remove just renamed. If a user disables the //foo// collection, the file //foo// is renamed to //foo~//. To restore the foo collection, a user will have to do the following:
+  $ cd ~/.lmod.d; mv foo~ foo
+==== Rules for loading modules from a collection ====
+//module// has rules on what modules to load when restoring a collection. In this guide, we call ''gnu8/8.3.0'' the //fullName// of the module and ''gnu8'' as the //shortName//. We also call what the user asked for as the //userName// which could either be the //fullName// or the //shortName// depending on what the user typed on the command line.
+  - //module// records the //fullName// and the //userName// in the collection.
+  - If the //userName// **is the same** as the //fullName// then it loads //fullName// independent of the default.
+  - if the //userName// **is not the same** as the //fullName// then it loads the default.
+  - Unless ''LMOD_PIN_VERSIONS=yes'' then the //fullName// is always loaded.
+In other words if a user does:
+  $ module --force purge; module load A B C
+  $ module save
+then ''module restore'' will load the default A, B, and C. So if the default for module A changed between when the collection was saved and then restored, a new version of A will be loaded. This assumes that ''LMOD_PIN_VERSIONS'' is not set. If it is set then if A/1.1, B/2.4 and C/3.3 are the default then those modules will be loaded in the future independent of what the defaults are in the future.
+On the other hand:
+  $ module --force purge; module load A/1.0 B/2.3 C/3.4
+  $ module save
+then ''module restore'' will load the A/1.0, B/2.3, and C/3.4 independent of what the defaults are now or in the future.