[1.3.41] 2025-07-22

🚨+ NEW PLUG-IN + 🚨
- Added a new `parameteroptimization` plug-in. Credit to Kyle Rizzo for developing this plug-in.

- Applied `.clang-format` to all source files. As such, there are a lot of small changes to many files in this commit.
- Converted the following plug-ins to use the doctest framework: `energybalance`, `photosynthesis`, `radiation`, `stomatalconductance`, `canopygenerator`, `leafoptics`, `lidar`, `planthydraulics`, `plantarchitecture`, `projectbuilder`, `voxelintersection`, `weberpenntree`, and `boundarylayerconductance`.

- Added `Context::listAllPrimitiveDataLabels()` and `Context::listAllObjectDataLabels()` methods to efficiently get a list of all primitive or object data labels that exist.
- Added `Context::showPrimitive()` and `Context::showObject()` methods to show a previously hidden primitive or object.
- Fixed an error in `Tube::scaleTubeGirth(float S)` where the stored radius value was not being updated (although the actual primitive geometry was).
- Split doctest tests into separate files for better organization.
- An error was corrected in `Context::cleanDeletedUUIDs(std::vector<std::vector<uint>> &UUIDs)` and `Context::cleanDeletedUUIDs(std::vector<std::vector<std::vector<uint>>> &UUIDs)`, which were checking for object IDs instead of primitive UUIDs.

- Modified inclined plate model code to fall back to purely free convection when wind speed is zero, rather than giving NaN.

- Re-factored the plug-in to streamline creation of new plant models in the library (see documentation).

- Functions for reading/writing of PNG and JPEG files have been removed from the Visualizer. Functions from the Context are now used instead, which reduces redundant code.

Co-authored by: Kyle Rizzo <[email protected]>

Author: bnbailey-psl

.claude/.gitignore

@@ -1,16 +1,71 @@
+## Common Mistakes to Avoid
+- **Never create build directories** - They already exist in all sample projects
+- **Never build from `core/` or `plugins/` directories** - Always use `samples/`
+- **Never use `mkdir` for build directories** - Just `cd` into the existing build directory
+
 ## Code Style
-- Code style should follow the style given in .clang-format.
-- Standard C++ library include headers are listed in the file core/include/global.h. Check these includes to make sure you do not add unnecessary includes.
+- Code style should follow the style given in `.clang-format`.
+- Standard C++ library include headers are listed in the file `core/include/global.h`. Check these includes to make sure you do not add unnecessary includes.
+- Prefer descriptive variable names that 'self-document' the code.
+- Prefer clearer code over clever optimized code that provides only marginal performance improvements.
+
+## Code Structure
+- The code is organized into a core library and plugins. The core library contains the main functionality, while plugins provide additional features.
+- The folder `samples` contains many examples that illustrate how to run the code. Each of these examples contains a `CMakeLists.txt` file that can be used to build the example. This file references `core/CMake_project.cmake`, which is the highest level CMake file for the core library, and also links any plugin CMake files.
+- CMakeLists.txt files inside `core` and `plugins` do not build by themselves. You need to build a project that uses `core/CMake_project.cmake` to build the core library and any plugins.
 
 ## 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:
+
+### Test File Organization
+- Core tests are located in `core/tests/` with 5 main test header files:
+    - `Test_utilities.h`: Vector types, colors, dates/times, coordinate systems
+    - `Test_functions.h`: Global helper functions and math utilities
+    - `Test_XML.h`: XML parsing functions
+    - `Test_context.h`: Context class methods
+    - `Test_data.h`: Context data management (primitive, object, global data)
+- Plugin tests are in `plugins/[plugin_name]/tests/selfTest.cpp`
+- Tests use the doctest framework with specific patterns (DOCTEST_TEST_CASE, DOCTEST_CHECK, etc.)
+- When adding new functions or classes, always add a test for it in the appropriate test file.
+
+### Build and Test Workflow
+1. **Building Tests**: Always build from a sample directory, not from core or plugins directly
+   ```bash
+   cd samples/[project_name]/
+   cd build  # The build directory already exists - DO NOT create it with mkdir
+   cmake .. && make
+   ```
+   **IMPORTANT**: Never use `mkdir` to create build directories - they already exist in all sample projects
+   
+2. **Running Tests**: 
+   - For core tests: `./context_tests` (from context_selftest/build/)
+   - For plugin tests: `./{plugin_name}_selftest` or `./{plugin_name}_tests`
+
+3. **Common Build Issues**:
+   - Always check compilation errors carefully for missing includes or function signature mismatches
+   - Plugin tests may have different data label expectations than actual implementation (verify against source code)
+   - Tests failing with "does not exist" errors usually indicate incorrect data labels in tests
+
+### Test Coverage
+- The script `utilities/generate_coverage_report.sh` can be used to check test coverage.
+- The script must be run from the build directory. For example, `cd samples/context_selftest/build && ../../../utilities/generate_coverage_report.sh -t context_tests -r html -l logfile.log`.
+- **Prefer HTML output (`-r html`)** over text output - it provides a clear summary table with color-coded coverage percentages and clickable file navigation in `coverage/index.html`.
+- Coverage analysis requires tests to compile and run successfully first
+- Coverage improvements should focus on:
+    - Adding tests for uncovered functions (check function names against test coverage)
+    - Verifying data manipulation functions use correct parameter types and labels
+    - Testing edge cases and error conditions
+    - Ensuring tests are organized with similar functionality and non-redundant
+
+### Debugging Plugin Tests
+- When plugin tests fail, first check if the test expectations match the actual implementation
+- Always verify test expectations against the source code in `plugins/[name]/src/`
+- Tests should not write any errors messages to std::cerr. Use the struct `capture_cerr` (defined in `core/include/global.h`) to capture any error messages and check them in the test.
+- Make sure that any functions marked `[[nodiscard]]` assign their return value to a variable in the test, otherwise the compiler will issue a warning.
+   
+## Documentation
+- When adding new functions or classes, always add a docstring to the header file, and consider whether additional documentation is needed (in `doc/*.dox` for the core or `plugins/[plugin_name]/doc/*.dox` for plugins).
+- If changes are made to docstrings or function signatures, build the documentation file `doc/Doxyfile` using doxygen to test it. 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".
-    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.
-### 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.
+    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.

AGENTS.md

@@ -2,10 +2,10 @@
 
 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
+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");
@@ -21,7 +21,7 @@ int main(){
     outfile << "PLY model load, " << elapsed << "\n";
 
     timer.tic();
-    ground_UUIDs = context.addTile(nullorigin, ground_size, nullrotation, make_int2(Nx, Ny) );
+    ground_UUIDs = context.addTile(nullorigin, ground_size, nullrotation, make_int2(Nx, Ny));
     elapsed = timer.toc("Ground geometry creation");
     outfile << "Ground geometry creation, " << elapsed << "\n";
 
@@ -51,4 +51,4 @@ int main(){
 
     outfile.close();
     return EXIT_SUCCESS;
-}
+}

benchmarks/energy_balance_dragon/main.cpp

@@ -2,11 +2,11 @@
 
 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
+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;
@@ -23,4 +23,4 @@ int main(){
 
     outfile.close();
     return EXIT_SUCCESS;
-}
+}

benchmarks/plant_architecture_bean/main.cpp

@@ -2,17 +2,17 @@
 
 using namespace helios;
 
-int main(){
+int main() {
 
     bool failure = false;
 
     uint Ndirect = 1024;
     uint Ndiffuse = 1024;
 
-    float D = 20;          //domain width
-    float LAI = 1.0;       //canopy leaf area index
-    float h = 3;           //canopy height
-    float w_leaf = 0.05;   //leaf width
+    float D = 20; // domain width
+    float LAI = 1.0; // canopy leaf area index
+    float h = 3; // canopy height
+    float w_leaf = 0.05; // leaf width
 
     std::ofstream outfile("../results/runtime.txt");
 
@@ -23,42 +23,41 @@ int main(){
 
     timer.tic();
 
-    uint objID_ptype = context.addTileObject( make_vec3(0,0,0), make_vec2(w_leaf,w_leaf), make_SphericalCoord(0,0), make_int2(2,2), "plugins/radiation/disk.png" );
+    uint objID_ptype = context.addTileObject(make_vec3(0, 0, 0), make_vec2(w_leaf, w_leaf), make_SphericalCoord(0, 0), make_int2(2, 2), "plugins/radiation/disk.png");
     std::vector<uint> UUIDs_ptype = context.getObjectPointer(objID_ptype)->getPrimitiveUUIDs();
 
     float A_leaf = 0;
-    for( uint p=0; p<UUIDs_ptype.size(); p++ ){
+    for (uint p = 0; p < UUIDs_ptype.size(); p++) {
         A_leaf += context.getPrimitiveArea(UUIDs_ptype.at(p));
     }
 
-    int Nleaves = round(LAI*D*D/A_leaf);
+    int Nleaves = round(LAI * D * D / A_leaf);
 
     std::vector<uint> UUIDs_leaf;
 
-    for( int i=0; i<Nleaves; i++ ){
+    for (int i = 0; i < Nleaves; i++) {
 
-        vec3 position( (-0.5+context.randu())*D, (-0.5+context.randu())*D, 0.5*w_leaf+context.randu()*h );
+        vec3 position((-0.5 + context.randu()) * D, (-0.5 + context.randu()) * D, 0.5 * w_leaf + context.randu() * h);
 
-        SphericalCoord rotation( 1.f, acos(1.f-context.randu()), 2.f*M_PI*context.randu() );
+        SphericalCoord rotation(1.f, acos(1.f - context.randu()), 2.f * M_PI * context.randu());
 
-        uint objID = context.copyObject( objID_ptype );
+        uint objID = context.copyObject(objID_ptype);
 
-        context.getObjectPointer( objID )->rotate( -rotation.elevation, "y" );
-        context.getObjectPointer( objID )->rotate( rotation.azimuth, "z" );
+        context.getObjectPointer(objID)->rotate(-rotation.elevation, "y");
+        context.getObjectPointer(objID)->rotate(rotation.azimuth, "z");
 
-        context.getObjectPointer( objID )->translate( position );
+        context.getObjectPointer(objID)->translate(position);
 
-        std::vector<uint> UUIDs = context.getObjectPointer( objID )->getPrimitiveUUIDs();
-
-        UUIDs_leaf.insert( UUIDs_leaf.end(), UUIDs.begin(), UUIDs.end() );
+        std::vector<uint> UUIDs = context.getObjectPointer(objID)->getPrimitiveUUIDs();
 
+        UUIDs_leaf.insert(UUIDs_leaf.end(), UUIDs.begin(), UUIDs.end());
     }
 
-    context.deleteObject( objID_ptype );
+    context.deleteObject(objID_ptype);
 
-    std::vector<uint> UUIDs_ground = context.addTile( make_vec3(0,0,0), make_vec2(D,D), make_SphericalCoord(0,0), make_int2(100,100) );
+    std::vector<uint> UUIDs_ground = context.addTile(make_vec3(0, 0, 0), make_vec2(D, D), make_SphericalCoord(0, 0), make_int2(100, 100));
 
-    context.setPrimitiveData( UUIDs_ground, "twosided_flag", uint(0) );
+    context.setPrimitiveData(UUIDs_ground, "twosided_flag", uint(0));
 
     elapsed = timer.toc("Geometry creation");
     outfile << "Geometry Creation, " << elapsed << "\n";
@@ -68,15 +67,15 @@ int main(){
 
     radiation.addRadiationBand("direct");
     radiation.disableEmission("direct");
-    radiation.setDirectRayCount("direct",Ndirect);
-    float theta_s = 0.2*M_PI;
-    uint ID = radiation.addCollimatedRadiationSource( make_SphericalCoord(0.5*M_PI-theta_s,0.f) );
-    radiation.setSourceFlux(ID,"direct",1.f/cos(theta_s));
+    radiation.setDirectRayCount("direct", Ndirect);
+    float theta_s = 0.2 * M_PI;
+    uint ID = radiation.addCollimatedRadiationSource(make_SphericalCoord(0.5 * M_PI - theta_s, 0.f));
+    radiation.setSourceFlux(ID, "direct", 1.f / cos(theta_s));
 
     radiation.addRadiationBand("diffuse");
     radiation.disableEmission("diffuse");
-    radiation.setDiffuseRayCount("diffuse",Ndiffuse);
-    radiation.setDiffuseRadiationFlux("diffuse",1.f);
+    radiation.setDiffuseRayCount("diffuse", Ndiffuse);
+    radiation.setDiffuseRadiationFlux("diffuse", 1.f);
 
     radiation.enforcePeriodicBoundary("xy");
 
@@ -104,5 +103,4 @@ int main(){
     outfile.close();
 
     return EXIT_SUCCESS;
-
-}
+}

benchmarks/radiation_homogeneous_canopy/main.cpp

@@ -9,12 +9,15 @@ endif()
 # Defining Helios Context source files to be built
 set(HELIOS_SOURCES
         src/Context.cpp
+        src/Context_primitive.cpp
+        src/Context_object.cpp
         src/Context_fileIO.cpp
         src/Context_data.cpp
         src/global.cpp
-        src/selfTest.cpp
+        tests/selfTest.cpp
         lib/pugixml/pugixml.cpp
 )
+
 add_library(helios STATIC ${HELIOS_SOURCES})
 
 # Defining Helios Context include files
@@ -50,6 +53,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/" )
 
-add_executable( context_tests "src/TestMain.cpp" )
+add_executable( context_tests tests/TestMain.cpp )
 target_link_libraries( context_tests PRIVATE helios )
-add_test( NAME context_tests COMMAND context_tests )
+add_test( NAME context_tests COMMAND context_tests )

core/CMakeLists.txt

@@ -19,6 +19,43 @@ if(GIT_FOUND)
             OUTPUT_STRIP_TRAILING_WHITESPACE
     )
     message( STATUS "[Helios] Detected Git commit hash: ${GIT_COMMIT_HASH}" )
+    
+    # Get current branch name
+    execute_process(
+        COMMAND ${GIT_EXECUTABLE} rev-parse --abbrev-ref HEAD
+        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+        OUTPUT_VARIABLE CURRENT_BRANCH
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        ERROR_QUIET
+        RESULT_VARIABLE BRANCH_RESULT
+    )
+    
+    # Only check for updates if we're on master/main branch
+    if(BRANCH_RESULT EQUAL 0 AND (CURRENT_BRANCH STREQUAL "master" OR CURRENT_BRANCH STREQUAL "main"))
+        execute_process(
+            COMMAND ${GIT_EXECUTABLE} fetch --dry-run
+            WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+            OUTPUT_QUIET
+            ERROR_QUIET
+            RESULT_VARIABLE FETCH_RESULT
+        )
+        
+        if(FETCH_RESULT EQUAL 0)
+            # Check if local branch is behind remote
+            execute_process(
+                COMMAND ${GIT_EXECUTABLE} rev-list HEAD..origin/${CURRENT_BRANCH} --count
+                WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+                OUTPUT_VARIABLE COMMITS_BEHIND
+                OUTPUT_STRIP_TRAILING_WHITESPACE
+                ERROR_QUIET
+                RESULT_VARIABLE REV_LIST_RESULT
+            )
+            
+            if(REV_LIST_RESULT EQUAL 0 AND COMMITS_BEHIND AND NOT COMMITS_BEHIND STREQUAL "0")
+                message(WARNING "[Helios] Your local ${CURRENT_BRANCH} branch is ${COMMITS_BEHIND} commit(s) behind the remote ${CURRENT_BRANCH} branch. Consider updating with 'git pull origin ${CURRENT_BRANCH}'.")
+            endif()
+        endif()
+    endif()
 else()
     set(GIT_COMMIT_HASH "unknown")
 endif()