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 energybalance in CPU mode (radiation requires CUDA)
- macOS (Intel): Pre-built wheels not available - please build from source
- Windows/Linux: All plugins with optional GPU acceleration (automatic CPU fallback)
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 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 (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)
Verification:
nvidia-smi # Should show GPU information
nvcc --version # Should show CUDA compiler versionTesting 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: OptiX-powered radiation simulation
- 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.