Tutorial setup

If you have not done the prior sections, you’ll need to start the docker image:

docker run -it ghcr.io/spack/tutorial:cineca23

and then set Spack up like this:

git clone --depth=100 --branch=releases/v0.19 https://github.com/spack/spack
. spack/share/spack/setup-env.sh
spack tutorial -y
spack bootstrap now
spack compiler find

See the Basic Installation Tutorial for full details on setup. For more help, join us in the #tutorial channel on Slack – get an invitation at spackpm.herokuapp.com

Module Files Tutorial

This tutorial illustrates how Spack can be used to generate module files for the software that has been installed. Both hierarchical and non-hierarchical deployments will be discussed in details and we will show how to customize the content and naming of each module file.

At the end of the tutorial readers should have a clear understanding of:

  • What module files are and how they are used on HPC clusters
  • How Spack generates module files for the software it installs
  • Which Spack commands can be used to manage module files
  • How module files generated by Spack can be customized

and be confident that Spack can deal with all of the common use cases that occur when maintaining software installations on HPC clusters.

Setup for the Tutorial

To prepare for this tutorial we are going to install a small but representative set of software that includes different configurations of the same packages and some external packages. To keep the installations manageable, let’s start by uninstalling everything from earlier in the tutorial:

$ spack uninstall -ay

Build a module tool

The first thing that we need is the module tool itself. In the tutorial we will use lmod because it can work with both hierarchical and non-hierarchical layouts.

$ spack install lmod

Once the module tool is installed we need to have it available in the current shell. Installation directories in Spack’s store are definitely not easy to remember, but they can be retrieved with the spack location command:

$ . $(spack location -i lmod)/lmod/lmod/init/bash

Now we can re-source the setup file and Spack modules will be put in our module path.

$ . spack/share/spack/setup-env.sh

Add a new compiler

The second step is to build a recent compiler. On first use, Spack scans the environment and automatically locates the compiler(s) already available on the system. For this tutorial, however, we want to use gcc@8.4.0.

$ spack install gcc@8.4.0

You can get this in your environment using spack load gcc@8.4.0:

$ spack load gcc@8.4.0
$ which gcc
/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/gcc

Now, gcc is in your PATH. You can add it to the list of compilers with spack compiler add:

$ spack compiler add
==> Added 1 new compiler to /home/spack/.spack/linux/compilers.yaml
    gcc@8.4.0
==> Compilers are defined in the following files:
    /home/spack/.spack/linux/compilers.yaml

To check which compilers are available you can use spack compiler list:

$ spack compiler list
==> Available compilers
-- clang ubuntu18.04-x86_64 -------------------------------------
clang@7.0.0

-- gcc ubuntu18.04-x86_64 ---------------------------------------
gcc@8.4.0  gcc@7.5.0  gcc@6.5.0

Finally, when you confirmed gcc@8.4.0 is properly registered, clean the environment with spack unload:

$ spack unload --all

Build the software that will be used in the tutorial

Finally, we will use Spack to install the packages used in the examples:

$ spack install netlib-scalapack ^openmpi ^openblas
$ spack install netlib-scalapack ^mpich ^openblas
$ spack install netlib-scalapack ^openmpi ^netlib-lapack
$ spack install netlib-scalapack ^mpich ^netlib-lapack
$ spack install py-scipy ^openblas

What are Module Files?

Module files are an easy way to modify your environment in a controlled manner during a shell session. In general, they contain the information needed to run an application or use a library. The module command is used to interpret and execute module files. For example, module show tells you what a module will do when loaded:

$ module show zlib-1.2.12-gcc-8.4.0-rlo3go7
----------------------------------------------------------------------------------------------------------------------------------------------------------
   /home/spack/spack/share/spack/modules/linux-ubuntu18.04-x86_64/zlib-1.2.12-gcc-8.4.0-rlo3go7:
----------------------------------------------------------------------------------------------------------------------------------------------------------
whatis("A free, general-purpose, legally unencumbered lossless data-compression library.")
prepend_path("LD_LIBRARY_PATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/zlib-1.2.12-rlo3go7mpfwicumepslj4pth7z4t3a46/lib")
prepend_path("MANPATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/zlib-1.2.12-rlo3go7mpfwicumepslj4pth7z4t3a46/share/man")
prepend_path("PKG_CONFIG_PATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/zlib-1.2.12-rlo3go7mpfwicumepslj4pth7z4t3a46/lib/pkgconfig")
prepend_path("CMAKE_PREFIX_PATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/zlib-1.2.12-rlo3go7mpfwicumepslj4pth7z4t3a46/")
help([[A free, general-purpose, legally unencumbered lossless data-compression
library.
]])

$ echo $LD_LIBRARY_PATH

module load will execute all of the changes shown above:

$ module load zlib-1.2.12-gcc-8.4.0-rlo3go7
$ echo $LD_LIBRARY_PATH
/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/zlib-1.2.12-rlo3go7mpfwicumepslj4pth7z4t3a46/lib

and to undo the modifications, you can use module unload:

$ module unload zlib
$ echo $LD_LIBRARY_PATH

$

Module Systems

There are two main module systems used in HPC, both installable by Spack. In this tutorial we will be working with lmod and be showing examples with both Tcl and Lua.

Environment Modules

This is the original modules tool. It can be installed with Spack using the following command:

$ spack install environment-modules

It was first coded in C in the early 1990s and was later rewritten entirely in Tcl. Long stagnant, the project has been revived in the past few years by Xavier Delaruelle at CEA, and it is now very actively developed. For further details we refer to its documentation.

Lmod

Lmod is a module system written in Lua, originally created at the “Texas Advanced Computing Center” (TACC) by Robert McLay. You can get it with:

$ spack install lmod

as shown in the Setup for the Tutorial section. It is a drop-in replacement for Environment Modules, and it works with both Tcl and Lua module files. It is fully compatible with Environment Modules, but it also has many distinguishing features of its own. The main one is the module hierarchy, which simplifies the module UI by only showing modules built with the currently loaded compiler and/or MPI. There are also some unique safety features.

How does Spack generate module files?

Before we dive into the hands-on sections it’s worth explaining how module files are generated by Spack. The following diagram provides a high-level view of the process:

_images/module_file_generation.png

Modules in Spack are generated using configuration files (config.yaml and modules.yaml), information from Spack’s package recipes, and Jinja2 templates. Spack comes with Jinja2, an external template engine, so you do not need to install it yourself.

Modules vs spack load

You may have noticed that we used spack load in the Setup for the Tutorial section above. This is a built-in mechanism of Spack’s – it’s designed so that users on a cluster or a laptop can quickly get a package into their path, and it understands Spack’s spec syntax. It does not require modules, as Spack needs to work regardless of whether modules are set up on the system.

As you might expect, you can see what is loaded via spack load using spack find:

$ spack find --loaded
-- linux-ubuntu18.04-x86_64 / gcc@7.5.0 -------------------------
autoconf@2.69	 berkeley-db@18.1.40  diffutils@3.8  gcc@8.4.0	gmp@6.2.1      libsigsegv@2.13	m4@1.4.19  mpfr@3.1.6	perl@5.36.0    readline@8.1.2  zlib@1.2.13
automake@1.16.5	 bzip2@1.0.8	      gawk@5.1.1     gdbm@1.23	libiconv@1.16  libtool@2.4.7	mpc@1.1.0  ncurses@6.3	pkgconf@1.8.0  texinfo@6.5
==> 21 loaded packages

Because Spack is designed to be run on HPC systems, it also generates a module file for every installed package. This allows users unfamiliar with Spack’s interface to see things through the module system they’re used to. To see this, try:

$ module avail

---------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/modules/linux-ubuntu18.04-x86_64 -----------------------------------------------------------------------------------------------
   autoconf-2.69-gcc-7.5.0-btoteei			   curl-7.85.0-gcc-7.5.0-wc2juod      gmp-6.2.1-gcc-7.5.0-iowhen4	   lua-5.4.4-gcc-7.5.0-ewawei4			mpfr-3.1.6-gcc-7.5.0-3brr36e	    readline-8.1.2-gcc-7.5.0-kgyvtw5
   automake-1.16.5-gcc-7.5.0-rxjqnjw			   diffutils-3.8-gcc-7.5.0-c3uhkcj    libiconv-1.16-gcc-7.5.0-ltvovvv	   lua-luafilesystem-1_8_0-gcc-7.5.0-6snuuy6	ncurses-6.3-gcc-7.5.0-zcuawli	    tcl-8.6.12-gcc-7.5.0-v63n6wx
   berkeley-db-18.1.40-gcc-7.5.0-53fb72w		   gawk-5.1.1-gcc-7.5.0-dco3nzd	      libsigsegv-2.13-gcc-7.5.0-e262sf6	   lua-luaposix-35.0-gcc-7.5.0-3edic26		openssl-1.1.1s-gcc-7.5.0-yr4z2pt    texinfo-6.5-gcc-7.5.0-hdyi7fu
   bzip2-1.0.8-gcc-7.5.0-cxcreln			   gcc-8.4.0-gcc-7.5.0-uobbegc	      libtool-2.4.7-gcc-7.5.0-bdxu4wn	   m4-1.4.19-gcc-7.5.0-z7d5q4f			perl-5.36.0-gcc-7.5.0-eydiwim	    unzip-6.0-gcc-7.5.0-pqjekjj
   ca-certificates-mozilla-2022-10-11-gcc-7.5.0-aurd37j	   gdbm-1.23-gcc-7.5.0-cpmynty	      lmod-8.7.2-gcc-7.5.0-4jrozw5	   mpc-1.1.0-gcc-7.5.0-l5bs2ru			pkgconf-1.8.0-gcc-7.5.0-k2lfw6f	    zlib-1.2.13-gcc-7.5.0-2hfr5rb

If the avail list is too long consider trying:

"module --default avail" or "ml -d av" to just list the default modules.
"module overview" or "ml ov" to display the number of modules for each name.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".

You can module load any of these. By default, Spack generates modules named by package-version-compiler-version-hash, which is a bit hard to read. We’ll show you how to customize this in the following sections.

Non-hierarchical Module Files

If you arrived to this point you should have an environment that looks similar to:

$ module avail

---------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/modules/linux-ubuntu18.04-x86_64 -----------------------------------------------------------------------------------------------
   autoconf-2.69-gcc-7.5.0-btoteei			   gdbm-1.23-gcc-7.5.0-cpmynty		     libxml2-2.10.1-gcc-8.4.0-rsueryu		  openblas-0.3.21-gcc-8.4.0-62oqts5	 py-scipy-1.8.1-gcc-8.4.0-oliuwzs
   autoconf-2.69-gcc-8.4.0-3ur6efa			   gdbm-1.23-gcc-8.4.0-6dpdzlt		     lmod-8.7.2-gcc-7.5.0-4jrozw5		  openmpi-4.1.4-gcc-8.4.0-cnq37ia	 py-setuptools-59.4.0-gcc-8.4.0-uh4z6vn
   automake-1.16.5-gcc-7.5.0-rxjqnjw			   gettext-0.21.1-gcc-8.4.0-lxoekir	     lua-5.4.4-gcc-7.5.0-ewawei4		  openssh-9.1p1-gcc-8.4.0-bu2y2rn	 py-wheel-0.37.1-gcc-8.4.0-htlk6hg
   automake-1.16.5-gcc-8.4.0-ltwno6t			   gmp-6.2.1-gcc-7.5.0-iowhen4		     lua-luafilesystem-1_8_0-gcc-7.5.0-6snuuy6	  openssl-1.1.1s-gcc-7.5.0-yr4z2pt	 python-3.10.8-gcc-8.4.0-4ots64k
   berkeley-db-18.1.40-gcc-7.5.0-53fb72w		   hwloc-2.8.0-gcc-8.4.0-76vxdwi	     lua-luaposix-35.0-gcc-7.5.0-3edic26	  openssl-1.1.1s-gcc-8.4.0-4h2attb	 readline-8.1.2-gcc-7.5.0-kgyvtw5
   berkeley-db-18.1.40-gcc-8.4.0-gfnsus4		   krb5-1.19.3-gcc-8.4.0-lbq4bnu	     m4-1.4.19-gcc-7.5.0-z7d5q4f		  perl-5.36.0-gcc-7.5.0-eydiwim		 readline-8.1.2-gcc-8.4.0-vrvkcpj
   bison-3.8.2-gcc-8.4.0-mne2r6i			   libbsd-0.11.5-gcc-8.4.0-p666k37	     m4-1.4.19-gcc-8.4.0-64hyzlr		  perl-5.36.0-gcc-8.4.0-oxh2v73		 sqlite-3.39.4-gcc-8.4.0-e373hd3
   bzip2-1.0.8-gcc-7.5.0-cxcreln			   libedit-3.1-20210216-gcc-8.4.0-zl6rdlr    mpc-1.1.0-gcc-7.5.0-l5bs2ru		  pigz-2.7-gcc-8.4.0-x4i7we6		 tar-1.34-gcc-8.4.0-vkidral
   bzip2-1.0.8-gcc-8.4.0-h2cyuuc			   libevent-2.1.12-gcc-8.4.0-zlkggwb	     mpfr-3.1.6-gcc-7.5.0-3brr36e		  pkgconf-1.8.0-gcc-7.5.0-k2lfw6f	 tcl-8.6.12-gcc-7.5.0-v63n6wx
   ca-certificates-mozilla-2022-10-11-gcc-7.5.0-aurd37j	   libfabric-1.16.1-gcc-8.4.0-zmoqcfm	     mpich-4.0.2-gcc-8.4.0-dehzhtf		  pkgconf-1.8.0-gcc-8.4.0-db44f6t	 texinfo-6.5-gcc-7.5.0-hdyi7fu
   ca-certificates-mozilla-2022-10-11-gcc-8.4.0-tug2vtk	   libffi-3.4.2-gcc-8.4.0-pfw5zcj	     ncurses-6.3-gcc-7.5.0-zcuawli		  pmix-4.1.2-gcc-8.4.0-alwqqyv		 unzip-6.0-gcc-7.5.0-pqjekjj
   cmake-3.24.3-gcc-8.4.0-3oinxkn			   libiconv-1.16-gcc-7.5.0-ltvovvv	     ncurses-6.3-gcc-8.4.0-pm3k5t4		  py-beniget-0.4.1-gcc-8.4.0-6fg7x2e	 util-linux-uuid-2.38.1-gcc-8.4.0-72abeix
   curl-7.85.0-gcc-7.5.0-wc2juod			   libiconv-1.16-gcc-8.4.0-faxyug5	     netlib-lapack-3.10.1-gcc-8.4.0-d75mbpb	  py-cython-0.29.32-gcc-8.4.0-g5hd5bt	 util-macros-1.19.3-gcc-8.4.0-caquoxb
   diffutils-3.8-gcc-7.5.0-c3uhkcj			   libmd-1.0.4-gcc-8.4.0-mbjxxpr	     netlib-scalapack-2.2.0-gcc-8.4.0-iuphysy	  py-gast-0.5.3-gcc-8.4.0-hthzien	 xz-5.2.7-gcc-8.4.0-yalo3gm
   diffutils-3.8-gcc-8.4.0-42nykx7			   libpciaccess-0.16-gcc-8.4.0-ygwuejw	     netlib-scalapack-2.2.0-gcc-8.4.0-nuulbgb	  py-numpy-1.23.4-gcc-8.4.0-v7eeehl	 yaksa-0.2-gcc-8.4.0-ohap5mv
   expat-2.4.8-gcc-8.4.0-ecxz4tu			   libsigsegv-2.13-gcc-7.5.0-e262sf6	     netlib-scalapack-2.2.0-gcc-8.4.0-vae5gpb	  py-pip-22.2.2-gcc-8.4.0-gdv6477	 zlib-1.2.13-gcc-7.5.0-2hfr5rb
   findutils-4.9.0-gcc-8.4.0-ye45pox			   libsigsegv-2.13-gcc-8.4.0-hzetpcu	     netlib-scalapack-2.2.0-gcc-8.4.0-xqcf6y4	  py-ply-3.11-gcc-8.4.0-i3li6qu		 zlib-1.2.13-gcc-8.4.0-qaq2asl
   gawk-5.1.1-gcc-7.5.0-dco3nzd				   libtool-2.4.7-gcc-7.5.0-bdxu4wn	     ninja-1.11.1-gcc-8.4.0-ctiucvr		  py-pybind11-2.8.1-gcc-8.4.0-pzlkf5u	 zstd-1.5.2-gcc-8.4.0-2b73tir
   gcc-8.4.0-gcc-7.5.0-uobbegc				   libtool-2.4.7-gcc-8.4.0-uejcu2m	     numactl-2.0.14-gcc-8.4.0-qo6lo2m		  py-pythran-0.11.0-gcc-8.4.0-t3pvyne

If the avail list is too long consider trying:

"module --default avail" or "ml -d av" to just list the default modules.
"module overview" or "ml ov" to display the number of modules for each name.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".

The non-hierarchical module files that have been generated so far follow Spack’s default rules for module generation. Taking a look at the gcc module you’ll see, for example:

$ module show gcc-8.4.0-gcc-7.5.0-uobbegc
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
   /home/spack/spack/share/spack/modules/linux-ubuntu18.04-x86_64/gcc-8.4.0-gcc-7.5.0-uobbegc:
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
whatis("The GNU Compiler Collection includes front ends for C, C++, Objective-C, Fortran, Ada, and Go, as well as libraries for these languages.")
prepend_path("PATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin")
prepend_path("MANPATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/share/man")
prepend_path("CMAKE_PREFIX_PATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/.")
setenv("CC","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/gcc")
setenv("CXX","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/g++")
setenv("FC","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/gfortran")
setenv("F77","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/gfortran")
help([[The GNU Compiler Collection includes front ends for C, C++, Objective-C,
Fortran, Ada, and Go, as well as libraries for these languages.
]])

As expected, a few environment variables representing paths will be modified by the module file according to the default prefix inspection rules.

Filter unwanted modifications to the environment

Now consider the case that your site has decided that CC, CXX, FC and F77 modifications should not be present in module files. What you can do to abide by the rules is to create a configuration file ${SPACK_ROOT}/etc/spack/modules.yaml with the following content:

modules:
  default:
    tcl:
      all:
        filter:
          exclude_env_vars:
          - "CC"
          - "CXX"
          - "FC"
          - "F77"

Next you should regenerate all the module files:

$ spack module tcl refresh -y
==> Regenerating tcl module files

If you take a look now at the module for gcc you’ll see that the unwanted paths have disappeared:

$ module show gcc-8.4.0-gcc-7.5.0-uobbegc
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
   /home/spack/spack/share/spack/modules/linux-ubuntu18.04-x86_64/gcc-8.4.0-gcc-7.5.0-uobbegc:
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
whatis("The GNU Compiler Collection includes front ends for C, C++, Objective-C, Fortran, Ada, and Go, as well as libraries for these languages.")
prepend_path("PATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin")
prepend_path("MANPATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/share/man")
prepend_path("CMAKE_PREFIX_PATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/.")
setenv("CC","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/gcc")
setenv("CXX","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/g++")
setenv("FC","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/gfortran")
setenv("F77","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/gfortran")
help([[The GNU Compiler Collection includes front ends for C, C++, Objective-C,
Fortran, Ada, and Go, as well as libraries for these languages.
]])

Prevent some module files from being generated

Another common request at many sites is to avoid exposing software that is only needed as an intermediate step when building a newer stack. Let’s try to prevent the generation of module files for anything that is compiled with gcc@7.5.0 (the OS provided compiler).

To do this you should add the exclude keyword to ${SPACK_ROOT}/etc/spack/modules.yaml:

modules:
  default:
    tcl:
      exclude:
      -  '%gcc@7.5.0'
      all:
        filter:
          exclude_env_vars:
          - "C_INCLUDE_PATH"
          - "CPLUS_INCLUDE_PATH"
          - "LIBRARY_PATH"

and regenerate the module files. This time we’ll pass the option --delete-tree so that Spack will delete the existing module tree and regenerate a new one, instead of overwriting the files in the existing directory.

$ spack module tcl refresh --delete-tree -y
==> Regenerating tcl module files
$ module avail

---------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/modules/linux-ubuntu18.04-x86_64 -----------------------------------------------------------------------------------------------
   autoconf-2.69-gcc-8.4.0-3ur6efa			   krb5-1.19.3-gcc-8.4.0-lbq4bnu	     mpich-4.0.2-gcc-8.4.0-dehzhtf		 perl-5.36.0-gcc-8.4.0-oxh2v73		py-setuptools-59.4.0-gcc-8.4.0-uh4z6vn
   automake-1.16.5-gcc-8.4.0-ltwno6t			   libbsd-0.11.5-gcc-8.4.0-p666k37	     ncurses-6.3-gcc-8.4.0-pm3k5t4		 pigz-2.7-gcc-8.4.0-x4i7we6		py-wheel-0.37.1-gcc-8.4.0-htlk6hg
   berkeley-db-18.1.40-gcc-8.4.0-gfnsus4		   libedit-3.1-20210216-gcc-8.4.0-zl6rdlr    netlib-lapack-3.10.1-gcc-8.4.0-d75mbpb	 pkgconf-1.8.0-gcc-8.4.0-db44f6t	python-3.10.8-gcc-8.4.0-4ots64k
   bison-3.8.2-gcc-8.4.0-mne2r6i			   libevent-2.1.12-gcc-8.4.0-zlkggwb	     netlib-scalapack-2.2.0-gcc-8.4.0-iuphysy	 pmix-4.1.2-gcc-8.4.0-alwqqyv		readline-8.1.2-gcc-8.4.0-vrvkcpj
   bzip2-1.0.8-gcc-8.4.0-h2cyuuc			   libfabric-1.16.1-gcc-8.4.0-zmoqcfm	     netlib-scalapack-2.2.0-gcc-8.4.0-nuulbgb	 py-beniget-0.4.1-gcc-8.4.0-6fg7x2e	sqlite-3.39.4-gcc-8.4.0-e373hd3
   ca-certificates-mozilla-2022-10-11-gcc-8.4.0-tug2vtk	   libffi-3.4.2-gcc-8.4.0-pfw5zcj	     netlib-scalapack-2.2.0-gcc-8.4.0-vae5gpb	 py-cython-0.29.32-gcc-8.4.0-g5hd5bt	tar-1.34-gcc-8.4.0-vkidral
   cmake-3.24.3-gcc-8.4.0-3oinxkn			   libiconv-1.16-gcc-8.4.0-faxyug5	     netlib-scalapack-2.2.0-gcc-8.4.0-xqcf6y4	 py-gast-0.5.3-gcc-8.4.0-hthzien	util-linux-uuid-2.38.1-gcc-8.4.0-72abeix
   diffutils-3.8-gcc-8.4.0-42nykx7			   libmd-1.0.4-gcc-8.4.0-mbjxxpr	     ninja-1.11.1-gcc-8.4.0-ctiucvr		 py-numpy-1.23.4-gcc-8.4.0-v7eeehl	util-macros-1.19.3-gcc-8.4.0-caquoxb
   expat-2.4.8-gcc-8.4.0-ecxz4tu			   libpciaccess-0.16-gcc-8.4.0-ygwuejw	     numactl-2.0.14-gcc-8.4.0-qo6lo2m		 py-pip-22.2.2-gcc-8.4.0-gdv6477	xz-5.2.7-gcc-8.4.0-yalo3gm
   findutils-4.9.0-gcc-8.4.0-ye45pox			   libsigsegv-2.13-gcc-8.4.0-hzetpcu	     openblas-0.3.21-gcc-8.4.0-62oqts5		 py-ply-3.11-gcc-8.4.0-i3li6qu		yaksa-0.2-gcc-8.4.0-ohap5mv
   gdbm-1.23-gcc-8.4.0-6dpdzlt				   libtool-2.4.7-gcc-8.4.0-uejcu2m	     openmpi-4.1.4-gcc-8.4.0-cnq37ia		 py-pybind11-2.8.1-gcc-8.4.0-pzlkf5u	zlib-1.2.13-gcc-8.4.0-qaq2asl
   gettext-0.21.1-gcc-8.4.0-lxoekir			   libxml2-2.10.1-gcc-8.4.0-rsueryu	     openssh-9.1p1-gcc-8.4.0-bu2y2rn		 py-pythran-0.11.0-gcc-8.4.0-t3pvyne	zstd-1.5.2-gcc-8.4.0-2b73tir
   hwloc-2.8.0-gcc-8.4.0-76vxdwi			   m4-1.4.19-gcc-8.4.0-64hyzlr		     openssl-1.1.1s-gcc-8.4.0-4h2attb		 py-scipy-1.8.1-gcc-8.4.0-oliuwzs

If the avail list is too long consider trying:

"module --default avail" or "ml -d av" to just list the default modules.
"module overview" or "ml ov" to display the number of modules for each name.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".

if you look closely you’ll see though that we went too far in excluding modules: the module for gcc@8.4.0 disappeared as it was bootstrapped with gcc@7.5.0. To specify exceptions to the exclude rules you can use include:

modules:
  default:
    tcl:
      include:
      -  gcc
      exclude:
      -  '%gcc@7.5.0'
      all:
        filter:
          exclude_env_vars:
          - "C_INCLUDE_PATH"
          - "CPLUS_INCLUDE_PATH"
          - "LIBRARY_PATH"

include rules always have precedence over exclude rules. If you regenerate the modules again:

$ spack module tcl refresh -y
==> Regenerating tcl module files

you’ll see that now the module for gcc@8.4.0 has reappeared:

$ module avail gcc-8.4.0-gcc-7.5.0-uobbegc

---------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/modules/linux-ubuntu18.04-x86_64 -----------------------------------------------------------------------------------------------
   gcc-8.4.0-gcc-7.5.0-uobbegc

If the avail list is too long consider trying:

"module --default avail" or "ml -d av" to just list the default modules.
"module overview" or "ml ov" to display the number of modules for each name.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".

An additional feature that you can leverage to unclutter the environment is to skip the generation of module files for implicitly installed packages. In this case you only need to add the following line:

modules:
  default:
    tcl:
      exclude_implicits: true
      include:
      -  gcc
      exclude:
      -  '%gcc@7.5.0'
      all:
        filter:
          exclude_env_vars:
          - "C_INCLUDE_PATH"
          - "CPLUS_INCLUDE_PATH"
          - "LIBRARY_PATH"

to modules.yaml and regenerate the module file tree as above.

Change module file naming

The next step in making module files more user-friendly is to improve their naming scheme. To reduce the length of the hash or remove it altogether you can use the hash_length keyword in the configuration file:

modules:
  default:
    tcl:
      hash_length: 0
      include:
      -  gcc
      exclude:
      -  '%gcc@7.5.0'
      all:
        filter:
          exclude_env_vars:
          - "C_INCLUDE_PATH"
          - "CPLUS_INCLUDE_PATH"
          - "LIBRARY_PATH"

If you try to regenerate the module files now you will get an error:

$ spack module tcl refresh --delete-tree -y
==> Error: Name clashes detected in module files:

file: /home/spack/spack/share/spack/modules/linux-ubuntu18.04-x86_64/netlib-scalapack-2.2.0-gcc-8.4.0
spec: netlib-scalapack@2.2.0%gcc@8.4.0~ipo~pic+shared build_system=cmake build_type=Release patches=072b006,1c9ce5f arch=linux-ubuntu18.04-x86_64
spec: netlib-scalapack@2.2.0%gcc@8.4.0~ipo~pic+shared build_system=cmake build_type=Release patches=072b006,1c9ce5f arch=linux-ubuntu18.04-x86_64
spec: netlib-scalapack@2.2.0%gcc@8.4.0~ipo~pic+shared build_system=cmake build_type=Release patches=072b006,1c9ce5f arch=linux-ubuntu18.04-x86_64
spec: netlib-scalapack@2.2.0%gcc@8.4.0~ipo~pic+shared build_system=cmake build_type=Release patches=072b006,1c9ce5f arch=linux-ubuntu18.04-x86_64

==> Error: Operation aborted

Note

We try to check for errors up front!

In Spack we check for errors upfront whenever possible, so don’t worry about your module files: as a name clash was detected nothing has been changed on disk.

The problem here is that without the hashes the four different flavors of netlib-scalapack map to the same module file name. We can change how the names are formatted to differentiate them:

modules:
  default:
    tcl:
      hash_length: 0
      include:
      -  gcc
      exclude:
      -  '%gcc@7.5.0'
      all:
        conflict:
        - '{name}'
        filter:
          exclude_env_vars:
          - "C_INCLUDE_PATH"
          - "CPLUS_INCLUDE_PATH"
          - "LIBRARY_PATH"
      projections:
        all:               '{name}/{version}-{compiler.name}-{compiler.version}'
        netlib-scalapack:  '{name}/{version}-{compiler.name}-{compiler.version}-{^lapack.name}-{^mpi.name}'
        ^python^lapack:    '{name}/{version}-{compiler.name}-{compiler.version}-{^lapack.name}'

As you can see it is possible to specify rules that apply only to a restricted set of packages using anonymous specs like ^mpi^lapack. Here we declare a conflict between any two modules with the same name, so they cannot be loaded together. We also format the names of modules according to compiler, compiler version, and MPI version using the spec format syntax. This allows us to match specs by their dependencies, and format them based on their DAGs.

$ spack module tcl refresh --delete-tree -y
==> Regenerating tcl module files
$ module avail

---------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/modules/linux-ubuntu18.04-x86_64 -----------------------------------------------------------------------------------------------
   autoconf/2.69-gcc-8.4.0			   hwloc/2.8.0-gcc-8.4.0	     m4/1.4.19-gcc-8.4.0					   openssl/1.1.1s-gcc-8.4.0		   py-scipy/1.8.1-gcc-8.4.0-openblas
   automake/1.16.5-gcc-8.4.0			   krb5/1.19.3-gcc-8.4.0	     mpich/4.0.2-gcc-8.4.0					   perl/5.36.0-gcc-8.4.0		   py-setuptools/59.4.0-gcc-8.4.0
   berkeley-db/18.1.40-gcc-8.4.0		   libbsd/0.11.5-gcc-8.4.0	     ncurses/6.3-gcc-8.4.0					   pigz/2.7-gcc-8.4.0			   py-wheel/0.37.1-gcc-8.4.0
   bison/3.8.2-gcc-8.4.0			   libedit/3.1-20210216-gcc-8.4.0    netlib-lapack/3.10.1-gcc-8.4.0				   pkgconf/1.8.0-gcc-8.4.0		   python/3.10.8-gcc-8.4.0
   bzip2/1.0.8-gcc-8.4.0			   libevent/2.1.12-gcc-8.4.0	     netlib-scalapack/2.2.0-gcc-8.4.0-netlib-lapack-mpich	   pmix/4.1.2-gcc-8.4.0			   readline/8.1.2-gcc-8.4.0
   ca-certificates-mozilla/2022-10-11-gcc-8.4.0	   libfabric/1.16.1-gcc-8.4.0	     netlib-scalapack/2.2.0-gcc-8.4.0-netlib-lapack-openmpi	   py-beniget/0.4.1-gcc-8.4.0		   sqlite/3.39.4-gcc-8.4.0
   cmake/3.24.3-gcc-8.4.0			   libffi/3.4.2-gcc-8.4.0	     netlib-scalapack/2.2.0-gcc-8.4.0-openblas-mpich		   py-cython/0.29.32-gcc-8.4.0		   tar/1.34-gcc-8.4.0
   diffutils/3.8-gcc-8.4.0			   libiconv/1.16-gcc-8.4.0	     netlib-scalapack/2.2.0-gcc-8.4.0-openblas-openmpi	    (D)	   py-gast/0.5.3-gcc-8.4.0		   util-linux-uuid/2.38.1-gcc-8.4.0
   expat/2.4.8-gcc-8.4.0			   libmd/1.0.4-gcc-8.4.0	     ninja/1.11.1-gcc-8.4.0					   py-numpy/1.23.4-gcc-8.4.0-openblas	   util-macros/1.19.3-gcc-8.4.0
   findutils/4.9.0-gcc-8.4.0			   libpciaccess/0.16-gcc-8.4.0	     numactl/2.0.14-gcc-8.4.0					   py-pip/22.2.2-gcc-8.4.0		   xz/5.2.7-gcc-8.4.0
   gcc/8.4.0-gcc-7.5.0				   libsigsegv/2.13-gcc-8.4.0	     openblas/0.3.21-gcc-8.4.0					   py-ply/3.11-gcc-8.4.0		   yaksa/0.2-gcc-8.4.0
   gdbm/1.23-gcc-8.4.0				   libtool/2.4.7-gcc-8.4.0	     openmpi/4.1.4-gcc-8.4.0					   py-pybind11/2.8.1-gcc-8.4.0		   zlib/1.2.13-gcc-8.4.0
   gettext/0.21.1-gcc-8.4.0			   libxml2/2.10.1-gcc-8.4.0	     openssh/9.1p1-gcc-8.4.0					   py-pythran/0.11.0-gcc-8.4.0-openblas	   zstd/1.5.2-gcc-8.4.0

  Where:
   D:  Default Module

If the avail list is too long consider trying:

"module --default avail" or "ml -d av" to just list the default modules.
"module overview" or "ml ov" to display the number of modules for each name.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".

Note

The conflict directive is Tcl-specific and can’t be used in the lmod section of the configuration file.

Add custom environment modifications

At many sites it is customary to set an environment variable in a package’s module file that points to the folder in which the package is installed. You can achieve this with Spack by adding an environment directive to the configuration file:

modules:
  default:
    tcl:
      hash_length: 0
      naming_scheme: '{name}/{version}-{compiler.name}-{compiler.version}'
      include:
      -  gcc
      exclude:
      -  '%gcc@7.5.0'
      all:
        conflict:
        - '{name}'
        filter:
          exclude_env_vars:
          - "C_INCLUDE_PATH"
          - "CPLUS_INCLUDE_PATH"
          - "LIBRARY_PATH"
        environment:
          set:
            '{name}_ROOT': '{prefix}'
      projections:
        all:               '{name}/{version}-{compiler.name}-{compiler.version}'
        netlib-scalapack:  '{name}/{version}-{compiler.name}-{compiler.version}-{^lapack.name}-{^mpi.name}'
        ^python^lapack:    '{name}/{version}-{compiler.name}-{compiler.version}-{^lapack.name}'

Under the hood Spack uses the format() API to substitute tokens in either environment variable names or values. There are two caveats though:

  • The set of allowed tokens in variable names is restricted to name, version, compiler, compiler.name, compiler.version, architecture
  • Any token expanded in a variable name is made uppercase, but other than that case sensitivity is preserved

Regenerating the module files results in something like:

$ spack module tcl refresh -y
==> Regenerating tcl module files
$ module show gcc
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
   /home/spack/spack/share/spack/modules/linux-ubuntu18.04-x86_64/gcc/8.4.0-gcc-7.5.0:
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
whatis("The GNU Compiler Collection includes front ends for C, C++, Objective-C, Fortran, Ada, and Go, as well as libraries for these languages.")
conflict("gcc")
prepend_path("PATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin")
prepend_path("MANPATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/share/man")
prepend_path("CMAKE_PREFIX_PATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/.")
setenv("CC","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/gcc")
setenv("CXX","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/g++")
setenv("FC","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/gfortran")
setenv("F77","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e/bin/gfortran")
setenv("GCC_ROOT","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-7.5.0/gcc-8.4.0-uobbegc3e3qn7lktajfr53buov2vf72e")
help([[The GNU Compiler Collection includes front ends for C, C++, Objective-C,
Fortran, Ada, and Go, as well as libraries for these languages.
]])

As you can see, the gcc module has the environment variable GCC_ROOT set.

Sometimes it’s also useful to apply environment modifications selectively and target only certain packages. You can for instance apply modifications to the openmpi module as follows:

modules:
  default:
    tcl:
      hash_length: 0
      naming_scheme: '{name}/{version}-{compiler.name}-{compiler.version}'
      include:
      - gcc
      exclude:
      - '%gcc@7.5.0'
      all:
        conflict:
        - '{name}'
        filter:
          exclude_env_vars:
          - "C_INCLUDE_PATH"
          - "CPLUS_INCLUDE_PATH"
          - "LIBRARY_PATH"
        environment:
          set:
            '{name}_ROOT': '{prefix}'
      openmpi:
        environment:
          set:
            SLURM_MPI_TYPE: pmi2
            OMPI_MCA_btl_openib_warn_default_gid_prefix: '0'
      projections:
        all:               '{name}/{version}-{compiler.name}-{compiler.version}'
        netlib-scalapack:  '{name}/{version}-{compiler.name}-{compiler.version}-{^lapack.name}-{^mpi.name}'
        ^python^lapack:    '{name}/{version}-{compiler.name}-{compiler.version}-{^lapack.name}'

This time we will be more selective and regenerate only the openmpi module file:

$ spack module tcl refresh -y openmpi
==> Regenerating tcl module files
$ module show openmpi
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
   /home/spack/spack/share/spack/modules/linux-ubuntu18.04-x86_64/openmpi/4.1.4-gcc-8.4.0:
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
whatis("An open source Message Passing Interface implementation.")
conflict("openmpi")
prepend_path("PATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/openmpi-4.1.4-cnq37ia4lu75epxegwxb2f2p2i5jd7cq/bin")
prepend_path("MANPATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/openmpi-4.1.4-cnq37ia4lu75epxegwxb2f2p2i5jd7cq/share/man")
prepend_path("PKG_CONFIG_PATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/openmpi-4.1.4-cnq37ia4lu75epxegwxb2f2p2i5jd7cq/lib/pkgconfig")
prepend_path("CMAKE_PREFIX_PATH","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/openmpi-4.1.4-cnq37ia4lu75epxegwxb2f2p2i5jd7cq/.")
setenv("MPICC","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/openmpi-4.1.4-cnq37ia4lu75epxegwxb2f2p2i5jd7cq/bin/mpicc")
setenv("MPICXX","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/openmpi-4.1.4-cnq37ia4lu75epxegwxb2f2p2i5jd7cq/bin/mpic++")
setenv("MPIF77","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/openmpi-4.1.4-cnq37ia4lu75epxegwxb2f2p2i5jd7cq/bin/mpif77")
setenv("MPIF90","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/openmpi-4.1.4-cnq37ia4lu75epxegwxb2f2p2i5jd7cq/bin/mpif90")
setenv("OPENMPI_ROOT","/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/openmpi-4.1.4-cnq37ia4lu75epxegwxb2f2p2i5jd7cq")
setenv("SLURM_MPI_TYPE","pmi2")
setenv("OMPI_MCA_btl_openib_warn_default_git_prefix","0")
help([[An open source Message Passing Interface implementation. The Open MPI
Project is an open source Message Passing Interface implementation that
is developed and maintained by a consortium of academic, research, and
industry partners. Open MPI is therefore able to combine the expertise,
technologies, and resources from all across the High Performance
Computing community in order to build the best MPI library available.
Open MPI offers advantages for system and software vendors, application
developers and computer science researchers.
]])

Autoload dependencies

Spack can also generate module files that contain code to load the dependencies automatically. You can, for instance generate python modules that load their dependencies by adding the autoload directive and assigning it the value direct:

modules:
  default:
    tcl:
      verbose: True
      hash_length: 0
      naming_scheme: '{name}/{version}-{compiler.name}-{compiler.version}'
      include:
      - gcc
      exclude:
      - '%gcc@7.5.0'
      all:
        conflict:
        - '{name}'
        filter:
          exclude_env_vars:
          - "C_INCLUDE_PATH"
          - "CPLUS_INCLUDE_PATH"
          - "LIBRARY_PATH"
        environment:
          set:
            '{name}_ROOT': '{prefix}'
      gcc:
        environment:
          set:
            CC: gcc
            CXX: g++
            FC: gfortran
            F90: gfortran
            F77: gfortran
      openmpi:
        environment:
          set:
            SLURM_MPI_TYPE: pmi2
            OMPI_MCA_btl_openib_warn_default_gid_prefix: '0'
      projections:
        all:               '{name}/{version}-{compiler.name}-{compiler.version}'
        netlib-scalapack:  '{name}/{version}-{compiler.name}-{compiler.version}-{^lapack.name}-{^mpi.name}'
        ^python^lapack:    '{name}/{version}-{compiler.name}-{compiler.version}-{^lapack.name}'
      ^python:
        autoload:  direct

and regenerating the module files for every package that depends on python:

$ spack module tcl refresh -y ^python
==> Regenerating tcl module files

and will contain code to autoload all the dependencies:

$ module load py-scipy
Autoloading openblas/0.3.21-gcc-8.4.0
Autoloading py-numpy/1.23.4-gcc-8.4.0-openblas
Autoloading openblas/0.3.21-gcc-8.4.0
Autoloading py-setuptools/59.4.0-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading py-pybind11/2.8.1-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading py-pythran/0.11.0-gcc-8.4.0-openblas
Autoloading py-beniget/0.4.1-gcc-8.4.0
Autoloading py-gast/0.5.3-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading py-gast/0.5.3-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading py-numpy/1.23.4-gcc-8.4.0-openblas
Autoloading openblas/0.3.21-gcc-8.4.0
Autoloading py-setuptools/59.4.0-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading openblas/0.3.21-gcc-8.4.0
Autoloading py-setuptools/59.4.0-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading py-ply/3.11-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0
Autoloading python/3.10.8-gcc-8.4.0

In case messages are unwanted during the autoload procedure, it will be sufficient to omit the line setting verbose: True in the configuration file above.

Hierarchical Module Files

So far we worked with non-hierarchical module files, i.e. with module files that are all generated in the same root directory and don’t attempt to dynamically modify the MODULEPATH. This results in a flat module structure where all the software is visible at the same time:

$ module avail

---------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/modules/linux-ubuntu18.04-x86_64 -----------------------------------------------------------------------------------------------
   autoconf/2.69-gcc-8.4.0			   hwloc/2.8.0-gcc-8.4.0	     m4/1.4.19-gcc-8.4.0					   openssl/1.1.1s-gcc-8.4.0		   py-scipy/1.8.1-gcc-8.4.0-openblas
   automake/1.16.5-gcc-8.4.0			   krb5/1.19.3-gcc-8.4.0	     mpich/4.0.2-gcc-8.4.0					   perl/5.36.0-gcc-8.4.0		   py-setuptools/59.4.0-gcc-8.4.0
   berkeley-db/18.1.40-gcc-8.4.0		   libbsd/0.11.5-gcc-8.4.0	     ncurses/6.3-gcc-8.4.0					   pigz/2.7-gcc-8.4.0			   py-wheel/0.37.1-gcc-8.4.0
   bison/3.8.2-gcc-8.4.0			   libedit/3.1-20210216-gcc-8.4.0    netlib-lapack/3.10.1-gcc-8.4.0				   pkgconf/1.8.0-gcc-8.4.0		   python/3.10.8-gcc-8.4.0
   bzip2/1.0.8-gcc-8.4.0			   libevent/2.1.12-gcc-8.4.0	     netlib-scalapack/2.2.0-gcc-8.4.0-netlib-lapack-mpich	   pmix/4.1.2-gcc-8.4.0			   readline/8.1.2-gcc-8.4.0
   ca-certificates-mozilla/2022-10-11-gcc-8.4.0	   libfabric/1.16.1-gcc-8.4.0	     netlib-scalapack/2.2.0-gcc-8.4.0-netlib-lapack-openmpi	   py-beniget/0.4.1-gcc-8.4.0		   sqlite/3.39.4-gcc-8.4.0
   cmake/3.24.3-gcc-8.4.0			   libffi/3.4.2-gcc-8.4.0	     netlib-scalapack/2.2.0-gcc-8.4.0-openblas-mpich		   py-cython/0.29.32-gcc-8.4.0		   tar/1.34-gcc-8.4.0
   diffutils/3.8-gcc-8.4.0			   libiconv/1.16-gcc-8.4.0	     netlib-scalapack/2.2.0-gcc-8.4.0-openblas-openmpi	    (D)	   py-gast/0.5.3-gcc-8.4.0		   util-linux-uuid/2.38.1-gcc-8.4.0
   expat/2.4.8-gcc-8.4.0			   libmd/1.0.4-gcc-8.4.0	     ninja/1.11.1-gcc-8.4.0					   py-numpy/1.23.4-gcc-8.4.0-openblas	   util-macros/1.19.3-gcc-8.4.0
   findutils/4.9.0-gcc-8.4.0			   libpciaccess/0.16-gcc-8.4.0	     numactl/2.0.14-gcc-8.4.0					   py-pip/22.2.2-gcc-8.4.0		   xz/5.2.7-gcc-8.4.0
   gcc/8.4.0-gcc-7.5.0				   libsigsegv/2.13-gcc-8.4.0	     openblas/0.3.21-gcc-8.4.0					   py-ply/3.11-gcc-8.4.0		   yaksa/0.2-gcc-8.4.0
   gdbm/1.23-gcc-8.4.0				   libtool/2.4.7-gcc-8.4.0	     openmpi/4.1.4-gcc-8.4.0					   py-pybind11/2.8.1-gcc-8.4.0		   zlib/1.2.13-gcc-8.4.0
   gettext/0.21.1-gcc-8.4.0			   libxml2/2.10.1-gcc-8.4.0	     openssh/9.1p1-gcc-8.4.0					   py-pythran/0.11.0-gcc-8.4.0-openblas	   zstd/1.5.2-gcc-8.4.0

  Where:
   D:  Default Module

If the avail list is too long consider trying:

"module --default avail" or "ml -d av" to just list the default modules.
"module overview" or "ml ov" to display the number of modules for each name.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".

This layout is quite simple to deploy, but you can see from the above snippet that nothing prevents users from loading incompatible sets of modules:

$ module purge
$ module load netlib-lapack openblas
$ module list

Currently Loaded Modules:
  1) netlib-lapack/3.10.1-gcc-8.4.0   2) openblas/0.3.21-gcc-8.4.0

Even if conflicts directives are carefully placed in module files, they:

  • won’t enforce a consistent environment, but will just report an error
  • need constant updates, for instance as soon as a new compiler or MPI library is installed

Hierarchical module files try to overcome these shortcomings by showing at start-up only a restricted view of what is available on the system: more specifically only the software that has been installed with OS provided compilers. Among this software there will be other - usually more recent - compilers that, once loaded, will prepend new directories to MODULEPATH unlocking all the software that was compiled with them. This “unlocking” idea can then be extended arbitrarily to virtual dependencies, as we’ll see in the following section.

Core/Compiler/MPI

The most widely used hierarchy is the so called Core/Compiler/MPI where, on top of the compilers, different MPI libraries also unlock software linked to them. There are just a few steps needed to adapt the modules.yaml file we used previously:

  1. enable the lmod file generator
  2. change the tcl tag to lmod
  3. remove the tcl specific conflict directive
  4. declare which compilers are considered core_compilers
  5. remove the mpi related suffixes in projections (as they will be substituted by hierarchies)

After these modifications your configuration file should look like:

modules:
  default:
    enable::
      - lmod
    lmod:
      core_compilers:
      - 'gcc@7.5.0'
      hierarchy:
      - mpi
      hash_length: 0
      include:
      - gcc
      exclude:
      - '%gcc@7.5.0'
      all:
        filter:
          exclude_env_vars:
          - "C_INCLUDE_PATH"
          - "CPLUS_INCLUDE_PATH"
          - "LIBRARY_PATH"
        environment:
          set:
            '{name}_ROOT': '{prefix}'
      openmpi:
        environment:
          set:
            SLURM_MPI_TYPE: pmi2
            OMPI_MCA_btl_openib_warn_default_gid_prefix: '0'
      projections:
        all:          '{name}/{version}'
        ^lapack:      '{name}/{version}-{^lapack.name}'

Note

Double colon in configuration files
The double colon after enable is intentional and it serves the purpose of overriding the default list of enabled generators so that only lmod will be active (see Overriding entire sections for more details).

The directive core_compilers accepts a list of compilers. Everything built using these compilers will create a module in the Core part of the hierarchy, which is the entry point for hierarchical module files. It is common practice to put the OS provided compilers in the list and only build common utilities and other compilers with them.

If we now regenerate the module files:

$ spack module lmod refresh --delete-tree -y
==> Regenerating lmod module files

and update MODULEPATH to point to the Core:

$ module purge
$ module unuse $HOME/spack/share/spack/modules/linux-ubuntu18.04-x86_64
$ module use $HOME/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/Core

asking for the available modules will return:

$ module avail

--------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/Core ----------------------------------------------------------------------------------------------
   gcc/8.4.0

If the avail list is too long consider trying:

"module --default avail" or "ml -d av" to just list the default modules.
"module overview" or "ml ov" to display the number of modules for each name.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".

Unsurprisingly, the only visible module is gcc. Loading that we’ll unlock the Compiler part of the hierarchy:

$ module load gcc
$ module avail

------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/gcc/8.4.0 -------------------------------------------------------------------------------------------
   autoconf/2.69			 cmake/3.24.3	    hwloc/2.8.0		    libffi/3.4.2	 libxml2/2.10.1		 numactl/2.0.14	    pigz/2.7		 py-numpy/1.23.4-openblas      py-setuptools/59.4.0    util-linux-uuid/2.38.1
   automake/1.16.5			 diffutils/3.8	    krb5/1.19.3		    libiconv/1.16	 m4/1.4.19		 openblas/0.3.21    pkgconf/1.8.0	 py-pip/22.2.2		       py-wheel/0.37.1	       util-macros/1.19.3
   berkeley-db/18.1.40			 expat/2.4.8	    libbsd/0.11.5	    libmd/1.0.4		 mpich/4.0.2		 openmpi/4.1.4	    pmix/4.1.2		 py-ply/3.11		       python/3.10.8	       xz/5.2.7
   bison/3.8.2				 findutils/4.9.0    libedit/3.1-20210216    libpciaccess/0.16	 ncurses/6.3		 openssh/9.1p1	    py-beniget/0.4.1	 py-pybind11/2.8.1	       readline/8.1.2	       yaksa/0.2
   bzip2/1.0.8				 gdbm/1.23	    libevent/2.1.12	    libsigsegv/2.13	 netlib-lapack/3.10.1	 openssl/1.1.1s	    py-cython/0.29.32	 py-pythran/0.11.0-openblas    sqlite/3.39.4	       zlib/1.2.13
   ca-certificates-mozilla/2022-10-11	 gettext/0.21.1	    libfabric/1.16.1	    libtool/2.4.7	 ninja/1.11.1		 perl/5.36.0	    py-gast/0.5.3	 py-scipy/1.8.1-openblas       tar/1.34		       zstd/1.5.2

--------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/Core ----------------------------------------------------------------------------------------------
   gcc/8.4.0 (L)

  Where:
   L:  Module is loaded

If the avail list is too long consider trying:

"module --default avail" or "ml -d av" to just list the default modules.
"module overview" or "ml ov" to display the number of modules for each name.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".

The same holds true also for the MPI part, that you can enable by loading either mpich or openmpi. Let’s start by loading mpich:

$ module load mpich
$ module avail

--------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/mpich/4.0.2-dehzhtf/gcc/8.4.0 ---------------------------------------------------------------------------------
   netlib-scalapack/2.2.0-netlib-lapack	   netlib-scalapack/2.2.0-openblas (D)

------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/gcc/8.4.0 -------------------------------------------------------------------------------------------
   autoconf/2.69			 diffutils/3.8		libbsd/0.11.5		    libpciaccess/0.16 (L)    netlib-lapack/3.10.1    perl/5.36.0	  py-numpy/1.23.4-openblas	py-wheel/0.37.1		  xz/5.2.7    (L)
   automake/1.16.5			 expat/2.4.8		libedit/3.1-20210216	    libsigsegv/2.13	     ninja/1.11.1	     pigz/2.7		  py-pip/22.2.2			python/3.10.8		  yaksa/0.2   (L)
   berkeley-db/18.1.40			 findutils/4.9.0	libevent/2.1.12		    libtool/2.4.7	     numactl/2.0.14	     pkgconf/1.8.0	  py-ply/3.11			readline/8.1.2		  zlib/1.2.13 (L)
   bison/3.8.2				 gdbm/1.23		libfabric/1.16.1     (L)    libxml2/2.10.1    (L)    openblas/0.3.21	     pmix/4.1.2		  py-pybind11/2.8.1		sqlite/3.39.4		  zstd/1.5.2
   bzip2/1.0.8				 gettext/0.21.1		libffi/3.4.2		    m4/1.4.19		     openmpi/4.1.4	     py-beniget/0.4.1	  py-pythran/0.11.0-openblas	tar/1.34
   ca-certificates-mozilla/2022-10-11	 hwloc/2.8.0	 (L)	libiconv/1.16	     (L)    mpich/4.0.2	      (L)    openssh/9.1p1	     py-cython/0.29.32	  py-scipy/1.8.1-openblas	util-linux-uuid/2.38.1
   cmake/3.24.3				 krb5/1.19.3		libmd/1.0.4		    ncurses/6.3	      (L)    openssl/1.1.1s	     py-gast/0.5.3	  py-setuptools/59.4.0		util-macros/1.19.3

--------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/Core ----------------------------------------------------------------------------------------------
   gcc/8.4.0 (L)

  Where:
   D:  Default Module
   L:  Module is loaded

If the avail list is too long consider trying:

"module --default avail" or "ml -d av" to just list the default modules.
"module overview" or "ml ov" to display the number of modules for each name.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
$ module load openblas netlib-scalapack/2.2.0-openblas
$ module list

Currently Loaded Modules:
  1) gcc/8.4.0		 3) libiconv/1.16   5) zlib/1.2.13	7) ncurses/6.3	 9) libfabric/1.16.1  11) mpich/4.0.2	   13) netlib-scalapack/2.2.0-openblas
  2) libpciaccess/0.16	 4) xz/5.2.7	    6) libxml2/2.10.1	8) hwloc/2.8.0	10) yaksa/0.2	      12) openblas/0.3.21

At this point we can showcase the improved consistency that a hierarchical layout provides over a non-hierarchical one:

$ export LMOD_AUTO_SWAP=yes
$ module load openmpi

Lmod is automatically replacing "mpich/4.0.2" with "openmpi/4.1.4".


Due to MODULEPATH changes, the following have been reloaded:
  1) netlib-scalapack/2.2.0-openblas

Lmod took care of swapping the MPI provider for us, and it also substituted the netlib-scalapack module to conform to the change in the MPI. In this way we can’t accidentally pull-in two different MPI providers at the same time or load a module file for a package linked to openmpi when mpich is also loaded. Consistency for compilers and MPI is ensured by the tool.

Add LAPACK to the hierarchy

The hierarchy just shown is already a great improvement over non-hierarchical layouts, but it still has an asymmetry: LAPACK providers cover the same semantic role as MPI providers, but yet they are not part of the hierarchy.

To be more practical, this means that although we have gained an improved consistency in our environment when it comes to MPI, we still have the same problems as we had before for LAPACK implementations:

$ module list

Currently Loaded Modules:
  1) gcc/8.4.0		 4) libiconv/1.16   7) libxml2/2.10.1  10) numactl/2.0.14  13) zstd/1.5.2      16) openssl/1.1.1s	 19) openssh/9.1p1    22) openmpi/4.1.4
  2) openblas/0.3.21	 5) xz/5.2.7	    8) ncurses/6.3     11) bzip2/1.0.8	   14) tar/1.34	       17) krb5/1.19.3		 20) libevent/2.1.12  23) netlib-scalapack/2.2.0-openblas
  3) libpciaccess/0.16	 6) zlib/1.2.13	    9) hwloc/2.8.0     12) pigz/2.7	   15) gettext/0.21.1  18) libedit/3.1-20210216	 21) pmix/4.1.2



$ module avail

-------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/openmpi/4.1.4-cnq37ia/gcc/8.4.0 --------------------------------------------------------------------------------
   netlib-scalapack/2.2.0-netlib-lapack	   netlib-scalapack/2.2.0-openblas (L,D)

------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/gcc/8.4.0 -------------------------------------------------------------------------------------------
   autoconf/2.69			     diffutils/3.8	    libbsd/0.11.5		libpciaccess/0.16 (L)	 netlib-lapack/3.10.1	     perl/5.36.0	      py-numpy/1.23.4-openblas	    py-wheel/0.37.1		  xz/5.2.7    (L)
   automake/1.16.5			     expat/2.4.8	    libedit/3.1-20210216 (L)	libsigsegv/2.13		 ninja/1.11.1		     pigz/2.7	       (L)    py-pip/22.2.2		    python/3.10.8		  yaksa/0.2
   berkeley-db/18.1.40			     findutils/4.9.0	    libevent/2.1.12	 (L)	libtool/2.4.7		 numactl/2.0.14	      (L)    pkgconf/1.8.0	      py-ply/3.11		    readline/8.1.2		  zlib/1.2.13 (L)
   bison/3.8.2				     gdbm/1.23		    libfabric/1.16.1		libxml2/2.10.1	  (L)	 openblas/0.3.21      (L)    pmix/4.1.2	       (L)    py-pybind11/2.8.1		    sqlite/3.39.4		  zstd/1.5.2  (L)
   bzip2/1.0.8			      (L)    gettext/0.21.1  (L)    libffi/3.4.2		m4/1.4.19		 openmpi/4.1.4	      (L)    py-beniget/0.4.1	      py-pythran/0.11.0-openblas    tar/1.34		   (L)
   ca-certificates-mozilla/2022-10-11	     hwloc/2.8.0     (L)    libiconv/1.16	 (L)	mpich/4.0.2		 openssh/9.1p1	      (L)    py-cython/0.29.32	      py-scipy/1.8.1-openblas	    util-linux-uuid/2.38.1
   cmake/3.24.3				     krb5/1.19.3     (L)    libmd/1.0.4			ncurses/6.3	  (L)	 openssl/1.1.1s	      (L)    py-gast/0.5.3	      py-setuptools/59.4.0	    util-macros/1.19.3

--------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/Core ----------------------------------------------------------------------------------------------
   gcc/8.4.0 (L)

  Where:
   D:  Default Module
   L:  Module is loaded

If the avail list is too long consider trying:

"module --default avail" or "ml -d av" to just list the default modules.
"module overview" or "ml ov" to display the number of modules for each name.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".


$ module load netlib-scalapack/2.2.0-netlib-lapack

The following have been reloaded with a version change:
  1) netlib-scalapack/2.2.0-openblas => netlib-scalapack/2.2.0-netlib-lapack

$ module list

Currently Loaded Modules:
  1) gcc/8.4.0		 4) libiconv/1.16   7) libxml2/2.10.1  10) numactl/2.0.14  13) zstd/1.5.2      16) openssl/1.1.1s	 19) openssh/9.1p1    22) openmpi/4.1.4
  2) openblas/0.3.21	 5) xz/5.2.7	    8) ncurses/6.3     11) bzip2/1.0.8	   14) tar/1.34	       17) krb5/1.19.3		 20) libevent/2.1.12  23) netlib-lapack/3.10.1
  3) libpciaccess/0.16	 6) zlib/1.2.13	    9) hwloc/2.8.0     12) pigz/2.7	   15) gettext/0.21.1  18) libedit/3.1-20210216	 21) pmix/4.1.2	      24) netlib-scalapack/2.2.0-netlib-lapack

Hierarchies that are deeper than Core/Compiler/MPI are probably still considered “unusual” or “impractical” at many sites, mainly because module files are written manually and keeping track of the combinations among multiple providers quickly becomes quite involved.

For instance, having both MPI and LAPACK in the hierarchy means we must classify software into one of four categories:

  1. Software that doesn’t depend on MPI or LAPACK
  2. Software that depends only on MPI
  3. Software that depends only on LAPACK
  4. Software that depends on both

to decide when to show it to the user. The situation becomes more involved as the number of virtual dependencies in the hierarchy increases.

We can take advantage of the DAG that Spack maintains for the installed software and solve this combinatorial problem in a clean and automated way. In some sense Spack’s ability to manage this combinatorial complexity makes deeper hierarchies feasible.

Coming back to our example, let’s add lapack to the hierarchy and remove the remaining suffix projection for lapack:

modules:
  default:
    enable::
    - lmod
    lmod:
      core_compilers:
      - 'gcc@7.5.0'
      hierarchy:
      - mpi
      - lapack
      hash_length: 0
      include:
      - gcc
      exclude:
      - '%gcc@7.5.0'
      all:
        filter:
          exclude_env_vars:
          - "C_INCLUDE_PATH"
          - "CPLUS_INCLUDE_PATH"
          - "LIBRARY_PATH"
        environment:
          set:
            '{name}_ROOT': '{prefix}'
      openmpi:
        environment:
          set:
            SLURM_MPI_TYPE: pmi2
            OMPI_MCA_btl_openib_warn_default_gid_prefix: '0'
      projections:
        all:          '{name}/{version}'

After module files have been regenerated as usual:

$ module purge
$ spack module lmod refresh --delete-tree -y
==> Regenerating lmod module files

we can see that now we have additional components in the hierarchy:

$ module load gcc

Lmod is automatically replacing "openblas/0.3.21" with "netlib-lapack/3.10.1".


Inactive Modules:
  1) netlib-scalapack/2.2.0-netlib-lapack     2) openblas

$ module load openblas

Lmod is automatically replacing "netlib-lapack/3.10.1" with "openblas/0.3.21".


Activating Modules:
  1) openblas/0.3.21

$ module avail

-------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/openmpi/4.1.4-cnq37ia/openblas/0.3.21-62oqts5/gcc/8.4.0 --------------------------------------------------------------------
   netlib-scalapack/2.2.0

------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/openblas/0.3.21-62oqts5/gcc/8.4.0 -------------------------------------------------------------------------------
   py-numpy/1.23.4    py-pythran/0.11.0	   py-scipy/1.8.1

------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/gcc/8.4.0 -------------------------------------------------------------------------------------------
   autoconf/2.69			     diffutils/3.8	    libbsd/0.11.5		libpciaccess/0.16 (L)	 netlib-lapack/3.10.1	     perl/5.36.0	      py-pip/22.2.2	      sqlite/3.39.4		    zstd/1.5.2 (L)
   automake/1.16.5			     expat/2.4.8	    libedit/3.1-20210216 (L)	libsigsegv/2.13		 ninja/1.11.1		     pigz/2.7	       (L)    py-ply/3.11	      tar/1.34		     (L)
   berkeley-db/18.1.40			     findutils/4.9.0	    libevent/2.1.12	 (L)	libtool/2.4.7		 numactl/2.0.14	      (L)    pkgconf/1.8.0	      py-pybind11/2.8.1	      util-linux-uuid/2.38.1
   bison/3.8.2				     gdbm/1.23		    libfabric/1.16.1		libxml2/2.10.1	  (L)	 openblas/0.3.21      (L)    pmix/4.1.2	       (L)    py-setuptools/59.4.0    util-macros/1.19.3
   bzip2/1.0.8			      (L)    gettext/0.21.1  (L)    libffi/3.4.2		m4/1.4.19		 openmpi/4.1.4	      (L)    py-beniget/0.4.1	      py-wheel/0.37.1	      xz/5.2.7		     (L)
   ca-certificates-mozilla/2022-10-11	     hwloc/2.8.0     (L)    libiconv/1.16	 (L)	mpich/4.0.2		 openssh/9.1p1	      (L)    py-cython/0.29.32	      python/3.10.8	      yaksa/0.2
   cmake/3.24.3				     krb5/1.19.3     (L)    libmd/1.0.4			ncurses/6.3	  (L)	 openssl/1.1.1s	      (L)    py-gast/0.5.3	      readline/8.1.2	      zlib/1.2.13	     (L)

--------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/Core ----------------------------------------------------------------------------------------------
   gcc/8.4.0 (L)

  Where:
   L:  Module is loaded

If the avail list is too long consider trying:

"module --default avail" or "ml -d av" to just list the default modules.
"module overview" or "ml ov" to display the number of modules for each name.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".


$ module load openmpi
$ module avail

-------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/openmpi/4.1.4-cnq37ia/openblas/0.3.21-62oqts5/gcc/8.4.0 --------------------------------------------------------------------
   netlib-scalapack/2.2.0

------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/openblas/0.3.21-62oqts5/gcc/8.4.0 -------------------------------------------------------------------------------
   py-numpy/1.23.4    py-pythran/0.11.0	   py-scipy/1.8.1

------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/gcc/8.4.0 -------------------------------------------------------------------------------------------
   autoconf/2.69			     diffutils/3.8	    libbsd/0.11.5		libpciaccess/0.16 (L)	 netlib-lapack/3.10.1	     perl/5.36.0	      py-pip/22.2.2	      sqlite/3.39.4		    zstd/1.5.2 (L)
   automake/1.16.5			     expat/2.4.8	    libedit/3.1-20210216 (L)	libsigsegv/2.13		 ninja/1.11.1		     pigz/2.7	       (L)    py-ply/3.11	      tar/1.34		     (L)
   berkeley-db/18.1.40			     findutils/4.9.0	    libevent/2.1.12	 (L)	libtool/2.4.7		 numactl/2.0.14	      (L)    pkgconf/1.8.0	      py-pybind11/2.8.1	      util-linux-uuid/2.38.1
   bison/3.8.2				     gdbm/1.23		    libfabric/1.16.1		libxml2/2.10.1	  (L)	 openblas/0.3.21      (L)    pmix/4.1.2	       (L)    py-setuptools/59.4.0    util-macros/1.19.3
   bzip2/1.0.8			      (L)    gettext/0.21.1  (L)    libffi/3.4.2		m4/1.4.19		 openmpi/4.1.4	      (L)    py-beniget/0.4.1	      py-wheel/0.37.1	      xz/5.2.7		     (L)
   ca-certificates-mozilla/2022-10-11	     hwloc/2.8.0     (L)    libiconv/1.16	 (L)	mpich/4.0.2		 openssh/9.1p1	      (L)    py-cython/0.29.32	      python/3.10.8	      yaksa/0.2
   cmake/3.24.3				     krb5/1.19.3     (L)    libmd/1.0.4			ncurses/6.3	  (L)	 openssl/1.1.1s	      (L)    py-gast/0.5.3	      readline/8.1.2	      zlib/1.2.13	     (L)

--------------------------------------------------------------------------------------------- /home/spack/spack/share/spack/lmod/linux-ubuntu18.04-x86_64/Core ----------------------------------------------------------------------------------------------
   gcc/8.4.0 (L)

  Where:
   L:  Module is loaded

If the avail list is too long consider trying:

"module --default avail" or "ml -d av" to just list the default modules.
"module overview" or "ml ov" to display the number of modules for each name.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".

Both MPI and LAPACK providers will now benefit from the same safety features:

$ module load py-numpy netlib-scalapack

Activating Modules:
  1) netlib-scalapack/2.2.0

$ module load mpich

Lmod is automatically replacing "openmpi/4.1.4" with "mpich/4.0.2".


Due to MODULEPATH changes, the following have been reloaded:
  1) netlib-scalapack/2.2.0

$ module load netlib-lapack

Lmod is automatically replacing "openblas/0.3.21" with "netlib-lapack/3.10.1".


Inactive Modules:
  1) expat/2.4.8     2) gdbm/1.23     3) libbsd/0.11.5	   4) libffi/3.4.2     5) libmd/1.0.4	  6) py-numpy	  7) py-setuptools/59.4.0     8) python/3.10.8	   9) readline/8.1.2	10) sqlite/3.39.4    11) util-linux-uuid/2.38.1

Due to MODULEPATH changes, the following have been reloaded:
  1) netlib-scalapack/2.2.0

Because we only compiled py-numpy with openblas the module is made inactive when we switch the LAPACK provider. The user environment is now consistent by design!

Working with Templates

As briefly mentioned in the introduction, Spack uses Jinja2 to generate each individual module file. This means that you have all of its flexibility and power when it comes to customizing what gets generated!

Module file templates

The templates that Spack uses to generate module files are stored in the share/spack/templates/module directory within the Spack prefix, and they all share the same common structure. Usually, they start with a header that identifies the type of module being generated. In the case of hierarchical module files it’s:

-- -*- lua -*-
-- Module file created by spack (https://github.com/spack/spack) on {{ timestamp }}
--
-- {{ spec.short_spec }}
--

The statements within double curly brackets {{ ... }} denote expressions that will be evaluated and substituted at module generation time. The rest of the file is then divided into blocks that can be overridden or extended by users, if need be. Control structures , delimited by {% ... %}, are also permitted in the template language:

{% elif command_name == 'AppendPath' %}
append_path("{{ cmd.name }}", "{{ cmd.value }}", "{{ cmd.separator }}")
{% elif command_name == 'RemovePath' %}
remove_path("{{ cmd.name }}", "{{ cmd.value }}", "{{ cmd.separator }}")
{% elif command_name == 'SetEnv' %}
setenv("{{ cmd.name }}", "{{ cmd.value }}")
{% elif command_name == 'UnsetEnv' %}
unsetenv("{{ cmd.name }}")
{% endif %}
{% endfor %}
{% endblock %}

{% block footer %}
{# In case the module needs to be extended with custom LUA code #}
{% endblock %}

The locations where Spack looks for templates are specified in config.yaml:

    projections:
      all: "${ARCHITECTURE}/${COMPILERNAME}-${COMPILERVER}/${PACKAGE}-${VERSION}-${HASH}"
    # install_tree can include an optional padded length (int or boolean)
    # default is False (do not pad)

and can be extended by users to employ custom templates, as we’ll see next.

Extend the default templates

Let’s assume one of our software is protected by group membership: allowed users belong to the same linux group, and access is granted at group level. Wouldn’t it be nice if people that are not yet entitled to use it could receive a helpful message at module load time that tells them who to contact in your organization to be inserted in the group?

To automate the generation of module files with such site-specific behavior we’ll start by extending the list of locations where Spack looks for module files. Let’s create the file ${SPACK_ROOT}/etc/spack/config.yaml with the content:

config:
  template_dirs:
    - $HOME/.spack/templates

This tells Spack to also search another location when looking for template files. Next, we need to create our custom template extension in the folder listed above:

{% extends "modules/modulefile.lua" %}
{% block footer %}
-- Access is granted only to specific groups
if not isDir("{{ spec.prefix }}") then
    LmodError (
        "You don't have the necessary rights to run \"{{ spec.name }}\".\n\n",
        "\tPlease write an e-mail to 1234@foo.com if you need further information on how to get access to it.\n"
    )
end
{% endblock %}

Let’s name this file group-restricted.lua. The line:

{% extends "modules/modulefile.lua" %}

tells Jinja2 that we are reusing the standard template for hierarchical module files. The section:

{% block footer %}
-- Access is granted only to specific groups
if not isDir("{{ spec.prefix }}") then
    LmodError (
        "You don't have the necessary rights to run \"{{ spec.name }}\".\n\n",
        "\tPlease write an e-mail to 1234@foo.com if you need further information on how to get access to it.\n"
    )
end
{% endblock %}

overrides the footer block. Finally, we need to add a couple of lines in modules.yaml to tell Spack which specs need to use the new custom template. For the sake of illustration let’s assume it’s netlib-scalapack:

modules:
  enable::
    - lmod
  lmod:
    core_compilers:
      - 'gcc@7.5.0'
    hierarchy:
      - mpi
      - lapack
    hash_length: 0
    include:
      - gcc
    exclude:
      - '%gcc@7.5.0'
      - readline
    all:
      filter:
        exclude_env_vars:
          - "C_INCLUDE_PATH"
          - "CPLUS_INCLUDE_PATH"
          - "LIBRARY_PATH"
      environment:
        set:
          '{name}_ROOT': '{prefix}'
    openmpi:
      environment:
        set:
          SLURM_MPI_TYPE: pmi2
          OMPI_MCA_btl_openib_warn_default_gid_prefix: '0'
    netlib-scalapack:
      template: 'group-restricted.lua'

If we regenerate the module files one last time:

$ spack module lmod refresh -y netlib-scalapack
==> Regenerating lmod module files

we’ll find the following at the end of each netlib-scalapack module file:

-- Access is granted only to specific groups
if not isDir("/home/spack/spack/opt/spack/linux-ubuntu18.04-x86_64/gcc-8.4.0/netlib-scalapack-2.0.2-2p75lzqjbsnev7d2j2osgpkz7ib33oca") then
    LmodError (
        "You don't have the necessary rights to run \"netlib-scalapack\".\n\n",
        "\tPlease write an e-mail to 1234@foo.com if you need further information on how to get access to it.\n"
    )
end

and every user that doesn’t have access to the software will now be redirected to the right e-mail address where to ask for it!

Restore settings for future sections

For future sections of the tutorial, we will not use the gcc@8.4.0 compiler. Since it is currently the default compiler (our current defualt is the most recent version of gcc available), we will remove it now.

$ spack compiler rm gcc@8.4.0

This will ensure the rest of the tutorial goes smoothly for you.