# 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. ```sh 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: ```sh 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: ```sh 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//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)`. ```sh 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//`). 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/` then `current_path()/spirv/` — 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//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`. ```sh 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//` directly. There are exactly three `TEST_CASE`s, 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: ```sh 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 ` 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//spirv/editor/..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. ```sh 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//`. 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 ```sh 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. ```sh ./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 ` 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. ```sh 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`.