Lmod modules — introduction and instructions

TIP: For the most robust listing of modules, please use the module search on our Portal https://portal.rc.fas.harvard.edu/apps/modules
or the module-query [name or partial name] command. These methods will yield much better results than commands like module spider or module avail.

About Modules

On the cluster, we want a variety of apps available, including different versions of the same app and apps that are incompatible. We accomplish this by using environment modules. When you first login to the cluster, you’re presented with a very basic software environment. You then make apps available to you or your jobs by loading the modules for them. The modules update shell environment variables so that the system can find and use the apps of your choice. Modules replace the need for separate setup scripts.
Our implementation of environment modules uses Lmod and the bash shell. That page has some excellent documentation for those wishing to learn more about Lmod. In addition to some new features, we’ve adopted a more systematic naming and versioning convention, and we’re more actively curating our app inventory. Below is a condensed version with more FASRC-specific information.

How to Use Modules

You can load one or more modules using the module load [module(s) name] command. Examples:
module load matlab/R2017a-fasrc02
module load gcc/7.1.0-fasrc01 openmpi/2.1.0-fasrc02 netcdf/4.5.0-fasrc01 
To see what modules you have loaded, run:
module list
To unload a module, run:
module unload [module name]
To unload all modules currently loaded, run:
module purge
To save all currently-loaded modules as a collection, run:
module save <collection-name>
To restore a previously-saved collection of modules, run:
module restore <collection-name>

Finding Modules

For the most robust listing of modules, please use:

• The module search on our Portal https://portal.rc.fas.harvard.edu/apps/modules
• The module-query [name or partial name] command (example: module-query matlab)

You may also see mention of module spider, however the methods above will yield much better results.
If you find there are modules you need that are not available, you may either install the software for yourself, or let us know if there is software that you believe will benefit many users by submitting a software install ticket.

Loading a Module May Reveal More Modules

For example, loading intel/17.0.4-fasrc01 will make available all the apps compiled with that version of the intel compiler suite. This is done for each compiler choice and for each MPI implementation choice.
For example, checking the available version of the library netcdf   using the module avail command returns one version.

[user@rclogin ~]$ module avail netcdf
------- /n/helmod/modulefiles/centos7/Core -------
netcdf/4.3.2-fasrc03

After loading the compiler module ( in this case intel/17.0.4-fasrc01, applications built with the intel compiler are made available and become the default. We can see in this case more versions of netcdf

[user@rclogin ~]$ module load intel/17.0.4-fasrc01
[user@rclogin ~]$ module avail netcdf
--------- /n/helmod/modulefiles/centos7/Comp/intel/17.0.4-fasrc01 ----------
netcdf/4.3.2-fasrc04    netcdf/4.5.0-fasrc02 (D)
--------- /n/helmod/modulefiles/centos7/Core -----------
netcdf/4.3.2-fasrc03

Bear in mind that the module avail command does not show all  the different modules you could possibly use, but only the ones that you could load in the current environment, given the modules already loaded. You should use module-query or the portal to find specific modules. module avail is used here to demonstrate how you can see the change in available modules when loading modules that unlock a dependency and make other modules available.

Module Naming and Versioning

You can load specific versions by supplying the full module name (example: module load matlab/R2017a-fasrc02) or let the module system automatically load the latest version (example: module load matlab). The default is determined either according to alphanumeric sorting or in some cases the version we have chosen to be the default latest version based on stability or commonality.
It is strongly recommended to load modules specifying name and specific version.  This way you are protected in case the default version changes.

Version Changes When Loading Dependencies.

If module A requires module B, and you already have some version of B loaded, A will usually consider the dependency satisfied, rather than force a specific different (often older) version of B to be loaded. This has the potential to cause issues if a specific version is required. Be sure to look at the module’s requirements before assuming this will work. Or, at the very least, test your script before trusting that it will work.

Additional Notes: Transitioning from CentOS6 to CentOS7

In May 2018 the compute nodes in the cluster were upgraded from CentOS6 to CentOS7.  Modules that used to be available in the CentOS6 environment might not be available in CentOS7.
Particularly if you have  module load statements in your bash configuration file .bashrc or in your slurm job scripts, for modules which are not available in the new environment,  you might see messages like this:
Lmod has detected the following error:  These module(s) exist but cannot be loaded as requested: some-modulename

What should you do in this case?

1.  Use the command module-query (or visit https://portal.rc.fas.harvard.edu/apps/modules) to find a suitable module for the new CentOS7 environment and use that version instead of the old version you used to use.  ** See example below.
2.  If the application you are looking for, previously available in CentOS6, is not yet available in CentOS7, you can request our help in installing the application by contacting our support: https://www.rc.fas.harvard.edu/kb/support/  However, we will likely be very busy with new requests for software immediately after the transition and new requests may take weeks to process.  So, in the meantime, we would recommend several other ways for you to use your software on the cluster (see items 3-5).
3.  The old CentOS6 modules may still work in CentOS7 and you can access them by first loading the centos6 module.  Once that is loaded, you can search the old modules with module-query --os=centos6 <modulename> or by visiting our portal (linked above).  Please keep in mind that we don’t guarantee that they would necessarily work in the new environment and we don’t support their use, and this should be considered a temporary workaround until a proper version of the application is deployed for the new operating system.  Also, you may need to load each CentOS6 module individually rather than serially in one command.
4.  As always, you can install software yourself on the cluster in locations where you have access (e.g. your home directory).  See our documentation here to get started with that process:  /kb/software-on-the cluster/installing-software-yourself/
5.  You can use Singularity which is new to the cluster as of CentOS7.  Singularity allows users to install software in containers that would otherwise require administrative (root) privileges to install.  We have documentation for that here:  /kb/software/singularity-on-the cluster/

** Example:
For example, suppose that in my job scripts I used to load for my calculations this particular version of netcdf
module load intel/17.0.2-fasrc01
module load impi/2017.2.174-fasrc01
module load netcdf/4.3.2-fasrc06
Which is a version of the netcdf library built with the Intel 17 compiler and the Intel implementation of MPI.
Using module-query I can search for an equivalent module in the new environment (note that –os=centos7 is actually the default when I run that command on CentOS7 )

[user@rclogin ~]$ module-query --os=centos7 netcdf/4.3.2
  netcdf
    Built for: centos7
...omitted output ...
    Versions:
            netcdf/4.3.2-fasrc05.................... MPI
            netcdf/4.3.2-fasrc04.................... Comp 
            netcdf/4.3.2-fasrc03.................... Core

Since I was using an MPI version of the netcdf I might be interested in the module netcdf/4.3.2-fasrc05 .
To get more information about that, including which versions of MPI supports and instructions on how to load it, I can use again module-query. As you can see that I have 4 options of that module, with various combinations of compilers and MPI implementations.

[user@rclogin ~]$ module-query --os=centos7 netcdf/4.3.2-fasrc05
  netcdf : netcdf/4.3.2-fasrc05
...omitted output...
    This module can be loaded as follows:
      module load gcc/7.1.0-fasrc01 openmpi/2.1.0-fasrc02 netcdf/4.3.2-fasrc05
      module load gcc/7.1.0-fasrc01 mvapich2/2.3b-fasrc02 netcdf/4.3.2-fasrc05
      module load intel/17.0.4-fasrc01 openmpi/2.1.0-fasrc02 netcdf/4.3.2-fasrc05
      module load intel/17.0.4-fasrc01 mvapich2/2.3b-fasrc02 netcdf/4.3.2-fasrc05

Most likely I would be okay in trying to use one of these versions, for example the version built with Intel17 and openmpi 2.1.0.  If I want to use that I can try the load statement
module load intel/17.0.4-fasrc01
module load openmpi/2.1.0-fasrc02
module load netcdf/4.3.2-fasrc05
Since I am adopting  a new version of a software, it is always a good idea to test jobs by submitting a small calculation that realistically mimics the real workflow  to make sure everything is working as expected, before submitting large scale jobs, or a large number of concurrent calculations. So I’ll try using that  in a couple of test jobs to make sure everything works. And if so I can resume my full scale work.
Otherwise, if for some reason I absolutely need to keep using Intel MPI, for example because of other dependencies, I will not find a module that fully satisfies my requirements.  What I could do in this case I  to load centos6  – after using module-query centos6  to get more information about it –  and temporarily try to use the old modules I was using before while I request  help from the RC support team to install the version of software  I need.
module load centos6/0.0.1-fasrc01 
module load intel/17.0.2-fasrc01
module load impi/2017.2.174-fasrc01
module load netcdf/4.3.2-fasrc06

TIP: If you do have your .bashrc or other at-login script print or echo output to stdout (standard out – that is, displayed back to your shell session) by default, this is likely to cause issues if you attempt to SFTP to the cluster. Many SFTP clients will fail at login when something prints back to stdout after you’ve authenticated. Removing whatever prints to stdout from your script will resolve this problem.