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 56 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.

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

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

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

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

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

float	getSolarFlux (self, float pressure_Pa, float temperature_K, float humidity_rel, float turbidity)
	Calculate total solar flux with atmospheric parameters.

float	getSolarFluxPAR (self, float pressure_Pa, float temperature_K, float humidity_rel, float turbidity)
	Calculate PAR (Photosynthetically Active Radiation) solar flux.

float	getSolarFluxNIR (self, float pressure_Pa, float temperature_K, float humidity_rel, float turbidity)
	Calculate NIR (Near-Infrared) solar flux.

float	getDiffuseFraction (self, float pressure_Pa, float temperature_K, float humidity_rel, float turbidity)
	Calculate the diffuse fraction of solar radiation.

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

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

	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.

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

Public Attributes
	context = context

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 (-12 to +12). 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 78 of file SolarPosition.py.

Member Function Documentation

◆ enter()

pyhelios.SolarPosition.SolarPosition.__enter__ ( self )

Context manager entry.

Definition at line 128 of file SolarPosition.py.

◆ exit()

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

Context manager exit - cleanup resources.

Definition at line 132 of file SolarPosition.py.

◆ calibrateTurbidityFromTimeseries()

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

Calibrate atmospheric turbidity using timeseries data.

Parameters

timeseries_label Label of timeseries data in Context

Exceptions

ValueError	If timeseries label is invalid
SolarPositionError	If calibration fails

Examples

>>> solar.calibrateTurbidityFromTimeseries("solar_irradiance")

Definition at line 431 of file SolarPosition.py.

◆ disableCloudCalibration()

pyhelios.SolarPosition.SolarPosition.disableCloudCalibration ( self )

Disable cloud calibration.

Exceptions

SolarPositionError If operation fails

Examples

>>> solar.disableCloudCalibration()

Definition at line 475 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

Examples

>>> solar.enableCloudCalibration("cloud_cover")

Definition at line 455 of file SolarPosition.py.

◆ getDiffuseFraction()

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

Calculate the diffuse fraction of solar radiation.

Parameters

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

Returns

Diffuse fraction as ratio (0.0-1.0) where:

0.0 = all direct radiation
1.0 = all diffuse radiation

Exceptions

ValueError	If atmospheric parameters are invalid
SolarPositionError	If calculation fails

Examples

>>> diffuse_fraction = solar.getDiffuseFraction(101325, 288.15, 0.6, 0.1)

>>> print(f"Diffuse fraction: {diffuse_fraction:.3f} ({diffuse_fraction*100:.1f}%)")

Definition at line 363 of file SolarPosition.py.

◆ getSolarFlux()

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

Calculate total solar flux with 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.05-0.5)

Returns: Total solar flux in W/m²

Exceptions

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

Examples

>>> # Standard atmospheric conditions
>>> flux = solar.getSolarFlux(101325, 288.15, 0.6, 0.1)
>>> print(f"Total solar flux: {flux:.1f} W/m²")

Definition at line 274 of file SolarPosition.py.

◆ getSolarFluxNIR()

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

Calculate NIR (Near-Infrared) solar flux.

Parameters

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

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

Exceptions

ValueError	If atmospheric parameters are invalid
SolarPositionError	If calculation fails

Examples

>>> nir_flux = solar.getSolarFluxNIR(101325, 288.15, 0.6, 0.1)

>>> print(f"NIR flux: {nir_flux:.1f} W/m²")

Definition at line 332 of file SolarPosition.py.

◆ getSolarFluxPAR()

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

Calculate PAR (Photosynthetically Active Radiation) solar flux.

Parameters

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

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

Exceptions

ValueError	If atmospheric parameters are invalid
SolarPositionError	If calculation fails

Examples

>>> par_flux = solar.getSolarFluxPAR(101325, 288.15, 0.6, 0.1)

>>> print(f"PAR flux: {par_flux:.1f} W/m²")

Definition at line 303 of file SolarPosition.py.

◆ getSunAzimuth()

float pyhelios.SolarPosition.SolarPosition.getSunAzimuth ( self )

Get the sun azimuth angle in degrees.

Returns: Sun azimuth angle in degrees (0° = North, 90° = East, 180° = South, 270° = West)

Exceptions

SolarPositionError If calculation fails

Examples

>>> azimuth = solar.getSunAzimuth()

>>> print(f"Sun azimuth: {azimuth:.1f}° (compass bearing)")

Definition at line 195 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

Examples

>>> spherical = solar.getSunDirectionSpherical()

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

Definition at line 239 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

Examples

>>> direction = solar.getSunDirectionVector()

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

Definition at line 217 of file SolarPosition.py.

◆ getSunElevation()

float pyhelios.SolarPosition.SolarPosition.getSunElevation ( self )

Get the sun elevation angle in degrees.

Returns: Sun elevation angle in degrees (0° = horizon, 90° = zenith)

Exceptions

SolarPositionError If calculation fails

Examples

>>> elevation = solar.getSunElevation()

>>> print(f"Sun is {elevation:.1f}° above horizon")

Definition at line 153 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

Examples

>>> sunrise = solar.getSunriseTime()

>>> print(f"Sunrise: {sunrise}") # Prints as HH:MM:SS

Definition at line 386 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

Examples

>>> sunset = solar.getSunsetTime()

>>> print(f"Sunset: {sunset}") # Prints as HH:MM:SS

Definition at line 408 of file SolarPosition.py.

◆ getSunZenith()

float pyhelios.SolarPosition.SolarPosition.getSunZenith ( self )

Get the sun zenith angle in degrees.

Returns: Sun zenith angle in degrees (0° = zenith, 90° = horizon)

Exceptions

SolarPositionError If calculation fails

Examples

>>> zenith = solar.getSunZenith()

>>> print(f"Sun zenith angle: {zenith:.1f}°")

Definition at line 174 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 489 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 116 of file SolarPosition.py.

◆ context

pyhelios.SolarPosition.SolarPosition.context = context

Definition at line 115 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 Attributes

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ __enter__()

◆ __exit__()

◆ calibrateTurbidityFromTimeseries()

◆ disableCloudCalibration()

◆ enableCloudCalibration()

◆ getDiffuseFraction()

◆ getSolarFlux()

◆ getSolarFluxNIR()

◆ getSolarFluxPAR()

◆ getSunAzimuth()

◆ getSunDirectionSpherical()

◆ getSunDirectionVector()

◆ getSunElevation()

◆ getSunriseTime()

◆ getSunsetTime()

◆ getSunZenith()

◆ is_available()

Member Data Documentation

◆ _solar_pos

◆ context

◆ init()

◆ enter()

◆ exit()