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:

• the naming scheme is more versatile,
• default and dependent modules are no longer being loaded,
• the module command behaves in slightly different ways.

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 full name of a module has several components that are separated by a slash /. The applications's typically author-provided main name and version, along with a local build number, form the first and last component of the module name, respectively. 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:

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 loading a module that has the full name foo/m.n/compiler/version-build by the abbreviated name foo/m.n, which enables you to select the features and binary compatibility level that you need without having to give a complete module name all the way down to a build number.
• compiler is a name component that is present only as needed when an application was compiled here and needs runtime libraries associated with the compiler used. The compiler name component is typically not present for applications installed from binary packages, notably commercial applications and, naturally, compilers themselves.
• mpi, also as neeeded, is present to denote an MPI flavor in use for parallel computations.

For reference and contrast, the previous scheme has been:

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. (Terminal output will not be highlighted.)
• 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.

Changes requiring attention

You may need to adapt the modules that you load in your shell startup and job files to the new naming scheme. For most modules, with exceptions shown below, 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.

Name change rules for most modules

• To select the latest or administratively designated default version of a package, remove version numbers from old-scheme module names of the formpackagename/version, leaving only packagename. This is the recommended approach, as you will automatically benefit from future updates and maintenance builds.
• To insist on a specific version and build for a package in new-scheme names:
  • Inspect the available flavors and versions, keeping in mind that some older modules were not migrated.

    module avail packagename

  • Choose the new-scheme name up to the desired specificity. You may leave out trailing name or directory parts.

    For instance, instead of vasp5/5.3/openmpi-1.4/intel/5.3.3p3-mkl-3 you could write vasp5/5.3/openmpi-1.4 or vasp5/5.3, letting the system pick the versions for MPI and compiler that are set as defaults at that time.

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		- use new module "python-hpc" instead

g09		gaussian/09
GaussView	gaussview  (lowercase)

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 selection varies 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.
• On CentOS-5 nodes, scheme 1 is normally used. A user can customize or upgrade to scheme 2 by creating configuration files ~/.modules-2 and optionally ~/.modules-1. The files will be detected and read as follows:

You have files: .bashrc and …		Remark	CentOS-6 reads:		CentOS-5 reads:
			files	module names	files	module names
–	–	Starting situation.	.bashrc only	scheme 2	.bashrc only	scheme 1
–	.modules-2	Switch over, recommended.	.modules-2 and .bashrc		.modules-2 and .bashrc	scheme 2
.modules-1	–	Only recommended during transition.	.bashrc only		.modules-1 and .bashrc	scheme 1
.modules-1	.modules-2	For advanced users.	.modules-2 and .bashrc		.modules-1 and .bashrc	scheme 1

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.

No default modules loaded by the system

• Users must load all applicable modules in their shell setup files or 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.

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 explicit and predictable.
• 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.

Loading modules in job files

• You may now safely load modules in PBS job files.

Given the previous items on module defaults and dependencies, recent builds of OpenMPI (1.4 and 1.10) and Intel MPI now have support compiled in to properly start proccesses on remote nodes.

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

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

Configure in dedicated files

It is cleanest to perform the module selection for each CentOS release in different files, so that you can make adjustments independently.

To migrate your existing configuration you will manage the following files:

.bashrc
.modules-1
.modules-2

Use a helper application to get you started:

modules-migrate

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.

Determining default module versions

The module avail command under CentOS-6 no longer includes the marker "(default)" when one has been set in a .version file. I am not sure if this is a bug or by design, but the change certainly makes the output more consistent.

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