.. ============================================================================================
.. Sidenav entries

.. toctree::
   :maxdepth: 2
   :hidden:
   :caption: 🛠️ Installation

   installation/user_installation
   installation/developer_installation
   installation/uv_tutorial

.. toctree::
   :maxdepth: 2
   :hidden:
   :caption: 🚀 Getting started

   getting-started/complete-workflow-example
   getting-started/slurm
   getting-started/containers
   getting-started/plugins
   getting-started/plugins-list
   getting-started/glossary

.. toctree::
   :maxdepth: 2
   :hidden:
   :caption: 🪄 How it works

   how-it-works/training/training
   how-it-works/loggers/explain_loggers
   how-it-works/workflows/explain_workflows
   how-it-works/hpo/explain-hpo
   how-it-works/scalability-report/scalability_report

.. toctree::
   :maxdepth: 2
   :hidden:
   :caption: 🎓 Tutorials

   tutorials/tutorials

.. toctree::
   :maxdepth: 2
   :hidden:
   :caption: 📚 Scientific Use Cases

   use-cases/use_cases
   use-cases/eurac_doc
   use-cases/virgo_doc
   use-cases/3dgan_doc
   use-cases/cyclones_doc
   use-cases/mnist_doc
   use-cases/xtclim_doc
   use-cases/radio-astronomy
   use-cases/latticeqcd_doc

.. toctree::
   :maxdepth: 2
   :hidden:
   :caption: ⚡ API reference

   api/cli_reference
   api/modules

.. toctree::
   :maxdepth: 2
   :hidden:
   :caption: 🎯 Github repository

   itwinai <https://github.com/interTwin-eu/itwinai>

.. ============================================================================================
.. Here the Homepage starts

.. raw:: html

   <div>
     <a href="https://github.com/interTwin-eu/itwinai">
       <img src="https://img.shields.io/github/stars/interTwin-eu/itwinai.svg?style=social&label=Star" alt="GitHub stars" />
     </a>
     &nbsp;
     <a href="https://pypi.org/project/itwinai/">
       <img src="https://img.shields.io/pypi/v/itwinai.svg" alt="PyPI version" />
     </a>
     &nbsp;
     <a href="https://readthedocs.org/projects/itwinai/">
       <img src="https://img.shields.io/readthedocs/itwinai.svg" alt="ReadTheDocs" />
     </a>
   </div>
   </br>

Welcome to **itwinai**
======================

**Accelerate AI & ML workflows** for **Scientific Digital Twins**.

**itwinai** streamlines distributed training, hyperparameter optimization, logging, and modular
workflows, so you can focus on **science**, not plumbing.

Features
--------

- 🚀 **Seamless Scaling**: Run training and inference on HPC clusters or cloud with a single CLI command.
- 🔍 **Effortless Logging**: Built-in support for MLflow, Weights & Biases, TensorBoard, and more.
- 🧩 **Modular Workflows**: Define reusable pipelines for end-to-end experiment management.
- 🤖 **HPO Made Easy**: Native hyperparameter optimization with minimal configuration.
- 🔌 **Extensible Plugins**: Add custom integrations or contribute new features.

Quick Start
-----------

.. code-block:: bash

   # Install via pip
   pip install itwinai

   # Launch a complete workflow with SLURM integration using the MNIST example
   itwinai run -c https://raw.githubusercontent.com/interTwin-eu/itwinai/refs/heads/main/use-cases/mnist/torch/run-example.yaml

   # View logs in MLflow
   itwinai mlflow-ui --path mllogs/mlflow

🚀 Begin Here
==============

- :doc:`User Installation (for non-developers) <installation/user_installation>`
- :doc:`Developer Installation <installation/developer_installation>`
- :doc:`Submitting jobs to SLURM on HPC <getting-started/slurm>`
- :doc:`Using itwinai Container Images <getting-started/containers>`

🛠️ Core Guides
===============

- :doc:`Training a Neural Network <how-it-works/training/training>`
- :doc:`Logging and Tracking ML workflows <how-it-works/loggers/explain_loggers>`
- :doc:`Defining machine learning workflows <how-it-works/workflows/explain_workflows>`
- :doc:`Hyperparameter Optimization <how-it-works/hpo/explain-hpo>`

🎓 Tutorials
=============

- :doc:`Writing Configuration Files for itwinai <tutorials/workflows/02-pipeline-configuration/tutorial_1_intermediate_workflow>`
- :ref:`Distributed Training <distributed-training-tutorials>`
- :ref:`Hyper-parameter Optimization <hpo-tutorials>`
- :ref:`ML Workflows <ml-workflows-tutorials>`
- :ref:`Code Profiling and Optimization <profiling-tutorials>`

📚 Use Cases & 🧩 Plugins
==========================

- :doc:`MNIST — A Toy Use Case Example <use-cases/mnist_doc>`
- :doc:`Drought Early Warning in the Alps (EURAC) <use-cases/eurac_doc>`
- :doc:`Fast particle detector simulation (CERN) <use-cases/3dgan_doc>`
- :doc:`Writing Plugins for itwinai <getting-started/plugins>`
- :doc:`Current List of itwinai Plugins <getting-started/plugins-list>`

For the full list of scientific use cases refer to the navigation side bar.

⚡ API Reference
================

- :doc:`CLI Reference <api/cli_reference>`
- :doc:`Python SDK <api/modules>`

Integration with EuroHPC centers
================================

Our code has been run and tested on the following EuroHPC systems:

- `LUMI <https://www.lumi-supercomputer.eu/>`_
- `JSC <https://www.fz-juelich.de/jsc/>`_
- `Vega <https://izum.si/en/vega-en/>`_
- `Deucalion <https://eurohpc-ju.europa.eu/supercomputers/our-supercomputers_en#deucalion>`_ (coming soon)

Community & Support
===================

- `Join our Discord <https://discord.gg/7ru8u2nP>`_
- `GitHub Repository <https://github.com/interTwin-eu/itwinai>`_
- `Contributors <https://github.com/interTwin-eu/itwinai/graphs/contributors>`_
- `interTwin Project <https://www.intertwin.eu/>`_

**itwinai** is an open-source Python library primarily developed by CERN, in collaboration with Forschungszentrum Jülich (FZJ).
As the primary contributor, CERN will retain administrative rights to the repository during and after the interTwin project,
except in cases where CERN is unable to maintain it.

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>`_.

Indices and Tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Citation
========

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

.. code-block:: text

   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:

.. code-block:: 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}
   }