[v0.0.6] 2025-08-27

🚨++ New Plug-in Integrated ++ 🚨
- Solar Position plug-in integrated with PyHelios

## Bug Fixes
- Fixed plugin registry detection for selective builds (`--plugins visualizer`)
- Fixed SolarPosition plugin metadata to correctly reflect optional status
- Fixed WeberPennTree constructor to properly handle unavailable plugin scenarios
- Updated error messages for plugin availability to match build configurations

## Testing
- Enhanced cross-platform tests for selective plugin builds
- Fixed test failures when building with limited plugin sets
- Improved error handling validation in plugin availability tests

Author: bnbailey-psl

.github/workflows/docs.yml

@@ -31,6 +31,7 @@ jobs:
       uses: actions/checkout@v4
       with:
         submodules: recursive  # Include helios-core submodule for doc assets
+        fetch-depth: 0  # Fetch full history including tags
 
     - name: Set up Python 3.11
       uses: actions/setup-python@v4
@@ -56,8 +57,13 @@ jobs:
         
     - name: Sync version to Doxygen config
       run: |
-        # Get version directly from _version.py to avoid importing PyHelios
-        VERSION=$(python -c "import sys; sys.path.insert(0, 'pyhelios'); from _version import __version__; print(__version__)")
+        # Get version from git tags (remove 'v' prefix if present)
+        VERSION=$(git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//' || echo "unknown")
+        if [ "$VERSION" = "unknown" ]; then
+          echo "Warning: Could not determine version from git tags, using fallback"
+          # Fallback to setuptools-scm if available
+          VERSION=$(python -c "import setuptools_scm; print(setuptools_scm.get_version())" 2>/dev/null | sed 's/^v//' || echo "dev")
+        fi
         echo "Updating Doxygen PROJECT_NUMBER to: $VERSION"
         sed -i "s/^PROJECT_NUMBER.*$/PROJECT_NUMBER         = $VERSION/" docs/Doxyfile.python
         

.gitignore

@@ -9,6 +9,9 @@ build/
 *.egg-info/
 *.egg
 
+# Auto-generated version file (setuptools-scm)
+pyhelios/_version.py
+
 # IDEs and editors
 .vscode/
 .idea/

build_scripts/build_helios.py

@@ -1406,12 +1406,13 @@ def get_default_plugins() -> List[str]:
     - weberpenntree: Procedural tree generation
     - radiation: OptiX-accelerated ray tracing (GPU optional)
     - energybalance: GPU-accelerated thermal modeling and energy balance
+    - solarposition: Solar position calculations and sun angle modeling
     
     Returns:
         List of default plugins
     """
     # Return the plugins that are actually integrated into PyHelios
-    integrated_plugins = ["visualizer", "weberpenntree", "radiation", "energybalance"]
+    integrated_plugins = ["visualizer", "weberpenntree", "radiation", "energybalance", "solarposition"]
 
     # Filter by platform compatibility
     default_plugins = []

docs/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+# [v0.0.6] 2025-08-27
+
+🚨++ New Plug-in Integrated ++ 🚨
+- Solar Position plug-in integrated with PyHelios
+
+## Bug Fixes
+- Fixed CMake build system to only compile wrapper sources for selected plugins
+- Fixed plugin registry detection for selective builds (`--plugins visualizer`)
+- Fixed SolarPosition plugin metadata to correctly reflect optional status
+- Fixed WeberPennTree constructor to properly handle unavailable plugin scenarios
+- Updated error messages for plugin availability to match build configurations
+
+## Testing
+- Enhanced cross-platform tests for selective plugin builds
+- Fixed test failures when building with limited plugin sets
+- Improved error handling validation in plugin availability tests
+
 # [v0.0.5] 2025-08-27
 
 - Helios native C++ had several bugs that was causing errors in the last version. Merged in patched version of 1.3.46.

docs/Doxyfile.python

@@ -131,6 +131,7 @@ INPUT                  = pyhelios \
                          docs/plugin_integration_guide.md \
                          docs/plugin_energybalance.md \
                          docs/plugin_radiation.md \
+                         docs/plugin_solarposition.md \
                          docs/plugin_visualizer.md \
                          docs/plugin_weberpenntree.md \
                          docs/CHANGELOG.md \
@@ -148,6 +149,7 @@ EXCLUDE                = pyhelios/plugins/__pycache__ \
                          pyhelios/wrappers/ULoggerWrapper.py \
                          pyhelios/wrappers/URadiationModelWrapper.py \
                          pyhelios/wrappers/UEnergyBalanceWrapper.py \
+                         pyhelios/wrappers/USolarPositionWrapper.py \
                          pyhelios/wrappers/UVisualizerWrapper.py \
                          pyhelios/wrappers/UWeberPennTreeWrapper.py \
                          pyhelios/config \

docs/DoxygenLayout.xml

@@ -25,6 +25,7 @@
       <!-- Currently Implemented Plugins (Alphabetized) -->
       <tab type="user" visible="yes" url="@ref EnergyBalanceDoc" title="Energy Balance Model"/>
       <tab type="user" visible="yes" url="@ref RadiationDoc" title="Radiation Model"/>
+      <tab type="user" visible="yes" url="@ref SolarPositionDoc" title="Solar Position"/>
       <tab type="user" visible="yes" url="@ref VisualizerDoc" title="Visualizer"/>
       <tab type="user" visible="yes" url="@ref WeberPennTreeDoc" title="Weber-Penn Tree"/>
     </tab>

docs/plugin_solarposition.md

@@ -0,0 +1,189 @@
+# Solar Position Plugin Documentation {#SolarPositionDoc}
+
+## Overview
+
+The Solar Position plugin provides comprehensive solar position calculations and sun angle modeling for PyHelios. This plugin enables accurate solar geometry computations essential for radiation modeling, energy balance calculations, and photosynthesis simulations in plant canopy models.
+
+Key features include:
+- Precise solar position calculations based on date, time, and geographic location
+- Sun direction vector computations for ray tracing applications
+- Solar flux calculations with atmospheric corrections
+- Sunrise and sunset time calculations
+- Atmospheric parameter calibration from time series data
+
+## System Requirements
+
+- **Platforms**: Windows, Linux, macOS  
+- **Dependencies**: None (uses standard mathematical functions)
+- **GPU**: Not required
+- **Memory**: Minimal memory footprint
+
+## Installation
+
+### Build with Solar Position Plugin
+
+The Solar Position plugin is included in the default PyHelios build. If building explicitly:
+
+```bash
+# Using interactive selection
+build_scripts/build_helios --interactive
+
+# Explicit selection
+build_scripts/build_helios --plugins solarposition
+
+# Check if available
+python -c "from pyhelios.plugins.registry import PluginRegistry; print('solarposition available:', PluginRegistry().is_plugin_available('solarposition'))"
+```
+
+## Quick Start
+
+```python
+from pyhelios import Context, SolarPosition
+
+# Create context and solar position calculator
+with Context() as context:
+    # Set date and time
+    context.setDate(year=2024, month=6, day=21)  # Summer solstice
+    context.setTime(hour=12, minute=0, second=0)     # Noon
+    
+    # Create solar position calculator with coordinates (NYC)
+    with SolarPosition(context, utc_offset=-5, latitude=40.7128, longitude=-74.0060) as solar:
+        # Get sun elevation angle
+        elevation = solar.getSunElevation()
+        print(f"Sun elevation: {elevation:.2f} degrees")
+        
+        # Get sun direction vector
+        direction = solar.getSunDirectionVector()
+        print(f"Sun direction: ({direction.x:.3f}, {direction.y:.3f}, {direction.z:.3f})")
+        
+        # Calculate solar flux (standard atmospheric conditions)
+        flux = solar.getSolarFlux(pressure_Pa=101325, temperature_K=288.15, 
+                                 humidity_rel=0.6, turbidity=0.1)
+        print(f"Solar flux: {flux:.2f} W/m²")
+```
+
+## Examples
+
+### Daily Solar Path Analysis
+
+```python
+from pyhelios import Context, SolarPosition
+import numpy as np
+import matplotlib.pyplot as plt
+
+with Context() as context:
+    context.setDate(year=2024, month=6, day=21)  # Summer solstice
+    
+    # Create solar position with coordinates (Davis, CA)
+    with SolarPosition(context, utc_offset=-8, latitude=38.5382, longitude=-121.7617) as solar:
+        # Calculate sun path throughout the day
+        hours = np.arange(5, 20, 0.5)  # 5 AM to 8 PM
+        elevations = []
+        azimuths = []
+        
+        for hour in hours:
+            hour_int = int(hour)
+            minute_int = int((hour - hour_int) * 60)
+            context.setTime(hour=hour_int, minute=minute_int, second=0)
+            
+            elevation = solar.getSunElevation()
+            azimuth = solar.getSunAzimuth()
+            
+            if elevation > 0:  # Sun above horizon
+                elevations.append(elevation)
+                azimuths.append(azimuth)
+        
+        # Plot solar path
+        plt.figure(figsize=(10, 6))
+        plt.subplot(1, 2, 1)
+        plt.plot(hours[:len(elevations)], elevations)
+        plt.xlabel('Hour of Day')
+        plt.ylabel('Sun Elevation (degrees)')
+        plt.title('Sun Elevation vs Time')
+        
+        plt.subplot(1, 2, 2)
+        plt.plot(azimuths, elevations)
+        plt.xlabel('Sun Azimuth (degrees)')
+        plt.ylabel('Sun Elevation (degrees)')
+        plt.title('Sun Path (Elevation vs Azimuth)')
+        plt.show()
+```
+
+### Solar Flux Analysis
+
+```python
+from pyhelios import Context, SolarPosition
+
+def analyze_solar_flux(latitude, longitude, year, month, day):
+    """Analyze solar flux variation throughout a day."""
+    
+    with Context() as context:
+        context.setDate(year=year, month=month, day=day)
+        
+        # Create solar position with provided coordinates  
+        with SolarPosition(context, utc_offset=0, latitude=latitude, longitude=longitude) as solar:
+            # Get sunrise/sunset times
+            sunrise = solar.getSunriseTime()
+            sunset = solar.getSunsetTime()
+            
+            print(f"Sunrise: {sunrise}")
+            print(f"Sunset: {sunset}")
+            # Calculate day length in hours
+            day_length = (sunset.hour * 3600 + sunset.minute * 60 + sunset.second) - (sunrise.hour * 3600 + sunrise.minute * 60 + sunrise.second)
+            print(f"Day length: {day_length / 3600:.2f} hours")
+            
+            # Calculate solar flux at key times
+            key_times = [
+                (sunrise.hour, sunrise.minute, 'Sunrise'),
+                (12, 0, 'Noon'),
+                (sunset.hour, sunset.minute, 'Sunset')
+            ]
+            
+            for hour, minute, label in key_times:
+                context.setTime(hour=hour, minute=minute, second=0)
+                
+                elevation = solar.getSunElevation()
+                flux = solar.getSolarFlux(pressure_Pa=101325, temperature_K=288.15,
+                                         humidity_rel=0.6, turbidity=0.1)
+                
+                print(f"{label}: Elevation = {elevation:.1f}°, Flux = {flux:.0f} W/m²")
+
+# Example usage
+analyze_solar_flux(40.7128, -74.0060, 2024, 6, 21)  # NYC summer solstice
+analyze_solar_flux(40.7128, -74.0060, 2024, 12, 21) # NYC winter solstice
+```
+
+### Error Handling
+
+```python
+from pyhelios import Context, SolarPosition, SolarPositionError
+
+with Context() as context:
+    try:
+        # This will fail if coordinates not provided
+        context.setDate(year=2024, month=7, day=15)
+        context.setTime(hour=12, minute=0, second=0)
+        with SolarPosition(context) as solar:
+            elevation = solar.getSunElevation()
+            
+    except SolarPositionError as e:
+        print(f"Solar position error: {e}")
+        # Error messages include specific requirements
+        
+        # Retry with coordinates
+        with SolarPosition(context, utc_offset=-8, latitude=40.0, longitude=-120.0) as solar:
+            elevation = solar.getSunElevation()
+            print(f"Sun elevation: {elevation:.2f}°")
+```
+
+## Algorithm Details
+
+The Solar Position plugin implements standard solar geometry algorithms:
+
+- **Solar declination**: Based on day of year using standard astronomical formulas
+- **Hour angle**: Calculated from local solar time and longitude
+- **Solar elevation/azimuth**: Standard spherical trigonometry calculations
+- **Atmospheric corrections**: Air mass calculations for solar flux attenuation
+- **Time calculations**: Sunrise/sunset based on solar elevation = 0° with refraction correction
+
+These implementations follow established solar engineering practices and produce results accurate to within 0.1° for typical applications.

native/include/pyhelios_wrapper_context.h

@@ -766,6 +766,58 @@ PYHELIOS_API void colorPrimitiveByDataPseudocolor(helios::Context* context, unsi
  */
 PYHELIOS_API void colorPrimitiveByDataPseudocolorWithRange(helios::Context* context, unsigned int* uuids, size_t num_uuids, const char* primitive_data, const char* colormap, unsigned int ncolors, float data_min, float data_max);
 
+/**
+ * @brief Set the simulation time using hour and minute
+ * @param context Pointer to the Context
+ * @param hour Hour (0-23)
+ * @param minute Minute (0-59)
+ */
+PYHELIOS_API void setTime_HourMinute(helios::Context* context, int hour, int minute);
+
+/**
+ * @brief Set the simulation time using hour, minute, and second
+ * @param context Pointer to the Context
+ * @param hour Hour (0-23)
+ * @param minute Minute (0-59)
+ * @param second Second (0-59)
+ */
+PYHELIOS_API void setTime_HourMinuteSecond(helios::Context* context, int hour, int minute, int second);
+
+/**
+ * @brief Set the simulation date using day, month, and year
+ * @param context Pointer to the Context
+ * @param day Day (1-31)
+ * @param month Month (1-12)
+ * @param year Year (1900-3000)
+ */
+PYHELIOS_API void setDate_DayMonthYear(helios::Context* context, int day, int month, int year);
+
+/**
+ * @brief Set the simulation date using Julian day and year
+ * @param context Pointer to the Context
+ * @param julian_day Julian day (1-366)
+ * @param year Year (1900-3000)
+ */
+PYHELIOS_API void setDate_JulianDay(helios::Context* context, int julian_day, int year);
+
+/**
+ * @brief Get the current simulation time
+ * @param context Pointer to the Context
+ * @param hour Output parameter for hour
+ * @param minute Output parameter for minute
+ * @param second Output parameter for second
+ */
+PYHELIOS_API void getTime(helios::Context* context, int* hour, int* minute, int* second);
+
+/**
+ * @brief Get the current simulation date
+ * @param context Pointer to the Context
+ * @param day Output parameter for day
+ * @param month Output parameter for month
+ * @param year Output parameter for year
+ */
+PYHELIOS_API void getDate(helios::Context* context, int* day, int* month, int* year);
+
 #ifdef __cplusplus
 }
 #endif