Introduction

Modules are files that contain the necessary setup and configuration information for a given software package. These modules can be dynamically loaded, unloaded, or swapped to tune your environment as you require. In this document, you will learn how to find and use modules on the cluster, in addition to some helpful tips regarding their use.

Finding Modules

The cluster features hundreds of software packages that power scientific computing. Sorting through these packages one-by-one would be a difficult task. In addition, searching through your environment to find the modules you have currently loaded would take a lot of time. Instead, use the module list, module avail, and module show commands to accomplish these precursory tasks.

The module list command outputs a list of the module files that are currently loaded in your environment. After you load a module, it will appear in the output of module list. The order of the modulefiles exists to enhance readability, not to indicate the priority of modules. Use this command to verify that all the modules you require are loaded into your environment.

By default, seven modulefiles are loaded into your environment when you log in to the cluster. Figure 2.1 shows these default modules.

[user-x@acf-login6 ~]$ module list
Currently Loaded Modulefiles:
  1) moab/9.1.1                 2) pbstools                   3) intel-compilers/2017.2.174              
  4) intel-mpi/2017.2.174	5) PE-intel                    6) xalt/0.7.5	7) DefApps

Figure 2.1 – Output of module list

All these modules are necessary for your environment to function correctly. For instance, without the moab/9.1.1 and pbstools modulefiles, some of the job monitoring commands would no longer function. The DefApps modulefile is especially critical to your environment. Please do not attempt to unload these default modules. Exceptions will be noted in the Troubleshooting Modules section.

The module avail command outputs all the modulefiles available to load on the cluster. Because there are many modules available, the output is extensive. To narrow the results, execute module avail <module>. For example, to determine which versions of Anaconda are available, execute module avail anaconda. The output would be more focused and manageable.

Each module in the output of module avail follows the same format. The module’s name comes first, followed by the version number. In some cases, the term “default” appears in parentheses next to the module. If you load a module without providing a version number, it will load the module that has the default flag applied to it.

The module show command retrieves information on the module you specify. In most cases, it provides the module’s description and the changes it will make to your environment. As an example, Figure 2.2 shows the output of module show for the LAMMPS module. In general, the module show command is helpful to determine which programming environment to use for the module and what dependencies it will load. The Troubleshooting Modules section will review this information in more detail.

[user-x@acf-login6 ~]$ module show lammps
-------------------------------------------------------------------
/sw/acf/modulefiles/lammps/11Aug17:

module-whatis	 LAMMPS (Large-scale Atomic/Molecular Massively Parallel Simulator) is a classical molecular dynamics code.
The executable 'lmp_beacon' is available upon loading this module. 
prepend-path	 PATH /sw/cs400_centos7.3_acfsoftware/lammps/11Aug17/centos7.3_intel17.2.174/bin 
setenv		 LAMMPS_DIR /sw/cs400_centos7.3_acfsoftware/lammps/11Aug17/centos7.3_intel17.2.174 
setenv		 LAMMPS_EXAMPLES_DIR /sw/cs400_centos7.3_acfsoftware/lammps/11Aug17/centos7.3_intel17.2.174/lammps-11Aug17/examples 
-------------------------------------------------------------------

Figure 2.2 – Output of module show for the LAMMPS Module

Loading and Unloading Modules

After you identify the module(s) you wish to load, execute module load <module>. Replace <module> with the name of the module you wish to load. You may load multiple modules at once by providing a space between each module name. For instance, to load Anaconda 3, Python 3, and RStudio all at the same time, execute module load anaconda3 python3 rstudio. The output of module list will verify that these modules were properly loaded.

If you do not specify a version to the module you load, the default version for that module will be loaded into your environment. To load a specific version of a module, supply the module name followed by the version. Using Anaconda 3 version 5.1.0 as an example, you would load this module with module load anaconda3/5.1.0.

Unloading a module follows the same process as loading a module. In this case, execute module unload <module> to remove a module from your environment. Replace <module> with the name of the module you wish to unload. Like module load, you can specify multiple modules if you separate them with a space. Use module list to verify that the modules were unloaded from your environment.

If you wish to automatically load certain modules when you log in to the cluster, you can add module load <module> to your .bashrc file. Always verify that the modules you wish to automatically load at log in do load with the module list command. Be aware that some modules, such as Anaconda, require configuration scripts to be executed before they can work. Consult the documentation for the module before attempting to automatically load it.

Troubleshooting Modules

Using the Correct Programming Environment

By default, every user environment loads the PE-intel programming environment, which uses Intel’s tools and compilers to handle software. In the context of the cluster, using this programming environment offers the greatest compatibility and performance for most modules. However, there are some modules that require GNU tools and compilers. LAPACK is one example. In these cases, you must switch from the PE-intel programming environment to the PE-gnu programming environment.

Before you switch your programming environment, use the module show command to determine if the module requires the PE-gnu programming environment. Figure 4.1 shows the output of module show for the LAPACK module. Observe the error that the module returns.

[user-x@acf-login6 ~]$ module show lapack
-------------------------------------------------------------------
/sw/acf/modulefiles/lapack/3.7.0:

module-whatis	 LAPACK (Linear Algebra Package) is a standard software library for numerical linear algebra. 
lapack: This library has not been built for this programming environment (PE-intel).

Figure 4.1 – LAPACK Module in the PE-intel Environment

In this case, the module informs the user that it cannot execute in the current programming environment. To remedy this problem, execute module swap PE-intel PE-gnu. The Intel tools and compilers will be unloaded and the GNU tools and compilers will be loaded. Though the PE-intel module is a default module, it is safe to change from it to PE-gnu. After the swap completes successfully, you may load the module into your environment. Figure 4.2 shows the output of module show for the LAPACK module in the PE-gnu programming environment.

[user-x@acf-login6 ~]$ module show lapack
-------------------------------------------------------------------
/sw/acf/modulefiles/lapack/3.7.0:

module-whatis	 LAPACK (Linear Algebra Package) is a standard software library for numerical linear algebra. 
prepend-path	 LD_LIBRARY_PATH /sw/cs400_centos7.3_acfsoftware/lapack/3.7.0/centos7.3_gnu6.3.0/lib 
setenv		 LAPACK_DIR /sw/cs400_centos7.3_acfsoftware/lapack/3.7.0/centos7.3_gnu6.3.0 
setenv		 LAPACK_LIB -L/sw/cs400_centos7.3_acfsoftware/lapack/3.7.0/centos7.3_gnu6.3.0/lib 
prepend-path	 PE_PRODUCT_LIST NICS_LAPACK 
setenv		 NICS_LAPACK_POST_LINK_OPTS -L/sw/cs400_centos7.3_acfsoftware/lapack/3.7.0/centos7.3_gnu6.3.0/lib 
prepend-path	 PKG_CONFIG_PATH /sw/cs400_centos7.3_acfsoftware/lapack/3.7.0/centos7.3_gnu6.3.0/lib/pkgconfig 
prepend-path	 PE_PKGCONFIG_PRODUCTS NICS_LAPACK 
prepend-path	 PE_PKGCONFIG_LIBS lapack 
setenv		 NICS_LAPACK_REQUIRED_PRODUCTS  
-------------------------------------------------------------------

Figure 4.2 – LAPACK Module in the PE-gnu Environment

Missing Modules or Dependencies

In the event that you cannot find the module you require for your work, consider using Anaconda or pip to locate the package. Please note that these tools are mostly for Python and R packages. Additionally, Singularity allows you to retrieve containers from various sources and use them as you would a standard executable program. Please review our Singularity User Guide for more information. If none of these solutions fit your situation, contact the OIT HelpDesk detailing your software needs. The staff will evaluate the request and determine if the package can be installed on the cluster.

Software License Issues

Some software on the cluster requires a license to use. Examples include VASP, TURBOMOLE, and MatLab. If you do not belong to the proper group that has access to the license, you cannot use it. If you need access to licensed software please contact the OIT Help Desk (see https://help.utk.edu/) to make your request.