<!-- markdownlint-disable MD041 -->
[![GitHub Super-Linter](https://github.com/interTwin-eu/T6.5-AI-and-ML/actions/workflows/lint.yml/badge.svg)](https://github.com/marketplace/actions/super-linter)
[![GitHub Super-Linter](https://github.com/interTwin-eu/T6.5-AI-and-ML/actions/workflows/check-links.yml/badge.svg)](https://github.com/marketplace/actions/markdown-link-check)
[![SQAaaS source code](https://github.com/EOSC-synergy/itwinai.assess.sqaaas/raw/main/.badge/status_shields.svg)](https://sqaaas.eosc-synergy.eu/#/full-assessment/report/https://raw.githubusercontent.com/eosc-synergy/itwinai.assess.sqaaas/main/.report/assessment_output.json)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.09409/status.svg)](https://doi.org/10.21105/joss.09409)

<!-- markdownlint-disable MD033 -->
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./docs/images/icon-itwinai-orange-white-subtitle.png">
  <img src="./docs/images/icon-itwinai-orange-black-subtitle.png" alt="itwinai-icon" width="430">
</picture>
<!-- markdownlint-enable MD033 -->

`itwinai` is a Python toolkit designed to help scientists and researchers streamline AI and machine learning
workflows, specifically for digital twin applications. It provides easy-to-use tools for distributed training,
hyper-parameter optimization on HPC systems, and integrated ML logging, reducing engineering overhead and accelerating
research. Developed primarily by CERN, in collaboration with Forschungszentrum Jülich (FZJ), `itwinai` supports modular
and reusable ML workflows, with the flexibility to be extended through third-party plugins, empowering AI-driven scientific
research in digital twins.

See the latest version of our docs [here](https://itwinai.readthedocs.io/).

## Installation

For instructions on how to install `itwinai`, please refer to the
[user installation guide](https://itwinai.readthedocs.io/latest/installation/user_installation.html)
or the
[developer installation guide](https://itwinai.readthedocs.io/latest/installation/developer_installation.html),
depending on whether you are a user or developer

For information about how to use containers or how to test with pytest, you can look
at the following documents:

- [Working with containers](/docs/working-with-containers.md)
- [Testing with pytest](/docs/testing-with-pytest.md)

## How to contribute

Want to help improve **itwinai**? Here are a few good ways to get involved:

- **Report a bug / request a feature:** open a [GitHub issue](https://github.com/interTwin-eu/itwinai/issues).
- **Contribute code or docs:** fork the repository and submit a [pull request](https://github.com/interTwin-eu/itwinai/pulls).
- **Ask questions or float ideas:** start a [GitHub discussion](https://github.com/interTwin-eu/itwinai/discussions)
or join us on [Discord](https://discord.gg/EZRtuK9Vjr).

## Citation

If you use **itwinai** in your research, please cite:

> Bunino et al., (2026). *itwinai: A Python Toolkit for Scalable Scientific Machine Learning on HPC Systems*.
> **Journal of Open Source Software**, 11(117), 9409. <https://doi.org/10.21105/joss.09409>

BibTeX:

```bibtex
@article{Bunino2026,
  doi = {10.21105/joss.09409},
  url = {https://doi.org/10.21105/joss.09409},
  year = {2026},
  publisher = {The Open Journal},
  volume = {11},
  number = {117},
  pages = {9409},
  author = {Bunino, Matteo and Sæther, Jarl and Eickhoff, Linus and Lappe, Anna and Tsolaki, Kalliopi and
            Verder, Killian and Mutegeki, Henry and Machacek, Roman and Girone, Maria and Krochak, Oleksandr and
            Rüttgers, Mario and Sarma, Rakesh and Lintermann, Andreas},
  title = {itwinai: A Python Toolkit for Scalable Scientific Machine Learning on HPC Systems},
  journal = {Journal of Open Source Software}
}
