Skip to content

Commit 09b146e

Browse files
bnbailey-pslbnbailey-psl
committed
[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
1 parent b6b7855 commit 09b146e

12 files changed

Lines changed: 1012 additions & 17 deletions

File tree

‎.claude/agents/code-reviewer.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ When reviewing code changes since the last commit, you will:
1515
3. Evaluate code against established best practices for the specific language and framework
1616
4. Look for potential security vulnerabilities, performance issues, and maintainability concerns
1717
5. Check for consistency with existing codebase patterns and conventions
18+
6. **ALWAYS check git status** to identify any new files that should be added to version control
1819

1920
**CRITICAL ISSUES TO CATCH:**
2021
- **Incomplete implementations**: Placeholder comments like "TODO", "FIXME", or unfinished logic
@@ -24,6 +25,9 @@ When reviewing code changes since the last commit, you will:
2425
- **Performance anti-patterns**: Inefficient algorithms, memory leaks, unnecessary database queries
2526
- **Error handling gaps**: Missing exception handling, inadequate error messages, swallowed exceptions
2627
- **Testing gaps**: Untestable code, missing edge case coverage, brittle test dependencies
28+
- **Git control gaps**: New files that should be added to version control but are missing from git
29+
- **Syntax errors**: Always run syntax checks on new Python files (python -m py_compile file.py)
30+
- **Missing imports**: Check that all required modules are imported in new files
2731

2832
**BEST PRACTICES ENFORCEMENT:**
2933
- Code readability and self-documenting practices

‎.github/workflows/build-wheels.yml‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
name: Build Wheels
2+
3+
on:
4+
push:
5+
branches: [ master, main ]
6+
tags: [ 'v*' ]
7+
pull_request:
8+
branches: [ master, main ]
9+
workflow_dispatch:
10+
11+
jobs:
12+
build_wheels:
13+
name: Build wheels on ${{ matrix.os }}
14+
runs-on: ${{ matrix.os }}
15+
strategy:
16+
matrix:
17+
include:
18+
- os: ubuntu-24.04
19+
arch: x86_64
20+
- os: windows-2022
21+
arch: AMD64
22+
- os: macos-13
23+
arch: x86_64
24+
- os: macos-14
25+
arch: arm64
26+
27+
steps:
28+
- name: Checkout PyHelios
29+
uses: actions/checkout@v4
30+
with:
31+
submodules: recursive
32+
fetch-depth: 0 # Required for setuptools-scm
33+
34+
- name: Set up Python
35+
uses: actions/setup-python@v4
36+
with:
37+
python-version: '3.8' # Use lowest supported version for compatibility
38+
39+
- name: Setup MSVC (Windows)
40+
if: runner.os == 'Windows'
41+
uses: ilammy/msvc-dev-cmd@v1
42+
43+
- name: Install Helios dependencies (Linux)
44+
if: runner.os == 'Linux'
45+
run: |
46+
cd helios-core/utilities
47+
sudo bash dependencies.sh ALL
48+
49+
- name: Install Helios dependencies (macOS)
50+
if: runner.os == 'macOS'
51+
run: |
52+
cd helios-core/utilities
53+
# Install base + visualization dependencies (no GPU/CUDA for macOS builds)
54+
bash dependencies.sh BASE
55+
bash dependencies.sh VIS
56+
57+
- name: Debug environment (macOS)
58+
if: runner.os == 'macOS'
59+
run: |
60+
echo "=== Directory structure ==="
61+
ls -la
62+
echo "=== PyHelios build scripts ==="
63+
ls -la build_scripts/
64+
echo "=== Helios core ==="
65+
ls -la helios-core/ || echo "helios-core not found"
66+
echo "=== Python version and location ==="
67+
python --version
68+
which python
69+
echo "=== Environment ==="
70+
env | grep -E "(PYTHON|PATH)" | head -10
71+
72+
- name: Install CUDA Toolkit (Windows)
73+
if: runner.os == 'Windows'
74+
shell: powershell
75+
run: |
76+
# Download CUDA 12.6 installer
77+
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"
78+
# Install CUDA toolkit components needed for compilation
79+
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
80+
# Add CUDA to PATH for subsequent steps
81+
echo "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
82+
83+
- name: Install cibuildwheel and repair tools
84+
run: |
85+
python -m pip install --upgrade pip
86+
python -m pip install cibuildwheel
87+
# Install platform-specific wheel repair tools
88+
if [ "${{ runner.os }}" = "Linux" ]; then
89+
python -m pip install auditwheel
90+
elif [ "${{ runner.os }}" = "macOS" ]; then
91+
python -m pip install delocate
92+
fi
93+
94+
- name: Build wheels
95+
run: python -m cibuildwheel --output-dir wheelhouse
96+
env:
97+
# Build for Python 3.8+ on all platforms
98+
CIBW_BUILD: cp38-* cp39-* cp310-* cp311-* cp312-*
99+
100+
# Skip 32-bit builds and PyPy
101+
CIBW_SKIP: "*-win32 *-manylinux_i686 *-musllinux* pp*"
102+
103+
# Architecture configuration based on runner
104+
CIBW_ARCHS: ${{ matrix.arch }}
105+
106+
# Platform-specific build commands with broad CUDA compatibility
107+
CIBW_BEFORE_BUILD_MACOS: "python build_scripts/prepare_wheel.py --buildmode release --nogpu --verbose"
108+
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"
109+
CIBW_BEFORE_BUILD_LINUX: "export PYHELIOS_CUDA_ARCHITECTURES=50;60;70;75;80;86;90 && python build_scripts/prepare_wheel.py --buildmode release --verbose"
110+
111+
# Test wheel installation
112+
CIBW_TEST_COMMAND: "python -c 'import pyhelios; print(f\"PyHelios {pyhelios.__version__} imported successfully\")'"
113+
CIBW_TEST_REQUIRES: "pytest"
114+
115+
# Repair wheels to bundle dependencies
116+
CIBW_REPAIR_WHEEL_COMMAND_MACOS: "delocate-wheel --require-archs {delocate_archs} -w {dest_dir} -v {wheel}"
117+
CIBW_REPAIR_WHEEL_COMMAND_LINUX: "auditwheel repair -w {dest_dir} {wheel}"
118+
119+
- name: Debug build failure
120+
if: failure()
121+
run: |
122+
echo "=== Build Failure Diagnostics ==="
123+
echo "Build directory contents:"
124+
find pyhelios_build -name "*.so" -o -name "*.dll" -o -name "*.dylib" 2>/dev/null || echo "No build directory found"
125+
echo ""
126+
echo "Plugin directory contents:"
127+
ls -la pyhelios/plugins/ 2>/dev/null || echo "No plugins directory found"
128+
echo ""
129+
echo "Wheel directory contents:"
130+
ls -la wheelhouse/ 2>/dev/null || echo "No wheelhouse directory found"
131+
echo ""
132+
echo "Python environment:"
133+
python --version
134+
pip list | grep -E "(cibuildwheel|auditwheel|delocate)" || echo "Wheel tools not found"
135+
136+
- name: Upload wheels as artifacts
137+
uses: actions/upload-artifact@v4
138+
with:
139+
name: wheels-${{ matrix.os }}-${{ matrix.arch }}
140+
path: wheelhouse/*.whl
141+
retention-days: 7
142+
143+
test_wheels:
144+
name: Test wheels on ${{ matrix.os }} Python ${{ matrix.python-version }}
145+
runs-on: ${{ matrix.os }}
146+
needs: build_wheels
147+
strategy:
148+
matrix:
149+
include:
150+
- os: ubuntu-24.04
151+
python-version: '3.8'
152+
- os: ubuntu-24.04
153+
python-version: '3.11'
154+
- os: windows-2022
155+
python-version: '3.8'
156+
- os: windows-2022
157+
python-version: '3.11'
158+
- os: macos-13
159+
python-version: '3.8'
160+
- os: macos-13
161+
python-version: '3.11'
162+
- os: macos-14
163+
python-version: '3.8'
164+
- os: macos-14
165+
python-version: '3.11'
166+
167+
steps:
168+
- name: Set up Python ${{ matrix.python-version }}
169+
uses: actions/setup-python@v4
170+
with:
171+
python-version: ${{ matrix.python-version }}
172+
173+
- name: Download wheels
174+
uses: actions/download-artifact@v4
175+
with:
176+
pattern: wheels-*
177+
merge-multiple: true
178+
path: wheelhouse
179+
180+
- name: Install wheel
181+
run: |
182+
python -m pip install --upgrade pip
183+
python -m pip install --find-links wheelhouse --no-index pyhelios
184+
185+
- name: Test basic functionality
186+
run: |
187+
python -c "
188+
import pyhelios
189+
from pyhelios import Context, WeberPennTree, WPTType
190+
from pyhelios.types import vec2, vec3, RGBcolor
191+
print(f'PyHelios version: {pyhelios.__version__}')
192+
193+
# Test basic Context operations
194+
context = Context()
195+
center = vec3(1, 2, 3)
196+
color = RGBcolor(0.5, 0.5, 0.5)
197+
uuid = context.addPatch(center=center, size=vec2(1, 1), color=color)
198+
print(f'Added patch with UUID: {uuid}')
199+
200+
# Test plugin availability reporting
201+
from pyhelios.plugins import print_plugin_status
202+
print_plugin_status()
203+
"
204+
205+
publish:
206+
name: Publish to PyPI
207+
runs-on: ubuntu-latest
208+
needs: [build_wheels, test_wheels]
209+
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
210+
environment:
211+
name: pypi
212+
url: https://pypi.org/p/pyhelios
213+
permissions:
214+
id-token: write # Required for trusted publishing
215+
216+
steps:
217+
- name: Download all wheels
218+
uses: actions/download-artifact@v4
219+
with:
220+
pattern: wheels-*
221+
merge-multiple: true
222+
path: wheelhouse
223+
224+
- name: Publish to PyPI
225+
uses: pypa/gh-action-pypi-publish@release/v1
226+
with:
227+
packages-dir: wheelhouse/
228+
verify-metadata: false # Skip metadata verification due to dynamic versioning

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@ build/
1212
# Auto-generated version file (setuptools-scm)
1313
pyhelios/_version.py
1414

15+
# Auto-generated documentation
16+
docs/generated/
17+
1518
# IDEs and editors
1619
.vscode/
1720
.idea/

‎MANIFEST.in‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Include build scripts
2+
include build_scripts/*.py
3+
include build_scripts/build_helios
4+
5+
# Include documentation
6+
include README.md
7+
include docs/CHANGELOG.md
8+
graft docs/examples
9+
recursive-exclude docs/generated *
10+
11+
# Include configuration files
12+
include pyproject.toml
13+
include requirements*.txt
14+
include pytest.ini
15+
16+
# Include native libraries that get built
17+
recursive-include pyhelios/plugins *.dll *.so *.dylib
18+
19+
# Exclude test and development files
20+
recursive-exclude tests *
21+
recursive-exclude .github *
22+
recursive-exclude pyhelios_build *
23+
exclude test_*.py
24+
exclude .gitignore
25+
exclude .gitmodules

‎README.md‎

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<br><br>
22

3-
[![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)
3+
[![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)
44

55
<div align="center">
66
<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
2222

2323
### Installation
2424

25+
**Easy Install (Recommended):**
26+
```bash
27+
pip install pyhelios
28+
```
29+
30+
This installs pre-built PyHelios with platform-appropriate plugins:
31+
- **macOS**: All plugins except GPU-accelerated ones (automatically detected)
32+
- **Windows/Linux**: All plugins including GPU acceleration (when hardware supports it)
33+
34+
PyHelios will gracefully handle GPU features - if you don't have CUDA-capable hardware, GPU plugins will display helpful error messages with setup instructions.
35+
36+
### Build from Source
37+
38+
If you need to customize plugins or build from source:
39+
2540
#### Windows
2641

2742
**Prerequisites:**
@@ -82,6 +97,35 @@ source helios-core/utilities/dependencies.sh
8297
pip install -e .
8398
```
8499

100+
### GPU Features Setup
101+
102+
If you want to use GPU-accelerated features (radiation modeling, aerial LiDAR), ensure you have:
103+
104+
**Requirements:**
105+
- NVIDIA GPU with CUDA support
106+
- NVIDIA drivers installed
107+
- CUDA Toolkit (version 11.8 or 12.x)
108+
109+
**Verification:**
110+
```bash
111+
nvidia-smi # Should show GPU information
112+
nvcc --version # Should show CUDA compiler version
113+
```
114+
115+
**Testing GPU Features:**
116+
```python
117+
from pyhelios import Context, RadiationModel
118+
119+
context = Context()
120+
try:
121+
radiation = RadiationModel(context)
122+
print("GPU radiation modeling available!")
123+
except RuntimeError as e:
124+
print(f"GPU features unavailable: {e}")
125+
```
126+
127+
If GPU features fail, PyHelios will provide specific guidance on installation and setup requirements.
128+
85129
### First Example
86130

87131
```python

‎build_scripts/build_helios.py‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
except ImportError:
2020
HAS_YAML = False
2121
from pathlib import Path
22-
from typing import List, Optional, Dict, Any
22+
from typing import List, Optional, Dict, Any, Tuple
2323

2424
# Load plugin configurations directly to avoid pyhelios library loading
2525
# We'll import the config data directly by reading and executing the files
@@ -1453,20 +1453,20 @@ def parse_plugin_selection(args) -> List[str]:
14531453
if args.nogpu:
14541454
# Remove GPU-dependent plugins
14551455
gpu_plugins = [p for p in selected_plugins
1456-
if PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [], [])).gpu_required]
1456+
if PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [])).gpu_required]
14571457
selected_plugins = [p for p in selected_plugins
1458-
if not PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [], [])).gpu_required]
1458+
if not PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [])).gpu_required]
14591459
if gpu_plugins:
14601460
print(f"[EXCLUDED] GPU-dependent plugins excluded (--nogpu): {gpu_plugins}")
14611461

14621462
if args.novis:
14631463
# Remove visualization plugins
14641464
vis_plugins = [p for p in selected_plugins
14651465
if any(dep in ["opengl", "glfw", "imgui"]
1466-
for dep in PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [], [])).system_dependencies)]
1466+
for dep in PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [])).system_dependencies)]
14671467
selected_plugins = [p for p in selected_plugins
14681468
if not any(dep in ["opengl", "glfw", "imgui"]
1469-
for dep in PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [], [])).system_dependencies)]
1469+
for dep in PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [])).system_dependencies)]
14701470
if vis_plugins:
14711471
print(f"[EXCLUDED] Visualization plugins excluded (--novis): {vis_plugins}")
14721472

@@ -1481,9 +1481,9 @@ def parse_plugin_selection(args) -> List[str]:
14811481
# 4. Check environment variables for additional exclusions
14821482
if os.environ.get('PYHELIOS_EXCLUDE_GPU', '').lower() in ['1', 'true', 'yes']:
14831483
env_gpu_plugins = [p for p in selected_plugins
1484-
if PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [], [])).gpu_required]
1484+
if PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [])).gpu_required]
14851485
selected_plugins = [p for p in selected_plugins
1486-
if not PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [], [])).gpu_required]
1486+
if not PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [])).gpu_required]
14871487
if env_gpu_plugins:
14881488
print(f"[EXCLUDED] GPU-dependent plugins excluded (PYHELIOS_EXCLUDE_GPU): {env_gpu_plugins}")
14891489

0 commit comments

Comments
 (0)