1. Introduction

Software modules are a very convenient way to set needed environment variables and include necessary directories in your path so that commands for particular applications can be found. Our systems use "modules" to initialize your environment with COTS application software, system commands and libraries, compiler suites, environment variables, and workload management system commands.

Module information is stored in specially formatted files called "modulefiles" or simply "modules." These files can be loaded and unloaded to tailor your shell environment to specific needs. A number of modules are loaded automatically as soon as you log in. You can modify your default environment manually using the module command.

In addition to modules that we provide, you can also create your own modules to share with other users or to supplement or replace the existing shared modules if desired.

2. Module Commands

The module command is the primary means of managing the modules that are loaded in your environment. There are a number of subcommands to the module command that allow you to see what is available and what is currently loaded, and that allow you to modify your selections as needed.

module help [module...]

Print the usage of each sub-command. If an argument is given, print the module-specific help information for that module.

module load module [module...]

Load a module into the shell environment. If you are attempting to replace a module that is currently loaded, use the swap (or switch) subcommand instead of load.

module unload module [module...]

Remove a module from the shell environment.

module swap module1 module2

Unload module1 and load module2. The swap subcommand is synonymous with the switch subcommand, which you may see in some documentation. Many modules have multiple versions, such as the compiler and MPI versions, and may have default versions set. You can typically use module swap to change from the generic version to a specific version by simply not specifying a version number for module1. For example:

module swap compiler compiler/intel/16.0.0
module swap mpi mpi/intelmpi/16.0.0

The first example will unload whatever compiler module is currently loaded and load the module for the Intel compiler version 16.0.0. The second example swaps any loaded MPI library module with the module for Intel MPI version 16.0.0.

module show module [module...]

The show subcommand will list the full path of the module and all (or most) of the environment changes the module will make if loaded. The show subcommand is synonymous with the display command, which you may see in some documentation.

module list

List the modules that are currently loaded.

module avail [path...]

List all available modules in the current $MODULEPATH. All directories in the $MODULEPATH are recursively searched. If the path argument is given, then only the modules available within that specific directory tree are listed.

module use [-a |--append] directory [directory...]

By default, this subcommand prepends the directory to the $MODULEPATH environment variable. If the -a or --append argument is used, then the directory will be appended to $MODULEPATH.

module unuse directory [directory...]

Remove the directory from the $MODULEPATH environment variable.

module update

Attempt to reload all loaded modules. The environment will be reconfigured to match the saved $HOME/.modulesbeginenv and the modules will be reloaded.

module purge

Unload all loaded modules.

3. Types of Modules Available

We provide two types of modules on our systems: system and application modules. In general, module names consist of a base name + a version number, for instance, "abaqus/2017". Sometimes, there may be multiple versions of the same module available for use. In such cases, one version will always be designated as the default. To see these, use the module avail command and note the modules with (default) at the end of the module name. If there is only one version of a particular module available, then (default) may not be present in the module name, but it is still treated as the default version. To load the default version of a module, use the module load command and simply omit the version number from the module name, for instance, "module load abaqus".

3.1. System Modules

System modules are provided by the system vendor and include programming environments, libraries, debuggers, profiling tools, system support, and the workload management system. In the output of the module avail command, these modules are usually grouped under /opt/.../modulefiles.

3.2. Application Modules

Application modules are created by our support staff to configure your environment to run specific applications. These are grouped under /usr/local/modulefiles/apps and /usr/local/modulefiles/unsupported. As a rule-of-thumb, we provide at least two versions of each application module: the current and previous default versions. In some cases, we also provide the latest release, although it may not yet be the default.

4. Creating Your Own Modules

In addition to the modules that we provide, you may also create your own custom modules. A thorough explanation of module creation is beyond the scope of this document, but the following information may help you get started.

First, you will need to create your module file. Module files are written in the Tool Command Language (TCL) using a simple text editor such as vi or notepad. For a discussion of the TCL syntax and available TCL commands, see the modulefile man page.

The following is an example of a simple module file:

    #%Module
    proc ModulesHelp { } {
       puts stderr "This modulefile defines the system paths and"
       puts stderr "environment variables needed to use the"
       puts stderr "APP software package"
       puts stderr ""
    }
    
    set APP_CURPATH /my_home_directory/my_modules/app
    setenv APP_HOME $APP_CURPATH
    prepend-path PATH $APP_CURPATH/bin

Once your module file is completed, you will need to modify the $MODULEPATH environment variable to include the path to the directory containing your module files. For example, you could run one of the following:

module use ${HOME}/my_modules
module use --append ${HOME}/my_modules

Your modules should then show up in the output of the module avail command and be available for your use.

To remove your module's path from the $MODULEPATH environment variable, do the following:

module unuse ${HOME}/my_modules