# maxaragon/rte-rrtmgp-cpp architecture

> Architecture diagram of the GitHub repository maxaragon/rte-rrtmgp-cpp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maxaragon/rte-rrtmgp-cpp
- Repository: https://github.com/maxaragon/rte-rrtmgp-cpp

## Overview

##### Project Type and Purpose
- This is a high‑performance scientific computing library with both CPU and GPU implementations of Radiative Transfer for Energetics (RTE) coupled to the Rapid Radiative Transfer Model for GCM applications Parallel (RRTMGP), plus a Monte Carlo ray‑tracer.
- It provides a core C++ API, CUDA backends, legacy Fortran‑style kernels, Python bindings for post‑processing and test case runners (allsky, rfmip, rcemip), and a CMake‑based build & test infrastructure.

##### High‑Level Architecture
- Core Library Layer (src & include)
- RTE modules: Rte_lw, Rte_sw
- Optical property modules: Aerosol_optics, Cloud_optics, Gas_optics, Optical_props
- Flux solver modules: Fluxes, Source_functions, Gas_concs
- GPU Backends
- CUDA implementations of each core module (src_cuda & include_kernels_cuda)
- Separate “rt” backends for GPU ray‑tracer (src_cuda_rt & include_rt_kernels)
- CPU‑only legacy kernels (src_kernels/*.F90)
- Testing & Example Harness
- Test executable (src_test + include_test) → test_rte_rrtmgp
- Example directories with orchestration scripts: allsky/, rfmip/, rcemip/
- Python Wrappers & Utilities
- Cython interface (python/*.pyx + setup.py)
- Post‑processing scripts for visualization and camera setup
- Build & Configuration
- CMakeLists.txt at root and in subdirectories
- config/*.cmake for platform targets (Ubuntu, Mac, HPC clusters)
- External Data & Dependencies
- NetCDF and coefficient files (data/, rrtmgp-data/)
- Submodule for original RRTMGP data & code (rrtmgp/)

##### Component Interactions
- Build System (CMake) orchestrates compilation of:
- Core C++ library → CPU code
- CUDA library → GPU code + ray‑tracer
- Fortran kernels → legacy CPU performance paths
- Cython extension → Python importable module
- Test executable → linked to the above
- At runtime:
- test_rte_rrtmgp (and Python scripts) open NetCDF input → call core API
- Core API dispatches to CPU or GPU kernels (templated / macro‑based)
- Monte Carlo ray‑tracer uses its own RT API layer
- Outputs are NetCDF or visualizations consumed by Python

##### Architectural Patterns & Design Principles
- Layered modular design: interface headers (include/ & include_rt/) separate from implementation (src/ & src_cuda/).
- Strategy pattern via compile‐time dispatch: CPU vs GPU backends selected through CMake flags.
- Test‑driven integration: dedicated src_test harness linking to core modules.
- Plugin‑style example runners: allsky, rfmip, rcemip share the same engine with different inputs and plotting scripts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Configuration Layer
    CMake["Build System (CMake)"]:::grayColor
    CMake -->|"compiles"| CoreEngine
    CMake -->|"compiles"| CPUKernels
    CMake -->|"compiles"| GPUKernels
    CMake -->|"compiles"| RayTracer
    CMake -->|"compiles"| PythonLayer
    CMake -->|"compiles"| TestExec

    %% Core C++ Engine Layer
    subgraph "Core C++ Engine" 
        CoreEngine["Core Engine API\n(src/ & include/)"]:::coreColor
        AeroOpt["Aerosol_optics.h"]:::coreColor
        CloudOpt["Cloud_optics.h"]:::coreColor
        AerosolCPP["Aerosol_optics.cpp"]:::coreColor
        CloudCPP["Cloud_optics.cpp"]:::coreColor
        CoreEngine --> AeroOpt
        CoreEngine --> CloudOpt
        CoreEngine --> AerosolCPP
        CoreEngine --> CloudCPP
    end

    %% CPU Kernels Layer
    subgraph "CPU‑only Legacy Kernels" 
        CPUKernels["Fortran Kernels\n(src_kernels/)"]:::cpuColor
        MoFlux["mo_fluxes_byband_kernels.F90"]:::cpuColor
        MoRte["mo_rte_solver_kernels.F90"]:::cpuColor
        CPUKernels --> MoFlux
        CPUKernels --> MoRte
    end

    %% GPU Backends Layer
    subgraph "GPU Backends (CUDA)" 
        GPUKernels["CUDA Kernels\n(src_cuda/ & include_kernels_cuda/)"]:::gpuColor
        FluxCUDA["Fluxes.cu"]:::gpuColor
        OptCUDA["optical_props_kernels_cuda.h"]:::gpuColor
        GPUKernels --> FluxCUDA
        GPUKernels --> OptCUDA
    end

    %% Monte Carlo Ray-Tracer
    subgraph "Monte Carlo Ray‑Tracer" 
        RayTracer["RT Module\n(include_rt/ & src_cuda_rt/)"]:::gpuColor
        RTHeader["Raytracer.h"]:::gpuColor
        RTCu["Raytracer.cu"]:::gpuColor
        RayTracer --> RTHeader
        RayTracer --> RTCu
    end

    %% Python Layer
    subgraph "Python Layer (Cython + Scripts)" 
        PythonLayer["Python Interface\n(python/)"]:::pyColor
        PyX["radiation.pyx"]:::pyColor
        SetupPy["setup.py"]:::pyColor
        PythonLayer --> PyX
        PythonLayer --> SetupPy
    end

    %% Test Executable & Harness
    subgraph "Test Executable & Harness" 
        TestExec["test_rte_rrtmgp"]:::coreColor
        NetcdfH["Netcdf_interface.h"]:::coreColor
        TestCpp["test_rte_rrtmgp.cpp"]:::coreColor
        TestExec --> NetcdfH
        TestExec --> TestCpp
    end

    %% Example Runners
    subgraph "Example Runners" 
        Allsky["allsky_run.py"]:::pyColor
        Rfmip["rfmip_run.py"]:::pyColor
        Rcemip["test_rcemip_input.py"]:::pyColor
        Allsky --> CoreEngine
        Rfmip --> CoreEngine
        Rcemip --> CoreEngine
    end

    %% Data Assets
    DataAssets["Data Assets\n(data/ & rrtmgp-data/)"]:::grayColor

    %% External Submodule
    Submodule["External Submodule\n(rrtmgp/)"]:::grayColor

    %% Runtime Flows
    TestExec -->|"invokes API"| CoreEngine
    PythonLayer -->|"imports Cython"| CoreEngine
    CoreEngine -->|"dispatches"| CPUKernels
    CoreEngine -->|"dispatches"| GPUKernels
    CoreEngine -->|"reads/writes"| DataAssets
    RayTracer -->|"reads/writes"| DataAssets
    Allsky -->|"orchestrates"| PythonLayer
    Rfmip -->|"orchestrates"| PythonLayer
    Rcemip -->|"orchestrates"| PythonLayer

    %% Click Events
    click CMake "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/CMakeLists.txt"
    click AeroOpt "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/include/Aerosol_optics.h"
    click CloudOpt "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/include/Cloud_optics.h"
    click AerosolCPP "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/src/Aerosol_optics.cpp"
    click CloudCPP "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/src/Cloud_optics.cpp"
    click MoFlux "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/src_kernels/mo_fluxes_byband_kernels.F90"
    click MoRte "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/src_kernels/mo_rte_solver_kernels.F90"
    click FluxCUDA "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/src_cuda/Fluxes.cu"
    click OptCUDA "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/include_kernels_cuda/optical_props_kernels_cuda.h"
    click RTHeader "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/include_rt/Raytracer.h"
    click RTCu "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/src_cuda_rt/Raytracer.cu"
    click PyX "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/python/radiation.pyx"
    click SetupPy "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/python/setup.py"
    click NetcdfH "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/include_test/Netcdf_interface.h"
    click TestCpp "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/src_test/test_rte_rrtmgp.cpp"
    click Allsky "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/allsky/allsky_run.py"
    click Rfmip "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/rfmip/rfmip_run.py"
    click Rcemip "https://github.com/maxaragon/rte-rrtmgp-cpp/blob/main/rcemip/test_rcemip_input.py"

    %% Styles
    classDef coreColor fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef gpuColor fill:#90EE90,stroke:#333,stroke-width:1px
    classDef cpuColor fill:#FFA500,stroke:#333,stroke-width:1px
    classDef pyColor fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef grayColor fill:#D3D3D3,stroke:#333,stroke-width:1px
```
