HPC/Module naming scheme 2016

Introduction

(*) Environment modules are the means by which software applications are made available to users. Using modules allows users and administrators to pick, by user or even by compute job, a desired or default version of an application from typically several current and historic versions persisting on the system. Older versions are kept to improve reproducibility of results, an important characteristic of scientific computing.

On Carbon, the environment modules system(*) has changed in the following aspects, explained further in this document:

• The naming scheme is more developed and more versatile.
• The system does not preload compiler and MPI modules - you must specify all modules yourself.
• Dependent modules are no longer being loaded.
• The module command behaves in slightly different ways.

Motivation

The changes were necessary because of increasing diversity and dependencies of applications, libraries, and the underlying operating system. The goal was to accommodate different compilers, MPI flavors, and (in the future) different aspects of the machine architecture like CPU generation, capabilities, and coprocessor facilities.

For different OS releases the new scheme enables existing application versions to continue being offered where possible, and to make new application versions available where suitable, either on both old and newer OS releases, or only on one.

Naming scheme (Nomenclature)

Overview

The full name of a module has two or more components separated by slashes /, in one of the following forms:

name/api/version-build			# binary packages, compilers
name/api/compiler/version-build		# compiled applications
name/api/mpi/compiler/version-build	# compiled applications that use MPI

• The first component is the applications's main name, usually as chosen by its author.
• The last component is the version number, also usually chosen by the author, followed by a build identifier chosen on Carbon.
• Other name components may be present and indicate which set of major tools were used to produce the application locally, which usually implies which modules are required to be loaded to run the application.

Details

• name is the package's name as chosen on Carbon. It is the name given by the software's author, lowercased for consistency. It may contain numbers if they are customarily part of the name, fftw3 being a prime example.
• api is the leading part or parts of the package's version number which indicates to suitable precision the API level across which different package versions are expected to be compatible (interchangable in terms of features). The api component typically has one of these forms:

  major

  major.minor

The specificity is subject to an administrator's intuition and understanding of the intentions of the package's author, and may well turn out to be incorrect in the future after unexpected turns in a package's development process (caveat emptor).

• compiler is a name component that is present when an application was compiled here and thus usually needs runtime libraries associated with the compiler used. The compiler name component is not strictly needed for applications that are statically linked, or come with all their own libraries, but can be present even then for informative purposes. The name component is typically absent for applications installed as binaries, notably commercial applications and, naturally, compilers themselves. The name component typically has sub-components of the form:

  compilerNAME-compilerAPI

• mpi, present when neeeded, denotes the MPI flavor in use for parallel computations. This name component typically also has sub-components of the form:

  mpiNAME-mpiAPI

Changes from previous scheme

For reference and contrast, the previous scheme used the simpler but less informative form:

name/version-build

Name changes for most modules

For most modules the leading name component (the part before any /) will be the same in the previous and new schemes. What will always differ are the name parts after the first slash, which is relevant if you deliberately (and hopefully with good reason) chose a specific version.

Name change exceptions

The names of following modules changed, making their names more consistent:

legacy scheme	new scheme
-------------------------------------
asap3		asap/3.x		

ase2		ase/2		- deprecated
ase3		ase/3		- not needed as separate module, instead, is installed within each of the new "python-env" modules

g09		gaussian/09
GaussView	gaussview  (lowercase)

python		python-env	- Several suites of Python environments, each with many packages
		python.org	- The interpreter only, from the main Python web site.

Note that the modules fftw3 and vasp5 did not change name, given widespread entrenched use of these names in the packages themselves, as Unix group names, and even in Makefiles of other packages.

Example

Here are the names for the FFT3 library module in the legacy and new naming schemes, as queried by the module avail shell command:

Current scheme	Legacy scheme
$ module -t avail fftw3 /opt/apps/M/x86_64/EL6: /opt/apps/M/x86_64/EL: fftw3/3.3/impi-5/intel-16/3.3.4-10 # uses Intel-MPI fftw3/3.3/intel/3.3.2-1 # legacy, serial only fftw3/3.3/openmpi-1.10/intel-16/3.3.4-11 # uses OpenMPI fftw3/3.3/openmpi-1.4/intel/3.3.2-4 # legacy, OpenMPI /usr/share/Modules/modulefiles: /etc/modulefiles:	$ module -t avail fftw3 /opt/soft/modulefiles: fftw3/3.2.1-1 fftw3/3.2.2-1 fftw3/3.3-1 fftw3/3.3.2-1 fftw3/3.3.2-4 /opt/intel/modulefiles: /usr/share/Modules/modulefiles: /etc/modulefiles:

• Note the MPI flavor and the compiler name components compared to the legacy naming scheme (bold is used here for illustration only, your output will appear all as regular text.)
• The -t option of module avail shows the output in "terse" form, one entry per line.
• Lines ending in : indicate file system directories in which modules are being located on the current node.

Module selection by operating system

For a time, nodes with different operating systems and therefore more or less different module catalogs will coexist in the cluster. Since you will always have the same home directory on each node, most of your script files would have to be written so they run on either operating system. This would mean having to code if statements in your scripts, which can be difficult and fragile to keep up. To simplify conditional module selection, each node on Carbon now looks for specific file names in your home directory. Depending on which files exist, a node:

1. determines whether to use the legacy or new naming scheme, and then
2. loads the file that is appropriate for the operating system running on that node, in the scheme determined.

Specifically:

• Files of the form ~/.modules-elx, with x = 5,6,..., trigger the new naming scheme and will be loaded on the corresponding OS.
• On CentOS-5 nodes, a file ~/.modules-el5-legacy will trigger the legacy scheme, but only if ~/.modules-el5 is not present. In other words, a ~/.modules-el5 file has priority and causes ~/.modules-el5-legacy to be ignored.
• Without any ~/.modules-* files, CentOS-5 nodes will use the legacy scheme; CentOS-6 nodes always use the new scheme.
• Your .bashrc file will always be read, expecting the naming scheme that was determined by the presence or absence of .modules-* files.
• When running a PBS job, module commands in the job file will be read, in the same naming scheme as .bashrc.

Tips

• To load the same modules on any node, in the new scheme:
  • Place your configuration in ~/.modules-el6, then create a symbolic link:

  cd; ln -s .modules-el6 .modules-el5

  • It is possible but not recommended (because less future-proof) to keep your module selection in ~/.bashrc, and activate the new scheme on CentOS-5 nodes by simply creating an empty configuration: touch ~/.modules-el5

Best Practices

Use migration utility

Use a helper utility to get started on splitting off and diversifying your existing module selection from .bashrc into .modules-* files:

modules-migrate

The utility will manage the following files:

.bashrc
.modules-el5-legacy
.modules-el6

See an example output of running the utility.

• Please note that the utility is fairly basic and cannot transform or choose versions and their dependencies as described here.
• The utility will give you the opportunity to inspect and edit the resulting files. Use a text editor of your choice, such as nano or vi to re-examine or edit these files further.
• To switch to the new scheme on all nodes, create or copy from .modules-el6:

.modules-el5

• #Test your module choices, as shown below.

Workflow to determine module names to load

• To select the default version of a package, e.g., after using the migration utility:
  1. On a Carbon command line, list the available flavors and versions, keeping in mind that some older modules were not migrated:

     module avail packagename

  2. When upgrading from the previous naming scheme, remove version numbers from names of the formpackagename/version, leaving only packagename.
  3. Use the module show command to inspect details of a module, including its full name:

     module show name/api

     Complete the desired package's name by appending API, MPI, and/or compiler specifications as needed.

  4. Determine a package's dependencies. Load them on a previous line.
• Insist on a specific version and build only if you require a build with a specific feature or behavior. To do so:

5. Append version and build specifications, as shown by the module avail packagename command.

Omit detailed versions from module names

(**) Caution: Module names are typically sorted as text strings the same way as Unix ls(1) does it. The resulting order may be counter-intuitive when the same part of several version numbers has a different number of digits. In the following example, version 8.16.x is the most recent release and needed to be administrator-designated as default because character for character, the string 8.7.x would be sorted highest. $ module avail lumerical ... lumerical/7.5.7-1 lumerical/8.0.5-1 lumerical/8.15.736-1 lumerical/8.16.931-1(default) lumerical/8.5.4-1 lumerical/8.7.1-1 ...

When constructing a module load command, try to omit detailed version and build numbers from the end, i.e., load a module that has the full name foo/m.n/compiler/version-build by an abbreviated name foo/m.n/compiler.

Module names that are abbreviated in this manner will be completed at the time of loading to select a default, which is either a version designated as such by an administrator or simply the version with the highest version number(**). In any case, with abbreviated module names you will benefit from newer modules that have been installed since you last looked. Version numbers are generally chosen so that versions with the same major version number are binary-compatible.

For instance, instead of:

module load intel/16/16.0.0-3
module load openmpi/1.10/intel-16/1.10.0-4

Write:

module load intel/16
module load openmpi/1.10/intel-16

It is preferable to supply the compiler name part of MPI modules (here …/intel-16) because they usually both (a) need compiler libraries and (b) impliclity use their native compiler for further compilations.

Modules load order

• To resolve module dependencies, edit your configuration or job files to load required modules first, in this order:
  1. compilers
  2. MPI flavor
  3. other libraries that are dynamically loaded.
  4. your desired application(s).

Understanding dependency errors

Learn to recognize error messages from module load when a required module has not been loaded:

Example: A typical error message will look like:

$ module load openmpi/1.10
openmpi/1.10/intel-16/1.10.2-1(27):ERROR:151: Module 'openmpi/1.10/intel-16/1.10.2-1' depends on one of the module(s) 'intel/16/16.0.2 intel/16/16.0.1-2 intel/16/16.0.0-3 intel/16/16.0.0-1 intel/16/16.0.0-0'
openmpi/1.10/intel-16/1.10.2-1(27):ERROR:102: Tcl command execution failed: prereq intel/16

Colors do not appear in the original terminal output but were added here for clarity:

• The missing prerequisite is the red item on the last line.
• The modules that would currently satisfy the requirement are shown on the preceding line, indicated here in blue.
• The full name of the "offending module", deduced from a possibly abbreviated name on the command line, appears in brown.

• You can inspect the prerequisites of a module in a more succinct manner:

$ module show openmpi/1.10 2>&1 | grep req
prereq	 intel/16

The sequence 2>&1 is necessary so the pipe | captures the entire output of the module show command, i.e., combining its stdout and stderr streams.

Test your module choices

Automated test

Use the test built into the migration utility:

modules-migrate --test
modules-migrate -t

This will simulate loading your existing .module-* files under the available operating systems. Review the output. To correct any errors, edit the respective files manually or use the migration utility again:

modules-migrate --edit
modules-migrate -e

Manual test

Same node	EL5 node	EL6 node
bash -l	ssh clogin5	ssh clogin8
module list
exit

To test your new module configuration in your actual environment:

1. Open another login shell on the current or another node.
2. Review error messages that might appear before your prompt.
3. Inspect which modules are loaded.
4. Edit your .module-* files and address any errors.
5. Close the test shell and repeat until your desired modules are loaded without errors.

Test in a job file

Your module selection is likely most important in a PBS job file. To avoid the hassle of extended wait times for production jobs, use test jobs with a short walltime limit and place just diagnostic commands in the job script.

Use the module list and type shell commands to verify that all your modules are loaded and that an application is properly callable without full paths.

Example

Consider the following job file modtest.sh:

#!/bin/bash
#PBS -l nodes=1:ppn=1
#PBS -l walltime=0:1:00
#PBS -N modtest

module list

type vasp_gam

Submit the job:

qsub modtest.sh

Alternatively, do the whole thing on the command line, without the need for a separate file:

echo "module list; type vasp5" | qsub -l nodes=1:ppn=1,walltime=0:1:00 -N modtest

In either case, wait for the job to finish, then inspect the output files:

qstat jobnumber
…
head modtest.[eo]1234*

You should see something like:

vasp_gam is /opt/apps/vasp5/5.4.1.3-6-openmpi-1.10-intel-16/bin/vasp_gam

An error looks like:

-bash: type: vasp_gam: not found

Effect on PBS job submissions

Loading modules in job files

• You may now safely load modules in PBS job files when using recent MPI modules, both in the legacy and new schemes. Previously, this was not recommended.

Recent builds of OpenMPI (1.4 and 1.10) and Intel MPI now have support compiled in to properly start proccesses on remote nodes.

• However, best practice is still to load all modules in dotfiles under your home directory.

This will always give you the same applications on both login and compute nodes. Place module commands in job files only when conflicts arise, such as when two of your regularly-used applications require different MPI flavors.

Job routing by operation system

• TORQUE/PBS jobs that are submitted from a node running CentOS-5 or CentOS-6 will normally be routed to run only on nodes that run the same OS release.
• Find the eligible OS in the qstat -f output:

$ qstat -f jobnumber | grep opsys
   Resource_List.opsys = el5

• You may override the automatic selection prior to submission by adding an opsys job resource:

#PBS -l opsys=el5

or:

#PBS -l opsys=el6

• In a pinch, you may even change the OS request of a queued job by using the qalter command, e.g.:

qalter -l opsys=el6 jobnumber

Using multiple MPI flavors

• Different MPI flavors can, with caution, be loaded at the same time. This may be necessary because the system is less homogeneous than in the past and no longer uses a single "one true" MPI implementation.
• When modules of multiple MPI flavors are loaded, call the appropriate MPI commands by a full path specified via the MODULENAME_HOME environment variables that is set by the modules.

Example: In a job file that is to run 2 applications that were compiled with different MPI flavors, write:

$OPENMPI_HOME/bin/mpirun app1_name
$IMPI_HOME/bin/mpirun app2_name

Changes requiring attention

Available modules differ between naming schemes

• The legacy naming scheme is being retired, along with some of its attendant conventions.
• Newer applications will primarily be compiled and installed on the newer OS release and in the new naming scheme. Some applications may turn out to be backwards-compatible with a previous OS release, and will be made available there as well, in the new scheme, to appropriately offer applications that run on both or only a specific release of the operating system.
• Only a subset of modules from the legacy scheme has been carried over into the new scheme, typically the modules representing the most recent version of an application.

Load all modules yourself

Under the new modules scheme, you must yourself load all desired modules, particularly compiler and MPI modules, in your shell setup files or in job files (see section below), in suitable order. Modules not depending on others must be loaded first.

This is born of necessity because still useful older applications were compiled with older MPI flavors and versions (typically OpenMPI-1.4) which partially interfere with newer flavors (OpenMPI-1.8, 1.10, or Intel-MPI-5.x). In particular, each MPI flavor provides commands like mpirun and mpifort, and special care is needed to run the correct one if your chosen module set spans different MPI flavors.

No modules are pre-loaded

(**) Technically, the system does load the module profile/user for you. This module only contains the instructions to select and read the appropriate .modules-* file.

• No modules are pre-loaded by the system**.

Previously, the Intel compilers, the Intel Math Kernel Library, and OpenMPI were loaded even when there were no module load commands in your dot-files.

No recursive loading

A module under the new scheme does not implicitly load other modules that it might depend on, such as modules for compilers, an MPI flavor, or specialized libraries. Previously, this was the case for some popular modules but with the system maturing and diversifying, unexpected consequences can occur easily.

You must load dependent modules yourself. While this may by a minor burden for you at first, your selections should become easier to understand now and easier to adapt later.

See HPC/Modules Best Practices#Load dependent modules first.

Determining prerequisites and load order

To see if an particular application module (such as VASP or Quantum-ESPRESSO) has any prerequisites, inspect the output of module show name, and look for any prereq statements.

Then edit your .modules-* file, load the prereq modules first, followed by the desired application module. Example:

• Let's load a vasp5 module that uses the Intel-MPI flavor, named "impi":

$ module avail vasp5
------------------------------------------------------------ /opt/apps/M/x86_64/EL ------------------------------------------------------------
vasp5/5.3/openmpi-1.4/intel/5.3.2-mkl-beef-1    vasp5/5.4/impi-5/intel-16/5.4.1.3-6
vasp5/5.3/openmpi-1.4/intel/5.3.3p3-mkl-3       vasp5/5.4/openmpi-1.10/intel-16/5.4.1.3-6
vasp5/5.3/openmpi-1.4/intel/5.3.3p3-mkl-cellz-1

• Let's try inspecting what it needs:

$ module show vasp5/5.4
-------------------------------------------------------------------
/opt/apps/M/x86_64/EL/vasp5/5.4/openmpi-1.10/intel-16/5.4.1.3-6: 
…

• Careful: The first output line shows the full file name of the module that would get loaded by the short name. In this case, the abbreviated module name, having no MPI name component, yields a module that uses a different MPI flavor than you want.
• You will need to be more explicit:

$ module show vasp5/5.4/impi-5
-------------------------------------------------------------------
/opt/apps/M/x86_64/EL/vasp5/5.4/impi-5/intel-16/5.4.1.3-6:

module-whatis	 VASP - Vienna Ab-initio Simulation Package 
conflict	 vasp 
conflict	 vasp-vtst 
prereq	 intel/16
prereq	 impi/5
setenv		 VASP5_HOME /opt/apps/vasp5/5.4.1.3-6-impi-5-intel-16 
prepend-path	 PATH /opt/apps/vasp5/5.4.1.3-6-impi-5-intel-16/bin 
setenv		 VASP_COMMAND vasp-ase 
setenv		 VASP_PP_PATH /opt/soft/vasp-pot/ase 
-------------------------------------------------------------------

• Therefore, you'd need to add the following lines to your .modules-el6 file:

module load intel/16
module load impi/5
module load vasp5/5.4/impi-5

Minor changes for the module command

Determining default module versions

To determine which module will be loaded when an abbreviated name is used, inspect the first relevant line in the output of one of these commands:

module show name
module help name

The reason is twofold:

• The module avail command under CentOS-6 no longer issues the marker "(default)" when set for a particular module (which is done administratively using a .version file). I am not sure if this is a bug or by design, but the change makes the output more consistent.
• On the older CentOS-5 system the module command honors .version files only for the last component of the module. This may lead to different module versions being selected on different systems even when the list of available modules is identical. (Side note: This is a possibly fortuitous bug since openmpi-1.4, used on CentOS-5, sorts after openmpi-1.10.)

Name completion on command line

When working interactively in a terminal, you can use the "Tab completion" feature of the Bash shell to complete a partially typed module name and show all names available for the name typed so far.

The feature works as follows. At a shell prompt (shown as "$"), type:

$ module load fft

Press the <TAB> key and the name will be expanded to fftw3/3.3/, and you'll see all possible completing names, with the cursor waiting at the end of the longest common substring:

$ module load fftw3/3.3/_
fftw3/3.3/impi-5/intel-16/3.3.4-10        fftw3/3.3/openmpi-1.10/intel-16/3.3.4-11
fftw3/3.3/intel/3.3.2-1                   fftw3/3.3/openmpi-1.4/intel/3.3.2-4

Type the letter o, hit the <TAB> key again. The choices will be narrowed down to OpenMPI.

$ module load fftw3/3.3/openmpi-1.<TAB>
fftw3/3.3/openmpi-1.10/intel-16/3.3.4-11  fftw3/3.3/openmpi-1.4/intel/3.3.2-4

Typing the digit 1 will pick the 1.10 version, at which point the then remaining single module name choice will be completed all the way, with the cursor waiting after an additional space character:

$ module load fftw3/3.3/openmpi-1.10/intel-16/3.3.4-11 _

"module purge" command

Previously on Carbon it was difficult to reset the module selection during an interactive terminal session, because the commands for the job queueing system, like qsub, were provided via a module. You may now safely use the module "purge" command for its intended purpose, as

module purge

followed by module load … to choose compilers, MPI flavors, and applications.

Expert Tip: Purge and reload.

You can re-load the customizations from your .modules-* files using the module profile:

module purge
module load profile