# iamkartik0704/fluidslab architecture

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

- Interactive diagram: https://gitdiagram.com/iamkartik0704/fluidslab
- Repository: https://github.com/iamkartik0704/fluidslab

## Overview

This repository implements a Go fluid-dynamics solver, with dam-break simulation as its clearest user-facing workflow and cavity-flow and single-phase modes also exposed by the CLI. The CLI configures a simulation, advances it, reports diagnostics, and can save alpha-field snapshots. Solver modules cover grid/state, time stepping, momentum prediction, VOF transport, pressure projection, and Poisson solving. The command directories also contain research and diagnostic programs for convergence, advection, cavity profiles, hydrostatics, and solver performance. Internal solver connections are shown as unverified where excerpts did not establish call ownership.

Main entry points: [`internal/solver/sim.go`](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/sim.go) (Simulation orchestration), [`cmd/dambreak/main.go`](https://github.com/iamkartik0704/fluidslab/blob/main/cmd/dambreak/main.go) (Dam-break CLI), [`internal/solver/project.go`](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/project.go) (Velocity projection), [`internal/solver/poisson.go`](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/poisson.go) (Poisson solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Simulation runtime"]
  node_dam_cli["Dam-break CLI<br/>[main.go]"]
  node_simulation["Simulation orchestration<br/>[sim.go]"]
  node_config["Simulation configuration<br/>[config.go]"]
  node_grid["Grid geometry<br/>[grid.go]"]
  node_fields["Flow fields<br/>[fields.go]"]
end

subgraph group_numerics["Numerical solver"]
  node_timestep["Timestep selection<br/>[timestep.go]"]
  node_predictor["Momentum predictor<br/>[predictor.go]"]
  node_vof["VOF transport<br/>[vof.go]"]
  node_project["Velocity projection<br/>[project.go]"]
  node_poisson["Poisson solver<br/>[poisson.go]"]
  node_boundary["Boundary conditions<br/>[bc.go]"]
  node_properties["Fluid properties<br/>[props.go]"]
end

subgraph group_studies["Research workflows"]
  node_dam_studies["Dam-break studies<br/>[main.go]"]
  node_front_study["Front convergence<br/>[main.go]"]
  node_advection_study["Advection comparison<br/>[main.go]"]
  node_cavity_study["Cavity studies<br/>[main.go]"]
  node_tg_study["Taylor-Green studies<br/>[main.go]"]
end

subgraph group_diagnostics["Diagnostics and output"]
  node_hydro_check["Hydrostatic check<br/>[main.go]"]
  node_poisson_bench["Poisson benchmark<br/>[main.go]"]
  node_cavity_diag["Cavity diagnosis<br/>[main.go]"]
  node_longrun["Long-run snapshots<br/>[main.go]"]
end

node_user(("CLI user"))

node_user -->|"configures and runs"| node_dam_cli
node_dam_cli -->|"creates and advances"| node_simulation
node_simulation -.->|"uses"| node_config
node_simulation -.->|"uses"| node_grid
node_simulation -.->|"updates"| node_fields
node_simulation -.->|"selects timestep"| node_timestep
node_simulation -.->|"predicts momentum"| node_predictor
node_simulation -.->|"transports interface"| node_vof
node_simulation -.->|"projects velocity"| node_project
node_project -.->|"solves pressure"| node_poisson
node_simulation -.->|"applies boundaries"| node_boundary
node_simulation -.->|"updates properties"| node_properties
node_dam_studies -->|"runs simulations"| node_simulation
node_front_study -->|"runs simulations"| node_simulation
node_advection_study -->|"compares runs"| node_simulation
node_cavity_study -->|"runs cavity flow"| node_simulation
node_tg_study -->|"runs vortex cases"| node_simulation
node_hydro_check -->|"checks pressure"| node_simulation
node_poisson_bench -->|"benchmarks solves"| node_poisson
node_cavity_diag -->|"measures cavity flow"| node_simulation
node_longrun -->|"runs and samples"| node_simulation

click node_dam_cli "https://github.com/iamkartik0704/fluidslab/blob/main/cmd/dambreak/main.go"
click node_simulation "https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/sim.go"
click node_config "https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/config.go"
click node_grid "https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/grid.go"
click node_fields "https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/fields.go"
click node_timestep "https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/timestep.go"
click node_predictor "https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/predictor.go"
click node_vof "https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/vof.go"
click node_project "https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/project.go"
click node_poisson "https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/poisson.go"
click node_boundary "https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/bc.go"
click node_properties "https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/props.go"
click node_dam_studies "https://github.com/iamkartik0704/fluidslab/blob/main/cmd/b_study/main.go"
click node_front_study "https://github.com/iamkartik0704/fluidslab/blob/main/cmd/frontconv/main.go"
click node_advection_study "https://github.com/iamkartik0704/fluidslab/blob/main/cmd/advcompare/main.go"
click node_cavity_study "https://github.com/iamkartik0704/fluidslab/blob/main/cmd/c_study/main.go"
click node_tg_study "https://github.com/iamkartik0704/fluidslab/blob/main/cmd/c_study2/main.go"
click node_hydro_check "https://github.com/iamkartik0704/fluidslab/blob/main/cmd/hydrotest/main.go"
click node_poisson_bench "https://github.com/iamkartik0704/fluidslab/blob/main/cmd/poissonbench/main.go"
click node_cavity_diag "https://github.com/iamkartik0704/fluidslab/blob/main/cmd/cavitydiag/main.go"
click node_longrun "https://github.com/iamkartik0704/fluidslab/blob/main/cmd/longrun/main.go"

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_dam_cli,node_simulation,node_config,node_grid,node_fields,node_user toneBlue
class node_timestep,node_predictor,node_vof,node_project,node_poisson,node_boundary,node_properties toneAmber
class node_dam_studies,node_front_study,node_advection_study,node_cavity_study,node_tg_study toneMint
class node_hydro_check,node_poisson_bench,node_cavity_diag,node_longrun toneRose
```

## Components

### Simulation runtime

- [Dam-break CLI](https://github.com/iamkartik0704/fluidslab/blob/main/cmd/dambreak/main.go): `cmd/dambreak/main.go`
- [Simulation orchestration](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/sim.go): `internal/solver/sim.go`
- [Simulation configuration](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/config.go): `internal/solver/config.go`
- [Grid geometry](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/grid.go): `internal/solver/grid.go`
- [Flow fields](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/fields.go): `internal/solver/fields.go`

### Numerical solver

- [Timestep selection](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/timestep.go): `internal/solver/timestep.go`
- [Momentum predictor](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/predictor.go): `internal/solver/predictor.go`
- [VOF transport](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/vof.go): `internal/solver/vof.go`
- [Velocity projection](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/project.go): `internal/solver/project.go`
- [Poisson solver](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/poisson.go): `internal/solver/poisson.go`
- [Boundary conditions](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/bc.go): `internal/solver/bc.go`
- [Fluid properties](https://github.com/iamkartik0704/fluidslab/blob/main/internal/solver/props.go): `internal/solver/props.go`

### Research workflows

- [Dam-break studies](https://github.com/iamkartik0704/fluidslab/blob/main/cmd/b_study/main.go): `cmd/b_study/main.go`
- [Front convergence](https://github.com/iamkartik0704/fluidslab/blob/main/cmd/frontconv/main.go): `cmd/frontconv/main.go`
- [Advection comparison](https://github.com/iamkartik0704/fluidslab/blob/main/cmd/advcompare/main.go): `cmd/advcompare/main.go`
- [Cavity studies](https://github.com/iamkartik0704/fluidslab/blob/main/cmd/c_study/main.go): `cmd/c_study/main.go`
- [Taylor-Green studies](https://github.com/iamkartik0704/fluidslab/blob/main/cmd/c_study2/main.go): `cmd/c_study2/main.go`

### Diagnostics and output

- [Hydrostatic check](https://github.com/iamkartik0704/fluidslab/blob/main/cmd/hydrotest/main.go): `cmd/hydrotest/main.go`
- [Poisson benchmark](https://github.com/iamkartik0704/fluidslab/blob/main/cmd/poissonbench/main.go): `cmd/poissonbench/main.go`
- [Cavity diagnosis](https://github.com/iamkartik0704/fluidslab/blob/main/cmd/cavitydiag/main.go): `cmd/cavitydiag/main.go`
- [Long-run snapshots](https://github.com/iamkartik0704/fluidslab/blob/main/cmd/longrun/main.go): `cmd/longrun/main.go`

### Other components

- **CLI user**

## Connections

- CLI user → Dam-break CLI: configures and runs (evidence: `cmd/dambreak/main.go`)
- Dam-break CLI → Simulation orchestration: creates and advances (evidence: `cmd/dambreak/main.go`)
- Simulation orchestration → Simulation configuration: uses
- Simulation orchestration → Grid geometry: uses
- Simulation orchestration → Flow fields: updates
- Simulation orchestration → Timestep selection: selects timestep
- Simulation orchestration → Momentum predictor: predicts momentum
- Simulation orchestration → VOF transport: transports interface
- Simulation orchestration → Velocity projection: projects velocity
- Velocity projection → Poisson solver: solves pressure
- Simulation orchestration → Boundary conditions: applies boundaries
- Simulation orchestration → Fluid properties: updates properties
- Dam-break studies → Simulation orchestration: runs simulations (evidence: `cmd/b_study/main.go`)
- Front convergence → Simulation orchestration: runs simulations (evidence: `cmd/frontconv/main.go`)
- Advection comparison → Simulation orchestration: compares runs (evidence: `cmd/advcompare/main.go`)
- Cavity studies → Simulation orchestration: runs cavity flow (evidence: `cmd/c_study/main.go`)
- Taylor-Green studies → Simulation orchestration: runs vortex cases (evidence: `cmd/c_study2/main.go`)
- Hydrostatic check → Simulation orchestration: checks pressure (evidence: `cmd/hydrotest/main.go`)
- Poisson benchmark → Poisson solver: benchmarks solves (evidence: `cmd/poissonbench/main.go`)
- Cavity diagnosis → Simulation orchestration: measures cavity flow (evidence: `cmd/cavitydiag/main.go`)
- Long-run snapshots → Simulation orchestration: runs and samples (evidence: `cmd/longrun/main.go`)
