[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

@@ -31,11 +31,14 @@ pip install pyhelios3d
 ```
 
 This installs pre-built PyHelios with platform-appropriate plugins:
-- **macOS (Apple Silicon)**: All plugins except GPU-accelerated ones (automatically detected)
+- **macOS (Apple Silicon)**: All plugins including energybalance in CPU mode (radiation requires CUDA)
 - **macOS (Intel)**: Pre-built wheels not available - please [build from source](#build-from-source)
-- **Windows/Linux**: All plugins including GPU acceleration (when hardware supports it)
+- **Windows/Linux**: All plugins with optional GPU acceleration (automatic CPU fallback)
 
-PyHelios will gracefully handle GPU features - if you don't have CUDA-capable hardware, GPU plugins will display helpful error messages with setup instructions.
+PyHelios automatically selects the best execution mode:
+- **Plugins with GPU-only modes** (radiation): Require CUDA-capable GPU
+- **Plugins with CPU/GPU modes** (energybalance): Work on all platforms, GPU acceleration optional
+- **CPU-only plugins**: Work on all platforms without special hardware
 
 > **Note for Intel Mac Users**: Due to GitHub Actions infrastructure limitations, pre-built wheels are only available for Apple Silicon Macs. Intel Mac users must build PyHelios from source following the [macOS build instructions](#macos) below.
 
@@ -103,11 +106,22 @@ source helios-core/utilities/dependencies.sh
 pip install -e .
 ```
 
-### GPU Features Setup
+### GPU Features Setup (Optional)
 
-If you want to use GPU-accelerated features (radiation modeling, aerial LiDAR), ensure you have:
+PyHelios plugins have three types of GPU support:
 
-**Requirements:**
+**GPU-Required Plugins** (need CUDA):
+- **Radiation Model**: OptiX-powered ray tracing for light simulation
+- **Aerial LiDAR**: GPU-accelerated LiDAR simulation
+
+**GPU-Optional Plugins** (work with or without CUDA):
+- **Energy Balance** *(v1.3.61+)*: Automatic mode selection - GPU (CUDA) → OpenMP (parallel CPU) → Serial CPU
+  - CPU mode recommended for most workloads without GPU
+
+**CPU-Only Plugins** (no GPU needed):
+- All other plugins (PlantArchitecture, Photosynthesis, SolarPosition, etc.)
+
+**For GPU Acceleration** (optional), ensure you have:
 - NVIDIA GPU with CUDA support
 - NVIDIA drivers installed
 - CUDA Toolkit (version 11.8 or 12.x)
@@ -120,18 +134,25 @@ nvcc --version  # Should show CUDA compiler version
 
 **Testing GPU Features:**
 ```python
-from pyhelios import Context, RadiationModel
+from pyhelios import Context, RadiationModel, EnergyBalanceModel
 
 context = Context()
+
+# Test GPU-required plugin (radiation)
 try:
     radiation = RadiationModel(context)
     print("GPU radiation modeling available!")
 except RuntimeError as e:
-    print(f"GPU features unavailable: {e}")
+    print(f"Radiation requires GPU: {e}")
+
+# Test GPU-optional plugin (energybalance)
+with EnergyBalanceModel(context) as energy:
+    if energy.isGPUAccelerationEnabled():
+        print("EnergyBalance using GPU acceleration")
+    else:
+        print("EnergyBalance using CPU mode (OpenMP or serial)")
 ```
 
-If GPU features fail, PyHelios will provide specific guidance on installation and setup requirements.
-
 ### First Example
 
 ```python
@@ -162,11 +183,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/examples/stanford_bunny_energy_balance.py

@@ -8,8 +8,8 @@
 temperatures, and visualizes the temperature distribution using the native PyHelios visualizer.
 
 HARDWARE REQUIREMENTS:
-- NVIDIA GPU with CUDA compute capability (for radiation simulation and energy balance)
-- CUDA Toolkit installed and configured
+- NVIDIA GPU with CUDA compute capability (for radiation simulation GPU acceleration)
+- CUDA Toolkit installed and configured (for radiation)
 - OptiX ray tracing SDK installed (for radiation)
 - OpenGL-compatible graphics system (for visualization)
 
@@ -18,7 +18,9 @@
 - Stanford Bunny PLY file (included in helios-core)
 
 NOTE: This example demonstrates the full PyHelios workflow including native 3D visualization.
-Both radiation and energy balance plugins require GPU acceleration for full functionality.
+- Radiation plugin REQUIRES GPU (CUDA + OptiX)
+- EnergyBalance plugin works on CPU or GPU (automatic fallback, GPU optional as of v1.3.61+)
+- Visualizer plugin works on all platforms with OpenGL
 
 This is the PyHelios equivalent of helios-core/samples/energybalance_StanfordBunny/main.cpp
 """

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