# otwin-core/otwin-hybrid architecture

> Architecture diagram of the GitHub repository otwin-core/otwin-hybrid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/otwin-core/otwin-hybrid
- Repository: https://github.com/otwin-core/otwin-hybrid

## Overview

This repository is a battery end-of-life forecasting tutorial and reproducible experiment, not a general digital-twin platform. Its Python workflow loads battery capacity data, derives state of health, fits physics-only, Gaussian-process, and residual-hybrid forecasts, evaluates held-out predictions and end-of-life estimates, then saves result tables for plotting. The notebooks extend the worked example to Julia and R. Relationships below are limited to the excerpts, source index, and README; notebook internals were not sampled.

Main entry points: [`src/otwin_hybrid/comparison.py`](https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py) (Experiment runner), [`src/otwin_hybrid/figures.py`](https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/figures.py) (Figure generator), [`src/otwin_hybrid/_paths.py`](https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/_paths.py) (Path resolver), [`results`](https://github.com/otwin-core/otwin-hybrid/tree/main/results) (Result tables)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Forecast analysis"]
  node_battery_data["Battery data<br/>[battery_soh.csv]"]
  node_path_resolver["Path resolver<br/>[_paths.py]"]
  node_comparison["Experiment runner<br/>[comparison.py]"]
  node_soh_prep["SoH preparation<br/>[comparison.py]"]
  node_physics["Physics model<br/>[comparison.py]"]
  node_gp["Gaussian process<br/>[comparison.py]"]
  node_hybrid["Residual hybrid<br/>[comparison.py]"]
  node_baselines["Forecast baselines<br/>[comparison.py]"]
end

subgraph group_evaluation["Evaluation outputs"]
  node_evaluation_metrics["Forecast evaluation<br/>[comparison.py]"]
  node_result_files["Result tables"]
  node_figure_generator["Figure generator<br/>[figures.py]"]
  node_figure_files["Figures"]
end

subgraph group_tutorial["Tutorial interfaces"]
  node_python_tutorial["Python tutorial"]
  node_julia_tutorial["Julia tutorial"]
  node_r_tutorial["R tutorial"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs example"| node_python_tutorial
node_researcher -->|"opens example"| node_julia_tutorial
node_researcher -->|"opens example"| node_r_tutorial
node_researcher -->|"runs analysis"| node_comparison
node_comparison -->|"resolves paths"| node_path_resolver
node_comparison -->|"loads data"| node_battery_data
node_comparison -->|"prepares SoH"| node_soh_prep
node_comparison -->|"fits and forecasts"| node_physics
node_comparison -->|"fits and forecasts"| node_gp
node_comparison -->|"fits and forecasts"| node_hybrid
node_comparison -->|"computes baselines"| node_baselines
node_comparison -->|"evaluates forecasts"| node_evaluation_metrics
node_comparison -->|"writes tables"| node_result_files
node_figure_generator -->|"resolves paths"| node_path_resolver
node_figure_generator -->|"reads tables"| node_result_files
node_figure_generator -->|"writes plots"| node_figure_files

click node_battery_data "https://github.com/otwin-core/otwin-hybrid/blob/main/data/battery_soh.csv"
click node_path_resolver "https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/_paths.py"
click node_comparison "https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py"
click node_soh_prep "https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py"
click node_physics "https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py"
click node_gp "https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py"
click node_hybrid "https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py"
click node_baselines "https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py"
click node_evaluation_metrics "https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py"
click node_result_files "https://github.com/otwin-core/otwin-hybrid/tree/main/results"
click node_figure_generator "https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/figures.py"
click node_figure_files "https://github.com/otwin-core/otwin-hybrid/tree/main/figures"
click node_python_tutorial "https://github.com/otwin-core/otwin-hybrid/blob/main/notebooks/hybrid_digital_twin_python.ipynb"
click node_julia_tutorial "https://github.com/otwin-core/otwin-hybrid/blob/main/notebooks/hybrid_digital_twin_julia.ipynb"
click node_r_tutorial "https://github.com/otwin-core/otwin-hybrid/blob/main/notebooks/hybrid_digital_twin_r.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_battery_data,node_path_resolver,node_comparison,node_soh_prep,node_physics,node_gp,node_hybrid,node_baselines toneBlue
class node_evaluation_metrics,node_result_files,node_figure_generator,node_figure_files toneAmber
class node_python_tutorial,node_julia_tutorial,node_r_tutorial toneMint
class node_researcher toneIndigo
```

## Components

### Forecast analysis

- [Battery data](https://github.com/otwin-core/otwin-hybrid/blob/main/data/battery_soh.csv): `data/battery_soh.csv`
- [Path resolver](https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/_paths.py): `src/otwin_hybrid/_paths.py`
- [Experiment runner](https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py): `src/otwin_hybrid/comparison.py`
- [SoH preparation](https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py): `src/otwin_hybrid/comparison.py`
- [Physics model](https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py): `src/otwin_hybrid/comparison.py`
- [Gaussian process](https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py): `src/otwin_hybrid/comparison.py`
- [Residual hybrid](https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py): `src/otwin_hybrid/comparison.py`
- [Forecast baselines](https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py): `src/otwin_hybrid/comparison.py`

### Evaluation outputs

- [Forecast evaluation](https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/comparison.py): `src/otwin_hybrid/comparison.py`
- [Result tables](https://github.com/otwin-core/otwin-hybrid/tree/main/results): `results`
- [Figure generator](https://github.com/otwin-core/otwin-hybrid/blob/main/src/otwin_hybrid/figures.py): `src/otwin_hybrid/figures.py`
- [Figures](https://github.com/otwin-core/otwin-hybrid/tree/main/figures): `figures`

### Tutorial interfaces

- [Python tutorial](https://github.com/otwin-core/otwin-hybrid/blob/main/notebooks/hybrid_digital_twin_python.ipynb): `notebooks/hybrid_digital_twin_python.ipynb`
- [Julia tutorial](https://github.com/otwin-core/otwin-hybrid/blob/main/notebooks/hybrid_digital_twin_julia.ipynb): `notebooks/hybrid_digital_twin_julia.ipynb`
- [R tutorial](https://github.com/otwin-core/otwin-hybrid/blob/main/notebooks/hybrid_digital_twin_r.ipynb): `notebooks/hybrid_digital_twin_r.ipynb`

### Other components

- **Researcher**

## Connections

- Researcher → Python tutorial: runs example (evidence: `README.md`)
- Researcher → Julia tutorial: opens example (evidence: `README.md`)
- Researcher → R tutorial: opens example (evidence: `README.md`)
- Researcher → Experiment runner: runs analysis (evidence: `README.md`)
- Experiment runner → Path resolver: resolves paths (evidence: `src/otwin_hybrid/comparison.py`)
- Experiment runner → Battery data: loads data (evidence: `src/otwin_hybrid/comparison.py`)
- Experiment runner → SoH preparation: prepares SoH (evidence: `src/otwin_hybrid/comparison.py`)
- Experiment runner → Physics model: fits and forecasts (evidence: `src/otwin_hybrid/comparison.py`)
- Experiment runner → Gaussian process: fits and forecasts (evidence: `src/otwin_hybrid/comparison.py`)
- Experiment runner → Residual hybrid: fits and forecasts (evidence: `src/otwin_hybrid/comparison.py`)
- Experiment runner → Forecast baselines: computes baselines (evidence: `src/otwin_hybrid/comparison.py`)
- Experiment runner → Forecast evaluation: evaluates forecasts (evidence: `src/otwin_hybrid/comparison.py`)
- Experiment runner → Result tables: writes tables (evidence: `src/otwin_hybrid/comparison.py`)
- Figure generator → Path resolver: resolves paths (evidence: `src/otwin_hybrid/figures.py`)
- Figure generator → Result tables: reads tables (evidence: `src/otwin_hybrid/figures.py`)
- Figure generator → Figures: writes plots (evidence: `src/otwin_hybrid/figures.py`)