[1.3.40] 2025-07-17

- Improvements to `utilities/run_benchmarks.sh` script with corresponding changes in `utilities/plot_benchmarks.py`.
- Added benchmarks to documentation.
- Added benchmark cases `energy_balance_dragon` and `plant_architecture_bean`.
- Updated required CMake version to 3.15 for plug-ins, and made many updates to plug-in CMakeLists.txt files to use more modern CMake features.
- Started transitioning tests to using the "doctest" framework. This will be a gradual process, and the old self-test framework will still be supported for now.

- Reverted a previous change in `Context::setPrimitiveData()` and `Context::setObjectData()` to not use range-based for loops when it is an openmp paralell loop.
- There was an issue in `Context::setObjectData()` and `Context::getObjectData()` where the openmp preprocessor directive needed to be placed after the static assert.
- Moved third-party library pugixml into the `core/lib` directory for better organization.
- Improved robustness of geometric intersection functions (`lineIntersection`, `pointInPolygon`, `fzero`).
- Added new geometric utility function `pointOnSegment`.
- Converted the self-tests to use the doctest framework.

- Updated visualizer code to only transfer buffer data to the GPU that has changed, rather than re-building all geometry every time any geometry changes.
- Changed the GLFW code to continuously update the window even when there are no new input events. This prevents the usual lag that can occur if the user doesn't move the mouse in the window.
- Converted the self-tests to use the doctest framework.

- Removed MacOS OptiX files from the repository.

- Minor updates based on edge cases found in the self-tests.
- Converted the self-tests to use the doctest framework.

Author: bnbailey-psl

AGENTS.md

@@ -4,9 +4,13 @@
 
 ## Testing
 - Do not try to run utilities/run_samples.sh. It will time out.
+### Documentation
 - If changes are made to docstrings or function signatures, build the documentation file `doc/Doxyfile` using doxygen. Some notes on this are given below:
-  - Run `doxygen doc/Doxyfile` to generate the documentation from the root directory not the `doc` directory.
-  - Check doxygen output for warnings. It is ok to ignore warnings of the form " warning: Member XXX is not documented." 
-  - The main concern when changing docstrings or function signatures is the potential for breaking \ref references, which produces a warning like:  warning: unable to resolve reference to XXX for \ref command".
+- Run `doxygen doc/Doxyfile` to generate the documentation from the root directory not the `doc` directory.
+- Check doxygen output for warnings. It is ok to ignore warnings of the form " warning: Member XXX is not documented." 
+- The main concern when changing docstrings or function signatures is the potential for breaking \ref references, which produces a warning like:  warning: unable to resolve reference to XXX for \ref command".
     When fixing these, don't just remove the funciton signature or use markdown `` ticks to suppress the warning. It is important to keep the signature in the reference for overloaded functions/methods. Figure out why the function signature is not matching and thus causing Doxygen to treat it as plain text.
-  - You tend to flag hash symbols in code blocks as erroneous and propose to add a double hash (e.g., '##include "Context.h"'). This is not needed and ends up rendering the double hash.
+- You tend to flag hash symbols in code blocks as erroneous and propose to add a double hash (e.g., '##include "Context.h"'). This is not needed and ends up rendering the double hash.
+### Test Coverage
+- The script `utilitiesgenerate_coverage_report.sh` can be used to check test coverage. 
+- It is recommended to use text-based output, which is achieved with the `-r text` option.

benchmarks/energy_balance_dragon/CMakeLists.txt

@@ -0,0 +1,10 @@
+# Helios standard CMakeLists.txt file version 1.9
+cmake_minimum_required(VERSION 3.15)
+project(helios)
+
+set(BASE_DIRECTORY "../..")
+set(EXECUTABLE_NAME "energy_balance_dragon")
+set(SOURCE_FILES "main.cpp")
+set(PLUGINS "energybalance")
+
+include("${BASE_DIRECTORY}/core/CMake_project.cmake")

benchmarks/energy_balance_dragon/main.cpp

@@ -0,0 +1,54 @@
+#include "EnergyBalanceModel.h"
+
+using namespace helios;
+
+int main(){
+    uint Nx = 500;      // grid size in x
+    uint Ny = 500;      // grid size in y
+    float D = 10.f;     // domain width
+    vec2 ground_size(D, D);
+
+    std::ofstream outfile("../results/runtime.txt");
+    Timer timer;
+    double elapsed;
+
+    Context context;
+    std::vector<uint> ground_UUIDs, dragon_UUIDs, all_UUIDs;
+
+    timer.tic();
+    dragon_UUIDs = context.loadPLY("../../../../PLY/StanfordDragon.ply");
+    elapsed = timer.toc("PLY model load");
+    outfile << "PLY model load, " << elapsed << "\n";
+
+    timer.tic();
+    ground_UUIDs = context.addTile(nullorigin, ground_size, nullrotation, make_int2(Nx, Ny) );
+    elapsed = timer.toc("Ground geometry creation");
+    outfile << "Ground geometry creation, " << elapsed << "\n";
+
+    all_UUIDs = ground_UUIDs;
+    all_UUIDs.insert(all_UUIDs.end(), dragon_UUIDs.begin(), dragon_UUIDs.end());
+
+    timer.tic();
+    context.setPrimitiveData(all_UUIDs, "radiation_flux_SW", 300.f);
+    float LW = 2.f * 5.67e-8f * pow(300.f, 4);
+    context.setPrimitiveData(all_UUIDs, "radiation_flux_LW", LW);
+    context.setPrimitiveData(all_UUIDs, "air_temperature", 300.f);
+    context.setPrimitiveData(all_UUIDs, "wind_speed", 1.f);
+    context.setPrimitiveData(all_UUIDs, "air_huidity", 0.5f);
+    context.setPrimitiveData(all_UUIDs, "air_pressure", 101000.f);
+    elapsed = timer.toc("Setting primitive data");
+    outfile << "Setting primitive data, " << elapsed << "\n";
+
+    EnergyBalanceModel eb(&context);
+    eb.disableMessages();
+
+    timer.tic();
+    eb.addRadiationBand("SW");
+    eb.addRadiationBand("LW");
+    eb.run();
+    elapsed = timer.toc("Energy balance run");
+    outfile << "Energy balance run, " << elapsed << "\n";
+
+    outfile.close();
+    return EXIT_SUCCESS;
+}

…tion_homogeneous_canopy/build/.gitignore …energy_balance_dragon/results/.gitignorebenchmarks/radiation_homogeneous_canopy/build/.gitignore renamed to benchmarks/energy_balance_dragon/results/.gitignore benchmarks/radiation_homogeneous_canopy/build/.gitignore renamed to benchmarks/energy_balance_dragon/results/.gitignore

@@ -0,0 +1,10 @@
+# Helios standard CMakeLists.txt file version 1.9
+cmake_minimum_required(VERSION 3.15)
+project(helios)
+
+set( BASE_DIRECTORY "../.." )
+set( EXECUTABLE_NAME "plant_architecture_bean" )
+set( SOURCE_FILES "main.cpp" )
+set( PLUGINS "plantarchitecture" )
+
+include( "${BASE_DIRECTORY}/core/CMake_project.cmake" )

benchmarks/plant_architecture_bean/CMakeLists.txt

@@ -0,0 +1,26 @@
+#include "PlantArchitecture.h"
+
+using namespace helios;
+
+int main(){
+    uint Nx = 5;       // number of plants in x-direction
+    uint Ny = 5;       // number of plants in y-direction
+    vec2 spacing(0.3f, 0.3f);  // plant spacing
+    float age = 45.f;   // age of plants in days
+
+    std::ofstream outfile("../results/runtime.txt");
+    Timer timer;
+    double elapsed;
+
+    Context context;
+    PlantArchitecture pa(&context);
+    pa.loadPlantModelFromLibrary("bean");
+
+    timer.tic();
+    pa.buildPlantCanopyFromLibrary(make_vec3(0.f, 0.f, 0.f), spacing, make_int2(Nx, Ny), age);
+    elapsed = timer.toc("Canopy build");
+    outfile << "Canopy build, " << elapsed << "\n";
+
+    outfile.close();
+    return EXIT_SUCCESS;
+}

benchmarks/plant_architecture_bean/main.cpp

@@ -2,21 +2,10 @@
 cmake_minimum_required(VERSION 3.15)
 project(helios)
 
-#-------- USER INPUTS ---------#
-
-#provide the path to Helios base directory, either as an absolute path or a path relative to the location of this file
 set( BASE_DIRECTORY "../.." )
-
-#define the name of the executable to be created
 set( EXECUTABLE_NAME "radiation_homogeneous_canopy" )
-
-#provide name of source file(s) (separate multiple file names with semicolon)
 set( SOURCE_FILES "main.cpp" )
-
-#specify which plug-ins to use (separate plug-in names with semicolon)
 set( PLUGINS "radiation" )
 
-
-#-------- DO NOT MODIFY ---------#
-include( "${BASE_DIRECTORY}/core/CMake_project.txt" )
+include( "${BASE_DIRECTORY}/core/CMake_project.cmake" )
 

benchmarks/plant_architecture_bean/results/.gitignore

@@ -13,15 +13,19 @@ set(HELIOS_SOURCES
         src/Context_data.cpp
         src/global.cpp
         src/selfTest.cpp
-        src/pugixml.cpp
+        lib/pugixml/pugixml.cpp
 )
 add_library(helios STATIC ${HELIOS_SOURCES})
 
 # Defining Helios Context include files
 target_include_directories(helios
         PUBLIC
         $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/lib/pugixml>
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/lib/doctest>
         $<INSTALL_INTERFACE:include>
+        $<INSTALL_INTERFACE:lib/pugixml>
+        $<INSTALL_INTERFACE:lib/doctest>
 )
 
 # External libraries
@@ -46,4 +50,6 @@ file( COPY "${CMAKE_CURRENT_SOURCE_DIR}/lib/images" DESTINATION "${CMAKE_BINARY_
 file( COPY "${CMAKE_CURRENT_SOURCE_DIR}/lib/models" DESTINATION "${CMAKE_BINARY_DIR}/lib/" )
 file( COPY "${CMAKE_CURRENT_SOURCE_DIR}/lib/testdata" DESTINATION "${CMAKE_BINARY_DIR}/lib/" )
 
-set( PLUGIN_INCLUDE_PATHS "${CMAKE_CURRENT_SOURCE_DIR}/include;" PARENT_SCOPE )
+add_executable( context_tests "src/TestMain.cpp" )
+target_link_libraries( context_tests PRIVATE helios )
+add_test( NAME context_tests COMMAND context_tests )

benchmarks/radiation_homogeneous_canopy/CMakeLists.txt

@@ -68,7 +68,7 @@ set( CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}" CACHE STRING "" )
 set( CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib" CACHE STRING "" )
 add_executable( ${EXECUTABLE_NAME} ${SOURCE_FILES} )
 add_subdirectory( "${BASE_DIRECTORY}/core" "lib" )
-target_link_libraries( ${EXECUTABLE_NAME} helios)
+target_link_libraries( ${EXECUTABLE_NAME} PUBLIC helios)
 if (CMAKE_CXX_COMPILER_ID STREQUAL "GNU" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 9)
     target_link_libraries(${EXECUTABLE_NAME} stdc++fs)
 endif()
@@ -85,18 +85,16 @@ foreach(PLUGIN ${PLUGINS})
         message( FATAL_ERROR "[Helios] The executable name cannot be the same as a plugin name. Please rename your executable." )
     endif()
     add_subdirectory( "${BASE_DIRECTORY}/plugins/${PLUGIN}" "${PROJECT_BINARY_DIR}/plugins/${PLUGIN}" )
-    target_link_libraries( ${EXECUTABLE_NAME} ${PLUGIN} )
+    target_link_libraries( ${EXECUTABLE_NAME} PUBLIC ${PLUGIN} )
+    target_link_libraries( ${PLUGIN} PUBLIC helios )
     if( NOT APPLE )
-        target_link_libraries( ${PLUGIN} helios )
         if (CMAKE_CXX_COMPILER_ID STREQUAL "GNU" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 9)
             target_link_libraries(${PLUGIN} stdc++fs)
         endif()
     endif()
 endforeach(PLUGIN)
-include_directories( "${PLUGIN_INCLUDE_PATHS};${CMAKE_CURRENT_SOURCE_DIRECTORY}" )
 
 target_compile_definitions(helios PUBLIC $<$<CONFIG:Debug>:HELIOS_DEBUG>  $<$<CONFIG:RelWithDebInfo>:HELIOS_DEBUG> )
-target_include_directories(helios PUBLIC "$<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/include>" )
 
 if( ENABLE_OPENMP )
     find_package(OpenMP)