CFDManager/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Read this first: the file is shared across branches

CLAUDE.md is deliberately untracked on every working branch — /CLAUDE.md sits in .gitignore on main, dev, research and rust. One physical file therefore survives every git checkout, so these notes stay put while the tree around them changes, and editing them never shows up in git status.

The master copy lives on the orphan branch notes, which holds this one file and nothing else, one commit per revision — that branch is both the backup and the change history. It shares no ancestor with any code branch, so it never merges into anything and never appears in a diff.

git show notes:CLAUDE.md > CLAUDE.md   # restore it in a fresh clone
git log --oneline notes                # history of these notes
git diff notes~1 notes                 # what changed in the last revision

After editing this file, publish the new revision — this touches neither the working tree nor the checked-out branch:

blob=$(git hash-object -w CLAUDE.md)
tree=$(printf '100644 blob %s\tCLAUDE.md\n' "$blob" | git mktree)
git branch -f notes "$(git commit-tree "$tree" -p notes -m 'CLAUDE.md: what changed')"
git push CFDManager notes

git clean -xfd deletes the working copy, since it is untracked — restore it with the first command above.

Drift is guarded automatically: a PostToolUse hook (.claude/hooks/notes_guard.py, wired in .claude/settings.local.json) compares this file against notes after every edit and demands a described commit when the two diverge — necessary because an untracked file never shows up in git status. Both live outside git, excluded through .git/info/exclude rather than .gitignore, so no branch has to carry them.

The consequence to keep in mind: this file describes the whole project, but no single branch contains all of it. Before assuming a directory exists, check git branch --show-current against the map below — rust/ and docs/theory/2d_solver/ each live on one branch only.

Branch map

branch	what it adds	trees present
main, dev	baseline; both at the same commit, one past the initial import — and that commit only untracks CLAUDE.md	src/, shaders/, tests/, docs/theory/ (Python)
research	the CFD work — kbc2d, a Rust LBM solver, its validation campaign and Docker images	+ docs/theory/2d_solver/, + docs/origins/Grad's_aproximation.pdf
rust	a Rust port of the C++ editor plus a measured C++/Rust comparison	+ rust/, docs/rust_vs_cpp.md

All five branches (including notes) are fully pushed to the CFDManager remote; verify with git ls-remote CFDManager rather than trusting a stale tracking ref.

Nothing is shared between the two Rust efforts: docs/theory/2d_solver/ (a CFD solver, branch research) and rust/ (a port of the 3D editor, branch rust) are unrelated projects that merely both happen to be Rust. Neither is part of the CMake build — CMakeLists.txt never mentions either tree.

A checkout away from research does not remove docs/theory/2d_solver/ — the tracked sources vanish but the untracked artefacts stay, so on rust that directory contains only out/, target/, wake.gif and demo_wake.gif and looks like a mutilated copy of the solver. To read the solver from another branch, go through git rather than the filesystem:

git show research:docs/theory/2d_solver/src/math.rs
git archive research docs/theory/2d_solver | tar -x -C /tmp/kbc2d   # to grep it

Untracked leftovers you will see regardless of branch: build/, rust/target/, docs/theory/2d_solver/target/, the __pycache__ dirs under docs/theory/, and docs/theory/2d_solver/out/ plus the two ~9 MB GIFs beside it (campaign results — the user's data, do not clean). pipeline_cache.bin and imgui.ini are written next to whichever executable ran, i.e. in build/<preset>/src/app/ and rust/pipeline_cache.bin — not at the repo root.

build/ in this working tree is foreign and stale. Its CMakeCache.txt records CMAKE_HOME_DIRECTORY=C:/Users/ivan/UAS/SimV4(Not_KBC)/SimVulcan, and _deps/ carries a 262 MB nlohmann_json clone that this project never declares. Do not measure anything from it without re-configuring first.

---

SimVulcan — C++/Vulkan editor (all branches)

A minimal Vulkan 1.3 / C++20 3D model editor: three reference grid planes (XY, XZ, YZ) through the origin plus coloured X/Y/Z axes, an orbit camera, and .obj loading with selectable display modes (solid, wireframe, solid + wireframe). It runs no simulation — no compute pipeline or .comp shader exists anywhere, and Renderer.cpp disables async compute explicitly. It is a rendering skeleton with two ImGui windows, titled Viewport and Mesh (the class behind the second is MeshLoadPanel, which is why the docs keep calling it the "mesh load panel"). Unchanged since the initial commit on every branch — git log --all -- src returns exactly one commit.

Build

Prerequisites: Vulkan SDK (for glslangValidator), CMake 3.26+, Ninja, a C++20 compiler. Only CMake 3.26 and C++20 are actually enforced (CMakeLists.txt:1, :9-11). cmake/VulkanSetup.cmake:3 is find_package(Vulkan REQUIRED COMPONENTS glslangValidator) with no version argument, so the "SDK 1.3.290+" in README.md is a comment, not a check; the de-facto floor comes from the pinned volk 1.3.295 and vk-bootstrap v1.3.295. The compiler minimums (MSVC 19.36+, gcc 11+, clang 14+) are likewise README prose, enforced nowhere. On macOS the only hard constraint is CMAKE_OSX_ARCHITECTURES: arm64 in the preset; MoltenVK is mentioned in a message(STATUS).

cmake --preset windows-msvc-release
cmake --build --preset windows-msvc-release

Presets: windows-msvc-debug, windows-msvc-release, linux-gcc-release, linux-clang-release, macos-arm64-release (all Ninja, one dir per preset under build/<presetName>/). None of them pins a compiler — they inherit whatever the environment provides, so README.md's "MSVC / clang-cl" is aspirational.

The first configure fetches nine repositories via FetchContent (GLFW, GLM, volk, vk-bootstrap, VulkanMemoryAllocator, Dear ImGui, spdlog, tinyobjloader, Catch2) and needs network access. There is no GIT_SHALLOW, so each is a clone with full history, and no shared cache is configured (the only FETCHCONTENT_* variable set is FETCHCONTENT_QUIET OFF) — every new build directory downloads all of it again. Budget ~400 MB of sources / ~510 MB of _deps once built, not the 775 MB quoted in docs/rust_vs_cpp.md: that figure was measured on the foreign build/ tree described above and includes 262 MB of nlohmann_json that nothing here declares.

VK_NO_PROTOTYPES is not project-wide — there is no add_compile_definitions at project scope. It is set PUBLIC on exactly two targets, imgui (CMakeLists.txt:114) and simv_vk (src/vk/CMakeLists.txt:29). Because simv_core links simv_vk PRIVATE, the definition never reaches simv_mesh, simv_editor or simv_tests. Vulkan entry points load through volk.

Warnings come from simv_set_warnings (cmake/CompilerWarnings.cmake), called by all six targets: /W4 /permissive- /Zc:preprocessor /Zc:__cplusplus /wd4100 plus the defines _CRT_SECURE_NO_WARNINGS, NOMINMAX, WIN32_LEAN_AND_MEAN on MSVC; -Wall -Wextra -Wpedantic -Wno-unused-parameter -Wshadow -Wnon-virtual-dtor -Wold-style-cast -Wcast-align -Wunused -Woverloaded-virtual elsewhere. They are not errors — no /WX or -Werror anywhere. cmake/Sanitizers.cmake defines simv_enable_sanitizers (Debug-only; ASan only on MSVC, ASan+UBSan elsewhere) but no target calls it — wire it in manually when chasing memory bugs.

Running

The executable resolves SPIR-V relative to the working directory (FindSpvPath, src/vk/Shader.cpp:24-33, probes spirv/<rel> then current_path()/spirv/<rel> — the second probe is a no-op, since the first is already CWD-relative). Two SimVulcan POST_BUILD steps copy assets/ and the compiled spirv/ tree next to the executable, so run from the executable's own directory (build/<preset>/src/app/). main.cpp:40-50 additionally probes four ../ ancestors for assets/meshes. Meshes load at runtime through the Mesh panel.

Running writes two files into the CWD: pipeline_cache.bin (serialised VkPipelineCache, reloaded on the next start) and ImGui's imgui.ini (no IniFilename is ever set, so ImGui's default applies). Both are disposable — delete them if pipeline creation or the panel layout misbehaves.

ContextOptions::enableValidation / enableDebugUtils default to true (src/vk/Context.h:15-16) and nothing overrides them, so the Khronos validation layer is requested even in Release. The severity mask is error + warning only (Context.cpp:56-58), which makes the INFO branch of the callback dead code. Those messages go to raw spdlog::, i.e. spdlog's default logger — not the "simv" logger that core::Logger creates.

run.bat at the repo root is stale: it launches build/vs2022/src/app/Release/SimVulcan.exe, a path the Ninja presets never produce — while its own error message tells the user to run those presets. Do not point users at it without fixing the path first.

Tests

Catch2 unit tests, mesh bounds + welding. No GPU is touched at runtime, but the binary is not free of Vulkan: static-lib propagation through simv_mesh → simv_core → (PRIVATE) simv_vk makes simv_tests.exe link simv_vk, vk-bootstrap, imgui, volk and glfw3.

cmake --build --preset windows-msvc-debug --target simv_tests
ctest --preset windows-msvc-debug

windows-msvc-debug is the only preset with a testPreset — for the other configs, invoke ctest in build/<preset>/ directly.

There are exactly three TEST_CASEs, all in tests/unit/test_mesh.cpp: Mesh::RecalculateBounds finds AABB [mesh], WeldVertices collapses near-duplicate vertices and WeldVertices drops degenerate triangles (both [mesh][decimator]). Each is registered individually by catch_discover_tests, so either filter works:

ctest --preset windows-msvc-debug -R "WeldVertices" -V     # matches the last two
./build/windows-msvc-debug/tests/simv_tests.exe "[decimator]"
./build/windows-msvc-debug/tests/simv_tests.exe --list-tests

Architecture

Library / target map

Arrows below show the project edges; each target also links third-party libraries, and the visibility keywords matter more than they look.

SimVulcan (exe) → simv_core, simv_vk, simv_mesh, simv_editor   (all PRIVATE)
                  + glm, spdlog;  add_dependencies(… simv_shaders)
simv_core   → PUBLIC spdlog · PRIVATE simv_vk, glfw   (App owns Window + Renderer)
simv_editor → PUBLIC simv_core, simv_mesh, imgui, glm      (no Vulkan)
simv_mesh   → PUBLIC simv_core, glm, tinyobjloader         (no Vulkan)
simv_vk     → PUBLIC Vulkan::Headers, volk, vk-bootstrap, VMA, glfw, glm, spdlog
              PRIVATE imgui
simv_shaders → glslangValidator (GLSL → SPIR-V), an ALL custom target

The simv_core → simv_vk edge being PRIVATE is what keeps VK_NO_PROTOTYPES (and volk) from reaching the rest of the tree — see the Build section.

Namespaces follow directories: simv::core, simv::vk, simv::mesh, simv::editor. Each library exports src/ as its include root, so includes are written module-qualified (#include "mesh/Mesh.h", #include "vk/Renderer.h").

Frame loop

main.cpp creates core::App, which owns the core::Window and a vk::Renderer, then runs the loop. Each frame Renderer::DrawFrame acquires a swapchain image, calls the UI callback (between ImGui NewFrame/Render), then begins the command buffer and records the scene: grid + mesh into one dynamic-rendering pass with a depth attachment, followed by ImGui, then presents (2 frames in flight, vkQueueSubmit2 / VkImageMemoryBarrier2).

The acquire-before-callback ordering is the root of defect 2 below — keep it in mind before moving work into the callback.

main.cpp wires the editor via the UI callback: it draws the panels, applies mouse input to the editor::Camera, and pushes the resulting state into the renderer (SetRenderMode, SetGridVisible, SetViewProj). Mesh loads go through MeshLoadPanel's callback → Renderer::SetMeshCpu.

Mesh load path

MeshLoadPanel lists *.obj in the mesh directory (extension match is case-insensitive, so .OBJ shows up too) and kicks off mesh::LoadObjAsync (std::async(std::launch::async, …), std::future). The future is drained on the main thread at the top of MeshLoadPanel::Draw, before the first ImGui::Begin, so the OnLoaded callback — and therefore the GPU upload — always runs on the render thread. Loader exceptions surface as the panel's status string.

main.cpp's OnLoaded welds the mesh (WeldVertices, tolerance 1e-4), logs the counts, uploads via SetMeshCpu, and reframes the camera to the bbox radius. Despite the file name, mesh/MeshDecimator.h declares one function and implements only spatial-hash vertex welding (round-to-nearest cell hash, collapse near-duplicates, drop degenerate triangles, recompute bounds) — there is no LOD/decimation.

Non-obvious invariants (read before editing)

• All Vulkan lives in src/vk/. core/, mesh/, editor/ and app/ make no Vulkan API calls — a grep for volk|vulkan|Vk[A-Z] across them returns zero hits. vk::Renderer's public header is deliberately Vulkan-free (pImpl + glm/RenderMode only) so App can own it without pulling in volk. Keep it that way — do not leak Vk* types into the public interfaces of those modules. Note this is convention only: every library exports src/ publicly, so nothing stops a #include <volk.h> in mesh/; the compiler will not catch it.
• Single render pass with depth. Scene (grid + mesh) and ImGui draw into one vkCmdBeginRendering pass that has both a colour and a D32_SFLOAT depth attachment (depth storeOp is DONT_CARE). The ImGui backend is initialised with depthAttachmentFormat set so its pipeline matches the pass.
• Wireframe needs fillModeNonSolid. MeshRenderer builds a fill pipeline and a VK_POLYGON_MODE_LINE pipeline; the line pipeline uses a small static depth bias (constantFactor and slopeFactor both -1.0) so the overlay sits on top of the fill. The device feature is requested in Context. Culling is off (VK_CULL_MODE_NONE) — loaded models may have mixed winding.
• Camera is fixed on the origin. editor::Camera orbits (yaw/pitch/distance) the world origin; loaded models are recentred there via a translate-only model matrix. Projection uses Vulkan clip space (GLM_FORCE_DEPTH_ZERO_TO_ONE + Y flip, isolated to Camera.cpp — the macro appears nowhere else in the tree).
• Buffers. vk::GpuMesh owns the model's vertex/index buffers (staged upload on the dedicated transfer queue). GridRenderer builds a static host-visible mapped line buffer once in its constructor. Both scene renderers create pipeline layouts with one push-constant range and no pSetLayouts — no descriptor sets at all.
• Push-constant layout is a cross-file contract. MeshRenderer.cpp's anonymous MeshPC { mat4 mvp; vec4 color; } (range VERTEX|FRAGMENT) must stay byte-identical to the push_constant block in mesh.vert/mesh.frag; color.a is a flag, not alpha — mesh.frag does mix(base, base*shade, pc.color.a), so 1 = flat-shaded and 0 = constant colour for wireframe. GridRenderer pushes a bare mat4 (vertex stage only). Change either side and you must change both.
• Swapchain recreation rebuilds depth and sync objects. RecreateSwapDependent runs WaitIdle → swap->Recreate() → CreateDepth → per-frame imageAvailable semaphores (a failed acquire can leave one signalled) → per- swapchain-image renderFinished semaphores (the image count may change) → re-ensure both pipelines. Keep that ordering if you touch resize handling.
• Mesh upload stalls the device. SetMeshCpu/ClearMesh call WaitIdle before touching GpuMesh — acceptable because loads are rare; do not copy that pattern into per-frame paths. SetMeshCpu early-returns on an empty mesh before the wait.

Known defects (found by the Rust port, all still present here)

Porting the editor surfaced four real bugs that nobody was looking for. They are unfixed in the C++ tree on every branch; full write-up in docs/rust_vs_cpp.md (branch rust).

1. A source-level dependency cycle that the CMake graph hides. core::App owns vk::Renderer, and vk::Renderer takes a core::Window& — so the sources are mutually dependent. The CMake graph is acyclic, which is exactly why nothing complains: simv_vk links no project target at all, seeing core/Window.h through target_include_directories(simv_vk PUBLIC ..) and getting Window's symbols at executable link time. Cargo rejects the same shape outright, which is what surfaced it.
2. Mesh upload runs inside the frame. MeshLoadPanel::Draw calls OnLoaded from the UI callback, which Renderer::DrawFrame invokes after vkAcquireNextImageKHR; the handler calls SetMeshCpu → vkDeviceWaitIdle. Legal, and command recording has not started yet (vkBeginCommandBuffer comes later) — but it waits for device idle while holding an acquired swapchain image.
3. Two sources of truth for "is there a mesh". GpuMesh::IsValid() and Renderer's separate hasMesh flag must be kept consistent by hand; MeshRenderer::Draw then re-checks IsValid() a third time.
4. Mesh ready is never printed. ObjLoader::LoadObj logs to category MeshIO, and main.cpp's handler logs Mesh ready: … to the same category immediately after; the category throttles at 0.5 s and both are Info, so the second message is always dropped (only Warn/Error/Critical bypass the throttle). Post-weld counts have therefore never appeared in any log.

Also dead weight: vk::Buffer and vk::Image are used by nobody — 362 lines across four files, still compiled into simv_vk. GridRenderer, GpuMesh and the depth attachment all call VMA directly. Image::Desc even defaults to VK_IMAGE_TYPE_3D and an R32G32B32A32_SFLOAT storage image, a leftover from some compute/CFD design. Note README.md:53-54 still lists both as part of the working Vulkan stack — that line is wrong.

Shaders

GLSL under shaders/editor/ (mesh.{vert,frag}, grid.{vert,frag}). simv_shaders compiles each to build/<preset>/spirv/editor/<name>.<stage>.spv — the stage suffix is kept, so the real artefacts are mesh.vert.spv, mesh.frag.spv and so on — targeting vulkan1.3, with shaders/ as the -I root (so #include "common/foo.glsl" would resolve). The glob is CONFIGURE_DEPENDS, so a new shader is picked up automatically, but it matches only editor/*.vert and editor/*.frag; a .comp or .geom dropped there is silently ignored.

mesh.frag reconstructs a flat normal from screen-space derivatives, so the mesh vertex stream carries only positions (tight float3, one binding, one attribute). The grid pipeline is different — two attributes, position + colour. The Rust port on branch rust compiles this same directory (build.rs reaches ../../../shaders) with the same glslangValidator flags — a shader change affects both versions.

Logging

simv::core::Logger (spdlog-backed, singleton) with category-based throttling. Log via LogFmt(LogCategory, LogLevel, fmt, args...). Categories: Core, Vulkan, MeshIO, UI, Test (printed as core, vk, mesh, ui, test).

Two things the API surface does not tell you:

• Only MeshIO is ever used. The entire tree contains three LogFmt call sites — two in ObjLoader.cpp, one in main.cpp. Core, Vulkan, UI and Test have zero.
• The runtime knobs are never turned. SetMinLevel / SetThrottle / SetEnabled exist but have no callers, and no flag, env var or UI control is wired to them. They are settable programmatically, not configurable.

And the whole of vk/ logs through raw spdlog::, never through LogFmt — as do core/App.cpp and main.cpp's fatal handler. That bypasses not just the category throttle but the "simv" logger entirely (different pattern, unaffected by Logger::Shutdown()), which is the only reason the GPU name survives startup; see defect 4 above.

---

rust/ — Rust port of the editor (branch rust only)

A port of SimVulcan from C++20 to Rust, existing for comparison: both versions sit side by side and build independently. Same Vulkan 1.3, dynamic rendering, synchronization2, and the same shaders/ directory.

The declared MSRV is wrong. rust/Cargo.toml:13 says rust-version = "1.82" (and rust/README.md repeats it), but the locked egui/egui-winit/epaint 0.36.1 each declare rust-version = "1.95", so Cargo refuses to resolve on 1.82. The real minimum is 1.95; the tree is tested on 1.97.1. The Vulkan SDK is needed for glslangValidator only.

cd rust
cargo build --release
./target/release/SimVulcan      # SimVulcan.exe on Windows; package is simv-app
cargo test                      # 13 tests + 1 #[ignore]d diagnostic

Work on the code with plain cargo build, not --release. The release profile sets lto = "thin" with codegen-units = 1, which makes a one-line edit re-optimise and relink the whole binary: 52 s versus ~5 s in debug.

The tests cover mesh bounds, welding (three cases), Cube.obj loading and its error path, camera clip space and zoom/pitch clamping, and logger category mapping. They need no GPU but are not pure math: the loader tests read real files from assets/meshes via $CARGO_MANIFEST_DIR, so they require the repo checkout. The ignored weld_counts_for_bundled_assets is the diagnostic that produced the loader parity table below.

Five crates mirror the CMake target map, and the "all Vulkan in one place" invariant is compiler-enforced here — simv-mesh and simv-editor have neither ash nor simv-vk among their dependencies. Third-party deps in full (each crate also depends on the workspace crates shown):

crates/simv-core/    logger, window          → log, chrono, winit
crates/simv-mesh/    .obj, welding, bounds   → glam, tobj, log, thiserror
                                              (+ simv-core)
crates/simv-vk/      all Vulkan + build.rs   → ash, ash-window, raw-window-handle,
                     (GLSL→SPIR-V)             gpu-allocator, egui, egui-winit,
                                               egui-ash-renderer, winit, glam,
                                               bytemuck, log, thiserror
                                              (+ simv-core, simv-mesh)
crates/simv-editor/  camera, input, panels   → egui, glam, log
                                              (+ simv-core, simv-mesh)
crates/simv-app/     App and entry point     → the four crates above
                                               + egui, winit, glam, log, anyhow

Structural differences from C++, each with a reason (full list in docs/rust_vs_cpp.md): App lives in the executable crate (Cargo rejects the target-graph cycle); the UI closure returns a FrameState instead of calling setters (it is invoked from a renderer method, so it cannot borrow the renderer) — Renderer's public API has no Set* methods at all; the loaded mesh is uploaded after draw_frame returns, not from inside it; Buffer and Image are actually used; no pImpl (private module fields give the same isolation); winit owns the event loop, so ShouldClose/PollEvents are gone.

SPIR-V is embedded via include_bytes! from build.rs, so there is no runtime shader lookup. Two runtime path dependencies remain, though, so "runs from any directory" is not quite true: assets/meshes is searched from the executable's ancestors and then the CWD's, and pipeline_cache.bin is written next to the exe. Unlike the C++ build, nothing copies assets/ — the port finds the repo-root copy by walking up from rust/target/<profile>/.

The UI toolkit differs by design: egui instead of Dear ImGui, because the imgui crate is bindings and would compile ~40k lines of C++, defeating the point of comparing ecosystems.

Comparison result (docs/rust_vs_cpp.md)

The document deliberately picks no winner. Machine: i5-1135G7 / Iris Xe / Windows 11, both builds release.

	C++	Rust
lines of code	2434	2976 (+22 %)
release from scratch	114 s	194 s (thin LTO) · 182 s (no LTO)
release, one-file edit	4.4 s	52.3 s (LTO) · 5.5 s (no LTO)
debug from scratch / one-file edit	112 s / 8.0 s	83 s / 5.2 s
release exe	1.18 MB	5.80 MB
dependency sources	~400 MB per build dir	80 MB shared registry
startup to renderer ready (best of 3)	1068 ms	754 ms
CPU at 60 Hz	11.2 %	12.6 %

Frame rate measures nothing — both are FIFO on a 60 Hz screen. The 1.4 pp CPU gap is egui rebuilding its layout every frame, not the language. The one sharp build cell (52 s) is the price of thin LTO, not of Rust — with LTO off it is 5.5 s against 4.4 s. Note the document's summary claim that no measurement differs by an order of magnitude is false on its own numbers: 52.3 / 4.4 = 11.9×. Every other cell stays under 10×.

The +22 % line count is mostly, not almost entirely, the missing vk-bootstrap replacement: Context + Swapchain go from 301 to 606 lines, which is 305 of the 542-line overhang (56 %); the whole Vulkan layer accounts for 346 (64 %). The rest is real — mesh +117, editor +104, app +90, core −64, and 176 in-module test lines against C++'s 51.

Loader parity: cow.obj matches exactly (2451 verts / 4898 tris); plane.obj differs by 0.13 %, entirely due to the reading libraries (tobj drops the 35 vertices no face references; fan triangulation of n-gons versus tinyobjloader's earcut).

Known errors in docs/rust_vs_cpp.md (numbers below are the measured truth): line-count total is 2976 / 494 comments, not 2962 / 492 — the mesh row is stale by the 17 lines of the ignored diagnostic test; "775 MB per build dir" is the foreign build/ tree (see the Build section) and so is the matching "10 packages in the C++ graph" — there are nine; the Rust package graph is 82, not 76; plane.obj has 119 faces with five or more vertices, not 121; "three Catch2 tests ported verbatim" should be all three ported, two more added; and Renderer::Impl's destructor is 22 lines, not thirty.

---

docs/theory/2d_solver/ — kbc2d, Rust LBM solver (branch research only)

The active research work. A D2Q9 Lattice Boltzmann solver with the entropic KBC collision operator, written from scratch in Rust (not a port): flow past bodies in a channel, two interchangeable backends, a ×2 nested AMR patch, sub-grid wall models, and GIF output locked to physical flow time. Cargo.toml declares Rust 1.75+; the Dockerfile pins rust:1.97-bookworm. Physics is anchored to the method authors' papers in docs/origins/; formula references in the code follow the 2D paper (arXiv:1507.02509), the only arXiv id in the tree, with the wall models citing Dorschner et al. JFM 801 (2016) for grad and Malaspinas 2015 / Coreixas et al. PRE 96 for hrr.

README.md there is the authoritative status/validation log (609 lines: what is verified, against which equation, with what measured numbers) and bench/README.md (248 lines) covers the validation campaign. Read them before changing physics or defaults — most defaults are the outcome of a documented measurement, not a guess.

Build / test / run

cd docs/theory/2d_solver
cargo build --release                        # with the GPU backend (default feature `gpu`)
cargo build --release --no-default-features  # CPU only, no wgpu
cargo test --release                         # 29 fast tests
cargo test --release -- --include-ignored    # + 4 long CPU runs (~18 s)
cargo test --release -- --ignored taylor_green_kbc_vs_bgk --nocapture   # one diagnostic

33 #[test] functions exist (18 in math.rs, 9 in cpu.rs, 6 in gif.rs); the 4 #[ignore]d ones are all in cpu.rs and are two reference benchmarks plus two diagnostics, not four benchmarks.

Never build --no-default-features last. Both builds write the same target/release/kbc2d, so a CPU-only build silently overwrites the wgpu one and --backend gpu then refuses to run. Order: no-default-features first, normal build second.

./target/release/kbc2d --shape cylinder --size 24 --re 150 \
    --nx 480 --ny 240 --steps 40000 --sponge-len 32 \
    --gif wake.gif --gif-field vorticity --verbose full

--help groups every key by role, under Russian headings — Физика, Сетка, Тело, Время, Схема, Анимация, Вывод. Note --time <seconds> as an alternative to --steps (the two conflict): a step is not a fixed slice of time (dt = u_lat * dx / u_phys, literally math.rs's Units::new), so refining the cell silently shortens a fixed step count.

Defaults worth knowing beyond the three discussed below: --backend is cpu, --collision kbc, --outlet extrapolate, --case channel, --refine 2.

File roles — one concern each

src/ holds exactly these five files — no lib.rs, no benches/, no integration tests.

file	owns
src/math.rs	all solver mathematics, nodewise and pure: D2Q9 lattice, product-form entropic equilibrium, shear projector, γ stabiliser, collision, Zou–He, body SDFs, wall-model closures, unit conversion, spectral diagnostics (strouhal). Tests against the papers' formulas live here. pub type R = f64.
src/cpu.rs	CPU backend: AoS layout, rayon, and the shared topology — Geom::build (masks), Bouzidi link assembly, Patch (AMR level coupling), initial_field. Also holds the four ignored reference runs.
src/gpu.rs	GPU backend: wgpu + WGSL (Vulkan/DX12/Metal), SoA layout, f32. Re-implements the physics line-for-line in WGSL but imports topology from cpu rather than duplicating it.
src/main.rs	CLI, problem assembly, step loop, live output, report, CSV. Owns the Spec / StepRec / FieldKind contract shared by both backends.
src/gif.rs	encoding, palettes, normalisation, the HUD, delay dithering, and the physical-time frame timing.

Invariants (read before editing)

• Physics is written twice, topology once. gpu.rs mirrors math.rs by hand in WGSL; masks, Bouzidi links and the patch frame come from cpu::Geom / cpu::Patch / cpu::initial_field. Keep it that way — a past regression had the GPU silently running Bouzidi for --wall staircase, caught only because two models produced bit-identical output where they had to differ. Backend parity is a hard requirement and bench/parity.py checks it: CPU f64 vs GPU f32 agree to 4–5 significant digits, and for each wall model the two backends agree to 0.007 % on Cd. (That number is backend parity, not agreement between wall models — those differ from one another by ~1 %.)
• The backends have different step contracts. Backend in main.rs is an enum, not a trait: CPU step() returns one StepRec, GPU advance(out) / flush(out) push a batch — results accumulate in a 128-slot ring (HIST, declared identically in Rust and WGSL) and sync once per batch. Adding a per-step GPU readback outside StepRec reintroduces a map_async + poll(Wait) per step, which cost ~8× throughput before batching (measured 863 → 6715 steps/s).
• GREL = 1e-8 is a relative threshold. The test is den > GREL * nrm, where den = ⟨Δh|Δh⟩ and nrm = ⟨Δ|Δ⟩ — so GREL is a fraction of the full non-equilibrium norm, not of ⟨Δh|Δh⟩ itself. ⟨Δh|Δh⟩ is quadratic in non-equilibrium and physically tiny (~1e-7…1e-9), so an absolute threshold fires almost everywhere and silently substitutes γ = 2, i.e. plain LBGK instead of KBC. The report prints the degenerate-node fraction; on a healthy threshold it must be ~0 (except the very first step).
• GPU is f32 and cannot be otherwise — WGSL has no f64 type at all, so no hardware helps. Convergence studies therefore run on CPU, everything else on GPU; below a true error of ~1e-3 f32 diverges from f64 by an order of magnitude. The statistics reductions (ρ, ⟨γ⟩, node and degenerate counts) use compensated Kahan–Neumaier summation via kadd. The force/torque kernel does not — it accumulates in plain f32 and reduces with a naive tree. Both README.md:366 and earlier revisions of this file claim otherwise; the code is the authority.
• GPU dispatch is 2-D with a linear index rebuilt in the shader (lin() / wlin()), lifting the 65535-workgroup limit that capped grids at ~2048². The workgroup → node mapping stays exactly linear, which is what lets the reductions keep working; verified to 4096×4096.
• Population storage has two binding layouts. Normally two bindings (f and post). When the adapter's max binding size is small (dzn/WSL2 caps a binding at 128 MiB while allowing a 2047 MiB buffer), each array is split across nine bindings — one per direction, 18 in total — raising the ceiling from 3.73 M to 33.5 M nodes. The choice comes from adapter limits. The split layout is the one built out of switch statements in fget/fset/pget/pset; the combined layout has none, which is the whole reason it is kept. Both give identical numbers; the split costs 5.7 % bandwidth. Force it with KBC2D_SPLIT_POPULATIONS set to anything other than 0.
• MAX_BODY_BUCKETS = 4. Geometry is assembled from any number of bodies, but per-body force is bucketed — bodies beyond the fourth have their forces merged (min(body, MAXB-1) in three places), and the CLI warns when that happens.
• Defaults encode measurements, not taste: --init uniform (a rest start pumps a quarter-wave channel resonance to 75 % of U and wrecks St/Cd/Cl — and the sponge cannot remove it, since a standing mode has its pressure node exactly where the sponge sits); --kbc-model n1 (equal accuracy to n2, but ~4× higher bulk viscosity, which damps longitudinal acoustics); --wall hrr (provisional — chosen on scheme structure, pending campaign group C; bouzidi resolves geometry ~4× better). Accepted values: --init uniform|rest, --kbc-model n1|n2, --wall hrr|bouzidi|grad|staircase.

Validation campaign (bench/)

115 runs in nine groups (A 12, B 16, C 20, D 14, E 12, F 9, G 14, H 9, I 9), ≈90 machine-hours — ≈87 GPU-hours over 108 runs plus ≈3 CPU-hours over the 7 CPU runs of group A. Each run writes cmd.txt, log.txt, report.txt, series.csv and summary.json into its own folder under out/ (untracked — those are results, never clean them). Only 59 of the 115 pass --gif; the rest produce no animation at all.

cd bench
python preflight.py             # start every scenario for two steps — catches typos
./run_campaign.sh --calibrate   # measure this machine's MLUPS (hour estimates need it)
./run_campaign.sh --dry-run     # cost estimate
./run_campaign.sh --resume      # run, skipping what is already done

run_campaign.sh also takes --smoke, --group, --only and --budget-hours; run_campaign.ps1 is the Windows twin. Run preflight.py for real — it caught group I failing on a GPU limit and group F's nine runs passing --body-x twice, both of which would otherwise have surfaced twenty hours into a server campaign.

Note the campaign has barely started: out/ currently holds four finished runs (A01, A02, A05, C09) plus campaign.log and summary.csv.

Deployment

Published image notbigghost/kbc2d:1.2.0; the server needs only docker-compose.server.yml (the only compose file with no build: section), not the sources. ENTRYPOINT is the campaign driver and CMD defaults to --dry-run, so a stray docker run prints an estimate instead of starting a 100-hour job. Check the card first (--profile check run --rm vulkan) — a missing GPU is better discovered in a minute than in an hour. The check profile also carries preflight, calibrate and plan services (plus parity in the WSL file).

Two version caveats: the 1.2.0 tag lives only in the compose files and prose — Cargo.toml still says version = "0.1.0" and the Dockerfile defaults ARG VERSION=dev. And linux/amd64 is asserted in README.md only; no compose file sets platform: and the Dockerfile sets no --platform.

Two environment traps, both already handled in the image but overridable from outside: NVIDIA Container Toolkit only injects the Vulkan ICD when NVIDIA_DRIVER_CAPABILITIES contains graphics (with compute alone wgpu sees no adapter), and WSL2 has no NVIDIA Vulkan driver for Linux at all — the card arrives over /dev/dxg. That path instead uses dzn (Mesa's Vulkan→D3D12 translation, why the base image is archlinux:base — Debian/Ubuntu do not build dzn), needs no NVIDIA runtime, and requires WGPU_ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER=1 because dzn reports conformanceVersion = 0.0.0.0 and wgpu hides such adapters by default (the variable is read only because gpu.rs builds the instance with .with_env()). Use docker-compose.wsl.yml there.

---

docs/theory/ — Python prototype (all branches)

The earlier Python/CuPy implementation of the same LBM physics — cylinder flow with a nested AMR patch and SDF+Bouzidi boundaries. kbc2d is a deliberate rewrite of this, not a port. Do not fold any of it into the CMake build, and do not treat it as dead code — but do not treat it as one program either.

This directory holds four generations of the same solver. CLAUDE.md used to name only the newest, which made the rest look like clutter. Oldest to newest:

generation	files	status
the original write-up	_legacy/kbc_lbm.ipynb (64 cells, executed, outputs stored) + _legacy/kbc_lbm.py	superseded
CPU reference prototypes	_amr_anims.py, _amr_anims_sdf.py (pure NumPy)	superseded, but these are the "verified CPU prototypes" the GPU core is checked against
GPU core + runners	amr_gpu_core.py (has a NumPy CPU fallback) driven by amr_cylinder_gpu.py (no SDF) and amr_cylinder_sdf_gpu.py (SDF+Bouzidi); both self-titled "ОСНОВНОЙ", three modes: none / 2× / nested 2×+4×	superseded as a model, still the producer of committed figures 11e–11g and four *_cyl*.gif animations — deleting it orphans notebook images
optimised rewrite	amr_opt/ (*_opt.py: no NumPy fallback, cp.fuse, precomputed link masks, CUDA Graphs)	dead intermediate — produced nothing that is committed
the current model	solver_2x_sdf/ (17 modules + README), demos in demos_gpu/	live

So "GPU/CuPy only, no CPU fallback" is true of solver_2x_sdf/ (backend.py raises outright), demos_gpu/ and amr_opt/ — but not of amr_gpu_core.py, which silently falls back to NumPy, nor of _amr_anims*.py and _legacy/, which are CPU-only.

Also committed and easy to mistake for junk: figures/ (14 PNG) and anim/ (10 GIF, 55 MB) are tracked deliberately so the notebook renders on a fresh clone; _amr_probe_data*.npz are probe scalars one runner writes and the other reads; factors.csv is a hand-preserved snapshot of the Experiment-№1 registry (nothing writes that path — run_factors.py writes solver_2x_sdf/out/factors.csv, which is gitignored).

• solver_2x_sdf/README.md — maps every file to the physics it owns (17 rows, 17 modules, exact); entry points run.py, run_blockage.py, run_factors.py. Two defects in it: it suggests switching cfg.collision="bgk" or registering a TRT operator in a get registry — neither the config field nor the registry exists, and the same README says two paragraphs later that the operator is fixed; and it declares all of its own quantitative results stale pending a re-run after the GREL fix, which also invalidates notebook §22–24.
• demos_gpu/ — 8 scripts + README producing 17 of the notebook's artefacts. They import the model's operators from solver_2x_sdf and add only what the model deliberately lacks: _common.py reimplements a polynomial equilibrium, BGK, the H-function and a γ-field for visualisation. figures_static.py is pure matplotlib and imports no physics at all.
• kbc_lbm.ipynb — the write-up. It does not merely "execute nothing": it has 20 cells, all markdown, zero code cells. Artefacts are relative-path links, not embedded data, so it is only readable in place — and 4 of its 26 image links are dead, all pointing into the gitignored solver_2x_sdf/out/.
• docs/origins/ — the six source PDFs behind both implementations (seven on research, which adds Grad's approximation).

How kbc2d differs from this prototype

Documented in one paragraph at docs/theory/2d_solver/README.md:390 — on branch research only; nothing under docs/theory/ mentions the divergence. There are three differences, not two:

1. kbc2d does not collide inside the body (those populations are fictitious; γ statistics are then gathered strictly over fluid). The Python solver does collide there — kbc_collide takes no fluid mask.
2. kbc2d's restriction additionally skips coarse nodes whose fine source node lies inside the body. The Python restriction already gates on the coarse destination mask.
3. kbc2d's CPU backend is f64 and its GPU backend f32; the Python side is fp32 by default, f64 only via AMR_FP64.