# gyselax/gyselalibxx architecture

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

- Interactive diagram: https://gitdiagram.com/gyselax/gyselalibxx
- Repository: https://github.com/gyselax/gyselalibxx

## Overview

Gyselalib++ is a C++ library and set of simulation applications for kinetic and gyrokinetic problems on large parallel systems. The principal workflow configures a simulation, initializes its fields on a selected geometry, evolves them with numerical operators and time integration, and writes diagnostics for analysis. The tree shows multiple geometry-specific applications and post-processing tools. The graph summarizes their product-level roles; several implementation details and runtime call sites were not sampled, so uncertain wiring is omitted.

Main entry points: [`simulations`](https://github.com/gyselax/gyselalibxx/tree/devel/simulations) (Simulation mains), [`src/geometryXVx/boltzmann`](https://github.com/gyselax/gyselalibxx/tree/devel/src/geometryXVx/boltzmann) (Kinetic solvers), [`src/geometryXVx/geometry/geometry_xvx.hpp`](https://github.com/gyselax/gyselalibxx/blob/devel/src/geometryXVx/geometry/geometry_xvx.hpp) (Geometry models), [`src/advection`](https://github.com/gyselax/gyselalibxx/tree/devel/src/advection) (Advection operators)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Simulation apps"]
  node_simulations["Simulation mains"]
end

subgraph group_physics["Physics operators"]
  node_initialization["Field initialization"]
  node_geometry["Geometry models<br/>[geometry_xvx.hpp]"]
  node_advection["Advection operators"]
  node_kinetic["Kinetic solvers"]
  node_poisson["Poisson solvers"]
  node_collisions["Collision operators"]
  node_time_integration["Time integration"]
end

subgraph group_numerics["Numerical foundations"]
  node_fields["Field data types"]
  node_coordinates["Coordinate mappings"]
  node_interpolation["Spline interpolation"]
end

subgraph group_runtime["Runtime and output"]
  node_configuration["Input configuration<br/>[input.hpp]"]
  node_parallel["MPI parallelism"]
  node_output["Simulation output<br/>[output.hpp]"]
end

subgraph group_analysis["Result analysis"]
  node_results["HDF5 results"]
  node_postprocessing["Diagnostics and plots"]
  node_hdf5_tools["HDF5 utilities<br/>[HDF5utils.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"configures and runs"| node_simulations
node_simulations -->|"reads settings"| node_configuration
node_simulations -->|"initializes fields"| node_initialization
node_simulations -->|"selects geometry"| node_geometry
node_simulations -->|"advances state"| node_time_integration
node_time_integration -->|"integrates dynamics"| node_kinetic
node_kinetic -->|"uses advection"| node_advection
node_kinetic -->|"uses field solver"| node_poisson
node_kinetic -->|"applies collisions"| node_collisions
node_kinetic -->|"operates on fields"| node_fields
node_geometry -->|"maps coordinates"| node_coordinates
node_advection -->|"evaluates splines"| node_interpolation
node_simulations -->|"uses MPI support"| node_parallel
node_simulations -->|"writes results"| node_output
node_output -->|"stores results"| node_results
node_researcher -->|"analyzes results"| node_postprocessing
node_postprocessing -->|"uses utilities"| node_hdf5_tools
node_hdf5_tools -->|"reads HDF5"| node_results

click node_simulations "https://github.com/gyselax/gyselalibxx/tree/devel/simulations"
click node_configuration "https://github.com/gyselax/gyselalibxx/blob/devel/src/io/input.hpp"
click node_initialization "https://github.com/gyselax/gyselalibxx/tree/devel/src/geometryXVx/initialisation"
click node_geometry "https://github.com/gyselax/gyselalibxx/blob/devel/src/geometryXVx/geometry/geometry_xvx.hpp"
click node_advection "https://github.com/gyselax/gyselalibxx/tree/devel/src/advection"
click node_kinetic "https://github.com/gyselax/gyselalibxx/tree/devel/src/geometryXVx/boltzmann"
click node_poisson "https://github.com/gyselax/gyselalibxx/tree/devel/src/geometryXVx/poisson"
click node_collisions "https://github.com/gyselax/gyselalibxx/tree/devel/src/collisions"
click node_time_integration "https://github.com/gyselax/gyselalibxx/tree/devel/src/geometryXVx/time_integration"
click node_fields "https://github.com/gyselax/gyselalibxx/tree/devel/src/data_types"
click node_coordinates "https://github.com/gyselax/gyselalibxx/tree/devel/src/coord_transformations"
click node_interpolation "https://github.com/gyselax/gyselalibxx/tree/devel/src/interpolation"
click node_parallel "https://github.com/gyselax/gyselalibxx/tree/devel/src/mpi_parallelisation"
click node_output "https://github.com/gyselax/gyselalibxx/blob/devel/src/io/output.hpp"
click node_postprocessing "https://github.com/gyselax/gyselalibxx/tree/devel/post-process/PythonScripts"
click node_hdf5_tools "https://github.com/gyselax/gyselalibxx/blob/devel/post-process/PythonScripts/HDF5utils.py"

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_simulations toneBlue
class node_initialization,node_geometry,node_advection,node_kinetic,node_poisson,node_collisions,node_time_integration toneAmber
class node_fields,node_coordinates,node_interpolation toneMint
class node_configuration,node_parallel,node_output toneRose
class node_results,node_postprocessing,node_hdf5_tools,node_researcher toneIndigo
```

## Components

### Simulation apps

- [Simulation mains](https://github.com/gyselax/gyselalibxx/tree/devel/simulations): `simulations`

### Physics operators

- [Field initialization](https://github.com/gyselax/gyselalibxx/tree/devel/src/geometryXVx/initialisation): `src/geometryXVx/initialisation`
- [Geometry models](https://github.com/gyselax/gyselalibxx/blob/devel/src/geometryXVx/geometry/geometry_xvx.hpp): `src/geometryXVx/geometry/geometry_xvx.hpp`
- [Advection operators](https://github.com/gyselax/gyselalibxx/tree/devel/src/advection): `src/advection`
- [Kinetic solvers](https://github.com/gyselax/gyselalibxx/tree/devel/src/geometryXVx/boltzmann): `src/geometryXVx/boltzmann`
- [Poisson solvers](https://github.com/gyselax/gyselalibxx/tree/devel/src/geometryXVx/poisson): `src/geometryXVx/poisson`
- [Collision operators](https://github.com/gyselax/gyselalibxx/tree/devel/src/collisions): `src/collisions`
- [Time integration](https://github.com/gyselax/gyselalibxx/tree/devel/src/geometryXVx/time_integration): `src/geometryXVx/time_integration`

### Numerical foundations

- [Field data types](https://github.com/gyselax/gyselalibxx/tree/devel/src/data_types): `src/data_types`
- [Coordinate mappings](https://github.com/gyselax/gyselalibxx/tree/devel/src/coord_transformations): `src/coord_transformations`
- [Spline interpolation](https://github.com/gyselax/gyselalibxx/tree/devel/src/interpolation): `src/interpolation`

### Runtime and output

- [Input configuration](https://github.com/gyselax/gyselalibxx/blob/devel/src/io/input.hpp): `src/io/input.hpp`
- [MPI parallelism](https://github.com/gyselax/gyselalibxx/tree/devel/src/mpi_parallelisation): `src/mpi_parallelisation`
- [Simulation output](https://github.com/gyselax/gyselalibxx/blob/devel/src/io/output.hpp): `src/io/output.hpp`

### Result analysis

- **HDF5 results**
- [Diagnostics and plots](https://github.com/gyselax/gyselalibxx/tree/devel/post-process/PythonScripts): `post-process/PythonScripts`
- [HDF5 utilities](https://github.com/gyselax/gyselalibxx/blob/devel/post-process/PythonScripts/HDF5utils.py): `post-process/PythonScripts/HDF5utils.py`

### Other components

- **Researcher**

## Connections

- Researcher → Simulation mains: configures and runs
- Simulation mains → Input configuration: reads settings
- Simulation mains → Field initialization: initializes fields
- Simulation mains → Geometry models: selects geometry
- Simulation mains → Time integration: advances state
- Time integration → Kinetic solvers: integrates dynamics
- Kinetic solvers → Advection operators: uses advection
- Kinetic solvers → Poisson solvers: uses field solver
- Kinetic solvers → Collision operators: applies collisions
- Kinetic solvers → Field data types: operates on fields
- Geometry models → Coordinate mappings: maps coordinates
- Advection operators → Spline interpolation: evaluates splines
- Simulation mains → MPI parallelism: uses MPI support
- Simulation mains → Simulation output: writes results
- Simulation output → HDF5 results: stores results
- Researcher → Diagnostics and plots: analyzes results
- Diagnostics and plots → HDF5 utilities: uses utilities
- HDF5 utilities → HDF5 results: reads HDF5