[1.3.27] 2025-02-11

**Some experimental OpenMP parallelization has been added. This is not enabled by default yet, but can be turned on by setting the CMake option ENABLE_OPENMP to ON.**
**Updates to core CMakeLists.txt to use more modern CMake features.**

*Context*
- Context::pruneTubeNodes() was added to allow for removal of part of a tube object.

*Plant Architecture*
- Added ground cherry weed model.
- Minor fix in PlantArchitecture::getPlsantLeafInclinationAngleDistribution() to prevent rare out of range index.
- Changed PlantArchitecture::getPlantLeafInclinationAngleDistribution() to area-weight the distribution, and removed the 'normalize' optional argument.
- Added PlantArchitecture::prunBranch() method to remove all or part of a branch and its downstream branches.
- Removed shoot parameter 'elongation_rate'. There is now an 'elongation_rate_max' shoot parameter that can be set by the user. The actual elongation rate can be reduced dynamically if the carbohydrate model is enabled.
- Many updates to carbohydrate model. Credit to Ethan Frehner for these updates.

*LiDAR*
- Added exportTriangleAzimuthDistribution() to write the triangulated azimuthal angle distribution to a file. Credit to Alejandra Ponce de Leon for this addition.
- The output distribution from exportTriangleInclinationDistribution() was not being normalized.

*Radiation*
- Added bindweed spectra to the default library.
- There was an error in the writeObjectDataLabelMap() method that could cause undefined behavior if the UUID in the pixel label map did not exist in the Context.
- There was an error in the writeObjectDataLabelMap() method where the primitive UUID was being used instead of the object ID.
- There was an error in the model that could cause incorrect assignment of radiative properties if runBand() is called with fewer bands than a previous call to runBand().
- The previous version could cause unnecessary updating of radiative properties, resulting in a performance hit. This has been fixed.
- Revised the radiation plug-in CMakeLists.txt to use a modern CMake approach for building CUDA source files. This update should also enable indexing of .cu source files in IDEs such as CLion.

Co-authored-by: Alejandra Ponce de Leon <[email protected]>
Co-authored-by: Ethan Frehner <[email protected]>

Author: 3 people

core/CMakeLists.txt

@@ -2,30 +2,43 @@ cmake_minimum_required(VERSION 3.15)
 
 project(helios)
 
-include_directories(include)
-
 if(NOT DEFINED CMAKE_SUPPRESS_DEVELOPER_WARNINGS)
      set(CMAKE_SUPPRESS_DEVELOPER_WARNINGS 1 CACHE INTERNAL "No dev warnings")
 endif()
 
-add_library( helios STATIC ${CMAKE_CURRENT_SOURCE_DIR}/src/Context.cpp;${CMAKE_CURRENT_SOURCE_DIR}/src/Context_fileIO.cpp;${CMAKE_CURRENT_SOURCE_DIR}/src/Context_data.cpp;${CMAKE_CURRENT_SOURCE_DIR}/src/global.cpp;${CMAKE_CURRENT_SOURCE_DIR}/src/selfTest.cpp;${CMAKE_CURRENT_SOURCE_DIR}/src/pugixml.cpp )
-
+# Defining Helios Context source files to be built
+set(HELIOS_SOURCES
+        src/Context.cpp
+        src/Context_fileIO.cpp
+        src/Context_data.cpp
+        src/global.cpp
+        src/selfTest.cpp
+        src/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>
+        $<INSTALL_INTERFACE:include>
+)
+
+# External libraries
 include_directories( "${CMAKE_CURRENT_SOURCE_DIR}/lib/zlib")
-add_subdirectory( "${CMAKE_CURRENT_SOURCE_DIR}/lib/zlib" "${CMAKE_BINARY_DIR}/lib/zlib" )
-target_link_libraries( zlibstatic )
+add_subdirectory("${CMAKE_CURRENT_SOURCE_DIR}/lib/zlib"     "${CMAKE_BINARY_DIR}/lib/zlib")
 
 include_directories( "${CMAKE_CURRENT_SOURCE_DIR}/lib/libpng")
-add_subdirectory( "${CMAKE_CURRENT_SOURCE_DIR}/lib/libpng" "${CMAKE_BINARY_DIR}/lib/libpng" )
+add_subdirectory("${CMAKE_CURRENT_SOURCE_DIR}/lib/libpng"   "${CMAKE_BINARY_DIR}/lib/libpng")
 add_dependencies( png_static zlibstatic )
 
-target_link_libraries( helios png_static )
-
 include_directories("${CMAKE_BINARY_DIR}/lib/libjpeg-9a;${CMAKE_CURRENT_SOURCE_DIR}/lib/libjpeg-9a")
-add_subdirectory("lib/libjpeg-9a" "${CMAKE_BINARY_DIR}/lib/libjpeg-9a" )
-target_link_libraries( helios jpeg )
+add_subdirectory("${CMAKE_CURRENT_SOURCE_DIR}/lib/libjpeg-9a" "${CMAKE_BINARY_DIR}/lib/libjpeg-9a")
+
+target_link_libraries( helios PRIVATE png_static  jpeg ) #note that zlib is already linked by libpng
 
 file( COPY "${CMAKE_CURRENT_SOURCE_DIR}/lib/images" DESTINATION "${CMAKE_BINARY_DIR}/lib/" )
 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 )
+set( PLUGIN_INCLUDE_PATHS "${CMAKE_CURRENT_SOURCE_DIR}/include;" PARENT_SCOPE )

core/CMake_project.txt

@@ -1,3 +1,9 @@
+option(ENABLE_OPENMP "Enable building with OpenMP" OFF)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
 if ( WIN32 )
     SET(CMAKE_C_COMPILER_ID "MSVC")
     SET(CMAKE_CXX_COMPILER_ID "MSVC")
@@ -13,15 +19,7 @@ if ( WIN32 )
         set( CMAKE_RUNTIME_OUTPUT_DIRECTORY_${OUTPUTCONFIG} "${CMAKE_BINARY_DIR}" )
         set( CMAKE_LIBRARY_OUTPUT_DIRECTORY_${OUTPUTCONFIG} "${CMAKE_BINARY_DIR}/lib" )
         set( CMAKE_ARCHIVE_OUTPUT_DIRECTORY_${OUTPUTCONFIG} "${CMAKE_BINARY_DIR}/lib" )
-    endforeach( OUTPUTCONFIG CMAKE_CONFIGURATION_TYPES )
-else()
-    SET(CMAKE_C_COMPILER_ID "GNU")
-    SET(CMAKE_CXX_COMPILER_ID "GNU")
-    SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17")
-    if( CMAKE_BUILD_TYPE STREQUAL Debug )
-        SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -g" )
-        SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -g")
-    endif()
+    endforeach(OUTPUTCONFIG)
 endif()
 if( CMAKE_BUILD_TYPE STREQUAL Debug )
     SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DHELIOS_DEBUG" )
@@ -49,9 +47,31 @@ foreach(PLUGIN ${PLUGINS})
     endif()
     add_subdirectory( "${BASE_DIRECTORY}/plugins/${PLUGIN}" "${PROJECT_BINARY_DIR}/plugins/${PLUGIN}" )
     target_link_libraries( ${EXECUTABLE_NAME} ${PLUGIN} )
-    target_link_libraries( ${PLUGIN} helios )
+    if( NOT APPLE )
+        target_link_libraries( ${PLUGIN} helios )
+    endif()
 endforeach(PLUGIN)
 include_directories( "${PLUGIN_INCLUDE_PATHS};${CMAKE_CURRENT_SOURCE_DIRECTORY}" )
 
+if( ENABLE_OPENMP )
+    find_package(OpenMP)
+    if (OpenMP_CXX_FOUND)
+        message( "-- Enabling experimental OpenMP support" )
+        target_link_libraries(${EXECUTABLE_NAME} OpenMP::OpenMP_CXX)
+        target_compile_definitions(${EXECUTABLE_NAME} PRIVATE USE_OPENMP)
+        if ( WIN32 )
+            set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /openmp")
+        else()
+            set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fopenmp")
+        endif()
+    else()
+        if(CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang")
+            message(WARNING "You are using Apple Clang compiler, which does not support OpenMP. The program will compile without OpenMP support.")
+        else()
+            message(WARNING "OpenMP not found! The program will compile without OpenMP support.")
+        endif()
+    endif()
+endif()
+
 enable_testing()
-add_test(Test0,"${EXECUTABLE_NAME}" "0")
+add_test(NAME Test0 COMMAND ${EXECUTABLE_NAME} 0)

core/include/Context.h

@@ -735,6 +735,12 @@ class Tube : public CompoundObject {
      */
     void setTubeNodes( const std::vector<helios::vec3> &node_xyz );
 
+    //! Remove a portion of the tube downstream of a specified node
+    /**
+     * \param[in] node_index Index of the tube segment node beyond which will be removed
+     */
+    void pruneTubeNodes( uint node_index );
+
 protected:
 
     std::vector<helios::vec3> nodes;
@@ -4793,6 +4799,13 @@ class Context{
      */
     void scaleTubeLength( uint ObjID, float scale_factor );
 
+    //! Remove a portion of the tube downstream of a specified node
+    /**
+     * \param[in] ObjID object ID of the Tube object
+     * \param[in] node_index Index of the tube segment node beyond which will be removed
+     */
+    void pruneTubeNodes( uint ObjID, uint node_index );
+
     //! Set tube vertex coordinates at each segment node
     /**
      * \param[in] ObjID object ID of the Tube object

core/include/global.h

@@ -53,6 +53,10 @@ constexpr float PI_F = 3.14159265358979323846f;
 #include <iomanip>
 #include <filesystem>
 
+#ifdef USE_OPENMP
+#include <omp.h>
+#endif
+
 typedef unsigned int uint;
 
 #include "helios_vector_types.h"

core/src/Context.cpp

@@ -3913,6 +3913,33 @@ void Tube::setTubeNodes( const std::vector<helios::vec3> &node_xyz ){
 
 }
 
+void Tube::pruneTubeNodes( uint node_index ){
+
+    if( node_index >= nodes.size() ){
+        helios_runtime_error("ERROR (Tube::pruneTubeNodes): Node index of " + std::to_string(node_index) + " is out of bounds.");
+    }
+
+    if( node_index == 0 ){
+        context->deleteObject(this->OID);
+        return;
+    }
+
+    nodes.erase( nodes.begin() + node_index, nodes.end() );
+    triangle_vertices.erase( triangle_vertices.begin() + node_index, triangle_vertices.end() );
+    radius.erase( radius.begin() + node_index, radius.end() );
+    colors.erase( colors.begin() + node_index, colors.end() );
+
+    int ii=0;
+    for (int i = node_index; i < nodes.size() - 1; i++) {
+        for(int j=0; j < subdiv; j++ ) {
+            context->deletePrimitive(UUIDs.at(ii));
+            context->deletePrimitive(UUIDs.at(ii+1));
+            ii += 2;
+        }
+    }
+
+}
+
 void Tube::updateTriangleVertices(){
 
     vec3 v0, v1, v2;
@@ -8212,6 +8239,13 @@ void Context::scaleTubeLength( uint ObjID, float scale_factor ){
     dynamic_cast<Tube*>(objects.at(ObjID))->scaleTubeLength(scale_factor);
 }
 
+void Context::pruneTubeNodes( uint ObjID, uint node_index ){
+    if( objects.find(ObjID) == objects.end() ) {
+        helios_runtime_error("ERROR (Context::pruneTubeNodes): ObjectID of " + std::to_string(ObjID) + " does not exist in the Context.");
+    }
+    dynamic_cast<Tube*>(objects.at(ObjID))->pruneTubeNodes(node_index);
+}
+
 void Context::setTubeNodes( uint ObjID, const std::vector<helios::vec3> &node_xyz ){
     if( objects.find(ObjID) == objects.end() ) {
         helios_runtime_error("ERROR (Context::setTubeNodes): ObjectID of " + std::to_string(ObjID) + " does not exist in the Context.");

core/src/Context_fileIO.cpp

@@ -4142,10 +4142,10 @@ void Context::writeOBJ( const std::string &filename, const std::vector<uint> &UU
   // - it would make more sense to write patches  as quads rather than two triangles
 
   if( UUIDs.empty() ){
-    std::cout << "WARNING (Context::writeOBJ): No primitives found to write - OBJ file will not be written." << std::endl;
+    std::cout << "WARNING (Context::writeOBJ): No primitives found to write - OBJ file " << filename << " will not be written." << std::endl;
     return;
   }else if( filename.empty() ){
-    std::cout << "WARNING (Context::writeOBJ): Filename was empty - OBJ file will not be written." << std::endl;
+    std::cout << "WARNING (Context::writeOBJ): Filename was empty - OBJ file " << filename << " will not be written." << std::endl;
     return;
   }
 

doc/CHANGELOG

@@ -2023,4 +2023,32 @@ The radiation model has been re-designed, with the following primary additions:
 - Added mouse-based camera controls in the interactive visualizer. Credit to Sean Banks for this update.
 
 *Plant Architecture*
-- Added methods for querying bulk properties of a plant (total leaf count, stem height, plant height, leaf angle distribution) and write plant mesh vertices to file.
+- Added methods for querying bulk properties of a plant (total leaf count, stem height, plant height, leaf angle distribution) and write plant mesh vertices to file.
+
+[1.3.27] 2025-02-11
+
+**Some experimental OpenMP parallelization has been added. This is not enabled by default yet, but can be turned on by setting the CMake option ENABLE_OPENMP to ON.**
+**Updates to core CMakeLists.txt to use more modern CMake features.**
+
+*Context*
+- Context::pruneTubeNodes() was added to allow for removal of part of a tube object.
+
+*Plant Architecture*
+- Added ground cherry weed model.
+- Minor fix in PlantArchitecture::getPlsantLeafInclinationAngleDistribution() to prevent rare out of range index.
+- Changed PlantArchitecture::getPlantLeafInclinationAngleDistribution() to area-weight the distribution, and removed the 'normalize' optional argument.
+- Added PlantArchitecture::prunBranch() method to remove all or part of a branch and its downstream branches.
+- Removed shoot parameter 'elongation_rate'. There is now an 'elongation_rate_max' shoot parameter that can be set by the user. The actual elongation rate can be reduced dynamically if the carbohydrate model is enabled.
+- Many updates to carbohydrate model. Credit to Ethan Frehner for these updates.
+
+*LiDAR*
+- Added exportTriangleAzimuthDistribution() to write the triangulated azimuthal angle distribution to a file. Credit to Alejandra Ponce de Leon for this addition.
+- The output distribution from exportTriangleInclinationDistribution() was not being normalized.
+
+*Radiation*
+- Added bindweed spectra to the default library.
+- There was an error in the writeObjectDataLabelMap() method that could cause undefined behavior if the UUID in the pixel label map did not exist in the Context.
+- There was an error in the writeObjectDataLabelMap() method where the primitive UUID was being used instead of the object ID.
+- There was an error in the model that could cause incorrect assignment of radiative properties if runBand() is called with fewer bands than a previous call to runBand().
+- The previous version could cause unnecessary updating of radiative properties, resulting in a performance hit. This has been fixed.
+- Revised the radiation plug-in CMakeLists.txt to use a modern CMake approach for building CUDA source files. This update should also enable indexing of .cu source files in IDEs such as CLion.

doc/Doxyfile

@@ -1298,7 +1298,7 @@ HTML_EXTRA_STYLESHEET  =
 # files will be copied as-is; there are no commands or markers available.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_FILES       =
+HTML_EXTRA_FILES = /Users/bnbailey/Dropbox/Helios/doc/assets/doxygen-awesome-darkmode-toggle.js
 
 # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output
 # should be rendered with a dark or light theme.
@@ -1611,7 +1611,7 @@ DISABLE_INDEX          = NO
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 
 # When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the
 # FULL_SIDEBAR option determines if the side bar is limited to only the treeview
@@ -1623,7 +1623,7 @@ GENERATE_TREEVIEW      = NO
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-FULL_SIDEBAR           = NO
+FULL_SIDEBAR           = YES
 
 # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that
 # doxygen will group on one line in the generated HTML documentation.
@@ -1702,7 +1702,7 @@ USE_MATHJAX            = NO
 # The default value is: MathJax_2.
 # This tag requires that the tag USE_MATHJAX is set to YES.
 
-MATHJAX_VERSION        = MathJax_2
+MATHJAX_VERSION        = MathJax_3
 
 # When MathJax is enabled you can set the default output format to be used for
 # the MathJax output. For more details about the output format see MathJax

doc/UserGuide.dox

@@ -1,4 +1,4 @@
-/*! \mainpage Helios Documentation v1.3.26
+/*! \mainpage Helios Documentation
 
   <p> <br> </p>
 
@@ -40,15 +40,19 @@ $ git pull
   $ git log
   ~~~~~~
 
-<p> <br><br><br><br> </p>
+ <p> <br><br><br><br> </p>
 
-  \image html doc/images/PSL_logo_compact.png
+ <div align="center">
+    \image html doc/images/PSL_logo_compact.png
+ </div>
 
+  <!--
   <p> <br><br> </p>
 
   Financial support provided by:
 
   \image html doc/images/sponsors.jpg
+  -->
 
   <p> <br><br> </p>
 
@@ -348,7 +352,7 @@ $ git pull
 
   Projects that use the Helios API are typically built using the CMake package a CMakeLists.txt file.  Helios requires CMake version 3.15+. A prototypical CMakeLists.txt file used for building Helios samples and projects is given in the code sample below.  Inputs for the specific case are entered in the top block of code by setting variables (see the CMake 'set' command reference).  The user sets the location of the Helios base directory, the name of the executable file, any source or header files, and a list of plug-ins to use (the example below uses the 'visualizer' plug-in). The last line in the file references another file in the core/ directory that contains additional code for setting up the project.
 
-  ~~~~~~
+  ```
   # Helios standard CMakeLists.txt file version 1.9
   cmake_minimum_required(VERSION 3.15)
   project(helios)
@@ -369,21 +373,21 @@ $ git pull
 
   #-------- DO NOT MODIFY ---------#
   include( "${BASE_DIRECTORY}/core/CMake_project.txt" )
-  ~~~~~~
+ ```
 
   The easiest way to compile the code is by using an IDE such as CLion, which is described in detail on the page \ref CLionIDE "Using the CLion IDE with Helios".
 
   To build the code from the command line based on the CMakeLists.txt file, which creates a makefile, simply run the command 'cmake', followed by the path to the CMakeLists.txt file.  If, as in the examples above, you are currently in the build directory and your CMakeLists.txt file is located one directory up, the CMake build is accomplished through:
 
-  ~~~~~~
+  ```
   $ cmake ..
-  ~~~~~~
+  ```
 
   By default, this will build Helios in "debug" mode. This is useful for debugging and testing because it will generate debug symbols and output more detailed error messages to the command line. However, this will make the code run much slower because it disables compiler optimizations (usually 3x slower on Linux and 4-5x slower on PC). For 'production' runs, it is recommended to build in 'release' mode in order to enable compiler optimizations. This is accomplished by passing an additional command-line argument to CMake:
 
-  ~~~~~~
+  ```
   $ cmake -DCMAKE_BUILD_TYPE='Release' ..
-  ~~~~~~
+  ```
 
   The code can then be compiled by issuing the 'make' command from the build directory, which will produce an executable in the build directory.
 
@@ -459,20 +463,20 @@ $ git pull
 
  In order to use the Context, the following header must be included:
 
- ~~~~~~{.cpp}
+ ~~~
  #include "Context.h"
- ~~~~~~
+ ~~~
 
  The context is typically created within the main function:
 
- ~~~~~~{.cpp}
+ ~~~
  #include "Context.h"
  using namespace helios;
 
  int main(){
     Context context;
  }
- ~~~~~~
+ ~~~
 
  The Context is usually passed to plugins (see \ref Plugins), which gives them access to geometry and data.
 
@@ -1621,7 +1625,7 @@ $ git pull
 
   \section XMLread Reading XML Files
 
-  XML files can be read by the Context via the function \ref loadXML().  This function parses the XML file and adds all specified structures (see above) to the Context. Below is an example of how to load an XML file into the Context.
+  XML files can be read by the Context via the function \ref Context::loadXML().  This function parses the XML file and adds all specified structures (see above) to the Context. Below is an example of how to load an XML file into the Context.
   ~~~~~~{.cpp}
    #include "Context.h"
    using namespace helios;
@@ -1752,7 +1756,7 @@ $ git pull
 
   \section Export Exporting Project to XML File Format
 
-  All geometry and global/primitive data loaded into the Context can be written to an XML file using the \ref writeXML() function, which can be later read back in using the \ref loadXML(). This functionality can be used to save progress during a simulation run, or to ensure that consistent geometry is always used across simulation runs, among other things.
+  All geometry and global/primitive data loaded into the Context can be written to an XML file using the \ref Context::writeXML() function, which can be later read back in using the \ref Context::loadXML(). This functionality can be used to save progress during a simulation run, or to ensure that consistent geometry is always used across simulation runs, among other things.
 
   An XML file can be written as follows: