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

	calculateDiffuseSolarSpectrum (self, str label, float resolution_nm=1.0)
	Calculate diffuse solar spectrum.

	calculateGlobalSolarSpectrum (self, str label, float resolution_nm=1.0)
	Calculate global (total) solar spectrum.

None	setOzoneColumn (self, float ozone_DU)
	Set the total column ozone, overriding the climatological value.

float	getOzoneColumn (self)
	Get the total column ozone used by the solar radiation models.

None	setGroundAlbedo (self, float albedo)
	Set the albedo of the ground surrounding the scene.

float	getGroundAlbedo (self)
	Get the albedo of the ground surrounding the scene.

None	calculateSensorAtmosphereSpectra (self, str label, vec3 direction_to_sensor, float resolution_nm=1.0)
	Calculate the spectral atmospheric quantities needed to simulate imagery from a sensor above the atmosphere (e.g., a satellite).

None	calculateSensorThermalAtmosphere (self, str label, vec3 direction_to_sensor)
	Calculate the thermal infrared atmospheric quantities needed to simulate thermal imagery from a sensor above the atmosphere (e.g., a satellite).

float	getThermalSkyFlux (self, float wavelength_min_nm, float wavelength_max_nm)
	Calculate the sky longwave irradiance on a horizontal surface within a thermal band.

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 204 of file SolarPosition.py.

◆ del()

pyhelios.SolarPosition.SolarPosition.__del__ ( self )

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

Definition at line 273 of file SolarPosition.py.

Member Function Documentation

◆ enter()

pyhelios.SolarPosition.SolarPosition.__enter__ ( self )

Context manager entry.

Definition at line 263 of file SolarPosition.py.

◆ exit()

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

Context manager exit - cleanup resources.

Definition at line 267 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 259 of file SolarPosition.py.

◆ calculateDiffuseSolarSpectrum()

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

Calculate diffuse solar spectrum.

   Computes the diffuse (sky) spectral irradiance on a horizontal surface from 300 to
   2600 nm, including light reflected by the ground and scattered back down by the
   atmosphere, with a spectral model that follows SSolar-GOA (Cachorro et al. 2022).
   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 conditions are taken from setAtmosphericConditions(), the ozone column from getOzoneColumn() and the ground albedo from setGroundAlbedo(); cloud calibration is applied if enabled with enableCloudCalibration()
The spectrum is referred to by its label, e.g. in RadiationModel.setSourceSpectrum() or RadiationModel.setDiffuseSpectrum(); context.getGlobalDataSize(label) gives its number of wavelengths
Fails if the sun is at or below the horizon, if the relative humidity is not greater than zero, or if no ozone column was set and the climatology has no data for the location and date (see getOzoneColumn())
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) ... n_wavelengths = context.getGlobalDataSize("diffuse_spectrum") # 461

Definition at line 1146 of file SolarPosition.py.

◆ calculateDirectSolarSpectrum()

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

Calculate direct beam solar spectrum.

   Computes the spectral irradiance of the direct solar beam on a surface normal to
   the sun direction from 300 to 2600 nm, with a spectral model that follows SSolar-GOA
   (Cachorro et al. 2022). 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 conditions are taken from setAtmosphericConditions(), the ozone column from getOzoneColumn() and the ground albedo from setGroundAlbedo(); cloud calibration is applied if enabled with enableCloudCalibration()
The spectrum is referred to by its label, e.g. in RadiationModel.setSourceSpectrum() or RadiationModel.setDiffuseSpectrum(); context.getGlobalDataSize(label) gives its number of wavelengths
Fails if the sun is at or below the horizon, if the relative humidity is not greater than zero, or if no ozone column was set and the climatology has no data for the location and date (see getOzoneColumn())

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) ... n_wavelengths = context.getGlobalDataSize("direct_spectrum") # 461

Definition at line 1094 of file SolarPosition.py.

◆ calculateGlobalSolarSpectrum()

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

Calculate global (total) solar spectrum.

   Computes the global (direct plus diffuse) spectral irradiance on a horizontal surface
   from 300 to 2600 nm, with a spectral model that follows SSolar-GOA (Cachorro et al. 2022).
   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 conditions are taken from setAtmosphericConditions(), the ozone column from getOzoneColumn() and the ground albedo from setGroundAlbedo(); cloud calibration is applied if enabled with enableCloudCalibration()
The spectrum is referred to by its label, e.g. in RadiationModel.setSourceSpectrum() or RadiationModel.setDiffuseSpectrum(); context.getGlobalDataSize(label) gives its number of wavelengths
Fails if the sun is at or below the horizon, if the relative humidity is not greater than zero, or if no ozone column was set and the climatology has no data for the location and date (see getOzoneColumn())
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) ... n_wavelengths = context.getGlobalDataSize("global_spectrum") # 231

Definition at line 1198 of file SolarPosition.py.

◆ calculateSensorAtmosphereSpectra()

None pyhelios.SolarPosition.SolarPosition.calculateSensorAtmosphereSpectra	(		self,
		str	label,
		vec3	direction_to_sensor,
		float	resolution_nm = 1.0 )

Calculate the spectral atmospheric quantities needed to simulate imagery from a sensor above the atmosphere (e.g., a satellite).

Radiance reaching the sensor is modeled as L_sensor = L_path + T_dir_up * L_surface + L_adj, where L_surface is the radiance leaving the scene. The atmosphere is described by a look-up table computed with the 6S radiative transfer code (continental aerosol), which gives both the upward path to the sensor and the downward solar illumination of the scene. For the two to be consistent, illuminate the scene with the "_direct_irradiance" and "_diffuse_irradiance" spectra stored by this method rather than those of calculateDirectSolarSpectrum() and calculateDiffuseSolarSpectrum().

The following spectra are stored in Context global data as vectors of vec2 (wavelength_nm, value), each labeled with the given label followed by a suffix:

"_path_radiance": radiance scattered by the atmosphere into the sensor without reaching the ground (W/m²/sr/nm)
"_adjacency_radiance": radiance reflected by the surrounding ground (albedo from setGroundAlbedo()) and scattered by the atmosphere into the sensor (W/m²/sr/nm)
"_upward_direct_transmittance": transmittance of the surface-leaving radiance straight to the sensor, including gas absorption
"_upward_diffuse_transmittance": transmittance of surface-leaving radiance scattered into the sensor direction, including gas absorption
"_spherical_albedo": spherical albedo of the atmosphere
"_direct_irradiance": direct solar irradiance at the ground, normal to the sun direction (W/m²/nm)
"_diffuse_irradiance": diffuse solar irradiance at the ground on a horizontal surface (W/m²/nm)
"_global_irradiance": global solar irradiance at the ground on a horizontal surface (W/m²/nm)

The unit vector toward the sensor is also stored, as vec3 global data with the suffix "_direction_to_sensor".

Parameters

label	Prefix of the labels under which the spectra are stored in Context global data
direction_to_sensor	Vector pointing from the scene toward the sensor (need not be normalized). Its zenith angle must not exceed 60 degrees.
resolution_nm	Wavelength resolution in nanometers (1.0-2300.0). Default is 1.0 nm.

Exceptions

ValueError	If label is empty, direction_to_sensor is not a non-zero vec3, or resolution is out of valid range
SolarPositionError	If calculation fails, including for conditions outside the range of the look-up table

Note

Atmospheric conditions are taken from setAtmosphericConditions(), the ozone column from getOzoneColumn() and the ground albedo from setGroundAlbedo(). The turbidity is converted to aerosol optical depth at 550 nm with an Ångström exponent of 1.3.
The look-up table covers solar zenith angles up to 70 degrees, view zenith angles up to 60 degrees, aerosol optical depths at 550 nm up to 1.2 (turbidity up to about 0.55) and surface pressures from 701.2 to 1013 hPa (ground elevations up to about 3 km); pressures up to 1050 hPa are extrapolated linearly. Its gas tables cover water vapor paths up to 320 g/cm². Conditions outside these ranges, and a sun below the horizon, raise an error.
The sensor is taken to be above the atmosphere. The model assumes clear sky and cannot be used with cloud calibration enabled.
RadiationModel.enableCameraAtmosphere() applies these spectra to a camera's images.

Example: >>> solar.setAtmosphericConditions(101325, 298, 0.5, 0.1) >>> solar.setGroundAlbedo(0.15) >>> solar.calculateSensorAtmosphereSpectra("satellite", vec3(0, 0, 1)) # sensor at nadir >>> radiation.setSourceSpectrum(sun_source, "satellite_direct_irradiance") >>> radiation.setDiffuseSpectrum("red", "satellite_diffuse_irradiance")

Definition at line 1395 of file SolarPosition.py.

◆ calculateSensorThermalAtmosphere()

None pyhelios.SolarPosition.SolarPosition.calculateSensorThermalAtmosphere	(		self,
		str	label,
		vec3	direction_to_sensor )

Calculate the thermal infrared atmospheric quantities needed to simulate thermal imagery from a sensor above the atmosphere (e.g., a satellite).

Radiance reaching the sensor at a thermal wavelength is modeled as L_sensor = tau * L_surface + L_up, where L_surface is the radiance leaving the scene (emitted plus reflected sky radiance), tau the atmospheric transmittance and L_up the radiance emitted upward by the atmosphere. These are interpolated from a look-up table computed with the libRadtran radiative transfer code (clear sky without aerosol).

The following spectra are stored in Context global data as vectors of vec2 (wavelength of the bin center in nm, value), with 234 points from 5502 to 15326 nm, each labeled with the given label followed by a suffix:

"_thermal_transmittance": atmospheric transmittance from the ground to the sensor
"_thermal_upwelling_radiance": radiance emitted by the atmosphere toward the sensor (W/m²/sr/nm)
"_thermal_downwelling_radiance": sky irradiance on a horizontal surface at the ground divided by pi (W/m²/sr/nm), independent of the view direction

The column water vapor (float, g/cm²) is stored with the suffix "_thermal_water_vapor_cm", and the unit vector toward the sensor, as vec3, with the suffix "_direction_to_sensor".

Parameters

label	Prefix of the labels under which the results are stored in Context global data
direction_to_sensor	Vector pointing from the scene toward the sensor (need not be normalized). Its zenith angle must not exceed 60 degrees.

Exceptions

ValueError	If label is empty or direction_to_sensor is not a non-zero vec3
SolarPositionError	If calculation fails, including for conditions outside the range of the look-up table

Note

The atmospheric profile is built from the surface air temperature, humidity and pressure set with setAtmosphericConditions() and the ozone column of getOzoneColumn(). The column water vapor, derived from the temperature and humidity, must lie within 0.1-7.5 g/cm², the pressure within 701.2-1050 hPa (pressures above 1013 hPa are extrapolated) and the ozone column within 150-450 DU. The supported air temperatures depend on the pressure: 246.2-321.7 K at 1013 hPa.
The model assumes clear sky and does not depend on the position of the sun, so night-time imagery can be simulated. Reflected sunlight, which is significant below about 5 µm, is not included.

Example: >>> solar.setAtmosphericConditions(101325, 298, 0.5, 0.1) >>> solar.calculateSensorThermalAtmosphere("satellite", vec3(0, 0, 1)) # sensor at nadir >>> context.getGlobalDataSize("satellite_thermal_transmittance") 234

Definition at line 1461 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 881 of file SolarPosition.py.

◆ disableCloudCalibration()

pyhelios.SolarPosition.SolarPosition.disableCloudCalibration ( self )

Disable cloud calibration.

Exceptions

SolarPositionError If operation fails

Example: >>> solar.disableCloudCalibration()

Definition at line 924 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 905 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 954 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, integrated over all longwave wavelengths. It is the diffuse flux to give an emission band without wavelength bounds. For the sky flux within a thermal band with wavelength bounds, use getThermalSkyFlux().

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 763 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), where turbidity is Ångström's aerosol turbidity coefficient (β), the aerosol optical depth at 1 µm

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 354 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	Ångström's aerosol turbidity coefficient (β), the aerosol optical depth at 1 µm [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 705 of file SolarPosition.py.

◆ getGroundAlbedo()

float pyhelios.SolarPosition.SolarPosition.getGroundAlbedo ( self )

Get the albedo of the ground surrounding the scene.

Returns: Ground albedo set by setGroundAlbedo(), or 0.2 if it has not been set

Exceptions

SolarPositionError If operation fails

Example: >>> albedo = solar.getGroundAlbedo()

Definition at line 1320 of file SolarPosition.py.

◆ getOzoneColumn()

float pyhelios.SolarPosition.SolarPosition.getOzoneColumn ( self )

Get the total column ozone used by the solar radiation models.

   Returns the ozone column set with setOzoneColumn(), if any. Otherwise returns the monthly
   zonal-mean climatology of the NASA SBUV Merged Ozone Data Set averaged over 2005-2024,
   interpolated linearly in latitude between the centers of its 5-degree latitude bands and in
   the day of the year between the middles of the months.

Returns: Total column ozone in Dobson units

Exceptions

SolarPositionError If no ozone column was set and the climatology has no data for the location and date. The climatology has no data in high-latitude winter months or poleward of 80 degrees; set the ozone column with setOzoneColumn() there.

Note: Next to a latitude band or month without data, the value of the band or month containing the location or date is used rather than interpolating toward the missing one.

Example: >>> ozone_DU = solar.getOzoneColumn()

Definition at line 1264 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	Ångström's aerosol turbidity coefficient (β), the aerosol optical depth at 1 µm [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)

Note: The model uses the total column ozone of getOzoneColumn(). Where the ozone climatology has no data (high-latitude winter months, or poleward of 80 degrees) the calculation fails until the ozone column is set with setOzoneColumn(). The same applies to getSolarFluxPAR(), getSolarFluxNIR() and getDiffuseFraction().

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 548 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	Ångström's aerosol turbidity coefficient (β), the aerosol optical depth at 1 µm [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 655 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	Ångström's aerosol turbidity coefficient (β), the aerosol optical depth at 1 µm [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 607 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 419 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 461 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 440 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 376 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 828 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 849 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 397 of file SolarPosition.py.

◆ getThermalSkyFlux()

float pyhelios.SolarPosition.SolarPosition.getThermalSkyFlux	(		self,
		float	wavelength_min_nm,
		float	wavelength_max_nm )

Calculate the sky longwave irradiance on a horizontal surface within a thermal band.

   This is the band-specific counterpart of getAmbientLongwaveFlux(): the downward irradiance
   emitted by a clear-sky atmosphere between two wavelengths, integrated from the downwelling
   radiance of the thermal atmosphere look-up table (see calculateSensorThermalAtmosphere()).
   It is the diffuse flux to give an emission band with the same wavelength bounds
   (RadiationModel.setDiffuseRadiationFlux()), so that the sky radiance the scene reflects is
   consistent with the thermal sensor atmosphere.

Parameters

wavelength_min_nm	Lower wavelength bound of the band in nm
wavelength_max_nm	Upper wavelength bound of the band in nm

Returns: Sky longwave irradiance within the band on a horizontal surface, in W/m²

Exceptions

ValueError	If the bounds are not numbers satisfying 0 < wavelength_min_nm < wavelength_max_nm
SolarPositionError	If calculation fails, including for bounds outside 5502-15326 nm or atmospheric conditions outside the ranges given for calculateSensorThermalAtmosphere()

Example: >>> radiation.addRadiationBand("TIR", 10600, 11190) # e.g., Landsat 8 TIRS band 10 >>> radiation.setDiffuseRadiationFlux("TIR", solar.getThermalSkyFlux(10600, 11190))

Definition at line 1498 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 1520 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 975 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 1043 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). The spectral solar irradiance, sensor atmosphere and thermal atmosphere methods derive the precipitable water from it and require a value greater than 0.
turbidity	Ångström's aerosol turbidity coefficient (β), the aerosol optical depth at 1 µm (must be >= 0). The aerosol optical depth at 550 nm is about 2.18 β and that at 500 nm about 2.46 β, so an aerosol optical depth measured at 500 nm corresponds to β of about 0.41 times that value. This is not Linke turbidity.

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 318 of file SolarPosition.py.

◆ setGroundAlbedo()

None pyhelios.SolarPosition.SolarPosition.setGroundAlbedo	(		self,
		float	albedo )

Set the albedo of the ground surrounding the scene.

   The ground albedo sets how much light is reflected back and forth between the ground and
   the atmosphere, which increases the global and diffuse irradiance, most strongly at short
   wavelengths. It is stored in Context global data as "atmosphere_ground_albedo".

Parameters

albedo Broadband ground albedo (must be between 0 and 1)

Exceptions

ValueError	If albedo is not a number between 0 and 1
SolarPositionError	If operation fails

Note: The ground albedo affects the global and diffuse spectra of calculateGlobalSolarSpectrum() and calculateDiffuseSolarSpectrum(), and the ground irradiance and adjacency radiance of calculateSensorAtmosphereSpectra(); without cloud calibration it does not affect the direct beam. It does not affect the broadband getSolarFlux() family of methods, and the Prague sky model takes its ground albedo as an argument of updatePragueSkyModel().

Example: >>> solar.setGroundAlbedo(0.8) # e.g., fresh snow

Definition at line 1296 of file SolarPosition.py.

◆ setOzoneColumn()

None pyhelios.SolarPosition.SolarPosition.setOzoneColumn	(		self,
		float	ozone_DU )

Set the total column ozone, overriding the climatological value.

   The ozone column is used by the broadband solar flux model (getSolarFlux() family), the
   spectral solar irradiance model and the sensor atmosphere models. It is stored in Context
   global data as "atmosphere_ozone_DU".

Parameters

ozone_DU Total column ozone in Dobson units (must be > 0)

Exceptions

ValueError	If ozone_DU is not a positive number
SolarPositionError	If operation fails

Example: >>> solar.setOzoneColumn(310.0) # e.g., from a local measurement

Definition at line 1229 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 496 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 (Ångström's β, the aerosol optical depth at 1 µm) from Context atmospheric conditions and converts the aerosol optical depth at 550 nm to the visibility that parameterizes the Prague model, limited to its range of 20-131.8 km: turbidities below about 0.029 (including the default of 0.02) use the cleanest Prague atmosphere and those above about 0.21 the haziest. 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 1010 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 245 of file SolarPosition.py.

◆ context

pyhelios.SolarPosition.SolarPosition.context = context

Definition at line 244 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()

◆ calculateSensorAtmosphereSpectra()

◆ calculateSensorThermalAtmosphere()

◆ calibrateTurbidityFromTimeseries()

◆ disableCloudCalibration()

◆ enableCloudCalibration()

◆ enablePragueSkyModel()

◆ getAmbientLongwaveFlux()

◆ getAtmosphericConditions()

◆ getDiffuseFraction()

◆ getGroundAlbedo()

◆ getOzoneColumn()

◆ getSolarFlux()

◆ getSolarFluxNIR()

◆ getSolarFluxPAR()

◆ getSunAzimuth()

◆ getSunDirectionSpherical()

◆ getSunDirectionVector()

◆ getSunElevation()

◆ getSunriseTime()

◆ getSunsetTime()

◆ getSunZenith()

◆ getThermalSkyFlux()

◆ is_available()

◆ isPragueSkyModelEnabled()

◆ pragueSkyModelNeedsUpdate()

◆ setAtmosphericConditions()

◆ setGroundAlbedo()

◆ setOzoneColumn()

◆ setSunDirection()

◆ updatePragueSkyModel()

Member Data Documentation

◆ _solar_pos

◆ context

◆ init()

◆ del()

◆ enter()

◆ exit()