MODULES APPROACH TO SOFTWARE MANAGEMENT
Table of Contents
Using Module Commands in a SLURM script
Introduction
For the Longleaf and Dogwood clusters we have implemented “modules” utility to manage the user environment for different software versions. The distinct advantage of the modules approach is that the user is no longer required to explicitly specify paths for different executable versions nor need to try to keep the PATH, LD_LIBRARY_PATH, MANPATH and related environment variables coordinated. With the modules approach, users simply “add” and “rm” modules to control their environment.
Modules provide an easy mechanism for updating a user’s environment especially the PATH, MANPATH, and LD_LIBRARY_PATH, etc. environment variables to name a few.
Initialization
You can use the commands below to modify your environment and to control what modules are loaded whenever you log in:
$ module add modulefile
$ module list
$ module rm modulefile
where “modulefile” is the name of the module you want loaded.
Use the “save” command to save your module environment and have a module automatically loaded each time you log into the system:
$ module save
To have the module loaded only for your current session you can do:
$ module add modulefile
or
$ module load modulefile
The following command will unload a module from your current session. To remove any listed modules from your current environment you can use the “module rm” or “module unload” command:
$ module list
$ module rm modulefile
or
$ module unload modulefile
More Module Commands
To get a usage list of module options type the following (the listing has been abbreviated to only those commands discussed in this webpage):
$ module help
Usage: module [options] sub-command [args ...]
Available SubCommands and Args:
+ add|load module [module...]
+ rm|unload module [module...]
+ display|show modulefile [module...]
+ avail [module [module...]]
+ list
+ help
+ spider
list
The “module list” command will list all the modules which are currently loaded in your environment:
$ module list
avail
And the “module avail” command lists all the modules available to be loaded
$ module avail
or
$ module spider
help
To get more information about a specific module use the module help command to display the “help” information contained within the given module file.
$ module help gromacs
------- Module Specific Help for "gromacs/2016.3" --------
gromacs/2016.3 module
****************************************************
This module sets up the following environment
variables for Gaussian
GMXPREFIX
GMXBIN
GMXLDLIB
GMXMAN
GMXDATA
GROMACS_DIR
PATH
LD_LIBRARY_PATH
PKG_CONFIG_PATH
MANPATH
show
The “module show” command allows you 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:
$ module show gromacs
------------------------------------------------------------
/nas/longleaf/apps/lmod/modulefiles/Core/gromacs/2016.3.lua:
------------------------------------------------------------
whatis("Set up environment for Gromacs 2016.3")
conflict("gromacs")
setenv("GMXPREFIX","/nas/longleaf/apps/gromacs/2016.3")
setenv("GMXBIN","/nas/longleaf/apps/gromacs/2016.3/bin")
setenv("GMXLDLIB","/nas/longleaf/apps/gromacs/2016.3/lib64")
setenv("GMXMAN","/nas/longleaf/apps/gromacs/2016.3/share/man")
setenv("GMXDATA","/nas/longleaf/apps/gromacs/2016.3/share/gromacs")
setenv("GROMACS_DIR","/nas/longleaf/apps/gromacs/2016.3")
setenv("GMX_FONT","10x20")
prepend_path("PATH","/nas/longleaf/apps/gromacs/2016.3/bin")
prepend_path("LD_LIBRARY_PATH","/nas/longleaf/apps/gromacs/2016.3/lib64")
prepend_path("PKG_CONFIG_PATH","/nas/longleaf/apps/gromacs/2016.3/lib64/pkgconfig")
prepend_path("MANPATH","/nas/longleaf/apps/gromacs/2016.3/share/man")
help([[ gromacs/2016.3 module
****************************************************
This module sets up the following environment
variables for Gaussian
GMXPREFIX
GMXBIN
GMXLDLIB
GMXMAN
GMXDATA
GROMACS_DIR
PATH
LD_LIBRARY_PATH
PKG_CONFIG_PATH
MANPATH
add
The following command adds one or more modulefiles to your current environment. If you load a module name without the version infomation, you will get the default version (D). Modules load silently without a confirmation message unless there is a problem with a modulefile. If there is problem, please notify us via email research@unc.edu with the research cluster name (e.g. longleaf) and a screen shot or copy’n’paste of the error/issue.
$ module add modulefile
At times one module will conflict with another. In that event you will receive an error and will need to remove the conflicting module yourself before being able to proceed. To load a specific version, load the module using its full specification. An example showing this follows:
$ module add gaussian/09e01
$ module add gaussian/16a03
The following have been reloaded with a version change:
1) gaussian/09e01 => gaussian/16a03
$ module rm gaussian/09e01
$ module list
Using Module Commands in a SLURM script
You can also use module commands inside a SLURM job submission script. Using the methods in this section will reduce errors and confusion, by being very explicit about the environment in which batch jobs run. While modules can be saved to your environment as described above which is convenient for interactive work, batch jobs do not have access to your saved environment.
Best practice is to explicitly define the environment required by the job: first purging all modules, the load exactly the modules needed by the job. These module commands go directly after the SBATCH options as shown in this example:
#!/bin/bash
#SBATCH -p general
#SBATCH -N 1
#SBATCH -n 1
#SBATCH -t 2:00:00
module purge
module add anaconda/2021.11
python myscript.py
Specifically, in your submission script you can use
module purge
followed by
module add <application>
commands to ensure a job is using only a specific set of modules at runtime. The module purge command wipes out any modules that are currently in your Longleaf environment. Therefore, doing module purge first means the module environment is starting clean before adding the modules for the job. So, for example, the commands from above
module purge
module add anaconda/2021.11
inside a SLURM job submission script guarantees the job will only have the anaconda/2021.11 module loaded during its execution regardless of any other modules that are permanently saved, or may have been added using the command-line, to your Longleaf environment prior to submitting the SLURM job. This approach is useful, particularly if you find yourself saving a large number of modules to your Longleaf environment in order to run different workloads where each workload has different module requirements, because it allows you to restrict a job's environment only to the modules it needs in order to run. Having extraneous modules loaded in your job environment can sometimes introduce unintended conflicts into the job's environment resulting in job failures. We also recommend loading modules into your job submission script while Longleaf transitions from RHEL 7 to RHEL 8.
Email research@unc.edu with any questions or feedback.
Last Update 10/3/2024 7:08:57 PM