Wannier Software Ecosystem Registry

This repository contains the source code of the official Wannier Software Ecosystem Registry.

Adding a code to the 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:

1. 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.

2. 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.

Valid keys for code entries in codes.yaml

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.

Valid keys for code metadata

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).

Information for maintainers

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.