# VIPR Framework Documentation

## What is VIPR?

VIPR (Versatile Inverse Problem Software Framework) is a modular machine-learning framework for scientific inverse problems in physics.

It provides a plugin-based architecture for configurable inference workflows: domain-specific code for data loading, model loading, preprocessing, prediction, postprocessing, visualization, and result storage can be combined through declarative YAML configuration and executed either from the command line or through the web application.

## Inference Pipeline Overview

At the core of VIPR is a domain-agnostic, five-step inference pipeline. The same workflow structure can be adapted to concrete scientific domains through plugins, handlers, filters, and hooks.

1. **Load Data** - read experimental input files and standardize them into a `DataSet`
2. **Load Model** - load and prepare the configured model for inference
3. **Preprocess** - transform the input data for model consumption
4. **Predict** - run the model and produce predictions
5. **Postprocess** - format results and generate artifacts such as plots, tables, and summaries

## Quick Installation

For local CLI usage, install `vipr-core` together with the domain plugins you need:

```bash
python3.10 -m venv myenv
source myenv/bin/activate
pip install git+https://codebase.helmholtz.cloud/vipr/vipr-core.git
pip install git+https://codebase.helmholtz.cloud/vipr/vipr-reflectometry-plugin.git
```

After installation, the packaged PTCDI-C3 reflectometry example can be run directly from the CLI:

```bash
vipr --config @vipr_reflectometry/reflectorch/examples/configs/PTCDI-C3.yaml inference run
```

This configuration loads PTCDI-C3 reflectometry data, applies the configured preprocessing filter, runs the Reflectorch predictor, and stores the generated result artifacts in the VIPR storage directory.

For the full web application stack, use the Docker deployment:

```bash
git clone https://codebase.helmholtz.cloud/vipr/vipr-framework.git
cd vipr-framework
cp docker-compose.override.yml.example docker-compose.override.yml
mkdir -p storage
docker compose up --wait
```

For details, see [CLI Installation](docs/installation/cli.md) and [Docker Deployment](docs/installation/docker.md).

```{toctree}
:maxdepth: 2
:caption: Getting Started

docs/TLDR VIPR Introduction <docs/TLDR VIPR Introduction.pdf>
VIPR_CLI
VIPR_web_app
docs/web-app/inference-flow
docs/web-app/compare-results
```

```{toctree}
:maxdepth: 2
:caption: Setup & Configuration

docs/setup/authentication
docs/installation/cli
docs/installation/docker
```

```{toctree}
:maxdepth: 2
:caption: CLI Usage

docs/cli/commands
```

```{toctree}
:maxdepth: 2
:caption: Plugins

docs/plugins/README
docs/plugins/developing
docs/plugins/built-in/api/README
docs/plugins/built-in/api/usage
docs/plugins/built-in/api/visualization
docs/generated/api_routes
docs/plugins/built-in/discovery
docs/plugins/built-in/huggingface
docs/plugins/built-in/inference
docs/plugins/built-in/normalizers
docs/plugins/built-in/registry
docs/plugins/built-in/registry-quickstart
docs/plugins/built-in/performance
docs/plugins/filters
docs/plugins/external/reflectometry/index
docs/plugins/external/gid/index
```

```{toctree}
:maxdepth: 2
:caption: Extensions

docs/extensions/strict_registration
docs/extensions/dynamic_hooks_filters
```

```{toctree}
:maxdepth: 2
:caption: Frontend

docs/frontend/index
```

```{toctree}
:maxdepth: 2
:caption: API Reference

docs/api/vipr-core/modules
docs/api/vipr-api/modules
docs/api/reflectometry/modules
```

## System Overview

**VIPR** is a modular ML framework with:
- **vipr-frontend** - Web interface (Nuxt.js)
- **vipr-api** - REST API backend (FastAPI) with async processing (Celery)
- **vipr-core** - Extensible plugin framework (Python CLI)

## Component Repositories

- [vipr-core](https://codebase.helmholtz.cloud/vipr/vipr-core) - Core framework repository
- [vipr-api](https://codebase.helmholtz.cloud/vipr/vipr-api) - API service repository
- [vipr-frontend](https://codebase.helmholtz.cloud/vipr/vipr-frontend) - Frontend repository
- [vipr-reflectometry-plugin](https://codebase.helmholtz.cloud/vipr/vipr-reflectometry-plugin) - Reflectometry plugin

## Project Partners

The VIPR Framework is developed by the VIPR Project Consortium with contributions from:

- [Helm & Walter IT-Solutions GmbH](https://www.helmundwalter.de/)
- [Forschungszentrum Jülich (FZJ) - Jülich Centre for Neutron Science (JCNS)](https://www.fz-juelich.de)
- [Technische Universität München (TUM)](https://www.tum.de)
- [University of Tübingen](https://www.uni-tuebingen.de)
- [University of Siegen](https://www.uni-siegen.de)
- [Helmholtz-Zentrum Dresden-Rossendorf (HZDR)](https://www.hzdr.de)
- [DESY (Deutsches Elektronen-Synchrotron)](https://www.desy.de)

For more information, visit [vipr-project.de](https://vipr-project.de).

## License

The VIPR Framework is licensed under the **GNU Lesser General Public License v3.0 (LGPL-3.0)**.

For details, see the `LICENSE.txt` file in each repository (for example `vipr-framework/LICENSE.txt`).
