⚠️ Repository migration notice

This repository was migrated from nomad-coe/nomad-simulations to fairmat-nfdi/nomad-simulations on 2025-01-02. Existing GitHub links and clone URLs continue to work via redirects.

If you encounter any broken links or unexpected issues related to the migration, please report them.

nomad-simulations

nomad-simulations is an open-source Python package for managing materials-science simulation data. It follows the plugin architecture of NOMAD. The package provides section definitions (Python classes) with quantities and methods that support extracting and organizing data from different simulation codes. These definitions can be used, modified, and extended at the level needed by the user, and external contributions are welcome.

Read more in the official documentation page.

Getting started

nomad-simulations can be installed as a PyPI package using pip:

pip install nomad-simulations

Development

If you want to develop locally, clone the project and create a virtual environment with Python 3.10 or newer:

git clone https://github.com/fairmat-nfdi/nomad-simulations.git
cd nomad-simulations
python3.11 -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 package with development dependencies:

uv pip install '.[dev]'

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

uv pip install -e '.[dev]'

Run the tests

You can run the tests locally:

uv run pytest -sv tests

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

Our CI/CD pipeline produces a more comprehensive test report using the pytest-cov package. You can generate a local coverage report:

uv run pytest --cov=src tests

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

./scripts/generate_coverage_txt.sh

Run linting and auto-formatting

We use Ruff for linting and formatting the code. Ruff auto-formatting is also a part of the GitHub workflow actions. You can run locally:

uv run ruff check .
uv run ruff format . --check

Debugging

For interactive debugging of the tests, use pytest with the --pdb flag. We recommend using an IDE for debugging, e.g., VSCode. If that is the case, 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 <path-to-plugin-tests> must be changed to the local path to the test module to be debugged.

The settings configuration file .vscode/settings.json automatically applies the linting and formatting upon saving the modified file.

Launching the documentation locally

To view the documentation locally, run MkDocs with the extra docs dependencies:

uv run --extra docs mkdocs serve

Documentation conventions for maintainers are tracked in docs/contributor_guides/documentation_writing_guide.md.

Note that part of the documentation is generated via repository scripts. For that workflow, see docs/contributor_guides/documentation_automation_guide.md.

Adding this plugin to NOMAD

If you are developing locally using the nomad-distro-dev environment, see NOMAD distro-dev README: day-to-day development.

If you are adding this plugin to a NOMAD Oasis, see NOMAD plugin installation docs.

How to cite this work

Pizarro, J.M., Boydas, E.B., Daelman, N., Ladines, A.N., Mohr, B. & Rudzinski, J.F., NOMAD Simulations [Computer software]. https://zenodo.org/doi/10.5281/zenodo.13838811

Main contributors