.. index::
  Modules Tutorial
  Tutorial; Modules
  
.. _modules_tutorial:

=========================
Software Modules Tutorial
=========================

Modular software management allows a user to dynamically augment their
environment with software that has been installed on the system.

Each module file contains the required information to configure the environment
for that particular software package.  As a user, you are able to load module
files in your environment thereby making the software packages they describe
available for use.  More information about using the module command can be
obtained by typing :command:`module help` at the command line.


Command Summary
===============

Some commonly used module command options:

+----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| Command                          | Description                                                                                                                      |
+==================================+==================================================================================================================================+
| module list                      | Lists all currently loaded software packages                                                                                     |
+----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| module avail                     | Displays a list of all software packages that have been compiled for the system                                                  |
+----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| module load [software_package]   | Enables use of software_package by setting the appropriate environmental variables and adding the software binaries to your path |
+----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| module swap [pgk1] [pkg2]        | Unloads software pkg1 and loads pkg2                                                                                             |
+----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| module unload [software_package] | Removes software_package from your path and unsets any environmental variables set by that package                               |
+----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| module purge                     | Unloads all currently loaded software packages                                                                                   |
+----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| module help [software_package]   | Displays a description of software_package                                                                                       |
+----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+

Example
=======

The following briefly shows how to load, swap, and unload a software package (in this case, the molecular dynamics visualization
program VMD):

1. Find the name of the modulefile you wish to load by typing the command: 
   
   :command:`module avail`

.. code:: bash

   $ module avail

   R/2.14 
   bino/1.3
   gnuplot/4.4
   matlab/2012a
   pgi/2012
   vmd/1.9
   vmd/1.9.1(default)

2. Verify VMD is not currently loaded by typing the command:
   
   :command:`module list`

.. code:: bash

   $ module list

   Currently Loaded Modulefiles:
   1) R/2.14
   2) gnuplot/4.4


3. To load the default version of a software module, just specify the name of the software module, in this case, "vmd": 
   
   :command:`module load vmd`

4. Verify the module has been loaded with the command:
   
   :command:`module list`

.. code:: bash

   $ module list

   Currently Loaded Modulefiles:
   1) R/2.14
   2) gnuplot/4.4
   3) vmd/1.9.1


VMD has now been loaded and can be invoked from the command line.  If for some
reason we need to switch to version 1.9 of VMD, the :command:`module swap` command can
be used as follows:

1. Swap the default version of VMD (v1.9.1) for a different version (v1.9 for example):

   :command:`module swap vmd/1.9.1 vmd/1.9`

2. Verify the module has been swapped with:

   :command:`module list`

.. code:: bash

   $ module list

   Currently Loaded Modulefiles:
   1) R/2.14
   2) gnuplot/4.4
   3) vmd/1.9

Version 1.9 of VMD is now available on the command line instead of version
1.9.1.  To remove VMD from your environment, use the :command:`module unload` command:

1. Unload VMD software package with:

   :command:`module unload vmd`

2. Verify the module has been removed with:

   :command:`module list`

.. code:: bash

   $ module list

   Currently Loaded Modulefiles:
   1) R/2.14
   2) gnuplot/4.4


Further Assistance
==================

To request software packages, build variants, specific versions or any other software package related questions please contact
help@rcc.uchicago.edu