Skip to content

Commit 23a4f25

Browse files
polyluxuspolyluxus
authored
Release version v0.4.0 (#27)
* Fix: tilde expands in XTBPATH settings #26 - bin directory was not found when xtb_root was set with ~ * Update setting of the environment variables #25 - adjusted runxtb.sh to find the new paths - updated example rc file with more info - changed example modules to reflect new settings - updated configure script to make it more clearer * fix: check location of a directory - check whether a given file exists before trying to determine its absolute path; this will throw an error, before the remainder is executed. This will catch whether an entered path is actually a valid target. * fix: forward error to program exit - the exit status of get_bindir was not carried through, program did not exit - used same check for -B option - resolve found xtb_home to absolute location before writing it back * fix: configure script was missing a crucial expand tilde * fix: externalise path settings - function to set the paths so that it can be reused * Update documentation/guides and version * updated shellcheck parameters * meta: convert script for the markdown guides * corrected dates, formatting issues
1 parent 7932e24 commit 23a4f25

16 files changed

Lines changed: 584 additions & 224 deletions

‎README.md‎

Lines changed: 77 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,11 @@
33
This script provides a wrapper for the
44
extended tight-binding semi-empirical program package
55
[xtb](https://www.chemie.uni-bonn.de/pctc/mulliken-center/software/xtb/xtb)
6-
(version 6.0 or later)
7-
from Stefan Grimme's group at the University of Bonn
6+
(version 6.0 or later) from Stefan Grimme's group at the University of Bonn
87
(contact: xtb{at}thch.uni-bonn.de).
98
It is available via [GitHub](https://github.com/grimme-lab/xtb).
109

11-
It makes it unnecessary to set environment variables like
10+
The runxtb script makes it unnecessary to set environment variables like
1211
`OMP_NUM_THREADS`, `MKL_NUM_THREADS`, `OMP_STACKSIZE`, and `XTBPATH` globally,
1312
for example via the `.bashrc`.
1413
It also provides a mechanism to automatically trap the output
@@ -17,119 +16,95 @@ Additionally it can be used to create scripts to submit it to a queueing system.
1716

1817
## Installation
1918

20-
My personally preferred way to install it, is to clone the git repository
21-
(or download the source code) and configure the script.
22-
There is a configure script, which will prompt for the values
23-
with a short description.
24-
It will also try to recover values from a previous configuration
25-
in the same locations as outlined below.
26-
I recommend deleting old configuration files before updating to version > 0.2.0 of this script.
27-
28-
The wrapper script will first look for a file `.runxtbrc`,
29-
then for a file `runxtb.rc` (example included),
30-
in directories of the following order:
19+
A more elaborate guide on how to set up runxtb and xtb can be found in the
20+
guides directory: [guides/set-up.md](guides/set-up.md).
21+
22+
Briefly:
23+
24+
Obtain the latest version of xtb (and crest) from its
25+
[GitHub](https://github.com/grimme-lab/xtb/releases/latest) page.
26+
Pick a directory, where you would like to install these packages, e.g.
27+
a separate user (here: software) and the root directory `/home/software/chemsoft/xtb`.
28+
Unpack the downloaded xtb archives (this may create a new directory for the downloaded version,
29+
which should be set as `xtb_install_root` for runxtb).
30+
Copy crest to the `bin` directory within there.
31+
32+
Get the latest release of this repository from
33+
[GitHub](https://github.com/polyluxus/runxtb.bash/releases/latest).
34+
You may want to install it alongside the original binary, e.g. `/home/software/chemsoft/xtb`.
35+
Unpack the contents, and if necessary rename the directory.
36+
Alternatively you can of course also clone this repository.
37+
38+
Change to the runxtb directory. If you have a previous version of the script, it might be possible
39+
to import your settings. This is dependent on where your installed them.
40+
Now you can simply run the configure script, which will prompt for the values
41+
with a short description. If you are using a fresh installation, it will recover the
42+
default settings from the supplied `runxtb.rc`.
43+
At the end, you will be prompted for a location for the configuration file.
44+
Keep in mind that the wrapper script will first look for a file `.runxtbrc`,
45+
then for a file `runxtb.rc`, in directories of the following order:
3146
`scriptpath`, `/home/$USER`, `/home/$USER/.config`, and `$PWD`.
3247
If a `.runxtbrc` is found, it will skip `runxtb.rc`.
33-
The last file found will be used to set the (local) default parameters.
34-
This gives the possibility that every user may configure local settings,
35-
it also gives the possibilities to overwrite settings for one directory only.
36-
A summary of the settings to be used are given with the `-h` option.
48+
The location the script has predefined is `$PWD/runxtb.rc`, hence overwriting the
49+
provided example file, if it is launched from the installation directory of runxtb.
50+
Alternative options (e.g. `'scriptpath'/.runxtbrc`) are also given.
51+
After that, the configuration script will ask about creating symbolic links in `~/bin`.
52+
If you choose to do that, you can basically access the script from anywhere in your file system.
3753

38-
This directory is currently set up to find `runxtb.rc` and should test
39-
sucessfully without any changes.
54+
## Updating
4055

41-
There used to be a way to install thes script alongside with the executable of xtb,
42-
without further need to configure it, and place a symbolic link to it
43-
in a directory included in `PATH`, e.g. in `~/bin`.
44-
I have not tested this set-up for a long time, so I am not sure if the recent edits have broken it.
45-
(I would not recommend trying it.)
56+
If you decided to clone the repository, make sure to stash your changes,
57+
then pull the most recent version.
58+
If you have stashed any changes, you may want to apply them now.
59+
After running the configuration script, everything should be working with the new version.
4660

47-
## Updating
61+
You can of course also install a fresh version of runxtb.
62+
If you want to import older settings, copy your configuration file to the root of runxtb,
63+
or supply the absolute path to the settings when prompted by the configuration script.
4864

49-
Updating should be as easy as pulling the new version of the repository.
50-
If the script has been configured with `.runxtbrc`,
51-
a file that won't be overwritten via git,
52-
then these settings should be reviewed.
53-
When updating from a pre 0.2.0 version of this script,
54-
I reommend deleting old configuration files.
55-
While I try to avoid renaming internal options,
56-
it was necessary due to the changes in the XTB distribution.
57-
In any case, a new feature may require new settings;
58-
hence, this should also be checked.
65+
When downloading a new version, you should always reconfigure the script.
5966

6067
## Usage and options
6168

62-
Simply call the the script as if you would call the original program:
69+
A more detailed description of the usage and the options can be found in the
70+
guides directory: [guides/usage-opts.md](guides/usage-opts.md).
71+
72+
Brief overview:
73+
If linked (or found) from a directory along the `PATH` environment variable,
74+
you can call the runxtb wrapper script as if you would call the original program:
6375
```
6476
runxtb.sh [script options] <coord_file> [xtb options]
6577
```
66-
Any switches used will overwrite rc settings,
67-
which take precedence over the built-in defaults.
68-
For the same options/ modes, only the last one will have an effect,
78+
Any provided options to runxtb used will overwrite the corresponding rc settings,
79+
which in turn take precedence over the built-in defaults.
80+
If same options or modes are specified multiple times, only the last one will have an effect,
6981
e.g. specifying `-sSi` will run interactively (immediately).
7082

7183
The following script options are available:
7284

73-
* `-p <ARG>` Specify the number of processors to be used.
74-
This will set `OMP_NUM_THREADS=<ARG>` and `MKL_NUM_THREADS=<ARG>`.
75-
(Default defined within the script is `4`.)
76-
* `-m <ARG>` Secify the memory to be used (in megabyte).
77-
This will set `OMP_STACKSIZE=<ARG>`. (Default in the script is `1000`.)
78-
* `-o <ARG>` Trap the output (without errors) of `xtb` into a file called `<ARG>`.
79-
The default behaviour in non-interactive mode is to guess the filename:
80-
If the first argument given after the script options is a readable file,
81-
i.e. a `coord_file` or `coords.xyz`, the job- and output-name will be based on that.
82-
If the executed program is not `xtb` (`-C` switch), it will be based on that.
83-
As fallback it will be derived from the parent working directory.
84-
If necessary, the automatic generation of the file name can be also be triggered
85-
with `-o ''` (space is important), `-o0`, or `-o auto`.
86-
This may be useful to overwrite any previous settings.
87-
To send the output stream to standad output, e.g. the terminal, settings can be overwritten
88-
with `-c stdout`, or `-c -`.
89-
(configuration option `output_file='',0,auto|stdout,-`)
90-
* `-s` Write a submitscript instead of interactive execution (PBS is default).
91-
This resulting file needs to be sumbitted separately,
92-
which might be useful if review is necessary
93-
(configuration option `run_interactive=no`).
94-
* `-S` Write submitscript and directly submit it to the queue.
95-
This also requires setting a queueing system with `-Q` (see below).
96-
(configuration option `run_interactive=sub`).
97-
* `-Q <ARG>` Set a queueing system for which the submitscript should be prepared.
98-
Currently supported are `pbs-gen`, `slurm-gen`, `slurm-rwth`, `bsub-gen`, and `bsub-rwth`
99-
(configuration option `request_qsys=<ARG>`).
100-
The `*rwth` suffix will test a few more options and will set some constraints according to
101-
the recommendations of the RWTH IT centre.
102-
* `-P <ARG>` Account to project `<ARG>`, which will also (currently) trigger
103-
`-Q bsub-rwth` to be set. It will not trigger `-s`/`-S`.
104-
* `-M` Use preinstalled modules instead of paths.
105-
This option also needs a specified module or a list of modules,
106-
which can be set with `-l <ARG>`(see below) or in the rc
107-
(configuration option `use_modules=true`).
108-
* `-l <ARG>` Specify a module to be used. This will also invoke `-M`.
109-
The option may be specified multiple times to create a list (stored as an array).
110-
If `<ARG>` is `0`, the list will be deleted first.
111-
The modules (if more than one) need to be specified in the order they have to be loaded.
112-
This can also be set in the rc
113-
(configuration option `load_modules[<N>]=<ARG>` with `<N>` being the integer load order).
114-
* `-i` Execute in interactive mode. (Default without configuration.)
115-
This option is useful to overwrite rc settings
116-
(configuration option `run_interactive=yes`).
117-
* `-B <ARG>` Set the absolute path to the executable `xtb` to `<ARG>`.
118-
The name of the program needs to be included.
119-
In the configuration file these are separated.
120-
* `-C <ARG>` Set the name of the program directly.
121-
This may be useful to access a different executeable from the package,
122-
e.g. confscript (if installed, only 6.0), or crest (if installed, > 6.1).
123-
* `-q` Suppress any logging messages of the script.
124-
If specified twice, it will also suppress warnings,
125-
if specified more than twice, it will suppress also errors.
126-
* `-h` Prints a small help text and current configuration.
127-
* `-H` Retrieve the man page of xtb of the original distribution.
128-
* `-X` Retrieve the man page of xcontrol of the original distribution.
129-
130-
## Included files
131-
132-
The following files come with this script:
85+
| Option | Description
86+
|:------------|:------------
87+
| `-p <ARG>` | Specify the number of processors to be used. (Default: `4`)
88+
| `-m <ARG>` | Specify the memory to be used (in megabyte). (Default: `1000`)
89+
| `-w <ARG>` | Specify the wall time to be used (`[[HH]:[MM]:]SS`). (Default: `24:00:00`)
90+
| `-o <ARG>` | Trap the output (without errors) of `xtb` into a file called `<ARG>`. (Default: `auto`)
91+
| `-s` | Write a submit script instead of interactive execution (default: PBS). Resulting file needs to be submitted.
92+
| `-S` | Write submit script and directly submit it to the queue, requires setting a queueing system with `-Q`.
93+
| `-Q <ARG>` | Set a queueing system for which the submit script should be prepared, supported `pbs-gen`, `slurm-gen`, `bsub-gen`.
94+
| `-P <ARG>` | Account to project or account `<ARG>`, only slurm, LSF (bsub).
95+
| `-M` | Use pre-installed modules instead of path settings, also needs specified module(s).
96+
| `-l <ARG>` | Specify a module to be used, will also invoke `-M`, may be specified multiple times to create a list, `<ARG>=0` clears the list.
97+
| `-i` | Execute in interactive mode (default without configuration).
98+
| `-B <ARG>` | Set the absolute path to the executable `xtb` to `<ARG>`. The name of the program needs to be included.
99+
| `-C <ARG>` | Set the name of the program directly, e.g. to access a different executable like crest (if installed).
100+
| `-q` | Suppress any logging messages of the script, specify twice, to also suppress warnings, specify more, also suppress errors.
101+
| `-h` | Prints a small help text and current configuration.
102+
| `-H` | Retrieve the man page of xtb of the original xtb distribution.
103+
| `-X` | Retrieve the man page of xcontrol of the original xtb distribution.
104+
105+
## Included files and directories
106+
107+
The following files and/or directories come with this script:
133108

134109
* `runxtb.sh` The main wrapper.
135110
* `runxtb.rc` An example set-up file.
@@ -143,7 +118,7 @@ The following files come with this script:
143118

144119
## Exit status
145120

146-
The script `runxtb` carries over the exit statusses of its dependencies.
121+
The script `runxtb` carries over the exit status of its dependencies.
147122
In interactive mode that is the exit status of `xtb`.
148123
In submission mode it is the exit status of `qsub`, `bsub`, or `sbatch`.
149124
In all other cases it will be `0` if everything went according to plan,
@@ -186,4 +161,4 @@ See [LICENSE](LICENSE) to see the full text.
186161
You should have received a copy of the GNU General Public License
187162
along with this program. If not, see <https://www.gnu.org/licenses/>.
188163

189-
(Martin; 2020-02-27; wrapper version 0.3.2)
164+
(Martin; 2020-04-09; wrapper version 0.4.0)

‎VERSION‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
#!/bin/bash
2-
version="0.3.2"
3-
versiondate="2020-02-27"
2+
version="0.4.0"
3+
versiondate="2020-04-09"

‎configure/configure.sh‎

Lines changed: 40 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ backup_if_exists ()
7373
fi
7474
}
7575

76-
expand_tilde ()
76+
expand_tilde_path ()
7777
{
7878
local expand_string="$1" return_string
7979
# Tilde does not expand like a variable, this might lead to files not being found
@@ -107,9 +107,19 @@ check_exist_executable ()
107107

108108
get_bindir ()
109109
{
110-
# Taken from https://stackoverflow.com/a/246128/3180795
111-
local resolve_file="$1" description="$2" link_target directory_name resolve_dir_name
110+
# Resolves the absolute location of parameter and returns it
111+
# partially taken from https://stackoverflow.com/a/246128/3180795
112+
local resolve_file="$1" description="$2"
113+
local link_target directory_name resolve_dir_name
112114
debug "Getting directory for '$resolve_file'."
115+
resolve_file=$( expand_tilde_path "$resolve_file" )
116+
117+
# Check if anything exists in this location, otherwise abort.
118+
if [[ ! -e "$resolve_file" ]] ; then
119+
fatal "It appears, that '$resolve_file' does not exist."
120+
else
121+
debug "File resolved to '$resolve_file' and does exist."
122+
fi
113123

114124
# resolve $resolve_file until it is no longer a symlink
115125
while [ -h "$resolve_file" ]; do
@@ -159,7 +169,7 @@ test_rc_file ()
159169
get_rc ()
160170
{
161171
local test_runxtbrc_dir test_runxtbrc_loc return_runxtbrc_loc
162-
while [[ ! -z $1 ]] ; do
172+
while [[ -n $1 ]] ; do
163173
test_runxtbrc_dir="$1"
164174
shift
165175
if test_runxtbrc_loc="$(test_rc_file "$test_runxtbrc_dir/.runxtbrc")" ; then
@@ -182,16 +192,16 @@ recover_rc ()
182192
runxtbrc_loc="$(get_rc "$scriptpath" "$runxtbrc_path" "/home/$USER" "/home/$USER/.config/" "$PWD")"
183193
debug "runxtbrc_loc=$runxtbrc_loc"
184194

185-
if [[ ! -z $runxtbrc_loc ]] ; then
186-
# shellcheck source=/home/te768755/devel/runxtb.bash/runxtb.rc
195+
if [[ -n $runxtbrc_loc ]] ; then
196+
# shellcheck source=../runxtb.rc
187197
. "$runxtbrc_loc"
188198
message "Configuration file '$runxtbrc_loc' applied."
189199
ask "Would you like to specify a different file?"
190200
if read_boolean ; then
191201
ask "What file would you like to load?"
192202
runxtbrc_loc=$(read_human_input)
193203
if runxtbrc_loc=$(test_rc_file "$runxtbrc_loc") ; then
194-
# shellcheck source=/home/te768755/devel/runxtb.bash/runxtb.rc
204+
# shellcheck source=../runxtb.rc
195205
. "$runxtbrc_loc"
196206
message "Configuration file '$runxtbrc_loc' applied."
197207
message "If some values were not set in this file,"
@@ -208,7 +218,7 @@ recover_rc ()
208218
ask "What file would you like to load?"
209219
runxtbrc_loc=$(read_human_input)
210220
if runxtbrc_loc=$(test_rc_file "$runxtbrc_loc") ; then
211-
# shellcheck source=/home/te768755/devel/runxtb.bash/runxtb.rc
221+
# shellcheck source=../runxtb.rc
212222
. "$runxtbrc_loc"
213223
message "Configuration file '$runxtbrc_loc' applied."
214224
else
@@ -242,6 +252,14 @@ recover_rc ()
242252
debug "use_memory=$use_memory"
243253

244254
use_xtbhome="$xtb_install_root"
255+
if [[ -n $use_xtbhome ]] ; then
256+
if use_xtbhome=$( get_bindir "$xtb_install_root/bin" "xTB root directory" ) ; then
257+
debug "XTB root directory successfully resolved: '$use_xtbhome'"
258+
else
259+
use_xtbhome=""
260+
debug "Could not extract xtb root directory, will set empty."
261+
fi
262+
fi
245263
use_xtbname="$xtb_callname"
246264
if [[ -z $use_xtbhome || -z $use_xtbname ]] ; then
247265
ask_installation_path
@@ -421,7 +439,7 @@ ask_installation_path ()
421439
# Will be empty if skipped; can return without assigning/testing empty values
422440
[[ -z $use_xtbpath ]] && return
423441
debug "use_xtbpath=$use_xtbpath"
424-
use_xtbpath="$(expand_tilde "$use_xtbpath")"
442+
use_xtbpath="$( expand_tilde_path "$use_xtbpath" )"
425443
if check_exist_executable "$use_xtbpath" ; then
426444
use_xtbhome=$(get_bindir "$use_xtbpath" "XTB bin directory") && use_xtbname=${use_xtbpath##*/}
427445
use_xtbhome="${use_xtbhome%/bin}"
@@ -624,10 +642,12 @@ print_settings ()
624642
echo "# "
625643
echo "###"
626644

627-
echo "## Set directory (not including the executable)."
645+
echo "## Set directory."
646+
echo "# (Without including the bin directory/ executable name; avoid trailing slashes.)"
628647
echo "# "
629648
if [[ -z $use_xtbhome ]] ; then
630649
echo "# xtb_install_root=/path/to/xtbhome"
650+
echo "# xtb_install_root='~polyluxus/chemsoft/xtb/xtb_6.3.pre2'"
631651
else
632652
echo " xtb_install_root=\"$use_xtbhome\""
633653
fi
@@ -636,7 +656,7 @@ print_settings ()
636656
echo "## (This should be xtb. Here set to xtb.dummy for testing.)"
637657
echo "#"
638658
echo "# xtb_callname=\"xtb.dummy\""
639-
if [[ ! -z $use_xtbname ]] ; then
659+
if [[ -n $use_xtbname ]] ; then
640660
echo " xtb_callname=\"$use_xtbname\""
641661
fi
642662
echo "#"
@@ -788,21 +808,28 @@ fi
788808

789809
# Get to know where this script is located
790810
scriptpath="$(get_bindir "$0" "directory of configure script")"
791-
runxtbrc_path="$(get_bindir "$scriptpath/../.runxtbrc" "directory of configuration file")"
811+
runxtbrc_path="$(get_bindir "$scriptpath/../runxtb.rc" "directory of configuration file")"
792812

793813
# Gather all information
794814
recover_rc || ask_all_settings
795815

796-
ask "Where do you want to store these settings?"
816+
ask "Where do you want to store these settings? (Please enter an absolute/ relative file and path.)"
797817
message "Predefined location: $PWD/runxtb.rc"
818+
message " (Creates the configuration file in the current directory. This option will be chosen if the input is empty.)"
798819
message "Suggested location : $runxtbrc_path/.runxtbrc"
820+
message " (This creates the configuration in the runxtb installation directory. Entering 'auto' will choose this location.)"
821+
message "You may also choose to enter a directory in which the file 'runxtb.rc' will be created."
822+
message "Please note that only the filenames 'runxtb.rc' and '.runxtbrc' will be recognised by the script."
799823

800824
settings_filename=$(read_human_input)
801825
if [[ -z $settings_filename ]] ; then
802826
settings_filename="$PWD/runxtb.rc"
803827
elif [[ -d "$settings_filename" ]] ; then
804828
settings_filename="$settings_filename/runxtb.rc"
805829
message "No filename specified, use '$settings_filename' instead."
830+
elif [[ $settings_filename =~ ^[Aa][Uu][Tt][Oo]$ ]] ; then
831+
settings_filename="$runxtbrc_path/.runxtbrc"
832+
message "Automatic mode chosen, using '$settings_filename'."
806833
fi
807834
backup_if_exists "$settings_filename"
808835

0 commit comments

Comments
 (0)