https://github.com/polyluxus/runxtb.bash
wrapper for the extended tight-binding semi-empirical program package xtb
https://github.com/polyluxus/runxtb.bash
bash-script computational-chemistry wrapper-script
Last synced: 2 months ago
JSON representation
wrapper for the extended tight-binding semi-empirical program package xtb
- Host: GitHub
- URL: https://github.com/polyluxus/runxtb.bash
- Owner: polyluxus
- License: gpl-3.0
- Created: 2018-02-09T12:12:39.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-11-02T16:47:31.000Z (8 months ago)
- Last Synced: 2025-04-01T12:49:23.397Z (3 months ago)
- Topics: bash-script, computational-chemistry, wrapper-script
- Language: Shell
- Size: 953 KB
- Stars: 2
- Watchers: 2
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# runxtb.bash
This script provides a wrapper for the
extended tight-binding semi-empirical program package
[xtb](https://www.chemie.uni-bonn.de/grimme/de/software/xtb)
(version 6.0 or later) from Stefan Grimme's group at the University of Bonn
(contact: xtb{at}thch.uni-bonn.de).
It is available via [GitHub](https://github.com/grimme-lab/xtb).
The runxtb script makes it unnecessary to set environment variables like
`OMP_NUM_THREADS`, `MKL_NUM_THREADS`, `OMP_STACKSIZE`, and `XTBPATH` globally,
for example via the `.bashrc`.
It also provides a mechanism to automatically trap the output
that would normally go to standard out (i.e. the terminal).
Additionally it can be used to create scripts to submit it to a queueing system.
## Installation
A more elaborate guide on how to set up runxtb and xtb can be found in the
guides directory: [guides/set-up.md](guides/set-up.md).
Briefly:
Obtain the latest version of xtb (and crest) from its
[GitHub](https://github.com/grimme-lab/xtb/releases/latest) page.
While you're at it, you might want to pick up crest, too. It is also available at
[GitHub](https://github.com/crest-lab/crest/releases/latest).
Pick a directory, where you would like to install these packages, e.g.
a separate user (here: software) and the root directory `/home/software/chemsoft/xtb`.
Unpack the downloaded xtb archives (this may create a new directory for the downloaded version,
which should be set as `xtb_install_root` for runxtb).
Copy crest to the `bin` directory within there.
Get the latest release of this repository from
[GitHub](https://github.com/polyluxus/runxtb.bash/releases/latest).
You may want to install it alongside the original binary, e.g. `/home/software/chemsoft/xtb`.
Unpack the contents, and if necessary rename the directory.
Alternatively you can of course also clone this repository.
Change to the runxtb directory. If you have a previous version of the script, it might be possible
to import your settings. This is dependent on where your installed them.
Now you can simply run the configure script, which will prompt for the values
with a short description. If you are using a fresh installation, it will recover the
default settings from the supplied `runxtb.rc`.
At the end, you will be prompted for a location for the configuration file.
Keep in mind that the wrapper script will first look for a file `.runxtbrc`,
then for a file `runxtb.rc`, in directories of the following order:
`scriptpath`, `/home/$USER`, `/home/$USER/.config`, and `$PWD`.
If a `.runxtbrc` is found, it will skip `runxtb.rc`.
The location the script has predefined is `$PWD/runxtb.rc`, hence overwriting the
provided example file, if it is launched from the installation directory of runxtb.
Alternative options (e.g. `'scriptpath'/.runxtbrc`) are also given.
After that, the configuration script will ask about creating symbolic links in `~/bin`.
If you choose to do that, you can basically access the script from anywhere in your file system.
### Using environment modules
This script can interface to environment modules.
For the developement of this feature, [Lmod](https://lmod.readthedocs.io/) was used.
More details can be found in the guides directory: [guides/module-examples.md](guides/module-examples.md).
To check whether your supplied module system is supported, please find the script
`test_modules.sh` in the [configure directory](configure) of this repository.
## Updating
If you decided to clone the repository, make sure to stash your changes,
then pull the most recent version.
If you have stashed any changes, you may want to apply them now.
After running the configuration script, everything should be working with the new version.
You can of course also install a fresh version of runxtb.
If you want to import older settings, copy your configuration file to the root of runxtb,
or supply the absolute path to the settings when prompted by the configuration script.
When downloading a new version, you should always reconfigure the script.
## Usage and options
A more detailed description of the usage and the options can be found in the
guides directory: [guides/usage-opts.md](guides/usage-opts.md).
Brief overview:
If linked (or found) from a directory along the `PATH` environment variable,
you can call the runxtb wrapper script as if you would call the original program:
```
runxtb.sh [script options] [xtb options]
```
Any provided options to runxtb used will overwrite the corresponding rc settings,
which in turn take precedence over the built-in defaults.
If same options or modes are specified multiple times, only the last one will have an effect,
e.g. specifying `-sSi` will run interactively (immediately).
The following script options are available:
| Option | Description
|:------------|:------------
| `-p ` | Specify the number of processors to be used. (Default: `4`)
| `-m ` | Specify the memory to be used (in megabyte). (Default: `1000`)
| `-w ` | Specify the wall time to be used (`[[HH]:[MM]:]SS`). (Default: `24:00:00`)
| `-o ` | Trap the output (without errors) of `xtb` into a file called ``. (Default: `auto`)
| `-s` | Write a submit script instead of interactive execution (default: PBS). Resulting file needs to be submitted.
| `-S` | Write submit script and directly submit it to the queue, requires setting a queueing system with `-Q`.
| `-Q ` | Set a queueing system for which the submit script should be prepared, supported `pbs-gen`, `slurm-gen`, (`bsub-gen`).
| `-P ` | Account to project or account ``, only slurm, LSF (bsub).
| `-M` | Use pre-installed modules instead of path settings, also needs specified module(s).
| `-l ` | Specify a module to be used, will also invoke `-M`, may be specified multiple times to create a list, `=purge` unloads all modules and `=0` clears the list.
| `-i` | Execute in interactive mode (default without configuration).
| `-B ` | Set the absolute path to the executable `xtb` to ``. The name of the program needs to be included.
| `-C ` | Set the name of the program directly, e.g. to access a different executable like crest (if installed).
| `-q` | Suppress any logging messages of the script, specify twice, to also suppress warnings, specify more, also suppress errors.
| `-h` | Prints a small help text and current configuration.
| `-H` | Retrieve the man page of xtb of the original xtb distribution.
| `-X` | Retrieve the man page of xcontrol of the original xtb distribution.
Please note that support for LSF (bsub) is now deprecated and will be removed in a future update.
## Included files and directories
The following files and/or directories come with this script:
* `runxtb.sh` The main wrapper.
* `runxtb.rc` An example set-up file.
* `xtb.dummy` A tiny bash script only for testing.
This will only echo ` [options]` verbatim.
* `crest.prepare.sh` A small script that creates a new directory
with a suitable `coord` file to start a `crest` run.
* `README.md` This file.
* `configure` A directory containing a script to configure the wrapper.
* `guides` A directory with markup-formatted file(s), which can be used as tutorials.
## Exit status
The script `runxtb` carries over the exit status of its dependencies.
In interactive mode that is the exit status of `xtb`.
In submission mode it is the exit status of `qsub`, `bsub`, or `sbatch`.
In all other cases it will be `0` if everything went according to plan,
or `1` if there was a problem within the script.
The script `crest.prepare.sh` will exit with `0` if nothing went wrong
and a crest run can be started. If files are not present, or I/O operations
fail it will exit with `1`.
The dummy script `xtb.dummy` always exits with `2`.
## Debug
Things go wrong.
We need to accept that.
To find out more, using `debug` as the very first argument gives more information.
For example:
```
runxtb.sh debug -p1 -qq -s dummy.xyz --opt
```
If you find anything not going as expected,
please include the debug output when submitting a bug report to the
[GitHub issue tracker](https://github.com/polyluxus/runxtb.bash/issues).
## License (GNU General Public License v3.0)
runxtb.bash - a wrapper script for xtb
Copyright (C) 2019 - 2024 Martin C Schwarzer
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
See [LICENSE](LICENSE) to see the full text.
You should have received a copy of the GNU General Public License
along with this program. If not, see .
(Martin; 2024-11-02; wrapper version 0.6.0)