High-level interface for solar position calculations and radiation modeling. More...

Detailed Description

High-level interface for solar position calculations and radiation modeling.

SolarPosition provides comprehensive solar angle calculations, radiation flux modeling, sunrise/sunset time calculations, and atmospheric turbidity calibration. The plugin automatically uses Context time/date for calculations or can be initialized with explicit coordinates.

This class requires the native Helios library built with SolarPosition support. Use context managers for proper resource cleanup.

Examples: Basic usage with Context coordinates: >>> with Context() as context: ... context.setDate(2023, 6, 21) # Summer solstice ... context.setTime(12, 0) # Solar noon ... with SolarPosition(context) as solar: ... elevation = solar.getSunElevation() ... print(f"Sun elevation: {elevation:.1f}°")

: Usage with explicit coordinates: >>> with Context() as context: ... # Davis, California coordinates ... with SolarPosition(context, utc_offset=-8, latitude=38.5, longitude=-121.7) as solar: ... azimuth = solar.getSunAzimuth() ... flux = solar.getSolarFlux(101325, 288.15, 0.6, 0.1) ... print(f"Solar flux: {flux:.1f} W/m²")

Definition at line 119 of file SolarPosition.py.

Public Member Functions
	__init__ (self, Context context, Optional[float] utc_offset=None, Optional[float] latitude=None, Optional[float] longitude=None)
	Initialize SolarPosition with a Helios context.

	__enter__ (self)
	Context manager entry.

	__exit__ (self, exc_type, exc_val, exc_tb)
	Context manager exit - cleanup resources.

	__del__ (self)
	Destructor to ensure C++ resources freed even without 'with' statement.

None	setAtmosphericConditions (self, float pressure_Pa, float temperature_K, float humidity_rel, float turbidity)
	Set atmospheric conditions for subsequent flux calculations (modern API).

Tuple[float, float, float, float]	getAtmosphericConditions (self)
	Get currently set atmospheric conditions from Context.

float	getSunElevation (self)
	Get the sun elevation angle in radians.

float	getSunZenith (self)
	Get the sun zenith angle in radians.

float	getSunAzimuth (self)
	Get the sun azimuth angle in radians.

vec3	getSunDirectionVector (self)
	Get the sun direction as a 3D unit vector.

SphericalCoord	getSunDirectionSpherical (self)
	Get the sun direction as spherical coordinates.

	setSunDirection (self, SphericalCoord sundirection)
	Override the computed solar position with a prescribed sun direction.

float	getSolarFlux (self, Optional[float] pressure_Pa=None, Optional[float] temperature_K=None, Optional[float] humidity_rel=None, Optional[float] turbidity=None)
	Calculate total solar flux (supports legacy and modern APIs).

float	getSolarFluxPAR (self, Optional[float] pressure_Pa=None, Optional[float] temperature_K=None, Optional[float] humidity_rel=None, Optional[float] turbidity=None)
	Calculate PAR (Photosynthetically Active Radiation) solar flux.

float	getSolarFluxNIR (self, Optional[float] pressure_Pa=None, Optional[float] temperature_K=None, Optional[float] humidity_rel=None, Optional[float] turbidity=None)
	Calculate NIR (Near-Infrared) solar flux.

float	getDiffuseFraction (self, Optional[float] pressure_Pa=None, Optional[float] temperature_K=None, Optional[float] humidity_rel=None, Optional[float] turbidity=None)
	Calculate the diffuse fraction of solar radiation.

float	getAmbientLongwaveFlux (self, Optional[float] temperature_K=None, Optional[float] humidity_rel=None)
	Calculate the ambient (sky) longwave radiation flux.

Time	getSunriseTime (self)
	Calculate sunrise time for the current date and location.

Time	getSunsetTime (self)
	Calculate sunset time for the current date and location.

float	calibrateTurbidityFromTimeseries (self, str timeseries_label)
	Calibrate atmospheric turbidity using timeseries data.

	enableCloudCalibration (self, str timeseries_label)
	Enable cloud calibration using timeseries data.

	disableCloudCalibration (self)
	Disable cloud calibration.

	enablePragueSkyModel (self)
	Enable Prague Sky Model for physically-based sky radiance calculations.

bool	isPragueSkyModelEnabled (self)
	Check if Prague Sky Model is currently enabled.

	updatePragueSkyModel (self, float ground_albedo=0.33)
	Update Prague Sky Model and store spectral-angular parameters in Context.

bool	pragueSkyModelNeedsUpdate (self, float ground_albedo=0.33, float sun_tolerance=0.01, float turbidity_tolerance=0.02, float albedo_tolerance=0.05)
	Check if Prague Sky Model needs updating based on changed conditions.

	calculateDirectSolarSpectrum (self, str label, float resolution_nm=1.0)
	Calculate direct beam solar spectrum using SSolar-GOA model.

	calculateDiffuseSolarSpectrum (self, str label, float resolution_nm=1.0)
	Calculate diffuse solar spectrum using SSolar-GOA model.

	calculateGlobalSolarSpectrum (self, str label, float resolution_nm=1.0)
	Calculate global (total) solar spectrum using SSolar-GOA model.

bool	is_available (self)
	Check if SolarPosition is available in current build.

Public Attributes
	context = context

Protected Member Functions
	_check_context_alive (self)
	Raise if the owning Context has been destroyed (see Context.check_context_alive).

Protected Attributes
	_solar_pos

Constructor & Destructor Documentation

◆ init()

pyhelios.SolarPosition.SolarPosition.__init__	(		self,
		Context	context,
		Optional[float]	utc_offset = None,
		Optional[float]	latitude = None,
		Optional[float]	longitude = None )

Initialize SolarPosition with a Helios context.

Parameters

context	Active Helios Context instance
utc_offset	UTC time offset in hours (-14 to +12). Helios counts the offset positive moving West, which inverts the real-world UTC-12..UTC+14 span, so the range is asymmetric. If provided with latitude/longitude, creates plugin with explicit coordinates.
latitude	Latitude in degrees (-90 to +90). Required if utc_offset provided.
longitude	Longitude in degrees (-180 to +180). Required if utc_offset provided.

Exceptions

SolarPositionError	If plugin not available in current build
ValueError	If coordinate parameters are invalid or incomplete
RuntimeError	If plugin initialization fails

Note: If coordinates are not provided, the plugin uses Context location settings. Solar calculations depend on Context time/date - use context.setTime() and context.setDate() to set the simulation time before calculations.

Definition at line 143 of file SolarPosition.py.

◆ del()

pyhelios.SolarPosition.SolarPosition.__del__ ( self )

Destructor to ensure C++ resources freed even without 'with' statement.

Definition at line 212 of file SolarPosition.py.

Member Function Documentation

◆ enter()

pyhelios.SolarPosition.SolarPosition.__enter__ ( self )

Context manager entry.

Definition at line 202 of file SolarPosition.py.

◆ exit()

pyhelios.SolarPosition.SolarPosition.__exit__	(	self,
		exc_type,
		exc_val,
		exc_tb )

Context manager exit - cleanup resources.

Definition at line 206 of file SolarPosition.py.

◆ _check_context_alive()

pyhelios.SolarPosition.SolarPosition._check_context_alive ( self )

protected

Raise if the owning Context has been destroyed (see Context.check_context_alive).

Definition at line 198 of file SolarPosition.py.

◆ calculateDiffuseSolarSpectrum()

pyhelios.SolarPosition.SolarPosition.calculateDiffuseSolarSpectrum	(		self,
		str	label,
		float	resolution_nm = 1.0 )

Calculate diffuse solar spectrum using SSolar-GOA model.

   Computes the spectral irradiance of diffuse (scattered) solar radiation
   across 300-2600 nm wavelength range using the SSolar-GOA model. Results
   are stored in Context global data as a vector of (wavelength, irradiance) pairs.

Parameters

label	Label to store the spectrum data in Context global data
resolution_nm	Wavelength resolution in nanometers (1.0-2300.0). Lower values give finer spectral resolution but require more computation. Default is 1.0 nm.

Exceptions

ValueError	If label is empty or resolution is out of valid range
SolarPositionError	If calculation fails

Note

Requires Context time/date to be set for accurate solar position
Atmospheric parameters from Context location are used
Results accessible via context.getGlobalData(label)
Diffuse radiation results from atmospheric scattering (Rayleigh, aerosol)

Example: >>> with Context() as context: ... context.setDate(2023, 6, 21) ... context.setTime(12, 0) ... with SolarPosition(context) as solar: ... solar.calculateDiffuseSolarSpectrum("diffuse_spectrum", resolution_nm=5.0) ... spectrum = context.getGlobalData("diffuse_spectrum") ... # spectrum is list of vec2(wavelength_nm, irradiance_W_m2_nm)

Definition at line 1044 of file SolarPosition.py.

◆ calculateDirectSolarSpectrum()

pyhelios.SolarPosition.SolarPosition.calculateDirectSolarSpectrum	(		self,
		str	label,
		float	resolution_nm = 1.0 )

Calculate direct beam solar spectrum using SSolar-GOA model.

   Computes the spectral irradiance of direct beam solar radiation across
   300-2600 nm wavelength range using the SSolar-GOA (Global Ozone and
   Atmospheric) spectral model. Results are stored in Context global data
   as a vector of (wavelength, irradiance) pairs.

Parameters

label	Label to store the spectrum data in Context global data
resolution_nm	Wavelength resolution in nanometers (1.0-2300.0). Lower values give finer spectral resolution but require more computation. Default is 1.0 nm.

Exceptions

ValueError	If label is empty or resolution is out of valid range
SolarPositionError	If calculation fails

Note

Requires Context time/date to be set for accurate solar position
Atmospheric parameters from Context location are used
Results accessible via context.getGlobalData(label)
SSolar-GOA model accounts for atmospheric absorption and scattering

Example: >>> with Context() as context: ... context.setDate(2023, 6, 21) ... context.setTime(12, 0) ... with SolarPosition(context) as solar: ... solar.calculateDirectSolarSpectrum("direct_spectrum", resolution_nm=5.0) ... spectrum = context.getGlobalData("direct_spectrum") ... # spectrum is list of vec2(wavelength_nm, irradiance_W_m2_nm)

Definition at line 1000 of file SolarPosition.py.

◆ calculateGlobalSolarSpectrum()

pyhelios.SolarPosition.SolarPosition.calculateGlobalSolarSpectrum	(		self,
		str	label,
		float	resolution_nm = 1.0 )

Calculate global (total) solar spectrum using SSolar-GOA model.

   Computes the spectral irradiance of total solar radiation (direct + diffuse)
   across 300-2600 nm wavelength range using the SSolar-GOA model. Results
   are stored in Context global data as a vector of (wavelength, irradiance) pairs.

Parameters

label	Label to store the spectrum data in Context global data
resolution_nm	Wavelength resolution in nanometers (1.0-2300.0). Lower values give finer spectral resolution but require more computation. Default is 1.0 nm.

Exceptions

ValueError	If label is empty or resolution is out of valid range
SolarPositionError	If calculation fails

Note

Requires Context time/date to be set for accurate solar position
Atmospheric parameters from Context location are used
Results accessible via context.getGlobalData(label)
Global spectrum = direct beam + diffuse (sky) radiation
Most useful for plant canopy modeling and photosynthesis calculations

Example: >>> with Context() as context: ... context.setDate(2023, 6, 21) ... context.setTime(12, 0) ... with SolarPosition(context) as solar: ... solar.calculateGlobalSolarSpectrum("global_spectrum", resolution_nm=10.0) ... spectrum = context.getGlobalData("global_spectrum") ... # spectrum is list of vec2(wavelength_nm, irradiance_W_m2_nm) ... total_irradiance = sum([s.y for s in spectrum]) * 10.0 # Integrate

Definition at line 1090 of file SolarPosition.py.

◆ calibrateTurbidityFromTimeseries()

float pyhelios.SolarPosition.SolarPosition.calibrateTurbidityFromTimeseries	(		self,
		str	timeseries_label )

Calibrate atmospheric turbidity using timeseries data.

Parameters

timeseries_label Label of timeseries data in Context. The data should be global shortwave radiation flux on a horizontal plane in W/m^2, and should contain at least one day of clear-sky conditions.

Returns: The calibrated turbidity value

Exceptions

ValueError	If timeseries label is invalid
SolarPositionError	If calibration fails

Note: This method does not itself apply the calibrated value. Pass the returned turbidity to setAtmosphericConditions() to use it.

Example: >>> turbidity = solar.calibrateTurbidityFromTimeseries("solar_irradiance") >>> solar.setAtmosphericConditions(101325, 293.15, 0.5, turbidity)

Definition at line 797 of file SolarPosition.py.

◆ disableCloudCalibration()

pyhelios.SolarPosition.SolarPosition.disableCloudCalibration ( self )

Disable cloud calibration.

Exceptions

SolarPositionError If operation fails

Example: >>> solar.disableCloudCalibration()

Definition at line 839 of file SolarPosition.py.

◆ enableCloudCalibration()

pyhelios.SolarPosition.SolarPosition.enableCloudCalibration	(		self,
		str	timeseries_label )

Enable cloud calibration using timeseries data.

Parameters

timeseries_label Label of cloud timeseries data in Context

Exceptions

ValueError	If timeseries label is invalid
SolarPositionError	If calibration setup fails

Example: >>> solar.enableCloudCalibration("cloud_cover")

Definition at line 820 of file SolarPosition.py.

◆ enablePragueSkyModel()

pyhelios.SolarPosition.SolarPosition.enablePragueSkyModel ( self )

Enable Prague Sky Model for physically-based sky radiance calculations.

   The Prague Sky Model provides high-quality spectral and angular sky radiance
   distribution for accurate diffuse radiation modeling. It accounts for Rayleigh
   and Mie scattering to produce realistic sky radiance patterns across the
   360-1480 nm spectral range.

Exceptions

SolarPositionError If operation fails

Note: After enabling, call updatePragueSkyModel() to compute and store spectral-angular parameters in Context global data. Requires ~27 MB data file: plugins/solarposition/lib/prague_sky_model/PragueSkyModelReduced.dat

Example: >>> with Context() as context: ... with SolarPosition(context) as solar: ... solar.enablePragueSkyModel() ... solar.updatePragueSkyModel()

Definition at line 869 of file SolarPosition.py.

◆ getAmbientLongwaveFlux()

float pyhelios.SolarPosition.SolarPosition.getAmbientLongwaveFlux	(		self,
		Optional[float]	temperature_K = None,
		Optional[float]	humidity_rel = None )

Calculate the ambient (sky) longwave radiation flux.

   This method supports both legacy and modern APIs:
   - **Legacy API**: Pass temperature and humidity explicitly
   - **Modern API**: Pass no parameters, uses atmospheric conditions from setAtmosphericConditions()

Parameters

temperature_K	Temperature in Kelvin [optional]
humidity_rel	Relative humidity as fraction (0.0-1.0) [optional]

Returns: Ambient longwave flux in W/m²

Exceptions

ValueError	If one parameter provided but not the other
SolarPositionError	If calculation fails

Note: The longwave flux model is based on Prata (1996). Returns downwelling longwave radiation flux on a horizontal surface.

Examples

Legacy API: >>> lw_flux = solar.getAmbientLongwaveFlux(288.15, 0.6)

Modern API (uses temperature and humidity from setAtmosphericConditions): >>> solar.setAtmosphericConditions(101325, 288.15, 0.6, 0.1) >>> lw_flux = solar.getAmbientLongwaveFlux()

Definition at line 679 of file SolarPosition.py.

◆ getAtmosphericConditions()

Tuple[float, float, float, float] pyhelios.SolarPosition.SolarPosition.getAtmosphericConditions ( self )

Get currently set atmospheric conditions from Context.

Returns: Tuple of (pressure_Pa, temperature_K, humidity_rel, turbidity)

Exceptions

SolarPositionError If operation fails

Note: If atmospheric conditions have not been set via setAtmosphericConditions(), returns default values: (101325 Pa, 300 K, 0.5, 0.02)

Example: >>> pressure, temp, humidity, turbidity = solar.getAtmosphericConditions() >>> print(f"Pressure: {pressure} Pa, Temp: {temp} K")

Definition at line 287 of file SolarPosition.py.

◆ getDiffuseFraction()

float pyhelios.SolarPosition.SolarPosition.getDiffuseFraction	(		self,
		Optional[float]	pressure_Pa = None,
		Optional[float]	temperature_K = None,
		Optional[float]	humidity_rel = None,
		Optional[float]	turbidity = None )

Calculate the diffuse fraction of solar radiation.

   Supports both legacy (parameter-based) and modern (state-based) APIs.

Parameters

pressure_Pa	Atmospheric pressure in Pascals [optional]
temperature_K	Temperature in Kelvin [optional]
humidity_rel	Relative humidity as fraction (0.0-1.0) [optional]
turbidity	Atmospheric turbidity coefficient [optional]

Returns

Diffuse fraction as ratio (0.0-1.0) where:

0.0 = all direct radiation
1.0 = all diffuse radiation

Exceptions

ValueError	If some parameters provided but not all
SolarPositionError	If calculation fails

Examples: Legacy diffuse = solar.getDiffuseFraction(101325, 288.15, 0.6, 0.1) Modern solar.setAtmosphericConditions(101325, 288.15, 0.6, 0.1) diffuse = solar.getDiffuseFraction()

Definition at line 626 of file SolarPosition.py.

◆ getSolarFlux()

float pyhelios.SolarPosition.SolarPosition.getSolarFlux	(		self,
		Optional[float]	pressure_Pa = None,
		Optional[float]	temperature_K = None,
		Optional[float]	humidity_rel = None,
		Optional[float]	turbidity = None )

Calculate total solar flux (supports legacy and modern APIs).

   This method supports both legacy and modern APIs:
   - **Legacy API**: Pass all 4 atmospheric parameters explicitly
   - **Modern API**: Pass no parameters, uses atmospheric conditions from setAtmosphericConditions()

Parameters

pressure_Pa	Atmospheric pressure in Pascals (e.g., 101325 for sea level) [optional]
temperature_K	Temperature in Kelvin (e.g., 288.15 for 15°C) [optional]
humidity_rel	Relative humidity as fraction (0.0-1.0) [optional]
turbidity	Atmospheric turbidity coefficient (typically 0.02-0.5) [optional]

Returns: Total solar flux in W/m²

Exceptions

ValueError	If some parameters provided but not all, or if values are invalid
SolarPositionError	If calculation fails or atmospheric conditions not set (modern API)

Examples: Legacy API (backward compatible): >>> flux = solar.getSolarFlux(101325, 288.15, 0.6, 0.1)

: Modern API (cleaner, reuses atmospheric state): >>> solar.setAtmosphericConditions(101325, 288.15, 0.6, 0.1) >>> flux = solar.getSolarFlux() # No parameters needed

Definition at line 475 of file SolarPosition.py.

◆ getSolarFluxNIR()

float pyhelios.SolarPosition.SolarPosition.getSolarFluxNIR	(		self,
		Optional[float]	pressure_Pa = None,
		Optional[float]	temperature_K = None,
		Optional[float]	humidity_rel = None,
		Optional[float]	turbidity = None )

Calculate NIR (Near-Infrared) solar flux.

   Supports both legacy (parameter-based) and modern (state-based) APIs.

Parameters

pressure_Pa	Atmospheric pressure in Pascals [optional]
temperature_K	Temperature in Kelvin [optional]
humidity_rel	Relative humidity as fraction (0.0-1.0) [optional]
turbidity	Atmospheric turbidity coefficient [optional]

Returns: NIR solar flux in W/m² (wavelength range >700 nm)

Exceptions

ValueError	If some parameters provided but not all
SolarPositionError	If calculation fails

Examples: Legacy nir_flux = solar.getSolarFluxNIR(101325, 288.15, 0.6, 0.1) Modern solar.setAtmosphericConditions(101325, 288.15, 0.6, 0.1) nir_flux = solar.getSolarFluxNIR()

Definition at line 578 of file SolarPosition.py.

◆ getSolarFluxPAR()

float pyhelios.SolarPosition.SolarPosition.getSolarFluxPAR	(		self,
		Optional[float]	pressure_Pa = None,
		Optional[float]	temperature_K = None,
		Optional[float]	humidity_rel = None,
		Optional[float]	turbidity = None )

Calculate PAR (Photosynthetically Active Radiation) solar flux.

   Supports both legacy (parameter-based) and modern (state-based) APIs.

Parameters

pressure_Pa	Atmospheric pressure in Pascals [optional]
temperature_K	Temperature in Kelvin [optional]
humidity_rel	Relative humidity as fraction (0.0-1.0) [optional]
turbidity	Atmospheric turbidity coefficient [optional]

Returns: PAR solar flux in W/m² (wavelength range ~400-700 nm)

Exceptions

ValueError	If some parameters provided but not all
SolarPositionError	If calculation fails

Examples: Legacy par_flux = solar.getSolarFluxPAR(101325, 288.15, 0.6, 0.1) Modern solar.setAtmosphericConditions(101325, 288.15, 0.6, 0.1) par_flux = solar.getSolarFluxPAR()

Definition at line 532 of file SolarPosition.py.

◆ getSunAzimuth()

float pyhelios.SolarPosition.SolarPosition.getSunAzimuth ( self )

Get the sun azimuth angle in radians.

Returns: Sun azimuth angle in radians (0 = North, pi/2 = East, pi = South, 3*pi/2 = West)

Exceptions

SolarPositionError If calculation fails

Example: >>> import math >>> azimuth = solar.getSunAzimuth() >>> print(f"Sun azimuth: {math.degrees(azimuth):.1f}° (compass bearing)")

Definition at line 352 of file SolarPosition.py.

◆ getSunDirectionSpherical()

SphericalCoord pyhelios.SolarPosition.SolarPosition.getSunDirectionSpherical ( self )

Get the sun direction as spherical coordinates.

Returns: SphericalCoord with radius=1, elevation and azimuth in radians

Exceptions

SolarPositionError If calculation fails

Example: >>> spherical = solar.getSunDirectionSpherical() >>> print(f"Spherical: r={spherical.radius}, elev={spherical.elevation:.3f}, az={spherical.azimuth:.3f}")

Definition at line 394 of file SolarPosition.py.

◆ getSunDirectionVector()

vec3 pyhelios.SolarPosition.SolarPosition.getSunDirectionVector ( self )

Get the sun direction as a 3D unit vector.

Returns: vec3 representing the sun direction vector (x, y, z)

Exceptions

SolarPositionError If calculation fails

Example: >>> direction = solar.getSunDirectionVector() >>> print(f"Sun direction vector: ({direction.x:.3f}, {direction.y:.3f}, {direction.z:.3f})")

Definition at line 373 of file SolarPosition.py.

◆ getSunElevation()

float pyhelios.SolarPosition.SolarPosition.getSunElevation ( self )

Get the sun elevation angle in radians.

Returns: Sun elevation angle in radians (0 = horizon, pi/2 = zenith)

Exceptions

SolarPositionError If calculation fails

Example: >>> import math >>> elevation = solar.getSunElevation() >>> print(f"Sun is {math.degrees(elevation):.1f}° above horizon")

Definition at line 309 of file SolarPosition.py.

◆ getSunriseTime()

Time pyhelios.SolarPosition.SolarPosition.getSunriseTime ( self )

Calculate sunrise time for the current date and location.

Returns: Time object with sunrise time (hour, minute, second)

Exceptions

SolarPositionError If calculation fails

Example: >>> sunrise = solar.getSunriseTime() >>> print(f"Sunrise: {sunrise}") # Prints as HH:MM:SS

Definition at line 744 of file SolarPosition.py.

◆ getSunsetTime()

Time pyhelios.SolarPosition.SolarPosition.getSunsetTime ( self )

Calculate sunset time for the current date and location.

Returns: Time object with sunset time (hour, minute, second)

Exceptions

SolarPositionError If calculation fails

Example: >>> sunset = solar.getSunsetTime() >>> print(f"Sunset: {sunset}") # Prints as HH:MM:SS

Definition at line 765 of file SolarPosition.py.

◆ getSunZenith()

float pyhelios.SolarPosition.SolarPosition.getSunZenith ( self )

Get the sun zenith angle in radians.

Returns: Sun zenith angle in radians (0 = zenith, pi/2 = horizon)

Exceptions

SolarPositionError If calculation fails

Example: >>> import math >>> zenith = solar.getSunZenith() >>> print(f"Sun zenith angle: {math.degrees(zenith):.1f}°")

Definition at line 330 of file SolarPosition.py.

◆ is_available()

bool pyhelios.SolarPosition.SolarPosition.is_available ( self )

Check if SolarPosition is available in current build.

Returns: True if plugin is available, False otherwise

Definition at line 1108 of file SolarPosition.py.

◆ isPragueSkyModelEnabled()

bool pyhelios.SolarPosition.SolarPosition.isPragueSkyModelEnabled ( self )

Check if Prague Sky Model is currently enabled.

Returns: True if Prague Sky Model has been enabled via enablePragueSkyModel(), False otherwise

Exceptions

SolarPositionError If operation fails

Example: >>> if solar.isPragueSkyModelEnabled(): ... print("Prague Sky Model is active")

Definition at line 890 of file SolarPosition.py.

◆ pragueSkyModelNeedsUpdate()

bool pyhelios.SolarPosition.SolarPosition.pragueSkyModelNeedsUpdate	(		self,
		float	ground_albedo = 0.33,
		float	sun_tolerance = 0.01,
		float	turbidity_tolerance = 0.02,
		float	albedo_tolerance = 0.05 )

Check if Prague Sky Model needs updating based on changed conditions.

   Enables lazy evaluation to avoid expensive Prague updates when conditions haven't
   changed significantly. Compares current state against cached values.

Parameters

ground_albedo	Current ground albedo (default: 0.33)
sun_tolerance	Threshold for sun direction changes (default: 0.01 ≈ 0.57°)
turbidity_tolerance	Relative threshold for turbidity (default: 0.02 = 2%)
albedo_tolerance	Threshold for albedo changes (default: 0.05 = 5%)

Returns: True if updatePragueSkyModel() should be called, False if cached data is valid

Exceptions

SolarPositionError If check fails

Note: Reads turbidity from Context atmospheric conditions for comparison.

Example: >>> if solar.pragueSkyModelNeedsUpdate(): ... solar.updatePragueSkyModel()

Definition at line 954 of file SolarPosition.py.

◆ setAtmosphericConditions()

None pyhelios.SolarPosition.SolarPosition.setAtmosphericConditions	(		self,
		float	pressure_Pa,
		float	temperature_K,
		float	humidity_rel,
		float	turbidity )

Set atmospheric conditions for subsequent flux calculations (modern API).

   This method sets global atmospheric conditions in the Context that are used
   by parameter-free flux methods (modern API). Once set, you can call getSolarFlux(),
   getSolarFluxPAR(), etc. without passing atmospheric parameters.

Parameters

pressure_Pa	Atmospheric pressure in Pascals (e.g., 101325 for sea level)
temperature_K	Temperature in Kelvin (e.g., 288.15 for 15°C)
humidity_rel	Relative humidity as fraction (0.0-1.0)
turbidity	Atmospheric turbidity coefficient (typically 0.02-0.5)

Exceptions

ValueError	If atmospheric parameters are out of valid ranges
SolarPositionError	If operation fails

Note: This is the modern API pattern. Atmospheric conditions are stored in Context global data and reused by all parameter-free flux methods until changed.

Example: >>> # Modern API (set once, use many times) >>> with Context() as context: ... with SolarPosition(context) as solar: ... solar.setAtmosphericConditions(101325, 288.15, 0.6, 0.1) ... flux = solar.getSolarFlux() # No parameters needed ... par = solar.getSolarFluxPAR() # Uses same conditions ... diffuse = solar.getDiffuseFraction() # Uses same conditions

Definition at line 252 of file SolarPosition.py.

◆ setSunDirection()

pyhelios.SolarPosition.SolarPosition.setSunDirection	(		self,
		SphericalCoord	sundirection )

Override the computed solar position with a prescribed sun direction.

   By default the sun position is computed from the date, time and location
   set in the Context. Calling this method overrides that calculation, so
   all subsequent sun queries (elevation, zenith, azimuth, direction
   vectors) and flux calculations use the prescribed direction instead.

Parameters

sundirection SphericalCoord giving the direction of the sun. Elevation and azimuth are in radians.

Exceptions

ValueError	If sundirection is not a SphericalCoord
SolarPositionError	If the override fails

Example: >>> from pyhelios.types import SphericalCoord >>> import math >>> solar.setSunDirection(SphericalCoord(1.0, math.radians(45), math.radians(180))) >>> math.degrees(solar.getSunElevation()) 45.0

Definition at line 429 of file SolarPosition.py.

◆ updatePragueSkyModel()

pyhelios.SolarPosition.SolarPosition.updatePragueSkyModel	(		self,
		float	ground_albedo = 0.33 )

Update Prague Sky Model and store spectral-angular parameters in Context.

   This is a computationally intensive operation (~1100 model queries with OpenMP
   parallelization) that computes sky radiance distribution for current atmospheric
   and solar conditions. Use pragueSkyModelNeedsUpdate() for lazy evaluation to
   avoid unnecessary updates.

Parameters

ground_albedo Ground surface albedo (default: 0.33 for typical soil/vegetation)

Exceptions

SolarPositionError If update fails

Note: Reads turbidity from Context atmospheric conditions. Stores results in Context global data as "prague_sky_spectral_params" (1350 floats: 225 wavelengths × 6 params), "prague_sky_sun_direction", "prague_sky_visibility_km", "prague_sky_ground_albedo", and "prague_sky_valid" flag.

Example: >>> solar.setAtmosphericConditions(101325, 288.15, 0.6, 0.1) >>> solar.updatePragueSkyModel(ground_albedo=0.25)

Definition at line 921 of file SolarPosition.py.

Member Data Documentation

◆ _solar_pos

pyhelios.SolarPosition.SolarPosition._solar_pos

protected

Initial value:

=  solar_wrapper.createSolarPositionWithCoordinates(
                context.getNativePtr(), utc_offset, latitude, longitude
            )

Definition at line 184 of file SolarPosition.py.

◆ context

pyhelios.SolarPosition.SolarPosition.context = context

Definition at line 183 of file SolarPosition.py.

The documentation for this class was generated from the following file:

pyhelios/SolarPosition.py

Detailed Description

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ __init__()

◆ __del__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ _check_context_alive()

◆ calculateDiffuseSolarSpectrum()

◆ calculateDirectSolarSpectrum()

◆ calculateGlobalSolarSpectrum()

◆ calibrateTurbidityFromTimeseries()

◆ disableCloudCalibration()

◆ enableCloudCalibration()

◆ enablePragueSkyModel()

◆ getAmbientLongwaveFlux()

◆ getAtmosphericConditions()

◆ getDiffuseFraction()

◆ getSolarFlux()

◆ getSolarFluxNIR()

◆ getSolarFluxPAR()

◆ getSunAzimuth()

◆ getSunDirectionSpherical()

◆ getSunDirectionVector()

◆ getSunElevation()

◆ getSunriseTime()

◆ getSunsetTime()

◆ getSunZenith()

◆ is_available()

◆ isPragueSkyModelEnabled()

◆ pragueSkyModelNeedsUpdate()

◆ setAtmosphericConditions()

◆ setSunDirection()

◆ updatePragueSkyModel()

Member Data Documentation

◆ _solar_pos

◆ context

◆ init()

◆ del()

◆ enter()

◆ exit()