Getting Started

PyHelios is the Python API for Helios, an open-source framework for building virtual plants, canopies, and landscapes, then simulating the physics and physiology around them. Grow plants with a procedural plant model, then compute how they intercept light, photosynthesize, transpire, exchange heat, and appear to sensors, from a single leaf to a whole field.

• Plant architecture: functional-structural plant modeling (FSPM) with 20+ dynamic crop and tree models that grow over time, plus Weber-Penn trees
• Radiation: ray-traced radiation transfer on any GPU through Vulkan (NVIDIA, AMD, Intel, Apple) or on NVIDIA GPUs through OptiX
• Physiology and physics: photosynthesis, stomatal conductance, leaf optics, boundary-layer conductance, energy balance and evapotranspiration, plant hydraulics, and soil transport
• Synthetic sensing: simulated LiDAR point clouds and camera imagery with automatic annotation, for remote sensing, phenotyping, and machine-learning training data
• Analysis and visualization: parameter optimization, solar position, and OpenGL rendering, including headless rendering on compute nodes
• Cross-platform: pip install pyhelios3d provides pre-built wheels for Windows, Linux, and Apple Silicon macOS

📖 Complete Documentation · Helios C++ documentation

PyHelios is under active development, and not all Helios functionality is available from Python yet. Please report problems or missing features in the issue tracker.

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, 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 libxext6

EGL (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.

Build from Source

If you need to customize plugins or build from source:

Building on 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 .

Building on 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 .

Building on Linux (Ubuntu/Debian)

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

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

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

# Run the test suite
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://plantsimulationlab.github.io/Helios/

---

Note: This project is in active development. The API may change quickly - see docs/CHANGELOG.md for updates.