excitingworkflow 0.0.1

Tools to automatically perform and converge exciting calculations.

exciting-workflow

Repository to collect scripts for automatically setting up exciting calculations and performing convergence series. All workflows are written in the workflow language of jobflow.

Currently supported workflows:

• groundstate convergence of the parameters rgkmax, nempty and ngridk
• gw convergence of the parameters nempty and ngridq, and the HELO's (high energy local orbitals) in the species file
• bse convergence of the parameters gqmax and ngridk/ngridq

Installation

You should install and run this package in a virtual environment. Here is how you can install excitingworkflow in a new conda environment:

conda create --name exc_wf python=3.12
conda activate exc_wf
cd ~/code
git clone [e-mail]:peschelf/excitingworkflow.git
cd excitingworkflow
pip install -e .

Remote execution

If you want to execute your workflow on a remote machine, for instance on a supercomputer using slurm as a queue manager, you can achieve this using jobflow-remote. Installation is possible via pip (assumes to be still in the root dir of excitingworkflow):

pip install -e .[remote_execution]

For more details check out the documentation of jobflow-remote and look into the excitingworkflow tutorials.

Settings

For some use cases you might want to specify general settings for this package. You can either set them as environment variables or in a yaml config file. The default location and name for this file would be ~/.excitingworkflow.yaml. Here, you can set for instance a default exciting binary. More options can be found in config/settings.py.

Code Checking and Formatting

We currently favour the ruff formatter, which by default applies PEP8 formatting to the code. Additional rule selection and configuration can be found in the pyproject.toml file.

After installing ruff via pip, if you are in the root directory of excitingtools, you can simply type:

ruff check excitingtools/path/to/file.py

This will check the selected file for common errors. Without a path the whole project will be checked.

Some problems can be solved automatically with enabling the --fix feature:

ruff check --fix excitingtools/path/to/file.py

Afterward, you can type

ruff format excitingtools/path/to/file.py

and it will do the formatting for you for the selected file, or again for the whole project without an argument. Check out the docs for more options.

Moreover, pre-commit is available. After typing in the root dir:

pip install -U pre-commit
pre-commit install

pre-commit will run ruff and a few other checks before every git commit.

Tests

Tests are very important and highly appreciated. Tests are written and executed with pytest. Every new piece of code should be unit tested. This means a small, short test for every function covering the use case. Overall code coverage is also measured in the git pipeline and displayed on the webpage.

This package is developed to run exciting calculations. It's not feasible to run exciting in the pipeline. There are still tests covering the whole workflow, and actually running exciting. Those integration tests need to be marked with @pytest.mark.exciting(). They are not run in the standard git CI, but can be (and should be regularly) tested locally via:

pip install pytest
pytest --run-exciting tests/

Note, in order for the test case to find the exciting binary, the SETTINGS.exciting_binary will be used, so it needs to be set.

Authors and acknowledgment

Fabian Peschel: main developer and maintainer

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