# gyselax/gysela-mini-app_io architecture

> Architecture diagram of the GitHub repository gyselax/gysela-mini-app_io, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gyselax/gysela-mini-app_io
- Repository: https://github.com/gyselax/gysela-mini-app_io

## Overview

Gysela Mini Apps is a compact I/O and analysis application for GYSELA 5D particle-distribution data, also intended for coupling with GyselaX++. The principal workflow initializes a configured mesh and distribution, runs an MPI-based app, and writes data and timing results; Python tools then compute or verify fluid moments and inspect timings. Separate in-situ analytics and diagnostics provide Deisa/Dask-based analysis. The graph includes documented capabilities whose implementations are not fully sampled; those links are omitted or marked unverified where call ownership cannot be established from the excerpts.

Main entry points: [`src/checkpointing/gys_checkpointing.cpp`](https://github.com/gyselax/gysela-mini-app_io/blob/devel/src/checkpointing/gys_checkpointing.cpp) (MPI I/O app), [`processing/analytics.py`](https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/analytics.py) (Moment analytics), [`processing/utils/verify_fluid_moments.py`](https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/utils/verify_fluid_moments.py) (Moment verifier), [`processing/diagnostics.py`](https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/diagnostics.py) (In-situ diagnostics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cpp_app["C++ I/O app"]
  node_miniapp["MPI I/O app"]
  node_checkpointing["Checkpointing app"]
end

subgraph group_cpp_core["C++ domain core"]
  node_geometry["5D mesh types<br/>[geometry.hpp]"]
  node_moments_cpp["C++ fluid moments<br/>[fluid_moments.cpp]"]
  node_moments_api["Moments interface<br/>[fluid_moments.hpp]"]
end

subgraph group_python_analysis["Python analysis"]
  node_analytics["Moment analytics<br/>[analytics.py]"]
  node_moments_py["Moment calculations<br/>[fluid_moments.py]"]
  node_diagnostics["In-situ diagnostics<br/>[diagnostics.py]"]
  node_measure["Physical measurements<br/>[measure.py]"]
end

subgraph group_python_tools["Python utilities"]
  node_timing_cli["Timing reader"]
  node_verify["Moment verifier"]
  node_cli["Python CLI<br/>[cli.py]"]
end

node_user(("Research user"))
node_pdi["PDI I/O"]
node_mpi["MPI runtime"]
node_deisa["Deisa/Dask"]
node_hdf5[("HDF5 files")]
node_csv[("Diagnostics CSV")]

node_user -->|"runs"| node_miniapp
node_miniapp -->|"uses mesh types"| node_geometry
node_miniapp -->|"uses moments"| node_moments_api
node_moments_cpp -->|"implements"| node_moments_api
node_miniapp -->|"uses"| node_mpi
node_miniapp -->|"writes events"| node_pdi
node_miniapp -.->|"writes output"| node_hdf5
node_miniapp -.->|"supports"| node_checkpointing
node_analytics -->|"computes moments"| node_moments_py
node_analytics -->|"writes moments"| node_hdf5
node_analytics -->|"registers callback"| node_deisa
node_diagnostics -->|"registers callback"| node_deisa
node_diagnostics -->|"measures data"| node_measure
node_measure -->|"appends metrics"| node_csv
node_cli -->|"dispatches"| node_timing_cli
node_cli -->|"dispatches"| node_verify
node_verify -->|"calculates moments"| node_moments_py
node_verify -->|"reads reference"| node_hdf5
node_timing_cli -->|"reads timings"| node_hdf5

click node_miniapp "https://github.com/gyselax/gysela-mini-app_io/blob/devel/src/checkpointing/gys_checkpointing.cpp"
click node_geometry "https://github.com/gyselax/gysela-mini-app_io/blob/devel/src/geometry.hpp"
click node_moments_cpp "https://github.com/gyselax/gysela-mini-app_io/blob/devel/src/fluid_moments/fluid_moments.cpp"
click node_moments_api "https://github.com/gyselax/gysela-mini-app_io/blob/devel/src/fluid_moments/fluid_moments.hpp"
click node_analytics "https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/analytics.py"
click node_moments_py "https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/fluid_moments.py"
click node_diagnostics "https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/diagnostics.py"
click node_measure "https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/measure.py"
click node_timing_cli "https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/utils/read_timing_stats.py"
click node_verify "https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/utils/verify_fluid_moments.py"
click node_cli "https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/utils/cli.py"
click node_checkpointing "https://github.com/gyselax/gysela-mini-app_io/tree/devel/simulations/checkpointing"

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_miniapp,node_checkpointing,node_user toneBlue
class node_geometry,node_moments_cpp,node_moments_api,node_hdf5,node_csv toneAmber
class node_analytics,node_moments_py,node_diagnostics,node_measure toneMint
class node_timing_cli,node_verify,node_cli toneRose
class node_pdi,node_mpi,node_deisa toneIndigo
```

## Components

### C++ I/O app

- [MPI I/O app](https://github.com/gyselax/gysela-mini-app_io/blob/devel/src/checkpointing/gys_checkpointing.cpp): `src/checkpointing/gys_checkpointing.cpp`
- [Checkpointing app](https://github.com/gyselax/gysela-mini-app_io/tree/devel/simulations/checkpointing): `simulations/checkpointing`

### C++ domain core

- [5D mesh types](https://github.com/gyselax/gysela-mini-app_io/blob/devel/src/geometry.hpp): `src/geometry.hpp`
- [C++ fluid moments](https://github.com/gyselax/gysela-mini-app_io/blob/devel/src/fluid_moments/fluid_moments.cpp): `src/fluid_moments/fluid_moments.cpp`
- [Moments interface](https://github.com/gyselax/gysela-mini-app_io/blob/devel/src/fluid_moments/fluid_moments.hpp): `src/fluid_moments/fluid_moments.hpp`

### Python analysis

- [Moment analytics](https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/analytics.py): `processing/analytics.py`
- [Moment calculations](https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/fluid_moments.py): `processing/fluid_moments.py`
- [In-situ diagnostics](https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/diagnostics.py): `processing/diagnostics.py`
- [Physical measurements](https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/measure.py): `processing/measure.py`

### Python utilities

- [Timing reader](https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/utils/read_timing_stats.py): `processing/utils/read_timing_stats.py`
- [Moment verifier](https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/utils/verify_fluid_moments.py): `processing/utils/verify_fluid_moments.py`
- [Python CLI](https://github.com/gyselax/gysela-mini-app_io/blob/devel/processing/utils/cli.py): `processing/utils/cli.py`

### Other components

- **Research user**
- **PDI I/O**
- **MPI runtime**
- **Deisa/Dask**
- **HDF5 files**
- **Diagnostics CSV**

## Connections

- Research user → MPI I/O app: runs (evidence: `README.md`)
- MPI I/O app → 5D mesh types: uses mesh types (evidence: `src/checkpointing/gys_checkpointing.cpp`)
- MPI I/O app → Moments interface: uses moments (evidence: `src/checkpointing/gys_checkpointing.cpp`)
- C++ fluid moments → Moments interface: implements (evidence: `src/fluid_moments/fluid_moments.cpp`)
- MPI I/O app → MPI runtime: uses (evidence: `src/checkpointing/gys_checkpointing.cpp`)
- MPI I/O app → PDI I/O: writes events (evidence: `src/checkpointing/gys_checkpointing.cpp`)
- MPI I/O app → HDF5 files: writes output
- MPI I/O app → Checkpointing app: supports
- Moment analytics → Moment calculations: computes moments (evidence: `processing/analytics.py`)
- Moment analytics → HDF5 files: writes moments (evidence: `processing/analytics.py`)
- Moment analytics → Deisa/Dask: registers callback (evidence: `processing/analytics.py`)
- In-situ diagnostics → Deisa/Dask: registers callback (evidence: `processing/diagnostics.py`)
- In-situ diagnostics → Physical measurements: measures data (evidence: `processing/diagnostics.py`)
- Physical measurements → Diagnostics CSV: appends metrics (evidence: `processing/measure.py`)
- Python CLI → Timing reader: dispatches (evidence: `processing/utils/cli.py`)
- Python CLI → Moment verifier: dispatches (evidence: `processing/utils/cli.py`)
- Moment verifier → Moment calculations: calculates moments (evidence: `processing/utils/verify_fluid_moments.py`)
- Moment verifier → HDF5 files: reads reference (evidence: `processing/utils/verify_fluid_moments.py`)
- Timing reader → HDF5 files: reads timings (evidence: `processing/utils/read_timing_stats.py`)
