MODULES APPROACH TO SOFTWARE MANAGEMENT

Table of Contents

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 4/19/2024 7:46:49 AM