Merge pull request #84 from Project-SEA-Stack/release/v0.5

Release v0.5

Author: dav-og

CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] — 2026-02-16
+
+### Added
+
+- **VSG free-surface visualization** — animated water-surface mesh driven by the wave model, with per-vertex normals and configurable grid resolution (`vsg_water_surface`)
+- **Radiated wave overlay** — visualization of body-generated wave patterns layered on the free surface (`vsg_radiation_surface`)
+- **PBR ocean materials, scene lighting, and GUI stats component** — new modules `vsg_materials`, `vsg_lighting`, `vsg_gui_component`, `vsg_config`
+- **Wave model API extensions** — `GetElevationGradientXY()` and `GetElevationForVisualization()` added to `WaveBase`, `RegularWave`, and `IrregularWave`
+- **Added-mass determinism unit test** — `test_added_mass_determinism` verifies bit-identical added-mass assembly across independent trials and sweeps all Chrono solver types
+- **Regression tests produce HDF5 output** validated by external Python comparison scripts; tests now run fully headless (all GUI/visualization code stripped from test builds)
+- **CPack packaging** — project DLLs (`HydroChrono`, `HydroChronoGUI`) now included in the installer ZIP
+- **OpenMP runtime** (`vcomp140.dll`) explicitly installed for MSVC packages
+- **Chrono DLL collection** changed to glob all DLLs from Chrono's bin directory, capturing transitive VSG/yaml-cpp/draco dependencies
+
+### Changed
+
+- **Switched added-mass implementation to Chrono's built-in `ChLoadHydrodynamics`** — replaces HydroChrono's legacy `ChLoadAddedMass` (`ChLoadCustomMultiple`-based) as the default. The legacy implementation is retained in the codebase and can be re-activated by uncommenting `#define HYDROCHRONO_USE_LEGACY_ADDED_MASS` in `hydro_system.h`.
+- Default solver changed from GMRES to SPARSE_QR for most regression tests (faster, deterministic)
+- Irregular wave surface evaluation performance improved (parallelism and caching)
+- Regression test report generator now correctly parses CTest logs for PASS/FAIL status instead of assuming PASS when plots exist
+
+### Fixed
+
+- **YAML runner: `LoadSolverData` never called** — YAML structure mismatch prevented solver data from being loaded
+- **YAML runner: mesh file paths broken** — `m_script_directory` was empty, breaking relative `model_file:` paths
+- **Regression report image paths** — report generator now computes correct relative paths to plot images instead of using hardcoded paths
+- OSWEC solver switched from SPARSE_QR to GMRES to prevent divergence (see Known Issues)
+- RM3 decay test fixes and cleanup
+- Sphere irregular wave test default arguments corrected
+- **Regular wave excitation phase indexing for multi-body systems** — `RegularWave::GetForceAtTime()` used `excitation_force_phase_[rowEx]` instead of `excitation_force_phase_[body_offset + rowEx]`, causing body 2+ to use body 1's excitation phase. This affected the RM3 plate (and any second+ body) heave response in regular waves. Single-body models (e.g., sphere) were unaffected.
+
+### Known Issues
+
+- **OSWEC tests use GMRES solver.** OSWEC demos and tests use GMRES rather than SPARSE_QR. SPARSE_QR may work for OSWEC but has not yet been validated.
+- **PSOR solver cannot handle added-mass assembly.** The added-mass determinism unit test solver sweep reports that PSOR errors out because it cannot handle stiffness/damping matrices. All other swept solvers (SPARSE_QR, SPARSE_LU, MINRES, GMRES, BICGSTAB, BARZILAIBORWEIN, APGD) pass assembly.
+
+## [0.4.0] — 2025
+
+- YAML-driven CLI (`run_hydrochrono`) for running simulations from text-based configuration files
+- Cummins-equation time-domain solver with BEM hydrodynamic coefficients (BEMIO HDF5 format)
+- Multibody system support via Project Chrono (bodies, joints, actuators)
+- Irrlicht run-time visualization (optional)
+- HDF5 output for post-processing and validation
+- Regression test suite (IEA sphere, OSWEC, RM3, F3OF / DeepCWind)
+- Windows installer (ZIP) via CPack

CMakeLists.txt

@@ -20,7 +20,7 @@ endif()
 # ===============================================================================
 
 project(HydroChrono 
-    VERSION 0.4.0
+    VERSION 0.5.0
     DESCRIPTION "Hydrodynamics for Project Chrono."
     LANGUAGES CXX
 )
@@ -303,6 +303,7 @@ set(HC_SOURCES
     src/hydro/radiation/radiation_rirf_convolution.cpp
     src/hydro/core/hydro_forces.cpp
     # Chrono coupling layer (bridges Chrono physics with Chrono-free core)
+    src/hydro/chrono/added_mass.cpp
     src/hydro/chrono/chrono_state_utils.cpp
     src/hydro/chrono/chrono_hydro_coupler.cpp
     src/hydro/force_components/hydrostatics_component.cpp
@@ -325,6 +326,7 @@ set(HC_HEADERS
     include/hydroc/core/hydro_forces.h
     include/hydroc/core/hydro_types.h
     include/hydroc/core/system_state.h
+    include/hydroc/coupling/added_mass.h
     include/hydroc/coupling/chrono_coupler.h
     include/hydroc/io/h5_reader.h
     include/hydroc/io/h5_writer.h

README.md

@@ -2,11 +2,11 @@
 <p align="center">
   <img src="docs/assets/img/hydrochrono_banner.png" />
   <br/>
-  <a href="https://github.com/NREL/HydroChrono/releases"><img src="https://img.shields.io/badge/version-v0.4-blue.svg" /></a>
+  <a href="https://github.com/NREL/HydroChrono/releases"><img src="https://img.shields.io/badge/version-v0.5-blue.svg" /></a>
   <a href="#"><img src="https://img.shields.io/badge/status-Prototype-orange.svg" /></a>
 </p>
 
-> ⚠️ HydroChrono is under active development (`v0.4` prototype). This early release focuses on a YAML‑driven CLI and portable HDF5 outputs so you can try the code and share feedback. Expect rapid iteration over the coming year (inc. more advanced PTO, control, mooring & hydrodynamics) — please get in touch if you have any issues or feature requests.
+> ⚠️ HydroChrono is under active development (`v0.5` prototype). This early release focuses on a YAML‑driven CLI, real-time VSG visualization with animated free-surface rendering, and portable HDF5 outputs so you can try the code and share feedback. Expect rapid iteration over the coming year (inc. more advanced PTO, control, mooring & hydrodynamics) — please get in touch if you have any issues or feature requests.
 
 
 HydroChrono (Hydrodynamics for Project Chrono) is a hydrodynamics simulation toolkit built on [Project Chrono](https://projectchrono.org/). It is designed for simulating wave energy converters (WECs) and other complex ocean systems, and is **100% free and open‑source** end‑to‑end — no proprietary dependencies required. This repo ships a prototype, YAML‑driven CLI app for running simulations and exporting portable results.
@@ -20,6 +20,7 @@ HydroChrono (Hydrodynamics for Project Chrono) is a hydrodynamics simulation too
 - Uses Boundary Element Method (BEM) hydrodynamic coefficients (e.g., from [Capytaine](https://github.com/capytaine/capytaine)) to describe added mass, radiation damping, and wave excitation. HydroChrono reads these coefficients from BEMIO‑format HDF5 (.h5) files, an approach familiar to [WEC‑Sim](https://github.com/WEC-Sim/WEC-Sim) users.
 - Runs time‑domain simulations via the Cummins equation (impulse‑response/convolution form for radiation effects).
 - Builds complex, nonlinear multibody systems using Project Chrono; hydrodynamic loads are currently first‑order, with expanded models planned.
+- **Real-time VSG visualization** with animated free-surface rendering driven by the wave model, radiated wave overlays, PBR ocean materials, and interactive GUI stats (new in v0.5).
 - Supports a YAML-driven CLI, with logging, GUI and exports portable results to HDF5 for post‑processing and validation.
 
 ## Download
@@ -61,7 +62,7 @@ Tips: use `--quiet` to reduce logs, `--debug`/`--trace` for deeper diagnostics.
 
 ### GUI Example
 
-Use the GUI to visually inspect the assembled multibody system (bodies, joints, actuators) and verify that YAML inputs are wired correctly. Use the `--nogui` option to disable visualization straight from CLI, or change the settings in the `*.simulation.yaml` file.
+Use the GUI to visually inspect the assembled multibody system (bodies, joints, actuators) and verify that YAML inputs are wired correctly. With VSG enabled, the visualization includes an animated free-surface mesh and radiated wave overlays driven by the live wave model. Use the `--nogui` option to disable visualization straight from CLI, or change the settings in the `*.simulation.yaml` file.
 
 <p align="center"><img src="docs/assets/img/gui_example.png" width="40%" /></p>
 

build.ps1

@@ -71,6 +71,10 @@ if ($Help) {
     Write-Host "  .\build.ps1 -Clean -Verbose    # Clean build with details"
     Write-Host "  .\build.ps1 -Package           # Build and create ZIP`n"
 
+    Write-Host "LONG TESTS:" -ForegroundColor Yellow
+    Write-Host "  Set `$env:HYDROCHRONO_LONG_TESTS='1' before running ctest to use extended"
+    Write-Host "  simulation durations for publication-quality regression reports.`n"
+    
     Write-Host "CONFIG FILE:" -ForegroundColor Yellow
     Write-Host '  { "ChronoDir": "C:/path/to/chrono/build/cmake" }' -ForegroundColor Gray
     Write-Host ""
@@ -361,7 +365,16 @@ Write-Host "BUILD SUCCESSFUL" -ForegroundColor Green
 Write-Host "========================================`n" -ForegroundColor Green
 
 Write-Host "Output: $binPath" -ForegroundColor Cyan
+Write-Host ""
 Write-Host "Tests:  ctest -C $BuildType -L regression --test-dir build" -ForegroundColor Gray
 Write-Host "        ctest -C $BuildType -L unit       --test-dir build" -ForegroundColor Gray
 Write-Host "        Add -V for verbose output, --output-on-failure for failures only" -ForegroundColor DarkGray
 Write-Host ""
+Write-Host "Long:   `$env:HYDROCHRONO_LONG_TESTS='1'" -ForegroundColor Gray
+Write-Host "        ctest -C $BuildType -L regression --test-dir build" -ForegroundColor Gray
+Write-Host "        Runs with extended simulation durations" -ForegroundColor DarkGray
+Write-Host ""
+Write-Host "Report: python tests/regression/utilities/generate_report.py --build-dir build --pdf" -ForegroundColor Gray
+Write-Host "        Generates regression test report (markdown + PDF) in build/bin/report/" -ForegroundColor DarkGray
+Write-Host "        Requires: pip install pypandoc  (or pandoc on PATH)" -ForegroundColor DarkGray
+Write-Host ""