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, all explained further in this document:

• the naming scheme is more versatile,
• default and 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 interdependence of applications, their modules, 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.

Further, 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)

The general module naming scheme is as follows:

• The full name of a module has several components that are separated by a slash /.
• The first and last component of the module name, respectively, are formed by the applications's typically author-provided main name and version, along with a build number or identifier that is local to Carbon.
• Other name components may be present in-between and make apparent to the user which set of major tools was used to produce the application locally, which usually translates to which modules must be loaded to run the application.

In detail, module names have one of the following forms and typical use cases:

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

• name is the package's name as chosen on Carbon. It is usually the name given by the software's author, but lowercased for consistency, and it may contain a number if conventionally so named by the author, e.g. fftw3.
• api is the leading part or parts of the package's version number which typically signifies to suitable precision the API level across which different package versions are expected to be compatible (interchangable in terms of features). api is typically a sole major version number, or has the form major.minor. You may load a module that has the full name foo/m.n/compiler/version-build by the abbreviated name foo/m.n/compiler, which enables you to select the features and binary compatibility level that you need without having to give a complete name all the way down to a build number.
• 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, but is usually present even then for informative purposes. Conversely, the name component is typically not present for applications installed from binary distribution packages, notably commercial applications and, naturally, compilers themselves.
• mpi, present when neeeded, denotes the MPI flavor in use for parallel computations.

For reference and contrast, the previous scheme has been the simpler but more opaque:

name/version-build

Example: Names for the FFT3 library module in the old and new naming schemes, queried by the module avail shell command:

Scheme 2 (current)	Scheme 1 (being retired)
$ 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 older naming scheme. (Boldface shown here for illustration only, your output will appear all as regular text.)
• Lines ending in : indicate file system directories in which modules are being located. The means by which applications on different OS releases are accommodated is by tailoring the set of module search directories offered to users on a given node.
• The -t option of module avail shows the output in "terse" form, one entry per line.

Watch out: Changes requiring your attention

You may need to adapt the modules that you load in your shell startup and job files to the new naming scheme. Instructions about the affected files are given in the Migration guide section below. The module names themselves need to be changed as follows.

Name changes for most modules

For most modules, with a few exceptions, the leading name component (the part before any "/") is the same in the old and new naming schemes. What always differs are the name parts after the first slash, mostly relevant if you previously chose a specific version deliberately and hopefully with good reason.

• To select the latest or administratively designated default version of a package:
  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. In your configuration file, remove version numbers from old-scheme module names of the formpackagename/version, leaving only packagename.
  3. Append API, MPI, and/or compiler specifications as needed.

  This is the recommended approach, as you will automatically benefit from future updates and maintenance builds.

  For instance, instead of vasp5/5.3/openmpi-1.4/intel/5.3.3p3-mkl-3 write vasp5/5.3/openmpi-1.4

• To insist on a specific version and build for a package in new-scheme names, which you should do only if you require a build with a specific feature or behavior:

4. Append version and build specifications:

Name change exceptions

For the following modules the newer naming convention allowed for and thus uses more consistent names:

OLD		NEW
-------------------------------------
asap3		asap/3.x		

ase2		ase/2		- deprecated
ase3		ase/3		- not needed as separate module – installed within new module series "python-env"

g09		gaussian/09
GaussView	gaussview  (lowercase)

python		python-env	- (several suites of environments with many packages)
		python.org	- (interpreter only)

The modules fftw3 and vasp5 did not change name due to more entrenched usage of the qualified name in the package itself, in Unix group names, and in makefiles.

Scheme customization by operating system

During a transition period, nodes with different operating systems will coexist in the cluster. Each user, nonetheless, will see the same networked home directory on each node regardless of the OS that the node runs. Therefore, the user's shell and module configuration files (like .bashrc and others) will be interpreted by system utilities, end user applications, and in runtime environments that all differ by operating system, to a varying degree.

The module scheme that is active on a node is primarily determined by its operating system, secondarily by the user, according to these rules:

• On nodes running CentOS-6, scheme 2 is used always. Customize in ~/.bashrc or in a separate configuration file ~/.modules-2.
• On CentOS-5 nodes, scheme 1 is normally used. If only the file ~/.modules-2 exists, scheme 2 is used instead. You can go back to scheme 1 on these nodes by creating ~/.modules-1.

In other words, the files will be detected and read as follows:

You have files: .bashrc and …		Remark	CentOS-5 reads:		CentOS-6 reads:
			files	module names	files	module names
–	–	Starting situation	.bashrc only	scheme 1	.bashrc only	scheme 2
–	.modules-2	Full switch-over	.modules-2 and .bashrc	scheme 2	.modules-2 and .bashrc
.modules-1	.modules-2	Separate configs, recommended	.modules-1 and .bashrc	scheme 1	.modules-2 and .bashrc

Remember that your home directory is the same across nodes, and therefore your configuration scripts are sensitive to differences between OS releases.

Available modules differ between naming schemes

• The previous module naming scheme 1 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 naming scheme 2. Some applications may turn out to be backwards-compatible with a previous OS release, and will be made available there as well, in scheme 2, to appropriately offer applications that run on both or only a specific release of the operating system.
• Only a subset of modules from scheme 1 has been ported to scheme 2, typically the modules representing the most recent version of an application.

Users must load all modules yourself

• No modules are pre-loaded by the system. You must load all applicable modules yourself in your shell setup files or (see next section) in job files, in suitable order (modules not depending on others first).

This is born of necessity because still useful older applications were compiled with older MPI versions (typically OpenMPI-1.4) which partially interfere with newer versions (OpenMPI-1.8, 1.10, or Intel-MPI-5.x). In particular, each MPI flavor provides commands like mpirun and mpifort.

Loading modules in job files

• You may now safely load modules in PBS job files when using recent MPI modules. 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.

• Best practice is to load all modules in ~/.bashrc or ~/.modules-2.

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.

Modules do not load dependencies

• A module does not implicitly load other modules that it might depend on, such as modules for compilers, an MPI flavor, or specialized libraries. While a minor burden for the user to specify, this will make operations more flexible and explicit.
• Learn to recognize error messages issued by module load when a dependent module is found missing. For instance:

$ 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 red item in the last line shows the prerequisite as stated in the text of the module attempted to be loaded. The currently available modules that would satisfy the requirement are listed in blue. The full name of the offending module that was located from the abbreviated name given in the command appears in brown.

• You must load prerequisite modules yourself before modules that depend on them, by full or (recommended) abbreviated name. The typical order is: compiler, MPI, other (dynamic) libraries, and finally your intended module. In the example above, a suitable command would be:

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

Note how in this case it is preferable to explicitly supply the compiler name component …/intel-16 of the openmpi module to ensure it is consonant with the compiler.

• Different MPI flavors can (reluctantly) be loaded at the same time. In this situation, MPI commands will have to be called by absolute path, e.g. $OPENMPI_HOME/bin/mpirun …

Again, this is because the system is less homogeneous than in the past: it is impractical or even impracticable to upgrade and maintain applications at a single "one true" MPI implementation.

Migration guide – How to customize your module selection by OS release

In adapting your existing module selection, you have two choices:

Configure in dedicated files

It is cleanest to perform the module selection in separate files, one for each OS release. This allows you to change files later on with minimal interference.

To migrate your existing configuration, use a helper utility to get you started:

modules-migrate

This utility will manage the following files, which you should afterwards inspect and edit:

.bashrc
.modules-1
.modules-2

Example output

• Test: Open another login window or shell and review potential error messages that appear before your prompt.

Configure in .bashrc

To switch over to new-style module names entirely, on both CentOS releases, you could continue using only ~/.bashrc. To do this:

• Tell CentOS-5 nodes to offer you the new-style module catalog instead of the old one. To do so, simply create the new-scheme customization file but leave it empty:

touch ~/.modules-2

• Then, apply the changes shown in the nomenclature section above:

vi .bashrc
# or:
nano .bashrc

Use a text editor of your choice, such as nano or vi.

• Test – same as in previous section.

Minor changes for the module command

Name completion in command line

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

At a shell prompt (shown as "$"), type:

$ module load fft

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

$ module load fftw3/_
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 MPI version, at which the then remaining single module name choice will be completed, 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, the Carbon queueing system was made available to users by modules, which meant that it was difficult for a user to start with a clean slate, or to make and adjust a custom set of module choices. You may now safely use the module "purge" command for its intended purpose:

module purge

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

Extra Tip

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

module purge
module load profile

Determining default module versions

To determine which module will be loaded when an abbreviated name is used, I recommend to 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 in 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.)