HPC/Module Setup
Introduction
Carbon uses the Environment Modules package to dynamically provision software. The package primarily modifies your $PATH and other environment variables.
To select packages for your use, place module load name commands near the end of your ~/.bashrc file.
The Shell
The user shell on Carbon is bash.
A note on tcsh for long-time Unix/Linux users
[t]csh used to be the only vendor-agnostic and widely available shell with decent command line features. Bash is now much better positioned in this area, and offers consistent programming on the command line and in scripts. Therefore, tcsh is now available only on request (to me, stern), if you absolutely, positively, insist, and know what you're doing. (There will be a quiz.)
There are good reasons not to use the C shell,
and classic wisdom states “csh programming considered harmful”.
Even though using [t]csh merely for interactive purposes may appear tolerable,
it is too tempting to set out from tweaking .cshrc into serious programming.
Don't do it. It is not supported. It's dead, Jim.
- Do not use
chshorchfn. Changes will be overwritten.
Shell Customizations
Place customizations in your ~/.bashrc file by using a text editor such as nano. A pristine copy is shown below, or can be found at /etc/skel/.bashrc
# ~/.bashrc
# User's bash customization, Carbon template; stern 2011-09-15.
# Merge global definitions -- do not edit.
if [ -f /etc/bashrc ]; then
. /etc/bashrc
fi
# Carbon customizations -- edit below.
export PATH=$HOME/bin:$PATH
#alias blah="foo -xyz"
#module load ...
- For instance, to add binaries from a user's own compilation of
somepackage, and load a couple of modules:
export PATH=$HOME/somepackage/bin:$HOME/bin:$PATH
# Load Carbon applications
module load name1 name2 …
module load name3/version
Test
To test the impact of any changes, temporarily run a new shell:
bash -l # lowercase letter L
# run other shell commands
...
# inspect nesting level, then return to the parent shell
echo $SHLVL
exit
- Make further corrections to ~/.bashrc as needed.
- You might get lost in multiple nested shell levels. To see the current nesting level, inspect the environment variable $SHLVL as shown above. A normal login shell runs at level 1, and the
exitcommand in such a shell will log you out.
Pick up newly added modules
When all looks good, either:
- simply restart your shell in place:
exec bash -l- Again, that's a lowercase letter "L".
- Alternatively, log out and back in, which is a bit more involved.
Caveats
- Among the various bash startup files .bashrc is the one relevant when invoked remotely, such as on MPI child nodes reached by sshd.
- In general, do not place a
"module load …"command in a PBS job script.- This will only work reliably for single-node jobs.
- It will generally fail for multi-node jobs (nodes > 1).
- Reason: The job script is only executed (by the
pbs_momdaemon on your behalf) on the first core on the first node of your request. The environment of this process will be cloned for the other cores on the first node, but not for cores on other nodes. How remote environments are configured depends on the MPI implementation. The variousmpirunormpiexecoffer flags to pass some or all environment variables to other MPI processes, but these flags are implementation-specific and may not work reliably.
- Reason: The job script is only executed (by the
- The most reliable and recommended way is as above, to place module commands in ~/.bashrc. This might preclude job-specific module sets for conflicting modules or tasks. I'm thinking about a proper solution for this. --stern
Modules – General documentation
$ module help … Usage: module [ switches ] [ subcommand ] [subcommand-args ] … Available SubCommands and Args: + load modulefile [modulefile ...] + unload modulefile [modulefile ...] + switch [modulefile1] modulefile2.] + list + avail [modulefile [modulefile ...]] + whatis [modulefile [modulefile ...]] + help [modulefile [modulefile ...]] + show modulefile [modulefile ..]
For full documentation, consult the manual page:
$ man module