Cross-platform Python bindings for Helios 3D plant simulation library.
PyHelios provides a Python interface to the powerful Helios C++ library for 3D physical simulation of plant and environmental systems. It enables plant modeling, geometry manipulation, and biophysical simulations including GPU-accelerated radiation transfer, photosynthesis, and plant architecture modeling.
See the Helios C++ documentation for a more in-depth description of Helios: https://baileylab.ucdavis.edu/software/helios
Easy Install (Recommended):
pip install pyhelios3dThis installs pre-built PyHelios with platform-appropriate plugins:
- macOS (Apple Silicon): All plugins including radiation via Vulkan backend
- macOS (Intel): Pre-built wheels not available - please build from source
- Windows/Linux: All plugins with GPU acceleration via OptiX backend (NVIDIA GPUs)
PyHelios automatically selects the best execution mode:
- Plugins with GPU backends (radiation): Require GPU - Vulkan (all platforms) or OptiX (NVIDIA)
- 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 below.
If you need to customize plugins or build from source:
Prerequisites:
- Visual Studio 2019+ or Build Tools for Visual Studio
- Python 3.7+
# Clone repository
git clone --recursive https://github.com/PlantSimulationLab/PyHelios.git
cd PyHelios/
# Build native libraries (optional - pre-built binaries included)
./build_scripts/build_helios
# Install PyHelios dependencies
pip install -e .Prerequisites:
- Xcode command line tools
- Python 3.7+
# Install Xcode command line tools
xcode-select --install
# Clone repository
git clone --recursive https://github.com/PlantSimulationLab/PyHelios.git
cd PyHelios/
# Install c++ dependencies and build native libraries
source helios-core/utilities/dependencies.sh
./build_scripts/build_helios
# Install PyHelios dependencies
pip install -e .Prerequisites:
- Build essentials
- CMake
- Python 3.7+
# Clone repository
git clone --recursive https://github.com/PlantSimulationLab/PyHelios.git
cd PyHelios/
# Install c++ dependencies and build native libraries
source helios-core/utilities/dependencies.sh
./build_scripts/build_helios
# Install PyHelios dependencies
pip install -e .PyHelios plugins have three types of GPU support:
GPU-Required Plugins:
- Radiation Model: GPU-accelerated ray tracing via Vulkan (all GPUs) or OptiX (NVIDIA)
- Aerial LiDAR: GPU-accelerated LiDAR simulation (CUDA)
GPU-Optional Plugins (work with or without GPU):
- 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:
- Vulkan SDK installed (supports NVIDIA, AMD, Intel, Apple Silicon GPUs)
- OR for NVIDIA-optimized path: CUDA Toolkit (version 11.8 or 12.x) + OptiX
Verification:
vulkaninfo # Should show Vulkan device information
# OR for NVIDIA:
nvidia-smi # Should show GPU informationTesting GPU Features:
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"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)")from pyhelios import Context
from pyhelios.types import *
# Create simulation context
context = Context()
# Add a patch primitive
center = vec3(2, 3, 4)
size = vec2(1, 1)
color = RGBcolor(0.25, 0.25, 0.25)
patch_uuid = context.addPatch(center=center, size=size, color=color)
print(f"Created patch: {patch_uuid}")| Section | Description |
|---|---|
| Getting Started | Installation, setup, and first steps |
| User Guide | Core concepts, API reference, and examples |
| Cross-Platform | Platform-specific usage and deployment |
| Plugin System | Available plugins and configuration |
- Cross-platform: Windows, macOS, and Linux support
- Plant modeling: 20+ plant species models in the plant architecture plug-in
- GPU acceleration: Radiation simulation via Vulkan or OptiX backends
- 3D visualization: OpenGL-based real-time rendering
If you installed via pip, simply upgrade to the latest version:
pip install --upgrade pyhelios3dIf you built PyHelios from source, update with the latest changes:
# Update main repository and submodules recursively
git pull --recurse-submodules
# Alternative: Update main repo first, then submodules
git pull
git submodule update --init --recursive
# Rebuild native libraries after updates (recommended)
./build_scripts/build_helios --clean
# Reinstall PyHelios
pip install -e .Important: Always use --recurse-submodules or manually update submodules when pulling updates, as PyHelios depends on the helios-core submodule for C++ functionality.
# Test installation (uses subprocess isolation for robust testing)
pytest
# Check plugin status
python -m pyhelios.plugins status
# Interactive plugin selection
./build_scripts/build_helios --interactive- Documentation: https://plantsimulationlab.github.io/PyHelios/
- Issues: GitHub Issues
- Helios C++ Docs: https://baileylab.ucdavis.edu/software/helios
Note: This project is in active development. The API may change quickly - see docs/CHANGELOG.md for updates.