Merge branch 'main' into feature/radiation-state-space

Author: dav-og

.gitignore

@@ -60,3 +60,4 @@ build-config.json
 /tests/regression/run_hydrochrono/iea_sphere/decay/outputs
 /tests/regression/run_hydrochrono/oswec/decay/outputs
 /tests/regression/run_hydrochrono/rm3/decay/outputs
+/data/demos/run_hydrochrono/**/outputs

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
 )
@@ -169,8 +169,7 @@ endif()
 
 find_package(Chrono
              CONFIG REQUIRED
-             COMPONENTS Parsers
-             OPTIONAL_COMPONENTS Irrlicht VSG)
+             COMPONENTS Parsers)
 
 message(STATUS "----\n")
 
@@ -306,6 +305,7 @@ set(HC_SOURCES
     src/hydro/radiation/radiation_ss_fitter.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
@@ -329,6 +329,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
@@ -422,6 +423,19 @@ endif()
 if(HYDROCHRONO_ENABLE_VSG)
   set(HCGUI_SOURCES ${HCGUI_SOURCES}
       src/gui/guihelperVSG.cpp
+      src/gui/vsg_gui_component.cpp
+      src/gui/vsg_lighting.cpp
+      src/gui/vsg_materials.cpp
+      src/gui/vsg_water_surface.cpp
+      src/gui/vsg_radiation_surface.cpp
+  )
+  set(HCGUI_HEADERS ${HCGUI_HEADERS}
+      src/gui/vsg_config.h
+      src/gui/vsg_gui_component.h
+      src/gui/vsg_lighting.h
+      src/gui/vsg_materials.h
+      src/gui/vsg_water_surface.h
+      src/gui/vsg_radiation_surface.h
   )
 endif()
 
@@ -534,6 +548,7 @@ if(HYDROCHRONO_ENABLE_TESTS)
     endif()
 
     add_subdirectory(tests/regression)
+    add_subdirectory(tests/unit)
 endif()
 
 # ===============================================================================
@@ -609,27 +624,33 @@ endif()
 # Flat install tree for public distribution
 option(HC_INSTALL_DEV_DEMOS "Install developer demo executables" OFF)
 
-# Install main CLI only (if built)
+# Install main CLI and project shared libraries (if built)
 if(TARGET run_hydrochrono)
     install(TARGETS run_hydrochrono  CONFIGURATIONS Release DESTINATION bin COMPONENT runtime)
 endif()
+if(TARGET HydroChrono)
+    install(TARGETS HydroChrono      CONFIGURATIONS Release RUNTIME DESTINATION bin COMPONENT runtime)
+endif()
+if(TARGET HydroChronoGUI)
+    install(TARGETS HydroChronoGUI   CONFIGURATIONS Release RUNTIME DESTINATION bin COMPONENT runtime)
+endif()
 
 # On Windows, install DLLs
 if(${CMAKE_SYSTEM_NAME} MATCHES "Windows")
     message(STATUS "Set DLLs for installation")
 
-    # Chrono DLLs
-    foreach(tgt ${CHRONO_TARGETS})
-        get_target_property(tgt_DLL ${tgt} IMPORTED_LOCATION_RELEASE)
-        get_target_property(tgt_DLL_d ${tgt} IMPORTED_LOCATION_DEBUG)
-        if(EXISTS ${tgt_DLL})
-            message(STATUS "  Chrono DLL ${tgt_DLL}")
-            install(FILES ${tgt_DLL} DESTINATION bin COMPONENT runtime)
-        endif()
-        if(EXISTS ${tgt_DLL_d})
-            install(FILES ${tgt_DLL_d} DESTINATION bin COMPONENT runtime)
-        endif()
-    endforeach()
+    # Chrono DLLs — glob ALL DLLs from the Chrono bin directory to catch
+    # transitive dependencies (e.g., Chrono_fsitdpf_vsg, yaml-cpp) that may
+    # not be listed in CHRONO_TARGETS.
+    get_target_property(_chrono_core_dll Chrono::Chrono_core IMPORTED_LOCATION_RELEASE)
+    if(_chrono_core_dll)
+        get_filename_component(_chrono_dll_dir "${_chrono_core_dll}" DIRECTORY)
+        file(GLOB _chrono_dlls "${_chrono_dll_dir}/*.dll")
+        foreach(_dll ${_chrono_dlls})
+            message(STATUS "  Chrono DLL ${_dll}")
+            install(FILES "${_dll}" DESTINATION bin COMPONENT runtime)
+        endforeach()
+    endif()
 
     # HDF5 DLLs
     foreach(tgt ${HDF5_TARGETS})
@@ -658,24 +679,42 @@ if(${CMAKE_SYSTEM_NAME} MATCHES "Windows")
         endif()
     endif()
 
-    # Python DLLs, if Chrono::Parsers depends on it
-    if(CHRONO_PARSERS_PYTHON)
-        find_package(Python3 QUIET COMPONENTS Interpreter Development)
-        if(Python3_Interpreter_FOUND AND Python3_Development_FOUND)
-            #message(STATUS "Found Python and dependencies")
-            #message(STATUS "  Python3_Interpreter_FOUND: ${Python3_Interpreter_FOUND}")
-            #message(STATUS "  Python3_Development_FOUND: ${Python3_Development_FOUND}")
-            get_target_property(tgt_DLL Python3::Python IMPORTED_LOCATION_RELEASE)
-            get_target_property(tgt_DLL_d Python3::Python IMPORTED_LOCATION_DEBUG)
-            if(EXISTS ${tgt_DLL})
-                message(STATUS "  Python DLL ${tgt_DLL}")
-                install(FILES ${tgt_DLL} DESTINATION bin COMPONENT runtime)
+    # VSG DLLs (vsg, vsgImGui, vsgXchange, draco, etc.)
+    if(HYDROCHRONO_ENABLE_VSG)
+        # VSG_DLL_DIR is set by Chrono's find_package when VSG is found
+        # Fall back to deriving from vsg_DIR if VSG_DLL_DIR is not set
+        if(NOT DEFINED VSG_DLL_DIR OR VSG_DLL_DIR STREQUAL "")
+            if(DEFINED vsg_DIR)
+                # vsg_DIR points to lib/cmake/vsg, go up 3 levels to root then into bin
+                get_filename_component(_vsg_root "${vsg_DIR}" DIRECTORY)  # lib/cmake
+                get_filename_component(_vsg_root "${_vsg_root}" DIRECTORY)  # lib
+                get_filename_component(_vsg_root "${_vsg_root}" DIRECTORY)  # root
+                set(VSG_DLL_DIR "${_vsg_root}/bin")
             endif()
-            if(EXISTS ${tgt_DLL_d})
-                install(FILES ${tgt_DLL_d} DESTINATION bin COMPONENT runtime)
+        endif()
+        
+        if(DEFINED VSG_DLL_DIR AND EXISTS "${VSG_DLL_DIR}")
+            file(GLOB _vsg_dlls "${VSG_DLL_DIR}/*.dll")
+            if(_vsg_dlls)
+                message(STATUS "Installing VSG DLLs from: ${VSG_DLL_DIR}")
+                install(FILES ${_vsg_dlls} DESTINATION bin COMPONENT runtime)
             endif()
+        else()
+            message(WARNING "HYDROCHRONO_ENABLE_VSG is ON but VSG_DLL_DIR not found. VSG DLLs will not be packaged.")
         endif()
     endif()
+    
+    # Python DLLs, if Chrono::Parsers depends on it.
+    # Derive the DLL path from the already-found interpreter rather than calling
+    # find_package(Python3 ... Development), which can stall on Windows/conda.
+    if(CHRONO_PARSERS_PYTHON AND Python3_EXECUTABLE)
+        get_filename_component(_py_bin_dir "${Python3_EXECUTABLE}" DIRECTORY)
+        file(GLOB _py_dlls "${_py_bin_dir}/python3*.dll")
+        foreach(_py_dll ${_py_dlls})
+            message(STATUS "  Python DLL ${_py_dll}")
+            install(FILES "${_py_dll}" DESTINATION bin COMPONENT runtime)
+        endforeach()
+    endif()
 
 endif()
 
@@ -697,6 +736,20 @@ install(PROGRAMS ${PROJECT_SOURCE_DIR}/scripts/RUN-TESTS.ps1
         DESTINATION tests COMPONENT python-tests)
 
 # MSVC runtime DLLs and ZIP packaging via CPack
+# InstallRequiredSystemLibraries handles msvcp/vcruntime/ucrt, but not vcomp (OpenMP).
+# Append the OpenMP runtime so it's included in the package.
+if(MSVC AND OpenMP_CXX_FOUND)
+    get_filename_component(_msvc_dir "${CMAKE_CXX_COMPILER}" DIRECTORY)
+    find_file(_vcomp_dll "vcomp140.dll"
+        PATHS "${_msvc_dir}" "${_msvc_dir}/../../../redist/x64" "C:/Windows/System32"
+        NO_DEFAULT_PATH)
+    if(_vcomp_dll)
+        list(APPEND CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS "${_vcomp_dll}")
+        message(STATUS "  OpenMP DLL ${_vcomp_dll}")
+    else()
+        message(WARNING "vcomp140.dll not found — OpenMP runtime will be missing from package")
+    endif()
+endif()
 include(InstallRequiredSystemLibraries)
 set(CPACK_GENERATOR "ZIP")
 set(CPACK_PACKAGE_NAME "HydroChrono")

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

@@ -1,4 +1,4 @@
-<#
+<#
     HydroChrono Build Script
     
     Configures and builds HydroChrono. Dependency paths (Eigen, HDF5, Irrlicht)
@@ -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 ""
@@ -250,7 +254,7 @@ if ($LASTEXITCODE -ne 0) {
 Write-OK "Built in $buildSecs seconds"
 
 # =============================================================================
-# Copy Third-Party DLLs (Irrlicht - not handled by Chrono's DLL copy command)
+# Copy Third-Party DLLs (not handled by Chrono's DLL copy command)
 # =============================================================================
 
 $binPath = ".\build\bin\$BuildType"
@@ -269,6 +273,43 @@ if ($useIrrlicht) {
     }
 }
 
+if ($useVSG) {
+    # Get VSG DLL directory from Chrono config (set by find_package(vsg))
+    # VSG_DLL_DIR is set by Chrono when it finds VSG
+    $vsgDllDir = $null
+    
+    if ($chronoContent -match 'VSG_DLL_DIR\s+([^\s\)]+)') {
+        $vsgDllDir = $Matches[1].Trim('"')
+    }
+    
+    # Fallback: derive from vsg_DIR (lib/cmake/vsg -> bin)
+    if (-not $vsgDllDir -or -not (Test-Path $vsgDllDir)) {
+        if ($chronoContent -match 'vsg_DIR\s+"([^"]+)"') {
+            $vsgCmakeDir = $Matches[1]
+            # Go up from lib/cmake/vsg to root, then into bin
+            $vsgRoot = Split-Path (Split-Path (Split-Path $vsgCmakeDir))
+            $vsgDllDir = Join-Path $vsgRoot "bin"
+        }
+    }
+    
+    if ($vsgDllDir -and (Test-Path $vsgDllDir)) {
+        $vsgDlls = Get-ChildItem -Path $vsgDllDir -Filter "*.dll" -ErrorAction SilentlyContinue
+        $copiedCount = 0
+        foreach ($dll in $vsgDlls) {
+            $destDll = Join-Path $binPath $dll.Name
+            if (-not (Test-Path $destDll)) {
+                Copy-Item $dll.FullName $destDll -Force
+                $copiedCount++
+            }
+        }
+        if ($copiedCount -gt 0) {
+            Write-OK "Copied $copiedCount VSG DLLs from $vsgDllDir"
+        }
+    } else {
+        Write-Warn "VSG enabled but could not find VSG DLL directory"
+    }
+}
+
 # =============================================================================
 # Verify
 # =============================================================================
@@ -324,5 +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 ""