nomad-simulations schema plugin

This is a plugin for NOMAD which contains the base sections schema definitions for materials science simulations.

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/nomad-coe/nomad-simulations.git
cd nomad-simulations
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

You can also run the script to generate a local file coverage.txt with the same information by doing:

./scripts/generate_coverage_txt.sh

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-simulations-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

Main contributors