[v0.1.13] 2025-12-25

- Updated helios-core to v1.3.61

## Energy Balance
- **CUDA is now optional**: Plugin uses three-tier execution - GPU (CUDA), OpenMP (parallel CPU), or serial CPU fallback
- Added GPU acceleration control methods: `enableGPUAcceleration()`, `disableGPUAcceleration()`, `isGPUAccelerationEnabled()`, and `isGPUAccelerationAvailable()`
- OpenMP CPU mode is recommended for most workloads without GPU

## Plant Architecture
- Added capability to modify parameters for library plants or build custom plants

Author: bnbailey-psl

README.md

@@ -162,11 +162,9 @@ print(f"Created patch: {patch_uuid}")
 ## Key Features
 
 - **Cross-platform**: Windows, macOS, and Linux support
-- **Plant modeling**: WeberPennTree procedural generation 
+- **Plant modeling**: 20+ plant species models in the plant architecture plug-in
 - **GPU acceleration**: OptiX-powered radiation simulation
 - **3D visualization**: OpenGL-based real-time rendering
-- **Flexible plugins**: Currently 5 plug-ins implemented
-- **Development mode**: Mock mode for development without native libraries
 
 ## Updating PyHelios
 

docs/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+# [v0.1.13] 2025-12-25
+
+- Updated helios-core to v1.3.61
+
+## Energy Balance
+- **CUDA is now optional**: Plugin uses three-tier execution - GPU (CUDA), OpenMP (parallel CPU), or serial CPU fallback
+- Added GPU acceleration control methods: `enableGPUAcceleration()`, `disableGPUAcceleration()`, `isGPUAccelerationEnabled()`, and `isGPUAccelerationAvailable()`
+- OpenMP CPU mode is recommended for most workloads without GPU
+
+## Plant Architecture
+- Added capability to modify parameters for library plants or build custom plants
+
 # [v0.1.12] 2025-12-15
 
 - Many updates to documentation, transitioning toward consistency with c++ docs

docs/plugin_energybalance.md

@@ -5,7 +5,7 @@
 [TOC]
 
 <table>
-<tr><th>Dependencies</th><td>NVIDIA CUDA 9.0+</td></tr>
+<tr><th>Dependencies</th><td>None (CUDA optional for GPU acceleration)</td></tr>
 <tr><th>Python Import</th><td>`from pyhelios import EnergyBalanceModel`</td></tr>
 <tr><th>Main Class</th><td>\ref pyhelios.EnergyBalance.EnergyBalanceModel "EnergyBalanceModel"</td></tr>
 </table>
@@ -15,18 +15,24 @@
 <table>
   <tr>
     <th>Dependencies</th>
-    <td>NVIDIA CUDA 9.0+</td>
+    <td>None required (OpenMP recommended for parallel CPU execution)</td>
   </tr>
   <tr>
     <th>Platforms</th>
-    <td>Windows, Linux</td>
+    <td>Windows, Linux, macOS</td>
   </tr>
   <tr>
     <th>GPU</th>
-    <td>Required - NVIDIA CUDA-capable GPU</td>
+    <td>Optional - NVIDIA CUDA-capable GPU for GPU acceleration</td>
+  </tr>
+  <tr>
+    <th>Execution Modes</th>
+    <td>Three-tier: GPU (CUDA) → OpenMP (parallel CPU) → Serial CPU fallback</td>
   </tr>
 </table>
 
+**Note:** As of helios-core v1.3.61, CUDA is **optional**. The plugin automatically selects the best available execution mode: GPU acceleration with CUDA if available, parallel CPU with OpenMP if available, or serial CPU as fallback. OpenMP is recommended for most workloads on systems without CUDA.
+
 ## Quick Start
 
 ```python
@@ -68,37 +74,52 @@ with Context() as context:
  <tr>
   <td rowspan="2">**Runtime**<br>(pip install)</td>
   <td>NVIDIA GPU</td>
-  <td>Not supported</td>
-  <td colspan="2">Required - CUDA-capable (compute capability 3.5+)</td>
+  <td colspan="3">Optional - Enables GPU acceleration if available</td>
  </tr>
  <tr>
   <td>CUDA Runtime</td>
-  <td>Not supported</td>
-  <td colspan="2">Version 9.0+<br>Typically installed with NVIDIA drivers<br>Or install <a href="https://developer.nvidia.com/cuda-downloads">CUDA Toolkit</a></td>
+  <td colspan="3">Optional - Version 9.0+ for GPU acceleration<br>If not available, uses OpenMP CPU mode or serial fallback</td>
+ </tr>
+ <tr>
+  <td>**Runtime**<br>(recommended)</td>
+  <td>OpenMP</td>
+  <td colspan="3">Recommended - Enables parallel CPU execution<br>Typically included with GCC/Clang compilers</td>
  </tr>
  <tr style="border-top: 3px double #888">
-  <td>**Build from Source**<br>(additional deps)</td>
+  <td>**Build from Source**<br>(optional)</td>
   <td>CUDA Toolkit</td>
-  <td>Not supported</td>
-  <td colspan="2">Version 9.0+ with nvcc compiler<br><a href="https://developer.nvidia.com/cuda-downloads">Download CUDA Toolkit</a></td>
+  <td colspan="3">Optional - Version 9.0+ with nvcc compiler for GPU support<br><a href="https://developer.nvidia.com/cuda-downloads">Download CUDA Toolkit</a></td>
  </tr>
 </table>
 
-**For detailed CUDA installation instructions**, see the comprehensive \ref CUDASetup "CUDA Setup Guide", which covers:
+**Execution Mode Selection (v1.3.61+):**
+The plugin automatically selects the best available execution mode at runtime:
+1. **GPU mode (CUDA)** - Fastest, requires NVIDIA GPU and CUDA
+2. **Parallel CPU mode (OpenMP)** - Recommended for systems without GPU, uses multi-core parallelization
+3. **Serial CPU mode** - Fallback if neither GPU nor OpenMP available
+
+**For GPU acceleration setup**, see the comprehensive \ref CUDASetup "CUDA Setup Guide", which covers:
 - Choosing the correct CUDA toolkit version: \ref ChoosingCUDA
 - Platform-specific installation steps (Windows, Linux)
 - GPU timeout settings for Windows: \ref PCGPUTimeout
-- OptiX requirements: \ref OptiXSetup
 - Troubleshooting common issues
 
+**Note:** CUDA is **no longer required** as of helios-core v1.3.61. The plugin works on all platforms with automatic CPU fallback.
+
 
 ## Known Issues {#EBissues}
 
 None.
 
 ## Introduction {#EBIntro}
 
- This model plugin calculates a local energy balance for every primitive, and ultimately predicts sensible, latent, and longwave fluxes as well as surface temperature. The energy balance equation is solved in parallel on the GPU to accelerate calculations.
+ This model plugin calculates a local energy balance for every primitive, and ultimately predicts sensible, latent, and longwave fluxes as well as surface temperature. The energy balance equation is solved using one of three execution modes:
+
+ 1. **GPU acceleration (CUDA)** - Parallel execution on NVIDIA GPU for maximum performance
+ 2. **OpenMP parallel CPU** - Multi-core CPU parallelization (recommended for systems without GPU)
+ 3. **Serial CPU** - Single-threaded fallback if neither GPU nor OpenMP available
+
+ The execution mode is automatically selected based on available hardware and compiled libraries. GPU acceleration can be explicitly controlled using the GPU acceleration methods (see \ref EBGPUControl).
 
  The model is solving the steady-state budget between absorbed radiation, emitted radiation, sensible heat exchange, and latent heat exchange, which is written as
 

helios-core

@@ -148,6 +148,32 @@ PYHELIOS_API void printDefaultValueReport(EnergyBalanceModel* energy_model);
  */
 PYHELIOS_API void printDefaultValueReportForUUIDs(EnergyBalanceModel* energy_model, const unsigned int* uuids, unsigned int uuid_count);
 
+//=============================================================================
+// GPU Acceleration Control (Only available when compiled with CUDA)
+//=============================================================================
+
+/**
+ * @brief Enable GPU acceleration for energy balance calculations
+ * @param energy_model Pointer to the EnergyBalanceModel
+ * @note Only available when compiled with CUDA support
+ */
+PYHELIOS_API void enableGPUAcceleration(EnergyBalanceModel* energy_model);
+
+/**
+ * @brief Disable GPU acceleration and force CPU mode
+ * @param energy_model Pointer to the EnergyBalanceModel
+ * @note Only available when compiled with CUDA support
+ */
+PYHELIOS_API void disableGPUAcceleration(EnergyBalanceModel* energy_model);
+
+/**
+ * @brief Check if GPU acceleration is currently enabled
+ * @param energy_model Pointer to the EnergyBalanceModel
+ * @return 1 if GPU acceleration is enabled, 0 if not, -1 on error
+ * @note Only available when compiled with CUDA support
+ */
+PYHELIOS_API int isGPUAccelerationEnabled(EnergyBalanceModel* energy_model);
+
 #ifdef __cplusplus
 }
 #endif

native/include/pyhelios_wrapper_energybalance.h

@@ -21,8 +21,8 @@ PYHELIOS_API void destroyPlantArchitecture(PlantArchitecture* plantarch);
 
 // Plant library functions
 PYHELIOS_API int loadPlantModelFromLibrary(PlantArchitecture* plantarch, const char* plant_label);
-PYHELIOS_API unsigned int buildPlantInstanceFromLibrary(PlantArchitecture* plantarch, float* base_position, float age);
-PYHELIOS_API int buildPlantCanopyFromLibrary(PlantArchitecture* plantarch, float* canopy_center, float* plant_spacing, int* plant_count, float age, unsigned int** plant_ids, int* num_plants);
+PYHELIOS_API unsigned int buildPlantInstanceFromLibrary(PlantArchitecture* plantarch, float* base_position, float age, char** param_keys, float* param_values, int param_count);
+PYHELIOS_API int buildPlantCanopyFromLibrary(PlantArchitecture* plantarch, float* canopy_center, float* plant_spacing, int* plant_count, float age, unsigned int** plant_ids, int* num_plants, char** param_keys, float* param_values, int param_count_params);
 PYHELIOS_API int advanceTime(PlantArchitecture* plantarch, float dt);
 
 // Custom plant building functions
@@ -56,6 +56,18 @@ PYHELIOS_API int writePlantStructureXML(PlantArchitecture* plantarch, unsigned i
 PYHELIOS_API int writeQSMCylinderFile(PlantArchitecture* plantarch, unsigned int plantID, const char* filename);
 PYHELIOS_API int readPlantStructureXML(PlantArchitecture* plantarch, const char* filename, bool quiet, unsigned int** plant_ids, int* num_plants);
 
+// Parameter management functions
+PYHELIOS_API const char* getCurrentShootParametersJSON(PlantArchitecture* plantarch, const char* shoot_type_label);
+PYHELIOS_API int defineShootTypeFromJSON(PlantArchitecture* plantarch, helios::Context* context, const char* shoot_type_label, const char* json_params);
+
+// Phenological control functions
+PYHELIOS_API int setPlantPhenologicalThresholds(PlantArchitecture* plantarch, unsigned int plantID, float time_to_dormancy_break, float time_to_flower_initiation, float time_to_flower_opening, float time_to_fruit_set, float time_to_fruit_maturity, float time_to_dormancy, float max_leaf_lifespan);
+
+// Plant state query functions
+PYHELIOS_API float getPlantAge(PlantArchitecture* plantarch, unsigned int plantID);
+PYHELIOS_API float getPlantHeight(PlantArchitecture* plantarch, unsigned int plantID);
+PYHELIOS_API float sumPlantLeafArea(PlantArchitecture* plantarch, unsigned int plantID);
+
 #ifdef __cplusplus
 }
 #endif

native/include/pyhelios_wrapper_plantarchitecture.h

@@ -385,7 +385,76 @@ extern "C" {
             setError(PYHELIOS_ERROR_UNKNOWN, "ERROR (EnergyBalanceModel::printDefaultValueReport): Unknown error printing default value report for UUIDs.");
         }
     }
-    
+
+    //=============================================================================
+    // GPU Acceleration Control (Only available when compiled with CUDA)
+    //=============================================================================
+
+    PYHELIOS_API void enableGPUAcceleration(EnergyBalanceModel* energy_model) {
+        try {
+            clearError();
+            if (!energy_model) {
+                setError(PYHELIOS_ERROR_INVALID_PARAMETER, "EnergyBalanceModel pointer is null");
+                return;
+            }
+
+#ifdef HELIOS_CUDA_AVAILABLE
+            energy_model->enableGPUAcceleration();
+#else
+            setError(PYHELIOS_ERROR_RUNTIME, "GPU acceleration not available - library not compiled with CUDA support");
+#endif
+
+        } catch (const std::exception& e) {
+            setError(PYHELIOS_ERROR_RUNTIME, std::string("ERROR (EnergyBalanceModel::enableGPUAcceleration): ") + e.what());
+        } catch (...) {
+            setError(PYHELIOS_ERROR_UNKNOWN, "ERROR (EnergyBalanceModel::enableGPUAcceleration): Unknown error enabling GPU acceleration.");
+        }
+    }
+
+    PYHELIOS_API void disableGPUAcceleration(EnergyBalanceModel* energy_model) {
+        try {
+            clearError();
+            if (!energy_model) {
+                setError(PYHELIOS_ERROR_INVALID_PARAMETER, "EnergyBalanceModel pointer is null");
+                return;
+            }
+
+#ifdef HELIOS_CUDA_AVAILABLE
+            energy_model->disableGPUAcceleration();
+#else
+            // No-op if CUDA not available - already running in CPU mode
+#endif
+
+        } catch (const std::exception& e) {
+            setError(PYHELIOS_ERROR_RUNTIME, std::string("ERROR (EnergyBalanceModel::disableGPUAcceleration): ") + e.what());
+        } catch (...) {
+            setError(PYHELIOS_ERROR_UNKNOWN, "ERROR (EnergyBalanceModel::disableGPUAcceleration): Unknown error disabling GPU acceleration.");
+        }
+    }
+
+    PYHELIOS_API int isGPUAccelerationEnabled(EnergyBalanceModel* energy_model) {
+        try {
+            clearError();
+            if (!energy_model) {
+                setError(PYHELIOS_ERROR_INVALID_PARAMETER, "EnergyBalanceModel pointer is null");
+                return -1;
+            }
+
+#ifdef HELIOS_CUDA_AVAILABLE
+            return energy_model->isGPUAccelerationEnabled() ? 1 : 0;
+#else
+            return 0;  // GPU acceleration never enabled without CUDA
+#endif
+
+        } catch (const std::exception& e) {
+            setError(PYHELIOS_ERROR_RUNTIME, std::string("ERROR (EnergyBalanceModel::isGPUAccelerationEnabled): ") + e.what());
+            return -1;
+        } catch (...) {
+            setError(PYHELIOS_ERROR_UNKNOWN, "ERROR (EnergyBalanceModel::isGPUAccelerationEnabled): Unknown error checking GPU acceleration status.");
+            return -1;
+        }
+    }
+
 } //extern "C"
 
 #endif //ENERGYBALANCE_PLUGIN_AVAILABLE