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

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 {#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.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 .

macOS {#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 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.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 .

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.