|
1 | | -# Example for module files |
| 1 | +# Using modules to control the environment |
2 | 2 |
|
3 | | -The module system makes setting up different versions of software much easier to maintain. |
4 | | -Module files can be very simple, or very complex. |
5 | | -All they have to do though is to set the appropriate paths and variables for the execution. |
6 | | -I have used modified versions from CLAIX18 (the RWTH Aachen cluster), |
7 | | -which I have cleaned for this repository. |
| 3 | +## Introduction |
| 4 | + |
| 5 | +Running programs usually requires certain environment variables to be set to specific values. |
| 6 | +The script provided in this repository is one way to set up the environment for xtb. |
| 7 | +Another way is to use modules to set up these parameters, control dependencies, and possible clashes. |
| 8 | + |
| 9 | +With environment modules it is also possible to set up different versions of an executable alongside each other. |
| 10 | +Especially in scientific works it is important to be consistent with what versions you use throughout a project. |
| 11 | +When multiple users work on multiple projects for long periods of time, the need arises to manage different versions. |
| 12 | +Environment modules are a good way to maintain these versions. |
| 13 | + |
| 14 | +However, it should be pointed out, that with modules a wrapper script like runxtb is superfluous. |
| 15 | +Fortunately, the script provided within this repository has a few more features to offer. |
| 16 | +For these convenience features, the script comes with an interface to access environment modules. |
| 17 | + |
| 18 | +Unfortunately, not all environment module systems provide the capability necessary to operate within this script. |
| 19 | +Before runxtb v0.7.0 there were workarounds for module systems, that always used the exit code 0. |
| 20 | +Support for these system has been discontinued. |
| 21 | + |
| 22 | +For the developement of this feature, [Lmod](https://lmod.readthedocs.io/) was used. |
| 23 | +This choice was made as CLAIX18 (the RWTH Aachen University HPC Cluster) transitioned to this system. |
| 24 | +For more information, visit the documentation available |
| 25 | +[here](https://help.itc.rwth-aachen.de/service/rhr4fjjutttf/article/450d33cc19fd4e50b1dd07027e9b55bd/#user-content-toolchains). |
8 | 26 |
|
9 | 27 | *Disclaimer:* |
10 | | -I am no longer affiliated with RWTH Aachen, and I am not using the module system in my current setup. |
11 | | -Therefore the example files provided below are not tested in a working environment. |
12 | | -I have tried to incorporate some of the changes in the setup given in the xtb manual, |
13 | | -see [read the docs](https://xtb-docs.readthedocs.io/en/latest/contents.html). |
14 | | -Please also see my guide on [how to set up xtb for runxtb](set-up.md). |
15 | | -You may use the files provided below as a starting point for your own templates and |
16 | | -review them carefully before use. |
17 | | -Please note that this guide was outdated already in 2020 as you can roughly calculate that back from |
18 | | -the used versions. |
19 | | -Support for modules will change in upcoming versions. |
20 | | - |
21 | | -(Martin; 2024-01-07; wrapper version 0.5.0) |
22 | | - |
23 | | -## Root module |
24 | | - |
25 | | -The root module is the one doing all the work, defining the module and setting the environment. |
26 | | - |
27 | | -The variable `PROJECTHOME` needs to be adjusted to the home of where the software is. |
28 | | -If it is your own home directory, you can also use `$::env(HOME)` as an argument. |
29 | | - |
30 | | -The installation variable `XTBHOME` also has to be adjusted accordingly. |
31 | | -It currently assumes that the software is stored |
32 | | -in a directory `${PROJECTHOME}/local/$modulename/$modulename-$version`, |
33 | | -which could resolve to `/home/polyluxus/local/xtb/xtb-6.2.3` for the |
34 | | -most recent version of xtb. |
35 | | -The variable `version` will be set from the version module, see below. |
36 | | - |
37 | | - |
38 | | -``` |
39 | | -#%Module1.0###-*-tcl-*-######################################################### |
40 | | -## |
41 | | -## xtb modulefile |
42 | | -## https://www.chemie.uni-bonn.de/pctc/mulliken-center/software/xtb |
43 | | -### |
44 | | -
|
45 | | -# Naming the module |
46 | | -set modulename "xtb" |
47 | | -
|
48 | | -# Home directory of the installation |
49 | | -set PROJECTHOME "/home/polyluxus" |
50 | | -
|
51 | | -# Define local variable with path to installation software |
52 | | -# version will be set by referring module file |
53 | | -set XTBHOME "${PROJECTHOME}/local/$modulename/$modulename-$version" |
54 | | -
|
55 | | -# This is the help output, printed by "module help" |
56 | | -proc ModulesHelp { } { |
57 | | - # define the global variables version and modulename in this function |
58 | | - global version |
59 | | - global modulename |
60 | | - puts stderr "*** This module initialises the $modulename $version environment ***" |
61 | | - puts stderr " An extended tight-binding semi-empirical program package " |
62 | | - puts stderr " Please contact xtb@thch.uni-bonn.de for details. " |
63 | | - puts stderr " See also: https://github.com/grimme-lab/xtb " |
64 | | -} |
65 | | -
|
66 | | -# Short description (preferably 1 line) what the loaded software does, |
67 | | -# or what the module is good for. |
68 | | -# Printed by "module whatis": |
69 | | -module-whatis "$modulename - extended tight-binding semi-empirical program package" |
70 | | -
|
71 | | -# If module should be loaded, check for conflicts and print info |
72 | | -switch [module-info mode] { |
73 | | - load { |
74 | | - # Is this module already loaded? |
75 | | - set conflict "$modulename/$version" |
76 | | - if { [is-loaded $conflict]} { |
77 | | - puts stderr "$conflict already loaded, doing nothing." |
78 | | - return |
79 | | - } |
80 | | - # Is a different version already loaded? (This would check xtb6) |
81 | | - set conflict $modulename |
82 | | - if { [is-loaded $conflict]} { |
83 | | - puts stderr "$conflict already loaded; conflicts with $modulename/$version." |
84 | | - puts stderr "Try unloading $conflict first." |
85 | | - exit |
86 | | - } |
87 | | - # Check if the software is really installed, if not error and abort. |
88 | | - if { ![file isdirectory $XTBHOME] } { |
89 | | - puts stderr "$modulename is not installed on this machine." |
90 | | - exit |
91 | | - } |
92 | | - # Nothing failed, print a success message: |
93 | | - puts stderr "Loading $modulename $version" |
94 | | - } |
95 | | - unload { |
96 | | - puts stderr "Unloading $modulename $version" |
97 | | - } |
98 | | -} |
99 | | -
|
100 | | -# XTBHOME is the root directory of the loaded xtb version |
101 | | -setenv XTBHOME $XTBHOME |
102 | | -
|
103 | | -# Recommendations for loading: |
104 | | -prepend-path XTBPATH $::env(HOME) |
105 | | -prepend-path XTBPATH $XTBHOME |
106 | | -prepend-path XTBPATH ${XTBHOME}/share/xtb |
107 | | -
|
108 | | -# The following paths need to be set/adjusted for the 6.0 distributions |
109 | | -prepend-path PATH $XTBHOME/bin |
110 | | -# Old MANPATH (~ 6.0) |
111 | | -if { [file isdirectory $XTBHOME/man] } { |
112 | | - prepend-path MANPATH $XTBHOME/man |
113 | | -} |
114 | | -# New MANPATH (~ 6.2.x) |
115 | | -if { [file isdirectory $XTBHOME/share/man] } { |
116 | | - prepend-path MANPATH $XTBHOME/share/man |
117 | | -} |
118 | | -# Include libraries |
119 | | -if { [file isdirectory $XTBHOME/lib] } { |
120 | | - prepend-path LD_LIBRARY_PATH $XTBHOME/lib |
121 | | -} |
122 | | -# Include the scripts directory, if it exists (very old, or very custom) |
123 | | -if { [file isdirectory $XTBHOME/scripts] } { |
124 | | - prepend-path PATH $XTBHOME/scripts |
125 | | -} |
126 | | -# Include the python directory, if it exists |
127 | | -if { [file isdirectory $XTBHOME/python] } { |
128 | | - prepend-path PATH $XTBHOME/python |
129 | | - prepend-path PYTHONPATH $XTBHOME/python |
130 | | -} |
131 | | -``` |
132 | | - |
133 | | -## Version module |
134 | | - |
135 | | -The version module is only necessary to set the `version` variable, so that |
136 | | -the root module will find the correct software path. |
137 | | - |
138 | | -The variable `module_base_path` needs to be adjusted to point to |
139 | | -the directory of the root module, the filename in the last line |
140 | | -also needs to be adjusted to point to the root module, which is defined above. |
141 | | - |
142 | | -``` |
143 | | -#%Module1.0###-*-tcl-*-######################################################### |
144 | | -## |
145 | | -## XTB modulefile |
146 | | -## |
147 | | -
|
148 | | -# For the local install (modify this to the correct path) |
149 | | -set module_base_path "/home/polyluxus/modules/source" |
150 | | -
|
151 | | -# Needs to be adjusted for what is to be loaded |
152 | | -set MAJORVERSION "6" |
153 | | -set MINORVERSION "2" |
154 | | -set REVISION "3" |
155 | | -
|
156 | | -# Will be read by the source module file |
157 | | -set version "$MAJORVERSION.$MINORVERSION.$REVISION" |
158 | | -
|
159 | | -# Load the source module file (needs to be adjusted to the name used for the root module above) |
160 | | -source "$module_base_path/xtb/xtb" |
161 | | -``` |
162 | | - |
163 | | -If no version control is wanted, one module with hard-coded paths should also do the trick. |
164 | | - |
165 | | -The version module should be placed in a directory which is found in the module path environment variable, |
166 | | -it could be, using the example above: `/home/polyluxus/modules/load/xtb/xtb_v6.2.3`. |
| 28 | +I am no longer affiliated with RWTH Aachen, and I am not testing the feature in a productive manner. |
| 29 | +I will try to support the feature in the way it is outlined in this guide. |
| 30 | +If you find anything not going as expected, |
| 31 | +please include detailed descriptions when submitting a bug report to the |
| 32 | +[GitHub issue tracker](https://github.com/polyluxus/runxtb.bash/issues). |
| 33 | + |
| 34 | +You'll find additional notes for the use of modules on CLAIX18 at the end of this document. |
| 35 | + |
| 36 | +You can test what is expected of the `module` command with the provided script in the configure directory of this repository. |
| 37 | + |
| 38 | +## Installation of Lmod on Ubuntu 22.04 |
| 39 | + |
| 40 | +As this is not a comprehensive guide, please see the documentation of Lmod to set it up properly. |
| 41 | + |
| 42 | +On my laptop it was as easy as installing Lmod as a package. |
| 43 | +As a user with root priveleges, you can simply install it with the `apt` packet manager: |
| 44 | +``` |
| 45 | +apt install lmod |
| 46 | +``` |
| 47 | + |
| 48 | +Now you need to make sure that files from the `/etc/profile.d/` directory are sourced. |
| 49 | +In many cases the default `/etc/profile` will take care of this. |
| 50 | +Sometimes you might want to adapt the `/etc/bash.bashrc` file, too. |
| 51 | + |
| 52 | +If this step is completed, you may test the installation with the script provided with this repository. |
| 53 | + |
| 54 | +## Setting up the modules |
| 55 | + |
| 56 | +This guide assumes pretty much everything written in the [set-up guide](./set-up.md). |
| 57 | + |
| 58 | +It should come as no surprise that running Lmod requires a properly set up environment, too. |
| 59 | +If you'll set software up system-wide, you may want to place your module files in the default location: |
| 60 | +`/usr/share/lmod/lmod/modulefiles`. |
| 61 | + |
| 62 | +In other cases, where you are running software in user spaces, you may want to extend the module search path in your `~/.bashrc` |
| 63 | +with the following line: |
| 64 | +``` |
| 65 | +export MODULEPATH="/home/martin/local/modulefiles/:$MODULEPATH" |
| 66 | +``` |
| 67 | +Please adjust according to your system. |
| 68 | + |
| 69 | +### The xtb module |
| 70 | + |
| 71 | +Create the file `/home/martin/local/modulefiles/xtb/6.6.1.lua` with this content: |
| 72 | +``` |
| 73 | +help([[ |
| 74 | +Description: |
| 75 | + xtb - An extended tight-binding semi-empirical program package. |
| 76 | +Homepage: |
| 77 | +https://xtb-docs.readthedocs.io |
| 78 | +]]) |
| 79 | +
|
| 80 | +whatis("Description: xtb - An extended tight-binding semi-empirical program package. ") |
| 81 | +whatis("Homepage: https://xtb-docs.readthedocs.io") |
| 82 | +whatis("URL: https://xtb-docs.readthedocs.io") |
| 83 | +conflict("xtb") |
| 84 | +
|
| 85 | +prepend_path("LD_LIBRARY_PATH","/home/martin/local/xtb/xtb-6.6.1") |
| 86 | +prepend_path("LIBRARY_PATH","/home/martin/local/xtb/xtb-6.6.1/lib") |
| 87 | +prepend_path("PATH","/home/martin/local/xtb/xtb-6.6.1/bin") |
| 88 | +prepend_path("PKG_CONFIG_PATH","/home/martin/local/xtb/xtb-6.6.1/lib/pkgconfig") |
| 89 | +prepend_path("XDG_DATA_DIRS","/home/martin/local/xtb/xtb-6.6.1/share") |
| 90 | +setenv("XTBHOME","/home/martin/local/xtb/xtb-6.6.1") |
| 91 | +setenv("XTBPATH","/home/martin/local/xtb/xtb-6.6.1") |
| 92 | +``` |
| 93 | + |
| 94 | +### The crest module |
| 95 | +Create the file `/home/martin/local/modulefiles/crest/2.12.lua` with this content: |
| 96 | +``` |
| 97 | +help([[ |
| 98 | +Description: |
| 99 | + CREST - conformer rotamer ensemble sampling tool |
| 100 | +Homepage: |
| 101 | + https://crest-lab.github.io/crest-docs/ |
| 102 | +]]) |
| 103 | +
|
| 104 | +whatis("Description: CREST - conformer rotamer ensemble sampling tool") |
| 105 | +whatis("Homepage: https://crest-lab.github.io/crest-docs/") |
| 106 | +whatis("URL: https://crest-lab.github.io/crest-docs/") |
| 107 | +conflict("crest") |
| 108 | +
|
| 109 | +load("xtb") |
| 110 | +``` |
| 111 | +For this to work, crest needs to be placed alongside xtb. |
| 112 | +If you have followed the other guide, this will be the case. |
| 113 | +In other cases, you might need to adjust these files. |
| 114 | + |
| 115 | +## Using modules |
| 116 | + |
| 117 | +It is now as simple as running |
| 118 | +``` |
| 119 | +module load crest |
| 120 | +``` |
| 121 | +to load the correct installation environment. |
| 122 | + |
| 123 | +In the configuration file it is only necessary to include the module: |
| 124 | +``` |
| 125 | +use_modules="true" |
| 126 | +load_modules[0]="crest" |
| 127 | +``` |
| 128 | + |
| 129 | +# Additional notes CLAIX18 |
| 130 | + |
| 131 | +As of late 2023 the following modules need to be included in the configuration file, e.g. `~/.runxtbrc`: |
| 132 | +``` |
| 133 | +load_modules[0]="foss/2022a" |
| 134 | +load_modules[1]="xtb/6.5.1" |
| 135 | +load_modules[2]="CREST/2.12" |
| 136 | +``` |
| 137 | +Unfortuantely, those modules have dependencies which have a conflict with the `intel` toolchain, |
| 138 | +which is loaded by default. |
| 139 | +This is specifically the dependency on the `OpenMPI` module which is part of the `foss/2022a` toolchain. |
| 140 | +You should therefore also use the option to purge all modules: |
| 141 | +``` |
| 142 | +purge_modules="true" |
| 143 | +``` |
| 144 | +This will unload all modules and allows you to include only the necessary ones. |
167 | 145 |
|
| 146 | +(Martin; 2024-01-XX; wrapper version 0.6.0) |
0 commit comments