This repository contains the source code of the official Wannier Software Ecosystem Registry.
All codes that are part of this registry must adhere to the following requirements:
- The code belongs to the Wannier-Functions Software Ecosystem, that is, it is interfaced to other codes of the Wannier ecosystem (e.g., it prepares the inputs to compute Wannier functions, or it uses Wannier functions generated by a Wannier engine).
- The code has a home page.
- The code is accessible to the research community (e.g. it is open source, or it is possible to acquire a license to use it).
Codes are added to the registry by adding an entry to the codes.yaml
file within this repository, following this simple procedure:
-
Create a pull request to this repository that adds a new entry to the
codes.yaml
file, e.g., by editing the file directly in the browser. Example:QuantumESPRESSO: categories: - ab-initio_engines metadata: description: | Quantum ESPRESSO is an integrated suite of open-source computer codes for quantum simulations of materials using state-of-the art electronic-structure techniques, based on density-functional theory, density-functional perturbation theory, and many-body perturbation theory, within the plane-wave pseudo-potential and projector-augmented-wave approaches homepage_url: https://www.quantum-espresso.org sourcecode_url: https://gitlab.com/QEF/q-e documentation_url: https://www.quantum-espresso.org/documentation/ title: Quantum ESPRESSO logo: https://www.quantum-espresso.org/wp-content/uploads/2022/03/quantum_ogo_ok.png
Note: To check which fields are optional, refer to the "Valid keys" subsection below; but it is highly encouraged to fill in all the fields to process your PR quickly. The
categories
field must contain at least one item.Note: a number of tests are run to ensure the syntactic validity of the file. These include also some "linting" checks, such as no trailing whitespaces, etc. If you create a pull request from your computer, you can avoid that the tests fail by installing and running the pre-commit checks. You can install them by running once, in the git folder that you checked out:
pip install -r src/requirements.txt pre-commit install
The checks will then run when you commit files - they will check and automatically fix any simple syntax error (such as traling whitespaces) and you will be prompted to commit again once the files are fixed. If you want to check all files before committing, you can run
pre-commit run --all-files
.Note: To generate and visualize the website, simply execute the following command:
$ python src/build.py
and then open the "src/build/html/index.html" file with a browser.
-
Your code will show up in the Wannier-Functions Software Ecosystem Registry once your pull request is approved and merged.
Tip: The registry supports the $ref
syntax to reference externally hosted documents.
That means you can reference metadata that is hosted at a different location, which makes it easier to dynamically update it.
For example, if you place a metadata.yaml
file within your code repository, then you can reference that file like this:
my-code:
metadata:
$ref: https://github.com/my-org/my-code/raw/main/metadata.yaml
categories:
- ab-initio_engines
You can even reference only parts of the metadata, example:
my-code:
metadata:
title: my-code
description:
$ref: https://github.com/my-org/my-code/raw/main/metadata.yaml#description
categories:
- ab-initio_engines
Feel free to propose a new codes category to be added to category.yaml
before adding your code.
Key | Requirement | Description |
---|---|---|
metadata |
Mandatory | General description of the code (see below). |
categories |
Mandatory | An array of categories, where each category must be one of the categories specified in categories.yaml . |
Key | Requirement | Description |
---|---|---|
title |
Mandatory | The title will be displayed in the list of codes. |
description |
Mandatory | A short description, displayed both on the page with the list of codes, and on the detail page of the code. |
homepage_url |
Mandatory | Link to the home page of the code. |
documentation_url |
Optional | Link to the documentation of the code (e.g. on Read The Docs); if possible/available, use a direct link to the subsection of the code documentation discussing the interaction with the Wannier ecosystem. |
sourcecode_url |
Optional | Link to the source code. Can be GitHub, GitLab, or any other publicly available repository. |
logo |
Optional | Url to a logo file (png or jpg). |
To prepare a development environment, please run the following steps:
$ pip install -r src/requirements.txt -r tests/requirements.txt
$ pre-commit install
This will install all requirements needed to run the git pre-commit hooks (linters), build the website locally, and execute the test framework.
To execute tests, run:
$ PYTHONPATH=src pytest
Executed tests include unit, integration, and validation tests.
The validation tests check the validity of all schema files, the data files e.g. codes.yaml
and categories.yaml
, and if present the configuration file (config.yaml
).
The continuous-integration workflow is implemented with GitHub Actions, which runs the pre-commit hooks, unit, integration, and validation tests.
In addition, all commits on the main
branch are automatically deployed to GitHub pages.