Port FluidSim core and scenarios to C++20

README.md

@@ -0,0 +1,83 @@
+# FluidSimCpp
+
+Native C++20 port of FluidSim. The C# application remains the reference while
+the component models and behavior are being ported and checked against it.
+
+## Build (Windows / Visual Studio)
+
+Open a Visual Studio Developer PowerShell (or initialize the MSVC environment
+with `VsDevCmd.bat`), then run from this directory:
+
+```powershell
+cmake -S . -B build -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+The first configure fetches SFML 3.0.2 with CMake FetchContent for the desktop
+window and audio stream. `-DFLUIDSIM_BUILD_DESKTOP=OFF` builds only the headless
+runner and physics tests.
+
+Run the interactive simulator with:
+
+```powershell
+.\build\fluidsim_desktop.exe
+```
+
+Controls: hold `W` for throttle, `C` for clutch, `A` / `D` to shift, `Z` for
+neutral, up/down to adjust throttle target, left/right to adjust engine load,
+`M` toggles mechanical engine noise, mouse wheel changes simulation playback
+speed, and Space toggles real time.
+
+The command-line runner is useful for repeatable checks:
+
+```powershell
+.\build\fluidsim_cpp.exe --seconds 1 --throttle 0.35
+.\build\fluidsim_cpp.exe --scenario two-stroke --seconds 1 --throttle 0.3
+.\build\fluidsim_cpp.exe --scenario helmholtz --seconds 1
+.\build\fluidsim_cpp.exe --scenario pulse --seconds 1
+```
+
+To compare deterministic checkpoints from the active C# twin scenario against
+the C++ port (energy variation is disabled for repeatability), build the C++
+trace runner and execute the PowerShell comparison script:
+
+```powershell
+cmake --build build-msvc --target fluidsim_parity_trace
+.\verification\Compare-ScenarioTrace.ps1
+```
+
+## Current port status
+
+The C++ core now includes the shared `EngineCylinder` model with four-stroke and
+two-stroke cycle implementations, crankshaft, crankcase, atmosphere and
+configurable 0-D volume components (including thermal relaxation and moving
+volume work), profiled compressible 1-D pipes and boundaries, adaptive solver
+stepping, the impulse-clutch motorcycle/road-load model, and the active 600 cc
+twin topology. Audio includes the flow-derivative source, spatialized
+intake/exhaust radiation, outdoor feedback-delay reverb, optional mechanical
+noise, a lock-free simulation audio buffer, a `SoundEngine` lifecycle wrapper,
+and an SFML desktop frontend. The shared 50-RPM-bin dyno history and graph are
+also ported. A crankcase-scavenged 125 cc two-stroke scenario is available in
+the core.
+
+This is still an in-progress port, not a claimed complete replacement. All four
+current C# scenarios (600 cc twin, 125 cc two-stroke, Helmholtz resonator, and
+pressure pulse) have headless C++ counterparts and can be selected by the CLI.
+Remaining parity work includes completing the C# drawing/diagnostic controls in
+the desktop UI and resolving numerical differences reported by the comparison
+harness. The latest MSVC build completed, CTest passed, and the one-second
+headless twin run completed with finite output. The desktop executable opened,
+but its client area rendered blank in the captured run, so desktop rendering is
+not yet verified.
+
+The one-second twin trace remains substantially outside its 1% tolerance. The
+latest comparison's largest relative difference is 40.6745 for cylinder 1
+pressure at checkpoint 33075 (69.8 kPa in C# versus 2.91 MPa in C++). A dense
+intake trace matches closely at first, then the C# plenum pressure begins
+rising at checkpoint 63 while C++ remains near ambient. This divergence needs
+to be resolved before claiming numerical parity. CTest covers cylinder
+geometry and valve timing, dyno-bin interpolation, configurable 0-D volume
+thermodynamics, crankcase and atmosphere state, profiled-pipe geometry,
+inertive and closed boundaries, gearing and clutch momentum transfer, finite
+runs for every scenario, and finite audio/reverb output.