Getting Started {#GettingStarted}

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

Requirements: Python 3.10 or later (pre-built wheels available for Python 3.10–3.14)

Easy Install (Recommended):

pip install pyhelios3d

This 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 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 libsm6 libice6 libx11-6 libxext6

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.

Build from Source {#build-from-source}

If you need to customize plugins or build from source:

Windows {#windows}

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 .

macOS {#macos}

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 libraries
source helios-core/utilities/dependencies.sh
./build_scripts/build_helios

# Install PyHelios dependencies
pip install -e .

Linux (Ubuntu/Debian) {#linux}

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 libraries
source helios-core/utilities/dependencies.sh
./build_scripts/build_helios

# Install PyHelios dependencies
pip install -e .

GPU Features Setup (Optional)

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 information

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

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

Key Features

• 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

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.