Metadata-Version: 2.4
Name: pyhelios3d
Version: 0.1.18
Summary: Cross-platform Python bindings for Helios 3D plant simulation
Home-page: https://github.com/PlantSimulationLab/PyHelios
Author: Brian Bailey
Author-email: bnbailey@ucdavis.edu
Project-URL: Documentation, https://baileylab.ucdavis.edu/software/helios
Project-URL: Source, https://github.com/PlantSimulationLab/PyHelios
Project-URL: Tracker, https://github.com/PlantSimulationLab/PyHelios/issues
Project-URL: Helios Core, https://github.com/PlantSimulationLab/Helios
Keywords: helios,plant simulation,3d modeling,ray tracing,photosynthesis,plant architecture
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.19.0
Requires-Dist: pyyaml>=5.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
Requires-Dist: pytest-forked>=1.6.0; extra == "dev"
Requires-Dist: doxypypy>=0.8.8.6; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
Requires-Dist: pytest-timeout>=2.1.0; extra == "test"
Requires-Dist: pytest-forked>=1.6.0; extra == "test"
Provides-Extra: build
Requires-Dist: cmake; extra == "build"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<br><br>

[![Build Wheels](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/build-wheels.yml/badge.svg?event=push)](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/build-wheels.yml) [![Test Linux](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-linux.yml/badge.svg?branch=master)](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-linux.yml) [![Test Windows](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-windows.yml/badge.svg?branch=master)](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-windows.yml) [![Test MacOS](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-macos.yml/badge.svg?branch=master)](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-macos.yml)
[![PyPI version](https://img.shields.io/pypi/v/pyhelios3d.svg)](https://pypi.org/project/pyhelios3d/)

<div align="center">
  <img src="https://raw.githubusercontent.com/PlantSimulationLab/PyHelios/master/docs/images/PyHelios_logo_whiteborder.png"  alt="" width="300" />
</div>

# Getting Started {#GettingStarted}

Cross-platform Python bindings for [Helios](https://github.com/PlantSimulationLab/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](https://plantsimulationlab.github.io/PyHelios/)**

⚠️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):**
```bash
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](#build-from-source)
- **Windows/Linux**: All plugins with GPU acceleration via OptiX backend (NVIDIA GPUs)

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](#macos) 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+

```bash
# 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+

```bash
# 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+

```bash
# 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:**
```bash
vulkaninfo  # Should show Vulkan device information
# OR for NVIDIA:
nvidia-smi  # Should show GPU information
```

**Testing GPU Features:**
```python
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

```python
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](https://plantsimulationlab.github.io/PyHelios/Introduction.html)** | Installation, setup, and first steps |
| **[User Guide](https://plantsimulationlab.github.io/PyHelios/API.html)**           | Core concepts, API reference, and examples |
| **[Cross-Platform](https://plantsimulationlab.github.io/PyHelios/CrossPlatform.html)**   | Platform-specific usage and deployment |
| **[Plugin System](https://plantsimulationlab.github.io/PyHelios/PluginSystem.html)**     | Available plugins and configuration |

## 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:

```bash
pip install --upgrade pyhelios3d
```

### Source Installation

If you built PyHelios from source, update with the latest changes:

```bash
# 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

```bash
# 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](https://github.com/PlantSimulationLab/PyHelios/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.
