PyHelios

PyHelios

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.

📖 Complete Documentation

⚠️Note that this is a work in progress. Not all Helios functionality has been implemented in PyHelios ⚠️

⚠️Help make PyHelios better by reporting issues: https://github.com/PlantSimulationLab/PyHelios/issues ⚠️

See the Helios C++ documentation for a more in-depth description of Helios: https://baileylab.ucdavis.edu/software/helios

Quick Start

Installation

Easy Install (Recommended):

pip install pyhelios3d

This installs pre-built PyHelios with platform-appropriate plugins:

• macOS (Apple Silicon): All plugins except GPU-accelerated ones (automatically detected)
• macOS (Intel): Pre-built wheels not available - please build from source
• Windows/Linux: All plugins including GPU acceleration (when hardware supports it)

PyHelios will gracefully handle GPU features - if you don't have CUDA-capable hardware, GPU plugins will display helpful error messages with setup instructions.

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.

Build from Source

If you need to customize plugins or build from source:

Windows

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
pip install -e .

macOS

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 dependencies and build native libraries
source helios-core/utilities/dependencies.sh
./build_scripts/build_helios
 
# Install PyHelios
pip install -e .

Linux (Ubuntu/Debian)

Prerequisites:

• Build essentials
• CMake
• Python 3.7+

# Clone repository
git clone --recursive https://github.com/PlantSimulationLab/PyHelios.git
cd PyHelios/
 
# Install dependencies and build native libraries
source helios-core/utilities/dependencies.sh
./build_scripts/build_helios
 
# Install PyHelios
pip install -e .

GPU Features Setup

If you want to use GPU-accelerated features (radiation modeling, aerial LiDAR), ensure you have:

Requirements:

• 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 version

Testing GPU Features:

from pyhelios import Context, RadiationModel
 
context = Context()
try:
    radiation = RadiationModel(context)
    print("GPU radiation modeling available!")
except RuntimeError as e:
    print(f"GPU features unavailable: {e}")

If GPU features fail, PyHelios will provide specific guidance on installation and setup requirements.

First Example

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}")

Documentation

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

Key Features

• Cross-platform: Windows, macOS, and Linux support
• Plant modeling: WeberPennTree procedural generation
• 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

PyPI Installation

If you installed via pip, simply upgrade to the latest version:

pip install --upgrade pyhelios3d

Source Installation

If 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.

Quick Commands

# 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

Support

• 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.