# jainothniel/ludwig_multiple_particle architecture

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

- Interactive diagram: https://gitdiagram.com/jainothniel/ludwig_multiple_particle
- Repository: https://github.com/jainothniel/ludwig_multiple_particle

## Overview

#### Purpose and entry points
Ludwig is an ANSI C, distributed-memory simulation engine for complex fluids. It combines lattice-Boltzmann hydrodynamics with free-energy/order-parameter models for mixtures, colloids, gels, liquid crystals, and electrokinetics. The executable starts at `src/main.c`; top-level orchestration and time stepping are centered in `src/ludwig.c` and `src/control.c`. Builds are driven by `Makefile` and `src/Makefile`.

#### Runtime, parallelism, and execution model
MPI provides domain-decomposed distributed-memory execution through the parallel-environment and coordinate layers (`src/pe.c`, `src/coords.c`). A serial MPI compatibility implementation exists in `mpi_s/mpi_serial.c`. Compute kernels use TargetDP abstractions, selecting x86/OpenMP, CUDA, or HIP implementations via `target/target.h`, `target/target_cuda.c`, and `target/target_hip.c`. This is an HPC batch executable, not a service-oriented application.

#### Initialization and configuration boundary
Runtime input is parsed and transformed into model options and initialized state through `src/runtime.c`, `src/physics_rt.c`, and `src/build.c`. This separates textual run configuration from allocated simulation objects. Spatial decomposition, lattice geometry, and boundary topology are established before physics modules; runtime-specific `*_rt.c` files configure optional models without embedding input parsing in core numerical kernels.

#### Hydrodynamic lattice-Boltzmann core
The fluid solver owns lattice distributions, collision/propagation, and macroscopic hydrodynamic fields. Key components are `src/lb_model.c`, `src/collision.c`, and `src/propagation.c`; supported velocity lattices include `src/lb_d2q9.c`, `src/lb_d3q19.c`, and `src/lb_d3q27.c`. Hydrodynamics is exposed through `src/hydro.c`, while inflow/outflow and moving/sheared-domain conditions are implemented at the solver boundary, e.g. `src/lb_bc_inflow_rhou.c` and `src/leesedwards.c`.

#### Free-energy fields and coupled physics
A shared field/gradient layer (`src/field.c`, `src/field_grad.c`, `src/free_energy.h`) lets selected free-energy models produce chemical potentials, stresses, and forces for the fluid. Major model families include symmetric and ternary mixtures (`src/symmetric.c`, `src/fe_ternary.c`), Cahn–Hilliard transport (`src/cahn_hilliard.c`, `src/phi_cahn_hilliard.c`), liquid crystals/blue phases (`src/blue_phase.c`, `src/blue_phase_beris_edwards.c`), and electrokinetics (`src/psi.c`, `src/nernst_planck.c`). Couplers such as `src/phi_lb_coupler.c` transfer field-derived forcing into LB evolution.

#### Particles, solid boundaries, and interactions
Colloid state, links to the lattice, halo exchange, and motion are handled by `src/colloid.c`, `src/colloids.c`, and `src/colloids_halo.c`. Bounce-back coupling (`src/bbl.c`) forms the principal fluid–solid/particle boundary. Pair potentials, bonds, lubrication, walls, and map-defined solids provide optional mechanical interactions: `src/interaction.c`, `src/lubrication.c`, and `src/map.c`. These modules consume hydrodynamic/field forces and feed particle and boundary effects back into the time step.

#### I/O, observability, and external dependencies
Parallel output is abstracted behind `src/io_impl.c` with MPI-IO support in `src/io_impl_mpio.c`; aggregation, subfiles, metadata, and event scheduling are in `src/io_aggregator.c`, `src/io_subfile.c`, and `src/io_event.c`. Statistics modules emit derived physical measures alongside snapshots. MPI is fundamental; PETSc is an optional electrostatic solver integration (`src/psi_petsc.c`, `src/util_petsc.c`); bundled cJSON support is exposed through `src/util_cJSON.c`.

#### Validation and deployment surfaces
Regression inputs exercise full executable configurations under `tests/regression/`; unit coverage targets core C modules under `tests/unit/`. Platform/compiler configurations cover GCC, MPI, CUDA/NVCC, HIP, Cray, and Intel environments in `config/`, including `config/unix-mpicc-default.mk` and `config/unix-hipcc-nvcc.mk`. CI workflows execute regression and analysis in `.github/workflows/regression.yml` and `.github/workflows/codeql-analysis.yml`.

Main entry points: [`src/collision.c`](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/collision.c) (LB evolution), [`src/field.c`](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/field.c) (Field & gradient layer), [`src/build.c`](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/build.c) (Simulation builder), [`src/ludwig.c`](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/ludwig.c) (Time-step control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & Setup"]
  node_build["Build configurations<br/>build system"]
  node_main["Executable entry<br/>C entry point<br/>[main.c]"]
  node_orchestration["Time-step control<br/>simulation orchestrator<br/>[ludwig.c]"]
  node_control["Run control<br/>time-step controller<br/>[control.c]"]
  node_runtime_config["Runtime configuration<br/>input parser<br/>[runtime.c]"]
  node_builder["Simulation builder<br/>initialization<br/>[build.c]"]
  node_mpi_domain{{"MPI domain decomposition<br/>parallel environment<br/>[pe.c]"}}
  node_target{{"TargetDP kernels<br/>accelerator abstraction<br/>[target.h]"}}
end

subgraph group_solver["Simulation Core"]
  node_lb_core["LB evolution<br/>fluid solver<br/>[collision.c]"]
  node_lb_model["Velocity lattice model<br/>LB model<br/>[lb_model.c]"]
  node_hydro["Hydrodynamic fields<br/>macroscopic fluid state<br/>[hydro.c]"]
  node_lb_boundaries["Fluid boundaries<br/>LB boundary conditions"]
end

subgraph group_physics["Coupled Physics"]
  node_field_layer["Field &amp; gradient layer<br/>free-energy fields<br/>[field.c]"]
  node_phase_transport["Phase transport<br/>Cahn–Hilliard solver<br/>[cahn_hilliard.c]"]
  node_liquid_crystals["Liquid crystals<br/>blue-phase model<br/>[blue_phase.c]"]
  node_electrokinetics["Electrokinetics<br/>ion transport<br/>[nernst_planck.c]"]
  node_field_lb_coupler["Field–LB coupling<br/>force coupler<br/>[phi_lb_coupler.c]"]
  node_colloids["Colloids &amp; solids<br/>particle subsystem<br/>[colloids.c]"]
  node_bounce_back["Bounce-back coupling<br/>fluid–solid boundary<br/>[bbl.c]"]
end

subgraph group_output["Output &amp; Dependencies"]
  node_parallel_io[("Parallel I/O<br/>output abstraction<br/>[io_impl.c]")]
  node_petsc{{"PETSc solver<br/>optional dependency<br/>[psi_petsc.c]"}}
end

node_build -->|"builds"| node_main
node_main -->|"starts"| node_orchestration
node_orchestration -->|"advances"| node_control
node_runtime_config -->|"options"| node_builder
node_builder -->|"initializes"| node_mpi_domain
node_builder -->|"creates"| node_lb_core
node_builder -->|"creates"| node_field_layer
node_orchestration -->|"time step"| node_lb_core
node_control -->|"schedules output"| node_parallel_io
node_mpi_domain -->|"distributed lattice"| node_lb_core
node_target -->|"executes kernels"| node_lb_core
node_lb_model -->|"velocity set"| node_lb_core
node_lb_core -->|"updates"| node_hydro
node_lb_boundaries -->|"boundary treatment"| node_lb_core
node_field_layer -->|"drives"| node_phase_transport
node_field_layer -->|"supports"| node_liquid_crystals
node_field_layer -->|"supports"| node_electrokinetics
node_field_layer -->|"forces"| node_field_lb_coupler
node_field_lb_coupler -->|"applies forcing"| node_lb_core
node_hydro -->|"hydrodynamic forces"| node_colloids
node_colloids -->|"lattice links"| node_bounce_back
node_bounce_back -->|"solid boundary effects"| node_lb_core
node_electrokinetics -.->|"optional solve"| node_petsc
node_hydro -->|"snapshots and statistics"| node_parallel_io

click node_build "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/Makefile"
click node_main "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/main.c"
click node_orchestration "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/ludwig.c"
click node_control "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/control.c"
click node_runtime_config "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/runtime.c"
click node_builder "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/build.c"
click node_mpi_domain "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/pe.c"
click node_target "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/target/target.h"
click node_lb_core "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/collision.c"
click node_lb_model "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/lb_model.c"
click node_hydro "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/hydro.c"
click node_lb_boundaries "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/lb_bc_inflow_rhou.c"
click node_field_layer "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/field.c"
click node_phase_transport "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/cahn_hilliard.c"
click node_liquid_crystals "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/blue_phase.c"
click node_electrokinetics "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/nernst_planck.c"
click node_field_lb_coupler "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/phi_lb_coupler.c"
click node_colloids "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/colloids.c"
click node_bounce_back "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/bbl.c"
click node_parallel_io "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/io_impl.c"
click node_petsc "https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/psi_petsc.c"

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_build,node_main,node_orchestration,node_control,node_runtime_config,node_builder,node_mpi_domain,node_target toneBlue
class node_lb_core,node_lb_model,node_hydro,node_lb_boundaries toneAmber
class node_field_layer,node_phase_transport,node_liquid_crystals,node_electrokinetics,node_field_lb_coupler,node_colloids,node_bounce_back toneMint
class node_parallel_io,node_petsc toneRose
```

## Components

### Runtime & Setup

- [Build configurations](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/Makefile): build system · Selects compiler, MPI, and accelerator toolchains. · `Makefile`
- [Executable entry](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/main.c): C entry point · `src/main.c`
- [Time-step control](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/ludwig.c): simulation orchestrator · `src/ludwig.c`
- [Run control](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/control.c): time-step controller · `src/control.c`
- [Runtime configuration](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/runtime.c): input parser · Transforms textual input into model options. · `src/runtime.c`
- [Simulation builder](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/build.c): initialization · Allocates initialized simulation objects from configured options. · `src/build.c`
- [MPI domain decomposition](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/pe.c): parallel environment · `src/pe.c`
- [TargetDP kernels](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/target/target.h): accelerator abstraction · Selects x86/OpenMP, CUDA, or HIP execution. · `target/target.h`

### Simulation Core

- [LB evolution](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/collision.c): fluid solver · Owns distributions, collision, and propagation. · `src/collision.c`
- [Velocity lattice model](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/lb_model.c): LB model · `src/lb_model.c`
- [Hydrodynamic fields](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/hydro.c): macroscopic fluid state · `src/hydro.c`
- [Fluid boundaries](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/lb_bc_inflow_rhou.c): LB boundary conditions · Handles inflow/outflow and sheared-domain conditions. · `src/lb_bc_inflow_rhou.c`

### Coupled Physics

- [Field & gradient layer](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/field.c): free-energy fields · Provides gradients, chemical potentials, stresses, and forces. · `src/field.c`
- [Phase transport](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/cahn_hilliard.c): Cahn–Hilliard solver · `src/cahn_hilliard.c`
- [Liquid crystals](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/blue_phase.c): blue-phase model · `src/blue_phase.c`
- [Electrokinetics](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/nernst_planck.c): ion transport · `src/nernst_planck.c`
- [Field–LB coupling](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/phi_lb_coupler.c): force coupler · Transfers field-derived forcing into LB evolution. · `src/phi_lb_coupler.c`
- [Colloids & solids](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/colloids.c): particle subsystem · Manages colloid state, halo exchange, and motion. · `src/colloids.c`
- [Bounce-back coupling](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/bbl.c): fluid–solid boundary · `src/bbl.c`

### Output & Dependencies

- [Parallel I/O](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/io_impl.c): output abstraction · Writes snapshots through MPI-IO, aggregation, and subfiles. · `src/io_impl.c`
- [PETSc solver](https://github.com/jainothniel/ludwig_multiple_particle/blob/master/src/psi_petsc.c): optional dependency · Optional electrostatic solver integration. · `src/psi_petsc.c`

## Connections

- Build configurations → Executable entry: builds
- Executable entry → Time-step control: starts
- Time-step control → Run control: advances
- Runtime configuration → Simulation builder: options
- Simulation builder → MPI domain decomposition: initializes
- Simulation builder → LB evolution: creates
- Simulation builder → Field & gradient layer: creates
- Time-step control → LB evolution: time step
- Run control → Parallel I/O: schedules output
- MPI domain decomposition → LB evolution: distributed lattice
- TargetDP kernels → LB evolution: executes kernels
- Velocity lattice model → LB evolution: velocity set
- LB evolution → Hydrodynamic fields: updates
- Fluid boundaries → LB evolution: boundary treatment
- Field & gradient layer → Phase transport: drives
- Field & gradient layer → Liquid crystals: supports
- Field & gradient layer → Electrokinetics: supports
- Field & gradient layer → Field–LB coupling: forces
- Field–LB coupling → LB evolution: applies forcing
- Hydrodynamic fields → Colloids & solids: hydrodynamic forces
- Colloids & solids → Bounce-back coupling: lattice links
- Bounce-back coupling → LB evolution: solid boundary effects
- Electrokinetics → PETSc solver: optional solve
- Hydrodynamic fields → Parallel I/O: snapshots and statistics