[v0.1.0] 2025-09-06

🎉++ PyPI Package Distribution ++ 🎉
- PyHelios now available on PyPI with `pip install pyhelios`

## Package Distribution
- Added comprehensive wheel building infrastructure with GitHub Actions CI/CD
- Cross-platform wheel support for Windows, macOS (x86_64 + ARM64), and Linux
- Automated CUDA toolkit installation and multi-architecture GPU support
- Smart platform detection for optimal plugin selection (macOS excludes GPU, Windows/Linux includes GPU when available)
- Added wheel preparation script for native library packaging
- Added MANIFEST.in for proper PyPI package structure

## Bug Fixes
- Fixed PluginMetadata constructor calls in build_helios.py
- Corrected plugin metadata parameter handling for GPU/visualization exclusions
- Enhanced build system robustness for different plugin configurations

Author: bnbailey-psl

.claude/agents/code-reviewer.md

@@ -15,6 +15,7 @@ When reviewing code changes since the last commit, you will:
 3. Evaluate code against established best practices for the specific language and framework
 4. Look for potential security vulnerabilities, performance issues, and maintainability concerns
 5. Check for consistency with existing codebase patterns and conventions
+6. **ALWAYS check git status** to identify any new files that should be added to version control
 
 **CRITICAL ISSUES TO CATCH:**
 - **Incomplete implementations**: Placeholder comments like "TODO", "FIXME", or unfinished logic
@@ -24,6 +25,9 @@ When reviewing code changes since the last commit, you will:
 - **Performance anti-patterns**: Inefficient algorithms, memory leaks, unnecessary database queries
 - **Error handling gaps**: Missing exception handling, inadequate error messages, swallowed exceptions
 - **Testing gaps**: Untestable code, missing edge case coverage, brittle test dependencies
+- **Git control gaps**: New files that should be added to version control but are missing from git
+- **Syntax errors**: Always run syntax checks on new Python files (python -m py_compile file.py)
+- **Missing imports**: Check that all required modules are imported in new files
 
 **BEST PRACTICES ENFORCEMENT:**
 - Code readability and self-documenting practices

.github/workflows/build-wheels.yml

@@ -0,0 +1,225 @@
+name: Build Wheels
+
+on:
+  push:
+    tags: [ 'v*' ]
+  workflow_dispatch:
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-24.04
+            arch: x86_64
+          - os: windows-2022
+            arch: AMD64
+          - os: macos-13
+            arch: x86_64
+          - os: macos-14
+            arch: arm64
+
+    steps:
+    - name: Checkout PyHelios
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
+        fetch-depth: 0  # Required for setuptools-scm
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.8'  # Use lowest supported version for compatibility
+
+    - name: Setup MSVC (Windows)
+      if: runner.os == 'Windows'
+      uses: ilammy/msvc-dev-cmd@v1
+
+    - name: Install Helios dependencies (Linux)
+      if: runner.os == 'Linux'
+      run: |
+        cd helios-core/utilities
+        sudo bash dependencies.sh ALL
+        
+    - name: Install Helios dependencies (macOS)
+      if: runner.os == 'macOS'
+      run: |
+        cd helios-core/utilities
+        # Install base + visualization dependencies (no GPU/CUDA for macOS builds)
+        bash dependencies.sh BASE
+        bash dependencies.sh VIS
+
+    - name: Debug environment (macOS)
+      if: runner.os == 'macOS'
+      run: |
+        echo "=== Directory structure ==="
+        ls -la
+        echo "=== PyHelios build scripts ==="
+        ls -la build_scripts/
+        echo "=== Helios core ==="
+        ls -la helios-core/ || echo "helios-core not found"
+        echo "=== Python version and location ==="
+        python --version
+        which python
+        echo "=== Environment ==="
+        env | grep -E "(PYTHON|PATH)" | head -10
+
+    - name: Install CUDA Toolkit (Windows)
+      if: runner.os == 'Windows'
+      shell: powershell
+      run: |
+        # Download CUDA 12.6 installer
+        Invoke-WebRequest -Uri "https://developer.download.nvidia.com/compute/cuda/12.6.2/network_installers/cuda_12.6.2_windows_network.exe" -OutFile "cuda_installer.exe"
+        # Install CUDA toolkit components needed for compilation
+        Start-Process -FilePath ".\cuda_installer.exe" -ArgumentList "-s","nvcc_12.6","cudart_12.6","nvrtc_12.6","nvrtc_dev_12.6","visual_studio_integration_12.6" -Wait
+        # Add CUDA to PATH for subsequent steps
+        echo "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+
+    - name: Install cibuildwheel and repair tools
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install cibuildwheel
+        # Install platform-specific wheel repair tools
+        if [ "${{ runner.os }}" = "Linux" ]; then
+          python -m pip install auditwheel
+        elif [ "${{ runner.os }}" = "macOS" ]; then
+          python -m pip install delocate
+        fi
+
+    - name: Build wheels
+      run: python -m cibuildwheel --output-dir wheelhouse
+      env:
+        # Build for Python 3.8+ on all platforms
+        CIBW_BUILD: cp38-* cp39-* cp310-* cp311-* cp312-*
+        
+        # Skip 32-bit builds and PyPy
+        CIBW_SKIP: "*-win32 *-manylinux_i686 *-musllinux* pp*"
+        
+        # Architecture configuration based on runner
+        CIBW_ARCHS: ${{ matrix.arch }}
+        
+        # Platform-specific build commands with broad CUDA compatibility
+        CIBW_BEFORE_BUILD_MACOS: "python build_scripts/prepare_wheel.py --buildmode release --nogpu --verbose"
+        CIBW_BEFORE_BUILD_WINDOWS: "set CMAKE_RC_COMPILER= && set PYHELIOS_CUDA_ARCHITECTURES=50;60;70;75;80;86;90 && python build_scripts/prepare_wheel.py --buildmode release --verbose"
+        CIBW_BEFORE_BUILD_LINUX: "export PYHELIOS_CUDA_ARCHITECTURES=50;60;70;75;80;86;90 && python build_scripts/prepare_wheel.py --buildmode release --verbose"
+        
+        # Test wheel installation
+        CIBW_TEST_COMMAND: "python -c 'import pyhelios; print(f\"PyHelios {pyhelios.__version__} imported successfully\")'"
+        CIBW_TEST_REQUIRES: "pytest"
+        
+        # Repair wheels to bundle dependencies
+        CIBW_REPAIR_WHEEL_COMMAND_MACOS: "delocate-wheel --require-archs {delocate_archs} -w {dest_dir} -v {wheel}"
+        CIBW_REPAIR_WHEEL_COMMAND_LINUX: "auditwheel repair -w {dest_dir} {wheel}"
+
+    - name: Debug build failure
+      if: failure()
+      run: |
+        echo "=== Build Failure Diagnostics ==="
+        echo "Build directory contents:"
+        find pyhelios_build -name "*.so" -o -name "*.dll" -o -name "*.dylib" 2>/dev/null || echo "No build directory found"
+        echo ""
+        echo "Plugin directory contents:"
+        ls -la pyhelios/plugins/ 2>/dev/null || echo "No plugins directory found"
+        echo ""
+        echo "Wheel directory contents:"
+        ls -la wheelhouse/ 2>/dev/null || echo "No wheelhouse directory found"
+        echo ""
+        echo "Python environment:"
+        python --version
+        pip list | grep -E "(cibuildwheel|auditwheel|delocate)" || echo "Wheel tools not found"
+
+    - name: Upload wheels as artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: wheels-${{ matrix.os }}-${{ matrix.arch }}
+        path: wheelhouse/*.whl
+        retention-days: 7
+
+  test_wheels:
+    name: Test wheels on ${{ matrix.os }} Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    needs: build_wheels
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-24.04
+            python-version: '3.8'
+          - os: ubuntu-24.04  
+            python-version: '3.11'
+          - os: windows-2022
+            python-version: '3.8'
+          - os: windows-2022
+            python-version: '3.11'
+          - os: macos-13
+            python-version: '3.8'
+          - os: macos-13
+            python-version: '3.11'
+          - os: macos-14
+            python-version: '3.8'
+          - os: macos-14
+            python-version: '3.11'
+
+    steps:
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Download wheels
+      uses: actions/download-artifact@v4
+      with:
+        pattern: wheels-*
+        merge-multiple: true
+        path: wheelhouse
+
+    - name: Install wheel
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install --find-links wheelhouse --no-index pyhelios
+
+    - name: Test basic functionality
+      run: |
+        python -c "
+        import pyhelios
+        from pyhelios import Context, WeberPennTree, WPTType
+        from pyhelios.types import vec2, vec3, RGBcolor
+        print(f'PyHelios version: {pyhelios.__version__}')
+        
+        # Test basic Context operations
+        context = Context()
+        center = vec3(1, 2, 3)
+        color = RGBcolor(0.5, 0.5, 0.5)
+        uuid = context.addPatch(center=center, size=vec2(1, 1), color=color)
+        print(f'Added patch with UUID: {uuid}')
+        
+        # Test plugin availability reporting
+        from pyhelios.plugins import print_plugin_status
+        print_plugin_status()
+        "
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build_wheels, test_wheels]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pyhelios
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+    - name: Download all wheels
+      uses: actions/download-artifact@v4
+      with:
+        pattern: wheels-*
+        merge-multiple: true
+        path: wheelhouse
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        packages-dir: wheelhouse/
+        verify-metadata: false  # Skip metadata verification due to dynamic versioning

.gitignore

@@ -9,9 +9,16 @@ build/
 *.egg-info/
 *.egg
 
+# Generated assets and libraries for wheel packaging (created by prepare_wheel.py)
+pyhelios/assets/build/
+pyhelios/plugins/
+
 # Auto-generated version file (setuptools-scm)
 pyhelios/_version.py
 
+# Auto-generated documentation
+docs/generated/
+
 # IDEs and editors
 .vscode/
 .idea/

MANIFEST.in

@@ -0,0 +1,25 @@
+# Include build scripts
+include build_scripts/*.py
+include build_scripts/build_helios
+
+# Include documentation
+include README.md
+include docs/CHANGELOG.md
+graft docs/examples
+recursive-exclude docs/generated *
+
+# Include configuration files
+include pyproject.toml
+include requirements*.txt
+include pytest.ini
+
+# Include native libraries that get built
+recursive-include pyhelios/plugins *.dll *.so *.dylib
+
+# Exclude test and development files
+recursive-exclude tests *
+recursive-exclude .github *
+recursive-exclude pyhelios_build *
+exclude test_*.py
+exclude .gitignore
+exclude .gitmodules

README.md

@@ -1,6 +1,6 @@
 <br><br>
 
-[![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)
+[![Build Wheels](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/build-wheels.yml/badge.svg?branch=master)](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)
 
 <div align="center">
   <img src="https://raw.githubusercontent.com/PlantSimulationLab/PyHelios/master/docs/images/PyHelios_logo_whiteborder.png"  alt="" width="300" />
@@ -22,6 +22,21 @@ See the Helios C++ documentation for a more in-depth description of Helios: http
 
 ### Installation
 
+**Easy Install (Recommended):**
+```bash
+pip install pyhelios
+```
+
+This installs pre-built PyHelios with platform-appropriate plugins:
+- **macOS**: All plugins except GPU-accelerated ones (automatically detected)
+- **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.
+
+### Build from Source
+
+If you need to customize plugins or build from source:
+
 #### Windows
 
 **Prerequisites:**
@@ -82,6 +97,35 @@ source helios-core/utilities/dependencies.sh
 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:**
+```bash
+nvidia-smi  # Should show GPU information
+nvcc --version  # Should show CUDA compiler version
+```
+
+**Testing GPU Features:**
+```python
+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
 
 ```python