Merge branch 'main' into major/ui-io-upgrade

dav-og · dav-og · commit 923436226680 · 2025-09-27T17:12:37.000+01:00
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -169,8 +169,43 @@ set(HDF5_USE_STATIC_LIBRARIES ON)
 set(HDF5_ROOT "${HDF5_ROOT}" CACHE PATH "HDF5 root directory")
 find_package(HDF5 REQUIRED COMPONENTS CXX)
 
-# ── Platform-Specific Fixes ──
-# Fix for VS 2017 15.8+ to handle alignment specification with Eigen
+# ---- Eigen: support both CONFIG and module modes ----
+find_package(Eigen3 QUIET CONFIG)
+if (NOT Eigen3_FOUND)
+  find_package(Eigen3 REQUIRED)  # module mode -> EIGEN3_INCLUDE_DIR
+endif()
+
+# ---- Chrono include path: prefer imported target; fall back to vars; fall back to build tree ----
+set(HC_CHRONO_INCLUDE_DIRS "")
+
+# Prefer INTERFACE includes from an imported target, if provided
+if (TARGET Chrono::Chrono_core)
+  get_target_property(HC_CHRONO_INCLUDE_DIRS Chrono::Chrono_core INTERFACE_INCLUDE_DIRECTORIES)
+endif()
+
+# Fallback to legacy variable if the package sets it
+if (NOT HC_CHRONO_INCLUDE_DIRS AND DEFINED CHRONO_INCLUDE_DIRS)
+  set(HC_CHRONO_INCLUDE_DIRS ${CHRONO_INCLUDE_DIRS})
+endif()
+
+# Derive from Chrono_DIR when using Chrono from a build tree (headers live under <chrono_root>/src)
+if (NOT HC_CHRONO_INCLUDE_DIRS AND DEFINED Chrono_DIR)
+  get_filename_component(_CHR_CMAKE_DIR "${Chrono_DIR}" ABSOLUTE)     # .../chrono/build/cmake
+  get_filename_component(_CHR_BUILD_DIR "${_CHR_CMAKE_DIR}" DIRECTORY)# .../chrono/build
+  get_filename_component(_CHR_ROOT      "${_CHR_BUILD_DIR}" DIRECTORY)# .../chrono
+  set(_CHR_INC_CAND "${_CHR_ROOT}/src")
+  if (EXISTS "${_CHR_INC_CAND}/chrono/core/ChMatrix.h")
+    set(HC_CHRONO_INCLUDE_DIRS "${_CHR_INC_CAND}")
+  endif()
+endif()
+
+
+
+
+#-----------------------------------------------------------------------------
+# Fix for VS 2017 15.8 and newer to handle alignment specification with Eigen
+#-----------------------------------------------------------------------------
+
 if(${CMAKE_SYSTEM_NAME} MATCHES "Windows")
 	if(MSVC AND ${MSVC_VERSION} GREATER_EQUAL 1915)
 		add_compile_definitions("ENABLE_EXTENDED_ALIGNED_STORAGE")
@@ -274,6 +309,32 @@ configure_hydro_target(HydroChrono)
 # Add HDF5 as private dependency (don't expose to users)
 target_include_directories(HydroChrono PRIVATE ${HDF5_INCLUDE_DIRS})
 target_link_libraries(HydroChrono PRIVATE ${HDF5_LIBRARIES})
+target_compile_features(HydroChrono PUBLIC cxx_std_17)
+
+# target_include_directories(
+	# HydroChrono
+
+	# PUBLIC
+	# $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
+	# $<INSTALL_INTERFACE:include>
+	# ${CHRONO_INCLUDE_DIRS}
+
+	# PRIVATE
+	# ${CMAKE_CURRENT_SOURCE_DIR}/
+	# ${CMAKE_CURRENT_SOURCE_DIR}/include
+	# ${HDF5_INCLUDE_DIRS}
+# )
+
+target_include_directories(HydroChrono
+  PUBLIC
+    $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+    ${HC_CHRONO_INCLUDE_DIRS}     # <— ensures chrono/ headers are visible
+  PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}
+    ${CMAKE_CURRENT_SOURCE_DIR}/include
+    ${HDF5_INCLUDE_DIRS}
+)
 
 # Library-specific compile definitions
 target_compile_definitions(HydroChrono
@@ -320,13 +381,71 @@ if(HYDROCHRONO_ENABLE_YAML_RUNNER)
 else()
     message(STATUS "YAML runner disabled - not creating run_hydrochrono target")
 endif()
+target_link_libraries(HydroChrono
+  PUBLIC
+    ${CHRONO_TARGETS}             # Chrono::Chrono_core;Chrono::Chrono_irrlicht;...
+    $<$<TARGET_EXISTS:Eigen3::Eigen>:Eigen3::Eigen>
+  PRIVATE
+    ${HDF5_LIBRARIES}
+)
+
+# If Eigen is module-mode (no imported target), include its dir
+if (NOT TARGET Eigen3::Eigen AND DEFINED EIGEN3_INCLUDE_DIR)
+  target_include_directories(HydroChrono PUBLIC ${EIGEN3_INCLUDE_DIR})
+endif()
+
+# ====================
+# Irrlicht GUI helper
+# ====================
 
 # ── GUI Helper Library ──
 # Separate library for Irrlicht visualization helpers
 add_library(HydroChronoGUI src/gui/guihelper.cpp)
 configure_hydro_target(HydroChronoGUI)
 
 # ── Demo Executables ──
+target_sources(
+	HydroChronoGUI
+
+	PUBLIC
+	src/gui/guihelper.cpp
+)
+
+target_compile_features(HydroChronoGUI PUBLIC cxx_std_17)
+
+
+target_include_directories(HydroChronoGUI
+  PUBLIC
+    $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+    ${HC_CHRONO_INCLUDE_DIRS}
+)
+
+target_compile_options(HydroChronoGUI BEFORE
+	PUBLIC
+		${CHRONO_CXX_FLAGS}
+)
+
+target_link_options(HydroChronoGUI BEFORE
+	PUBLIC
+		${CHRONO_LINKER_FLAGS}
+)
+
+target_link_libraries(HydroChronoGUI
+  PUBLIC
+    ${CHRONO_TARGETS}
+    $<$<TARGET_EXISTS:Eigen3::Eigen>:Eigen3::Eigen>
+)
+
+if (NOT TARGET Eigen3::Eigen AND DEFINED EIGEN3_INCLUDE_DIR)
+  target_include_directories(HydroChronoGUI PUBLIC ${EIGEN3_INCLUDE_DIR})
+endif()
+
+
+
+# ====================
+# DEMOS
+# ====================
 if(HYDROCHRONO_ENABLE_DEMOS)
     add_subdirectory(demos)
 endif()
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 National Renewable Energy Laboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -27,52 +27,74 @@ Visit the [HydroChrono website](https://nrel.github.io/HydroChrono/) for informa
 
 ### Prerequisites
 
-- CMake 3.16 or higher
-- A C++ compiler (Visual Studio 2019 or higher, or GCC through MinGW/MSYS2)
-- Project Chrono (built from source, tested with v9.0.0 and v9.0.1)
-- HDF5 1.10.8 or higher
-- Python 3.8 or higher (with numpy and matplotlib)
-
-### Building from Source
+- **Visual Studio 2022** with C++ toolchain
+- **CMake 3.18+**
+- **Project Chrono** (built from source; tested v9.0.0–v9.0.1)
+- **HDF5 1.10.8+**
+- **Eigen 3.4+** (header-only unzip is fine)
+- **Irrlicht 1.8.x** (optional but required for GUI helper)
+- **Python 3.8+** (only for docs/tools)
+
+### Building from Source (using `build-config.json` + script)
+
+1. **Clone the repository**
+   ```powershell
+   git clone https://github.com/NREL/HydroChrono.git
+   cd HydroChrono
+   ```
+
+2. **Create your local config from the example**
+   ```powershell
+   copy build-config.example.json build-config.json
+   ```
+
+3. **Edit `build-config.json`** and set paths for your machine
+
+   **Example:**
+   ```json
+   {
+     "ChronoDir": "C:/path/to/chrono/build/cmake",
+     "Hdf5Dir": "C:/path/to/hdf5/share/cmake",
+     "EigenDir": "C:/path/to/eigen-3.4.0",
+     "IrrlichtDir": "C:/path/to/irrlicht-1.8.4",
+     "PythonRoot": "C:/Users/<you>/.conda/envs/<env>",
+     "CMakeModulePath": "C:/path/to/chrono/build/cmake"
+   }
+   ```
+
+4. **Build (from repo root)**
+
+   - Clean configure + build (default `Release`):
+     ```powershell
+     .\quick-build.ps1 -Clean
+     ```
+   - Build a different configuration (e.g., `Debug`):
+     ```powershell
+     .\quick-build.ps1 -BuildType Debug
+     ```
+
+4. **Post-Build Steps**
+
+Copy the following DLL files from your Chrono build directory to your build directory's `build/bin` folder:
+- ChronoEngine.dll
+- ChronoEngine_irrlicht.dll (if using Irrlicht)
+- Irrlicht.dll (if using Irrlicht)
 
-1. Clone the repository:
-```powershell
-git clone https://github.com/NREL/HydroChrono.git
-cd HydroChrono
-```
+5. **Run the tests**
+   ```powershell
+   cd build
+   ctest -C Release
+   ```
 
-2. Create a build directory and navigate to it:
-```powershell
-mkdir build
-cd build
-```
-
-3. Configure and build the project:
-```powershell
-cmake .. -DChrono_DIR="<path_to_chrono_build>/cmake" -DHDF5_DIR="<path_to_hdf5_cmake>" -DPython3_ROOT_DIR="<path_to_python>"
-cmake --build . --config Release
-```
-
-4. Run the tests:
-```powershell
-ctest -C Release --output-on-failure
-```
+---
 
 ### Clean Build
 
-To perform a clean rebuild of the project:
 ```powershell
 # From the project root
 Remove-Item -Recurse -Force build
-mkdir build
-cd build
+# then reconfigure/build
+.\quick-build.ps1 -Clean
 ```
 
-### Post-Build Steps
-
-Copy the following DLL files from your Chrono build directory to your build directory's `demos/Release` folder:
-- ChronoEngine.dll
-- ChronoEngine_irrlicht.dll (if using Irrlicht)
-- Irrlicht.dll (if using Irrlicht)
-
-For detailed build instructions, including Visual Studio setup and running demos, see the [developer documentation](https://nrel.github.io/HydroChrono/developer_docs/build_instructions.html).
+For more detailed build instructions, including Visual Studio setup and running demos, see the [developer documentation](https://nrel.github.io/HydroChrono/developer_docs/build_instructions.html).
diff --git a/build-config-example.json b/build-config-example.json
@@ -0,0 +1,13 @@
+{
+  "ChronoDir": "C:/path/to/chrono/build/cmake",
+  "Hdf5Dir": "C:/path/to/hdf5/share/cmake",
+  "EigenDir": "C:/path/to/eigen-3.4.0",
+  "IrrlichtDir": "C:/path/to/irrlicht-1.8.4",
+  "PythonRoot": "C:/Users/<you>/.conda/envs/<env>",
+  "ScriptVersion": "2.1",
+  "DefaultBuildType": "Release",
+  "DefaultYamlRunner": "ON",
+  "VisualStudioPath": "C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC",
+  "RuntimeLibrary": "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL",
+  "CMakeModulePath": "C:/path/to/chrono/build/cmake"
+}
diff --git a/docs/_main_pages/developer_docs/build_instructions.md b/docs/_main_pages/developer_docs/build_instructions.md
@@ -78,6 +78,8 @@ This is the recommended way to build HydroChrono.
    ```
    Note: The Chrono build directory typically contains a `cmake` folder with the Chrono CMake configuration files.
 
+   **⚠️ Important:** The build type (e.g., Release, Debug, RelWithDebInfo) used to build HydroChrono **must match** the build type used when building Project Chrono. On Windows, this is set when running `cmake --build . --config Release`. For more context on build configurations and CMake behavior across platforms, see [CMake Build Configuration Basics](/developer_docs/cmake_build_basics).
+
 3. **Build the Project**
    Compile the project using the following command:
    ```powershell
@@ -103,13 +105,15 @@ If you prefer using Visual Studio, you can use the CMake GUI to generate a Visua
    - Enable the following options for additional features: `HYDROCHRONO_ENABLE_DEMOS`, `HYDROCHRONO_ENABLE_IRRLICHT`, and `HYDROCHRONO_ENABLE_TESTS`
    - To build the docs: set `Python3_ROOT_DIR` to your Python environment with required packages
 
+   **⚠️ Important:** The build type (e.g., Release, Debug, RelWithDebInfo) used to build HydroChrono **must match** the build type used when building Project Chrono. On Windows, this is set when running `cmake --build . --config Release`. For more context on build configurations and CMake behavior across platforms, see [CMake Build Configuration Basics](/developer_docs/cmake_build_basics).
+
 3. Click "Generate" to create the Visual Studio solution.
 
 4. Open the generated solution in Visual Studio and build the project.
 
 ## Post-Build Steps
 
-1. Copy the `chrono_build/bin/data` file from the Project Chrono build directory to your build directory's `data` folder to obtain optional shaders and logos.
+1. Copy the `chrono_build/bin/data` folder from the Project Chrono build directory to your build directory's `data` folder to obtain optional shaders and logos.
 
 2. Copy the following DLL files from your Chrono build directory to your build directory's `demos/Release` folder:
    - ChronoEngine.dll
diff --git a/docs/_main_pages/developer_docs/cmake_build_basics.md b/docs/_main_pages/developer_docs/cmake_build_basics.md
diff --git a/quick-build.ps1 b/quick-build.ps1
