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
Requirements: Python 3.10 or later (pre-built wheels available for Python 3.10–3.14)
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)
Linux system libraries: the visualizer links OpenGL, EGL and X11, which Linux
wheels do not bundle (they are loaded from the system at runtime). Desktop
distributions normally already have them; minimal container images such as
python:3-slim and nvidia/cuda:* do not:
apt-get update && apt-get install -y \
libgl1 libegl1 libsm6 libice6 libx11-6 libxext6EGL (libegl1, helios-core 1.3.85+) is what lets the visualizer render headless on a
machine with no display server at all, such as a batch compute node.
Without these, import pyhelios reports the missing library and falls back to mock mode.
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.10+
# 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.10+
# 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 librariessource helios-core/utilities/dependencies.sh
./build_scripts/build_helios
# Install PyHelios dependencies
pip install -e .Prerequisites:
- Build essentials
- CMake
- Python 3.10+
# Clone repository
git clone --recursive https://github.com/PlantSimulationLab/PyHelios.git
cd PyHelios/
# Install c++ dependencies and build native librariessource 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 at least one:
- Vulkan loader library (macOS/Linux only; no extra packages on Windows)
- OR for NVIDIA-optimized path: CUDA 12.0+ with driver >= 560 (OptiX 8.1) or CUDA 9.0+ with driver < 560 (OptiX 6.5)
The radiation plugin auto-detects the best available backend at runtime (OptiX 8 -> OptiX 6 -> Vulkan).
Verification:
vulkaninfo # Should show Vulkan device information# OR for NVIDIA:
nvidia-smi # Should show GPU informationTesting GPU Features:
frompyheliosimportContext, RadiationModel, EnergyBalanceModelcontext=Context()
# Test GPU-required plugin (radiation)try:
radiation=RadiationModel(context)
print("GPU radiation modeling available!")
exceptRuntimeErrorase:
print(f"Radiation requires GPU: {e}")
# Test GPU-optional plugin (energybalance)withEnergyBalanceModel(context) asenergy:
ifenergy.isGPUAccelerationEnabled():
print("EnergyBalance using GPU acceleration")
else:
print("EnergyBalance using CPU mode (OpenMP or serial)")frompyheliosimportContextfrompyhelios.typesimport*# Create simulation contextcontext=Context()
# Add a patch primitivecenter=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.