# hel-astro-lab/runko architecture

> Architecture diagram of the GitHub repository hel-astro-lab/runko, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hel-astro-lab/runko
- Repository: https://github.com/hel-astro-lab/runko

## Overview

##### Project Type and Purpose
- Runko is a multi-physics simulation framework for astrophysical plasmas. It is designed to run on both CPUs and GPUs and is written in modern C++ with Python bindings. It supports several physics modules (Particle-In-Cell (PIC), FDTD electromagnetics (EMF), Force-Free Electrodynamics (FFE), Vlasov (VLV), and Radiation/QED) and integrates with the grid infrastructure library (corgi) for parallel domain decomposition and high-performance simulations.
- The README further highlights the separation between low-level performance-critical kernels (C++) and high-level drivers/prototyping (Python). It also emphasizes simulation aspects such as parallelism, load-balancing, and the ability to test on a laptop and scale to supercomputer platforms.

##### Analyzing the File Structure
- The top-level file tree contains directories like core, bindings, projects, prototypes, docs, external, tests, and tools.
- The core directory is subdivided into submodules for the different physics components (emf, ffe, pic, qed, vlv), each implemented in C++.
- The bindings directory provides the C++/Python interface code; this is key to the hybrid design.
- The projects/ directory holds example simulation setups (which might be used to illustrate usage and configuration).
- The prototypes directory contains experimental implementations and interface prototypes – useful for understanding extensibility and modularity.
- External libraries (e.g., corgi, ezh5, cppitertools) and build/configuration files (CMakeLists.txt, Travis, clang-format) also appear, showing that compilation, testing, and documentation are well supported.
- The presence of documentation, tests, and tools directories further suggests that the codebase is designed for high performance, modularity, and ease of scaling/testing.

##### Main Components
a. Core Computing Kernels:
- Segment these into the physics modules:
- EMF module (FDTD propagators, filters, boundaries)
- PIC module (particle pushers, depositers, interpolators)
- FFE module (currents, tile management)
- VLV module (Vlasov-specific solvers, AMR, momentum and spatial solvers)
- QED module (radiation interaction, pairing, photon management)
- Common infrastructure such as the “tile” abstractions and grid tasking.

b. Python Bindings Layer:
- Binding files (bindings/, pytools/) that ‘expose’ the C++ kernels to Python. This is the interface layer where high-level simulation scripts invoke the performance-critical routines.

c. External Dependencies and Infrastructure:
- Use of third-party libraries like corgi for domain decomposition and parallelization.
- External libraries listed in the file tree (e.g., external/corgi, external/fmt) to show how lower-level tasks and performance abstractions are augmented by external packages.

d. Projects and Prototypes:
- Projects directory as an example “simulation driver” area, where users design specific simulation setups to utilize the kernel and interface layers.
- A component for prototypes (including coupling, dispersion-solver, high-order methods, etc.) to signify experimental and extensible parts of the framework.

e. Supporting Infrastructure:
- Build, configuration, and testing components: CMake, Travis, documentation (docs), tests.
- Tools (for code quality, performance profiling, and debugging) should be included as auxiliary services.

##### Relationships and Interactions
- Simulation projects (Python scripts) call into the Python Bindings layer.
- Bindings invoke the corresponding high-performance C++ kernels in the core.
- C++ kernels use the tile-decomposition and load-balancing provided by the external grid library (corgi).
- Data input/output and snapshot functionality (contained under the io/ directory) acts as an interface to external storage facilities.
- Testing and prototypes loop back into both the Python interfaces and the core functionalities to validate design choices.

##### Important Architectural Patterns and Design Principles
- Modular Design: Each physics domain is separated in its own module within core (emf, pic, ffe, vlv, qed).
- Hybrid Layering: The separation between performance-critical C++ code (kernels) and high-level Python control (rapid prototyping and simulation setup).
- Domain Decomposition: Use of the corgi library for parallelism via grid tiling and load-balancing.
- Extensibility: Clear boundaries and interfaces between modules support independent development and coupling of different physical models.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/Simulation Layer
    subgraph "User/Simulation Layer"
        PROJ("Projects (Simulation Drivers)"):::userLayer
        PROTOTYPE("Prototypes (Experimental)"):::userLayer
    end

    %% Interface Layer
    subgraph "Interface Layer"
        BIND("Python Bindings & Pytools"):::interfaceLayer
    end

    %% Core Physics Kernel Layer
    subgraph "Core Physics Kernel Layer"
        EMF("EMF Module"):::coreLayer
        PIC("PIC Module"):::coreLayer
        FFE("FFE Module"):::coreLayer
        VLV("VLV Module"):::coreLayer
        QED("QED Module"):::coreLayer
    end

    %% Infrastructure/Support Layer
    subgraph "Infrastructure/Support Layer"
        EXT("External: Corgi & Libraries"):::infraLayer
        IO("IO & Data Handling"):::infraLayer
        BUILD("Build, Testing & Docs"):::infraLayer
    end

    %% Connections between layers
    PROJ -->|"calls"| BIND
    PROTOTYPE -->|"prototypeCalls"| BIND

    BIND -->|"invokes"| EMF
    BIND -->|"invokes"| PIC
    BIND -->|"invokes"| FFE
    BIND -->|"invokes"| VLV
    BIND -->|"invokes"| QED

    EMF -->|"usesGridLib"| EXT
    PIC -->|"usesGridLib"| EXT
    FFE -->|"usesGridLib"| EXT
    VLV -->|"usesGridLib"| EXT
    QED -->|"usesGridLib"| EXT

    EMF -->|"handlesIO"| IO
    PIC -->|"handlesIO"| IO
    FFE -->|"handlesIO"| IO
    VLV -->|"handlesIO"| IO
    QED -->|"handlesIO"| IO

    IO -->|"reportsTo"| BUILD

    %% Click Events
    click EMF "https://github.com/hel-astro-lab/runko/tree/master/core/emf"
    click PIC "https://github.com/hel-astro-lab/runko/tree/master/core/pic"
    click FFE "https://github.com/hel-astro-lab/runko/tree/master/core/ffe"
    click QED "https://github.com/hel-astro-lab/runko/tree/master/core/qed"
    click VLV "https://github.com/hel-astro-lab/runko/tree/master/core/vlv"
    click BIND "https://github.com/hel-astro-lab/runko/tree/master/bindings"
    click EXT "https://github.com/hel-astro-lab/runko/tree/master/external/corgi"
    click PROJ "https://github.com/hel-astro-lab/runko/tree/master/projects"
    click PROTOTYPE "https://github.com/hel-astro-lab/runko/tree/master/prototypes"
    click IO "https://github.com/hel-astro-lab/runko/tree/master/io"
    click BUILD "https://github.com/hel-astro-lab/runko/blob/master/CMakeLists.txt"

    %% Styles
    classDef userLayer fill:#fef9c3,stroke:#b45309,stroke-width:2px;
    classDef interfaceLayer fill:#dbeafe,stroke:#1e40af,stroke-width:2px;
    classDef coreLayer fill:#fecaca,stroke:#991b1b,stroke-width:2px;
    classDef infraLayer fill:#d1fae5,stroke:#065f46,stroke-width:2px;
```
