Using modules

From SciNet Users Documentation
Revision as of 13:10, 1 October 2018 by Ejspence (talk | contribs) (Saving combinations of modules)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

In the simplest case, the software you need will already be installed on Niagara. It will then be accessible in the form of a "module". If this is not the case, you can either ask SciNet staff to install it for you, or do it yourself.

Modules are configuration files that contain instructions for modifying your software environment. This modular architecture allows multiple versions of the same application to be installed without conflict. On Niagara, modules are managed with the Lmod tool developed at TACC. This tool replaces Environment Modules, which was used on the GPC, and is still used on BGQ. If you are familiar with this system you should not be too disoriented since "Lmod" was designed to be very similar to "Environment Modules". Refer to the #Lmod vs Environment Modules section for the main differences between the two systems.

A "modulefile" contains the information needed to make an application or library available in the user's login session. Typically a module file contains instructions that modify or initialize environment variables such as PATH and LD_LIBRARY_PATH in order to use different installed programs. Note that the simple fact of loading a module doesn't execute the software in question. To learn the name of the program binary or the syntax for its use, you should read the documentation for this software. By using the module command, you shouldn't normally need to know the exact location or path of the software or library but you can nevertheless see such details about the module by means of the command module show MODULENAME.

Loading software modules

The command module spider shows the available software.

For example:

nia-login07:~$ module spider
---------------------------------------------------
The following is a list of the modules currently av
---------------------------------------------------
  CCEnv: CCEnv

  NiaEnv: NiaEnv/2018a

  anaconda2: anaconda2/5.1.0

  anaconda3: anaconda3/5.1.0

  autotools: autotools/2017
    autoconf, automake, and libtool 

  boost: boost/1.66.0

  cfitsio: cfitsio/3.430

  cmake: cmake/3.10.2 cmake/3.10.3

  ...

The list contains the name of the software, followed by the available version. Some software have their own pages describing what they are and how to use them.

Module subcommands

Common module subcommands are:

  • module load <module-name>: load the default version of a particular software.
  • module load <module-name>/<module-version>: load a specific version of a particular software.
  • module purge: unload all currently loaded modules.
  • module spider (or module spider <module-name>): list available software packages.
  • module avail: list currently loadable software packages.
  • module list: list loaded modules.

Along with modifying common environment variables, such as PATH, and LD_LIBRARY_PATH, these modules also create a SCINET_MODULENAME_ROOT environment variable, which can be used to access commonly needed software directories, such as $SCINET_MODULENAME_ROOT/include and $SCINET_MODULENAME_ROOT/lib.

Finding experimental modules

When modules are first created, they are often put into an 'experimental' state until they are tested and declared to be worthy of use. If you are looking for an experimental module, use the command

  module --show_hidden spider <module-name>

This will show the experimental modules, which can be loaded in the usual way.

Software stacks: NiaEnv and CCEnv

On Niagara, there are really two software stacks:

  1. A Niagara software stack tuned and compiled for this machine. This stack is available by default, but if not, can be reloaded with

    module load NiaEnv
  2. The same software stack available on Compute Canada's General Purpose clusters Graham and Cedar, compiled (for now) for a previous generation of CPUs:

    module load CCEnv

    If you want the same default modules loaded as on Cedar and Graham, then afterwards also module load StdEnv.

Note: the *Env modules are sticky; remove them by --force. However, you will rarely need to do this.

To switch from NiaEnv to CCEnv do this:

module load CCEnv
module load StdEnv
module spider
... and so on ...

Saving combinations of modules

The module command can be used to save combinations of loaded modules. Once you have an ideal combination of modules loaded, that you wish to save, you can use the commmand

 module save MYMODULES

to save the combination of modules, where MYMODULES is the name you wish to give this combination. After you have saved your set of modules you can put the command

 module restore MYMODULES

in your job submission script to load this set of modules, or you can just type this command at the command line prompt.

To list all of your saved combinations of modules, use the command

 module savelist

To list which modules are saved in a particular module set, use the command

 module describe MYMODULES

Tips for loading software

  • We advise against loading modules in your .bashrc. This can lead to very confusing behaviour under certain circumstances. Our guidelines for .bashrc files can be found here.
  • The default .bashrc and .bash_profile files on Niagara can be found here.
  • Instead, load modules by hand when needed, or by sourcing a separate script.
  • Load run-specific modules inside your job submission script.
  • Short names give default versions; e.g. intelintel/2018.2. It is usually better to be explicit about the versions, for future reproducibility.
  • Handy abbreviations:
 ml → module list
 ml NAME → module load NAME  # if NAME is an existing module
 ml X → module X
  • Modules sometimes require other modules to be loaded first.

Solve these dependencies by using module spider.

Module spider

Oddly named, the module subcommand spider is the search-and-advice facility for modules.

Suppose one wanted to load the openmpi module. Upon trying to load the module, one may get the following message:

nia-login07:~$ module load openmpi
Lmod has detected the error:  These module(s) exist but cannot be loaded as requested: "openmpi"
   Try: "module spider openmpi" to see how to load the module(s).

So while that fails, following the advice that the command outputs, the next command would be:

nia-login07:~$ module spider openmpi
------------------------------------------------------------------------------------------------------
  openmpi:
------------------------------------------------------------------------------------------------------
     Versions:
        openmpi/2.1.3
        openmpi/3.0.1
        openmpi/3.1.0

------------------------------------------------------------------------------------------------------
  For detailed information about a specific "openmpi" module (including how to load the modules) use
  the module s full name.
  For example:

     $ module spider openmpi/3.1.0
------------------------------------------------------------------------------------------------------

So this gives just more detailed suggestions on using the spider command. Following the advice again, one would type:

nia-login07:~$ module spider openmpi/3.1.0
------------------------------------------------------------------------------------------------------
  openmpi: openmpi/3.1.0
------------------------------------------------------------------------------------------------------
    You will need to load all module(s) on any one of the lines below before the "openmpi/3.1.0"
    module is available to load.

      NiaEnv/2018a  gcc/7.3.0
      NiaEnv/2018a  intel/2018.2

These are concrete instructions on how to load this particular openmpi module. Following these leads to a successful loading of the module.

nia-login07:~$ module load NiaEnv/2018a  intel/2018.2   # note: NiaEnv is usually already loaded
nia-login07:~$ module load openmpi/3.1.0
nia-login07:~$ module list
Currently Loaded Modules:
  1) NiaEnv/2018a (S)   2) intel/2018.2   3) openmpi/3.1.0

  Where:
   S:  Module is Sticky, requires --force to unload or purge

Creating custom modules

I you desire to create your own modules to use on Niagara, perform the following steps:

  • Create a directory to hold you modules, say ~/mymodules.
  • Create and edit a module file, say ~/mymodules/foo/version (see for example /scinet/niagara/software/2018a/modules/base/gcc/7.3.0)
  • Run the command: module use ~/mymodules.
  • Load your module: module load foo/version.