nomad-neb-workflows

A NOMAD plugin containing the section definitions of a standard Nudged Elastic Band (NEB) workflow.

This nomad_ plugin was generated with Cookiecutter_ along with @nomad's cookiecutter-nomad-plugin template.

Getting started

Install the dependencies

Clone the project and in the workspace folder, create a virtual environment (note this project uses Python 3.9):

git clone https://github.com/FAIRmat-NFDI/nomad-neb-workflows.git
cd nomad-neb-workflows
python3.9 -m venv .pyenv
. .pyenv/bin/activate

Make sure to have pip upgraded:

pip install --upgrade pip

We recommend installing uv for fast pip installation of the packages:

pip install uv

Install the nomad-lab package:

uv pip install '.[dev]' --index-url https://gitlab.mpcdf.mpg.de/api/v4/projects/2187/packages/pypi/simple

Note! Until we have an official pypi NOMAD release with the plugins functionality. Make sure to include NOMAD's internal package registry (via --index-url in the above command).

The plugin is still under development. If you would like to contribute, install the package in editable mode (with the added -e flag) with the development dependencies:

uv pip install -e '.[dev]' --index-url https://gitlab.mpcdf.mpg.de/api/v4/projects/2187/packages/pypi/simple

Run the tests

You can run local tests using the pytest package:

python -m pytest -sv tests

where the -s and -v options toggle the output verbosity.

Our CI/CD pipeline produces a more comprehensive test report using coverage and coveralls packages. We suggest you to generate your own coverage reports locally by doing:

uv pip install pytest-cov
python -m pytest --cov=src tests

Setting up plugin on your local installation

Read the NOMAD plugin documentation for all details on how to deploy the plugin on your NOMAD instance.

Run linting and auto-formatting

ruff check .
ruff format . --check

Ruff auto-formatting is also a part of the GitHub workflow actions. Make sure that before you make a Pull Request, ruff format . --check runs in your local without any errors otherwise the workflow action will fail.

Debugging

For interactive debugging of the tests, use pytest with the --pdb flag. We recommend using an IDE for debugging, e.g., VSCode. If using VSCode, you can add the following snippet to your .vscode/launch.json:

{
  "configurations": [
      {
        "name": "<descriptive tag>",
        "type": "debugpy",
        "request": "launch",
        "cwd": "${workspaceFolder}",
        "program": "${workspaceFolder}/.pyenv/bin/pytest",
        "justMyCode": true,
        "env": {
            "_PYTEST_RAISE": "1"
        },
        "args": [
            "-sv",
            "--pdb",
            "<path to plugin tests>",
        ]
    }
  ]
}

where ${workspaceFolder} refers to the NOMAD root.

The settings configuration file .vscode/settings.json performs automatically applies the linting upon saving the file progress.

Build the python package

The pyproject.toml file contains everything that is necessary to turn the project into a pip installable python package. Run the python build tool to create a package distribution:

uv pip install build
python -m build --sdist

You can install the package with pip:

uv pip install dist/nomad-neb-workflows-0.1.0

Read more about python packages, pyproject.toml, and how to upload packages to PyPI on the PyPI documentation.

Documentation on Github pages

To deploy documentation on Github pages, make sure to enable GitHub pages via the repo settings.

To view the documentation locally, install the documentation related packages using:

uv pip install -r requirements_docs.txt

Run the documentation server:

mkdocs serve

Template update

We use cruft to update the project based on template changes. A cruft-update.yml is included in Github workflows to automatically check for updates and create pull requests to apply updates. Follow the instructions on how to enable Github Actions to create pull requests.

To run the check for updates locally, follow the instructions on cruft website.

License

Distributed under the terms of the Apache Software License 2.0_ license, "nomad-neb-workflows" is free and open source software

How to cite this work

Schumann, J., Pizarro, J.M., Gajera, U., Rudzinski, J.F., Näsström, H., NOMAD NEB Workflows (all versions) [Computer software]. https://zenodo.org/doi/10.5281/zenodo.XXX

Main contributors