excitingworkflow

exctingworkflow is a repository to collect scripts for automatically setting up exciting calculations and performing convergence series. All workflows are written in the workflow language of jobflow. excitingworklow can be used to execute dependent exciting calculations (WORKFLOWS) or simply many independent calculations (HIGH-THROUGHPUT).

Workflows

Currently supported workflows are:

• groundstate convergence of the parameters rgkmax, nempty and ngridk with respect to the total energy
• GW convergence of the parameters nempty and ngridq, and the HELO's (high energy local orbitals) in the species file(s) with respect to the Quasiparticle energies CBm and VBM, and the bandgap
• BSE convergence of the parameters gqmax and ngridk/ngridq with respect to the exciton energy, and/or the spectral similarity (measured by spearman coefficient, or the tanimoto coefficient)
• species workflow to find a maximal local orbital basis and local orbital hierarchy
• GW workflow: automated workflow to execute a GW calculation using the task-based GW implementation

Installation

For innstructions on how to install excitingworkflow, please refer to the INSTALL file.

Remote execution

If you want to execute your workflows on a remote machine, for instance on a supercomputer using slurm as a queue manager, you can achieve this using jobflow-remote. You should read the remote_execution.md file to get started.

Command line interface

excitingworkflow provides a command line interface (CLI) written with typer. It contains mainly helper commands that should simplify your daily work. After the installation of excitingworkflow, you can invoke the CLI with:

ew

This is similar to calling ew -h or ew --help. You will see a list of all available commands. You can learn more about each command by calling ew <command> -h. Either you see the description of the command or you get a list of all available subcommands. For a complete overview of all commands, you can call:

ew --tree

Note that all commands using jobflow-remote will use the default project.

Tests

Tests are written and executed with pytest. Overall code coverage is also measured in the git pipeline and displayed on the webpage. You can run the test suite from the root directory via

pip install pytest
pytest tests/

This package is developed to execute exciting calculations. It's not possible to run exciting in the regular unit test suite. There are still tests covering the whole workflow, and actually running exciting. Those integration tests can be additionally triggered via:

pytest --run-exciting tests/

Note, in order for the test cases to find the exciting binary, the value for exciting_binary from the config file will be used, so it needs to be set.

Tutorials

We provide basic and advanced tutorials, as well as various example files for setting up and running this package. Refer to this README to get started.

Are you a SOL member?

Make sure to also read the SOL-specific information: SOL_info.md.

License

excitingworkflow is distributed under the GNU General Public License Version 3 (GPLv3) or any later version.

See the LICENSE file for details.

Contributing

We welcome contributions to this repository. Please refer to the CONTRIBUTING file for more information.

Compatibility

This package has been extensively tested and used on both Linux and macOS. Some of the standard paths given in the tutorials might need to be adjusted if you are using a different operating system. The plain usage of Windows is not recommended. Instead, you want to use a virtual machine or a docker-like environment.

Authors and acknowledgment

Fabian Peschel: main developer and maintainer

Hannah Kleine: contributed idea and parts of the implementation of the species workflow

Alexander Buccheri: thanks for supervision and guideline in writing the workflows