# cfd-go/tclb architecture

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

- Interactive diagram: https://gitdiagram.com/cfd-go/tclb
- Repository: https://github.com/cfd-go/tclb
- Video tour (about a minute): https://gitdiagram.com/cfd-go/tclb/video

## Overview

TCLB is a distributed, accelerator-capable computational-fluid-dynamics solver using the Lattice Boltzmann Method. The principal workflow is: a user supplies an XML run configuration; the executable initializes MPI and a solver, sizes its lattice, and dispatches XML elements to handlers that control the run; model-specific dynamics update the simulation, with callbacks and output handlers providing results. The tree and excerpts support the main dispatch and several internal layers; README-described subsystems with unsampled implementations are included at their exact enclosing paths, with uncertain wiring omitted.

Main entry points: [`src`](https://github.com/cfd-go/tclb/tree/master/src) (Solver state), [`src/main.cpp`](https://github.com/cfd-go/tclb/blob/master/src/main.cpp) (Runtime entry), [`src/Handlers.h`](https://github.com/cfd-go/tclb/blob/master/src/Handlers.h) (Handler dispatch), [`src/HandlerFactory.h`](https://github.com/cfd-go/tclb/blob/master/src/HandlerFactory.h) (Handler factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Run orchestration"]
  node_main["Runtime entry<br/>[main.cpp]"]
  node_handler["Handler dispatch<br/>[Handlers.h]"]
  node_factory["Handler factory<br/>[HandlerFactory.h]"]
  node_handlerbase["Handler lifecycle<br/>[vHandler.h]"]
end

subgraph group_simulation["LBM simulation"]
  node_solver["Solver state"]
  node_lattice[("Lattice state")]
  node_dynamics["LBM dynamics"]
  node_geometry["Geometry and regions<br/>[Geometry.h]"]
end

subgraph group_control["Control and optimization"]
  node_actions["Run controls"]
  node_design["Design handlers<br/>[Design.cpp]"]
  node_optimization["Adjoint optimization<br/>[OptimalControl.cpp]"]
  node_parameters["Model parameters<br/>[acParam.cpp]"]
end

subgraph group_results["Sampling and output"]
  node_callbacks["Runtime callbacks<br/>[Callback.cpp]"]
  node_sampling["Field sampling<br/>[Sampler.cpp]"]
  node_outputs["Output handlers"]
  node_hdf5["HDF5 output<br/>[hdf5Lattice.cpp]"]
  node_vtk["VTK output<br/>[vtkOutput.cpp]"]
end

subgraph group_integrations["Coupling and parallelism"]
  node_particles["Particle coupling<br/>[lammps.cpp]"]
  node_remote["Remote force"]
  node_turbulence["Synthetic turbulence"]
  node_mpi["MPI runtime"]
  node_accelerator["GPU runtime"]
end

node_user(("Simulation user"))
node_config["XML configuration"]

node_user -->|"launches"| node_main
node_user -->|"provides"| node_config
node_main -->|"parses"| node_config
node_main -->|"initializes"| node_solver
node_main -->|"constructs"| node_handler
node_handler -->|"creates"| node_factory
node_handler -->|"dispatches lifecycle"| node_handlerbase
node_factory -->|"selects handlers"| node_actions
node_factory -->|"selects handlers"| node_design
node_handler -->|"passes solver"| node_solver
node_solver -->|"owns state"| node_lattice
node_dynamics -->|"updates fields"| node_lattice
node_geometry -->|"defines regions"| node_solver
node_main -->|"registers callback"| node_callbacks
node_callbacks -->|"reports progress"| node_solver
node_sampling -->|"samples fields"| node_lattice
node_outputs -->|"writes HDF5"| node_hdf5
node_outputs -->|"writes VTK"| node_vtk
node_design -->|"supports adjoint control"| node_optimization
node_optimization -->|"gets and sets parameters"| node_parameters
node_solver -->|"uses MPI"| node_mpi
node_solver -.->|"uses CUDA or HIP"| node_accelerator
node_solver -.->|"couples DEM"| node_particles
node_solver -.->|"couples force interface"| node_remote
node_solver -.->|"uses turbulence model"| node_turbulence

click node_main "https://github.com/cfd-go/tclb/blob/master/src/main.cpp"
click node_handler "https://github.com/cfd-go/tclb/blob/master/src/Handlers.h"
click node_factory "https://github.com/cfd-go/tclb/blob/master/src/HandlerFactory.h"
click node_handlerbase "https://github.com/cfd-go/tclb/blob/master/src/Handlers/vHandler.h"
click node_actions "https://github.com/cfd-go/tclb/tree/master/src/Handlers"
click node_design "https://github.com/cfd-go/tclb/blob/master/src/Handlers/Design.cpp"
click node_optimization "https://github.com/cfd-go/tclb/blob/master/src/Handlers/OptimalControl.cpp"
click node_parameters "https://github.com/cfd-go/tclb/blob/master/src/Handlers/acParam.cpp"
click node_solver "https://github.com/cfd-go/tclb/tree/master/src"
click node_lattice "https://github.com/cfd-go/tclb/tree/master/src"
click node_dynamics "https://github.com/cfd-go/tclb/tree/master/models"
click node_geometry "https://github.com/cfd-go/tclb/blob/master/src/Geometry.h"
click node_callbacks "https://github.com/cfd-go/tclb/blob/master/src/Handlers/Callback.cpp"
click node_sampling "https://github.com/cfd-go/tclb/blob/master/src/Sampler.cpp"
click node_outputs "https://github.com/cfd-go/tclb/tree/master/src/Handlers"
click node_hdf5 "https://github.com/cfd-go/tclb/blob/master/src/hdf5Lattice.cpp"
click node_vtk "https://github.com/cfd-go/tclb/blob/master/src/vtkOutput.cpp"
click node_particles "https://github.com/cfd-go/tclb/blob/master/src/lammps.cpp"
click node_remote "https://github.com/cfd-go/tclb/blob/master/src/RemoteForceInterface.cpp"
click node_turbulence "https://github.com/cfd-go/tclb/blob/master/src/SyntheticTurbulence.cpp"

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_main,node_handler,node_factory,node_handlerbase,node_user toneBlue
class node_solver,node_lattice,node_dynamics,node_geometry toneAmber
class node_actions,node_design,node_optimization,node_parameters toneMint
class node_callbacks,node_sampling,node_outputs,node_hdf5,node_vtk toneRose
class node_particles,node_remote,node_turbulence,node_mpi,node_accelerator,node_config toneIndigo
```

## Components

### Run orchestration

- [Runtime entry](https://github.com/cfd-go/tclb/blob/master/src/main.cpp): `src/main.cpp`
- [Handler dispatch](https://github.com/cfd-go/tclb/blob/master/src/Handlers.h): `src/Handlers.h`
- [Handler factory](https://github.com/cfd-go/tclb/blob/master/src/HandlerFactory.h): `src/HandlerFactory.h`
- [Handler lifecycle](https://github.com/cfd-go/tclb/blob/master/src/Handlers/vHandler.h): `src/Handlers/vHandler.h`

### LBM simulation

- [Solver state](https://github.com/cfd-go/tclb/tree/master/src): `src`
- [Lattice state](https://github.com/cfd-go/tclb/tree/master/src): `src`
- [LBM dynamics](https://github.com/cfd-go/tclb/tree/master/models): `models`
- [Geometry and regions](https://github.com/cfd-go/tclb/blob/master/src/Geometry.h): `src/Geometry.h`

### Control and optimization

- [Run controls](https://github.com/cfd-go/tclb/tree/master/src/Handlers): `src/Handlers`
- [Design handlers](https://github.com/cfd-go/tclb/blob/master/src/Handlers/Design.cpp): `src/Handlers/Design.cpp`
- [Adjoint optimization](https://github.com/cfd-go/tclb/blob/master/src/Handlers/OptimalControl.cpp): `src/Handlers/OptimalControl.cpp`
- [Model parameters](https://github.com/cfd-go/tclb/blob/master/src/Handlers/acParam.cpp): `src/Handlers/acParam.cpp`

### Sampling and output

- [Runtime callbacks](https://github.com/cfd-go/tclb/blob/master/src/Handlers/Callback.cpp): `src/Handlers/Callback.cpp`
- [Field sampling](https://github.com/cfd-go/tclb/blob/master/src/Sampler.cpp): `src/Sampler.cpp`
- [Output handlers](https://github.com/cfd-go/tclb/tree/master/src/Handlers): `src/Handlers`
- [HDF5 output](https://github.com/cfd-go/tclb/blob/master/src/hdf5Lattice.cpp): `src/hdf5Lattice.cpp`
- [VTK output](https://github.com/cfd-go/tclb/blob/master/src/vtkOutput.cpp): `src/vtkOutput.cpp`

### Coupling and parallelism

- [Particle coupling](https://github.com/cfd-go/tclb/blob/master/src/lammps.cpp): `src/lammps.cpp`
- [Remote force](https://github.com/cfd-go/tclb/blob/master/src/RemoteForceInterface.cpp): `src/RemoteForceInterface.cpp`
- [Synthetic turbulence](https://github.com/cfd-go/tclb/blob/master/src/SyntheticTurbulence.cpp): `src/SyntheticTurbulence.cpp`
- **MPI runtime**
- **GPU runtime**

### Other components

- **Simulation user**
- **XML configuration**

## Connections

- Simulation user → Runtime entry: launches
- Simulation user → XML configuration: provides
- Runtime entry → XML configuration: parses
- Runtime entry → Solver state: initializes
- Runtime entry → Handler dispatch: constructs
- Handler dispatch → Handler factory: creates
- Handler dispatch → Handler lifecycle: dispatches lifecycle
- Handler factory → Run controls: selects handlers
- Handler factory → Design handlers: selects handlers
- Handler dispatch → Solver state: passes solver
- Solver state → Lattice state: owns state
- LBM dynamics → Lattice state: updates fields
- Geometry and regions → Solver state: defines regions
- Runtime entry → Runtime callbacks: registers callback
- Runtime callbacks → Solver state: reports progress
- Field sampling → Lattice state: samples fields
- Output handlers → HDF5 output: writes HDF5
- Output handlers → VTK output: writes VTK
- Design handlers → Adjoint optimization: supports adjoint control
- Adjoint optimization → Model parameters: gets and sets parameters
- Solver state → MPI runtime: uses MPI
- Solver state → GPU runtime: uses CUDA or HIP
- Solver state → Particle coupling: couples DEM
- Solver state → Remote force: couples force interface
- Solver state → Synthetic turbulence: uses turbulence model