1.3.64
 
Loading...
Searching...
No Matches
SolarPosition Class Reference

Public Member Functions

 SolarPosition (helios::Context *context_ptr)
 Solar position model default constructor. Initializes location based on the location set in the Context.
 
 SolarPosition (float UTC_hrs, float latitude_deg, float longitude_deg, helios::Context *context_ptr)
 Solar position model constructor.
 
helios::Time getSunriseTime () const
 Get the approximate time of sunrise at the current location.
 
helios::Time getSunsetTime () const
 Get the approximate time of sunset at the current location.
 
float getSunElevation () const
 Get the current sun elevation angle in radians for the current location. The sun angle is computed based on the current time and date set in the Helios context.
 
float getSunZenith () const
 Get the current sun zenithal angle in radians for the current location. The sun angle is computed based on the current time and date set in the Helios context.
 
float getSunAzimuth () const
 Get the current sun azimuthal angle in radians for the current location. The sun angle is computed based on the current time and date set in the Helios context.
 
helios::vec3 getSunDirectionVector () const
 Get a unit vector pointing toward the sun for the current location. The sun angle is computed based on the current time and date set in the Helios context.
 
helios::SphericalCoord getSunDirectionSpherical () const
 Get a spherical coordinate vector pointing toward the sun for the current location. The sun angle is computed based on the current time and date set in the Helios context.
 
void setSunDirection (const helios::SphericalCoord &sundirection)
 Override solar position calculation based on time in the Context by using a prescribed solar position.
 
float getSolarFlux (float pressure_Pa, float temperature_K, float humidity_rel, float turbidity) const
 Get the solar radiation flux perpendicular to the sun direction.
 
float getSolarFluxPAR (float pressure_Pa, float temperature_K, float humidity_rel, float turbidity) const
 Get the photosynthetically active (PAR) component of solar radiation flux perpendicular to the sun direction.
 
float getSolarFluxNIR (float pressure_Pa, float temperature_K, float humidity_rel, float turbidity) const
 Get the near-infrared (NIR) component of solar radiation flux perpendicular to the sun direction.
 
float getDiffuseFraction (float pressure_Pa, float temperature_K, float humidity_rel, float turbidity) const
 Get the fraction of solar radiation flux that is diffuse.
 
float getAmbientLongwaveFlux (float temperature_K, float humidity_rel) const
 Calculate the ambient (sky) longwave radiation flux.
 
float calibrateTurbidityFromTimeseries (const std::string &timeseries_shortwave_flux_label_Wm2) const
 Calculate the turbidity value based on a timeseries of net radiation measurements.
 
void enableCloudCalibration (const std::string &timeseries_shortwave_flux_label_Wm2)
 Enable calibration of solar flux and diffuse fraction when possibility of clouds are present against measured solar flux data.
 
void disableCloudCalibration ()
 Disable calibration of solar flux and diffuse fraction for clouds.
 
void setAtmosphericConditions (float pressure_Pa, float temperature_K, float humidity_rel, float turbidity)
 Set atmospheric conditions globally in the Context.
 
void getAtmosphericConditions (float &pressure_Pa, float &temperature_K, float &humidity_rel, float &turbidity) const
 Get atmospheric conditions from the Context.
 
float getSolarFlux () const
 Get the solar radiation flux perpendicular to the sun direction using atmospheric conditions from the Context.
 
float getSolarFluxPAR () const
 Get the photosynthetically active (PAR) component of solar radiation flux perpendicular to the sun direction using atmospheric conditions from the Context.
 
float getSolarFluxNIR () const
 Get the near-infrared (NIR) component of solar radiation flux perpendicular to the sun direction using atmospheric conditions from the Context.
 
float getDiffuseFraction () const
 Get the fraction of solar radiation flux that is diffuse using atmospheric conditions from the Context.
 
float getAmbientLongwaveFlux () const
 Calculate the ambient (sky) longwave radiation flux using atmospheric conditions from the Context.
 
void calculateDirectSolarSpectrum (const std::string &label, float resolution_nm=1.0f)
 Calculate direct beam solar spectrum and store in global data.
 
void calculateDiffuseSolarSpectrum (const std::string &label, float resolution_nm=1.0f)
 Calculate diffuse solar spectrum and store in global data.
 
void calculateGlobalSolarSpectrum (const std::string &label, float resolution_nm=1.0f)
 Calculate global (total) solar spectrum and store in global data.
 
void enablePragueSkyModel ()
 Enable Prague sky model for atmospheric sky radiance computation.
 
bool isPragueSkyModelEnabled () const
 Check if Prague sky model is enabled.
 
void updatePragueSkyModel (float ground_albedo=0.33f)
 Update Prague sky model and store spectral-angular parameters in Context.
 
bool pragueSkyModelNeedsUpdate (float ground_albedo=0.33f, float sun_tolerance=0.01f, float turbidity_tolerance=0.02f, float albedo_tolerance=0.05f) const
 Check if Prague sky model update is needed based on changed conditions.
 

Static Public Member Functions

static int selfTest (int argc=0, char **argv=nullptr)
 Function to perform a self-test of model functions.
 

Detailed Description

Definition at line 25 of file SolarPosition.h.

Constructor & Destructor Documentation

◆ SolarPosition() [1/2]

SolarPosition::SolarPosition ( helios::Context context_ptr)
explicit

Solar position model default constructor. Initializes location based on the location set in the Context.

Parameters
[in]context_ptrPointer to the Helios context

Definition at line 22 of file SolarPosition.cpp.

◆ SolarPosition() [2/2]

SolarPosition::SolarPosition ( float  UTC_hrs,
float  latitude_deg,
float  longitude_deg,
helios::Context context_ptr 
)

Solar position model constructor.

Parameters
[in]context_ptrPointer to the Helios context
[in]UTC_hrsHours from Coordinated Universal Time (UTC) for location of interest. Convention is that UTC is positive moving Westward.
[in]latitude_degLatitude in degrees for location of interest. Convention is latitude is positive for Northern hemisphere.
[in]longitude_degLongitude in degrees for location of interest. Convention is longitude is positive for Western hemisphere.

Definition at line 30 of file SolarPosition.cpp.

Member Function Documentation

◆ calculateDiffuseSolarSpectrum()

void SolarPosition::calculateDiffuseSolarSpectrum ( const std::string &  label,
float  resolution_nm = 1.0f 
)

Calculate diffuse solar spectrum and store in global data.

Parameters
[in]labelUser-defined label for storing spectral data in Context global data
[in]resolution_nmWavelength resolution in nm (default: 1 nm). Must be >= 1 nm and <= 2300 nm.
Note
Computes diffuse spectral irradiance on horizontal surface from 300-2600 nm using the SSolar-GOA model (Cachorro et al. 2022).
Stores result in Context global data as std::vector<helios::vec2> (wavelength_nm, W/m²/nm) with the specified label.

Definition at line 1013 of file SolarPosition.cpp.

◆ calculateDirectSolarSpectrum()

void SolarPosition::calculateDirectSolarSpectrum ( const std::string &  label,
float  resolution_nm = 1.0f 
)

Calculate direct beam solar spectrum and store in global data.

Parameters
[in]labelUser-defined label for storing spectral data in Context global data
[in]resolution_nmWavelength resolution in nm (default: 1 nm). Must be >= 1 nm and <= 2300 nm.
Note
Computes spectral irradiance normal to sun direction from 300-2600 nm using the SSolar-GOA model (Cachorro et al. 2022).
Stores result in Context global data as std::vector<helios::vec2> (wavelength_nm, W/m²/nm) with the specified label.

Definition at line 1007 of file SolarPosition.cpp.

◆ calculateGlobalSolarSpectrum()

void SolarPosition::calculateGlobalSolarSpectrum ( const std::string &  label,
float  resolution_nm = 1.0f 
)

Calculate global (total) solar spectrum and store in global data.

Parameters
[in]labelUser-defined label for storing spectral data in Context global data
[in]resolution_nmWavelength resolution in nm (default: 1 nm). Must be >= 1 nm and <= 2300 nm.
Note
Computes global spectral irradiance on horizontal surface from 300-2600 nm using the SSolar-GOA model (Cachorro et al. 2022).
Stores result in Context global data as std::vector<helios::vec2> (wavelength_nm, W/m²/nm) with the specified label.

Definition at line 1019 of file SolarPosition.cpp.

◆ calibrateTurbidityFromTimeseries()

float SolarPosition::calibrateTurbidityFromTimeseries ( const std::string &  timeseries_shortwave_flux_label_Wm2) const

Calculate the turbidity value based on a timeseries of net radiation measurements.

Parameters
[in]timeseries_shortwave_flux_label_Wm2Label of the timeseries variable in the Helios context that contains the net radiation flux measurements
Returns
Turbidity value
Note
The net radiation flux measurements contained in the timeseries should be global shortwave radiation flux on a horizontal plane in W/m^2. The data should contain at least one day with clear sky conditions.

Definition at line 390 of file SolarPosition.cpp.

◆ disableCloudCalibration()

void SolarPosition::disableCloudCalibration ( )

Disable calibration of solar flux and diffuse fraction for clouds.

Definition at line 442 of file SolarPosition.cpp.

◆ enableCloudCalibration()

void SolarPosition::enableCloudCalibration ( const std::string &  timeseries_shortwave_flux_label_Wm2)

Enable calibration of solar flux and diffuse fraction when possibility of clouds are present against measured solar flux data.

Parameters
[in]timeseries_shortwave_flux_label_Wm2Label for timeseries data field containing measured total shortwave flux data (W/m^2).

Definition at line 433 of file SolarPosition.cpp.

◆ enablePragueSkyModel()

void SolarPosition::enablePragueSkyModel ( )

Enable Prague sky model for atmospheric sky radiance computation.

Note
The Prague Sky Model computes physically-based sky radiance distributions accounting for Rayleigh and Mie scattering.
Uses the reduced dataset (360-1480 nm, ~27 MB) from plugins/solarposition/lib/prague_sky_model/PragueSkyModelReduced.dat
Once enabled, call updatePragueSkyModel() to compute and store spectral-angular parameters in Context global data.

Definition at line 1027 of file SolarPosition.cpp.

◆ getAmbientLongwaveFlux() [1/2]

float SolarPosition::getAmbientLongwaveFlux ( ) const

Calculate the ambient (sky) longwave radiation flux using atmospheric conditions from the Context.

Note
The longwave flux model is based on Prata (1996).
Atmospheric conditions must be set using setAtmosphericConditions() before calling this method. If not set, default values are used with a warning.
Returns
Ambient longwave flux in W/m^2

Definition at line 548 of file SolarPosition.cpp.

◆ getAmbientLongwaveFlux() [2/2]

float SolarPosition::getAmbientLongwaveFlux ( float  temperature_K,
float  humidity_rel 
) const

Calculate the ambient (sky) longwave radiation flux.

Parameters
[in]temperature_KAir temperature near the ground surface in Kelvin
[in]humidity_relAir relative humidity near the ground surface
Returns
Ambient longwave flux in W/m^2
Note
The longwave flux model is based on Prata (1996).
Deprecated:
Use setAtmosphericConditions() and the parameter-free getAmbientLongwaveFlux() instead

Definition at line 359 of file SolarPosition.cpp.

◆ getAtmosphericConditions()

void SolarPosition::getAtmosphericConditions ( float &  pressure_Pa,
float &  temperature_K,
float &  humidity_rel,
float &  turbidity 
) const

Get atmospheric conditions from the Context.

Parameters
[out]pressure_PaAtmospheric pressure near ground surface in Pascals
[out]temperature_KAir temperature near the ground surface in Kelvin
[out]humidity_relAir relative humidity near the ground surface
[out]turbidityÅngström's aerosol turbidity coefficient (β), representing aerosol optical depth (AOD) at 500 nm
Note
If atmospheric conditions have not been set via setAtmosphericConditions(), reasonable defaults are used: pressure=101325 Pa (1 atm), temperature=300 K (27°C), humidity=0.5 (50%), turbidity=0.02 (clear sky AOD)

Definition at line 468 of file SolarPosition.cpp.

◆ getDiffuseFraction() [1/2]

float SolarPosition::getDiffuseFraction ( ) const

Get the fraction of solar radiation flux that is diffuse using atmospheric conditions from the Context.

Note
Atmospheric conditions must be set using setAtmosphericConditions() before calling this method. If not set, default values are used with a warning.
Returns
Fraction of global radiation that is diffuse

Definition at line 536 of file SolarPosition.cpp.

◆ getDiffuseFraction() [2/2]

float SolarPosition::getDiffuseFraction ( float  pressure_Pa,
float  temperature_K,
float  humidity_rel,
float  turbidity 
) const

Get the fraction of solar radiation flux that is diffuse.

Parameters
[in]pressure_PaAtmospheric pressure near ground surface in Pascals
[in]temperature_KAir temperature near the ground surface in Kelvin
[in]humidity_relAir relative humidity near the ground surface
[in]turbidityÅngström's aerosol turbidity coefficient (AOD at 500 nm). Typical values: 0.02 (very clear), 0.05 (clear), 0.1 (hazy)
Returns
Fraction of global radiation that is diffuse
Deprecated:
Use setAtmosphericConditions() and the parameter-free getDiffuseFraction() instead

Definition at line 217 of file SolarPosition.cpp.

◆ getSolarFlux() [1/2]

float SolarPosition::getSolarFlux ( ) const

Get the solar radiation flux perpendicular to the sun direction using atmospheric conditions from the Context.

Note
The flux given by this function is the flux normal to the sun direction. To get the flux on a horizontal surface, multiply the returned value by cos(theta), where theta can be found by calling the getSunZenith() function.
The solar flux model is based on Gueymard (2008).
Atmospheric conditions must be set using setAtmosphericConditions() before calling this method. If not set, default values are used with a warning.
Returns
Global solar radiation flux NORMAL TO THE SUN DIRECTION in W/m^2

Definition at line 499 of file SolarPosition.cpp.

◆ getSolarFlux() [2/2]

float SolarPosition::getSolarFlux ( float  pressure_Pa,
float  temperature_K,
float  humidity_rel,
float  turbidity 
) const

Get the solar radiation flux perpendicular to the sun direction.

Parameters
[in]pressure_PaAtmospheric pressure near ground surface in Pascals
[in]temperature_KAir temperature near the ground surface in Kelvin
[in]humidity_relAir relative humidity near the ground surface
[in]turbidityÅngström's aerosol turbidity coefficient (AOD at 500 nm). Typical values: 0.02 (very clear), 0.05 (clear), 0.1 (hazy)
Note
The flux given by this function is the flux normal to the sun direction. To get the flux on a horizontal surface, multiply the returned value by cos(theta), where theta can be found by calling the getSunZenith() function.
The solar flux model is based on Gueymard (2008).
Returns
Global solar radiation flux NORMAL TO THE SUN DIRECTION in W/m^2
Deprecated:
Use setAtmosphericConditions() and the parameter-free getSolarFlux() instead

Definition at line 186 of file SolarPosition.cpp.

◆ getSolarFluxNIR() [1/2]

float SolarPosition::getSolarFluxNIR ( ) const

Get the near-infrared (NIR) component of solar radiation flux perpendicular to the sun direction using atmospheric conditions from the Context.

Note
The flux given by this function is the flux normal to the sun direction. To get the flux on a horizontal surface, multiply the returned value by cos(theta), where theta can be found by calling the getSunZenith() function.
The solar flux model is based on Gueymard (2008).
Atmospheric conditions must be set using setAtmosphericConditions() before calling this method. If not set, default values are used with a warning.
Returns
NIR component of solar radiation flux NORMAL TO THE SUN DIRECTION in W/m^2

Definition at line 524 of file SolarPosition.cpp.

◆ getSolarFluxNIR() [2/2]

float SolarPosition::getSolarFluxNIR ( float  pressure_Pa,
float  temperature_K,
float  humidity_rel,
float  turbidity 
) const

Get the near-infrared (NIR) component of solar radiation flux perpendicular to the sun direction.

Parameters
[in]pressure_PaAtmospheric pressure near ground surface in Pascals
[in]temperature_KAir temperature near the ground surface in Kelvin
[in]humidity_relAir relative humidity near the ground surface
[in]turbidityÅngström's aerosol turbidity coefficient (AOD at 500 nm). Typical values: 0.02 (very clear), 0.05 (clear), 0.1 (hazy)
Note
The flux given by this function is the flux normal to the sun direction. To get the flux on a horizontal surface, multiply the returned value by cos(theta), where theta can be found by calling the getSunZenith() function.
The solar flux model is based on Gueymard (2008).
Returns
Global solar radiation flux NORMAL TO THE SUN DIRECTION in W/m^2
Deprecated:
Use setAtmosphericConditions() and the parameter-free getSolarFluxNIR() instead

Definition at line 207 of file SolarPosition.cpp.

◆ getSolarFluxPAR() [1/2]

float SolarPosition::getSolarFluxPAR ( ) const

Get the photosynthetically active (PAR) component of solar radiation flux perpendicular to the sun direction using atmospheric conditions from the Context.

Note
The flux given by this function is the flux normal to the sun direction. To get the flux on a horizontal surface, multiply the returned value by cos(theta), where theta can be found by calling the getSunZenith() function.
The solar flux model is based on Gueymard (2008).
Atmospheric conditions must be set using setAtmosphericConditions() before calling this method. If not set, default values are used with a warning.
Returns
PAR component of solar radiation flux NORMAL TO THE SUN DIRECTION in W/m^2

Definition at line 512 of file SolarPosition.cpp.

◆ getSolarFluxPAR() [2/2]

float SolarPosition::getSolarFluxPAR ( float  pressure_Pa,
float  temperature_K,
float  humidity_rel,
float  turbidity 
) const

Get the photosynthetically active (PAR) component of solar radiation flux perpendicular to the sun direction.

Parameters
[in]pressure_PaAtmospheric pressure near ground surface in Pascals
[in]temperature_KAir temperature near the ground surface in Kelvin
[in]humidity_relAir relative humidity near the ground surface
[in]turbidityÅngström's aerosol turbidity coefficient (AOD at 500 nm). Typical values: 0.02 (very clear), 0.05 (clear), 0.1 (hazy)
Note
The flux given by this function is the flux normal to the sun direction. To get the flux on a horizontal surface, multiply the returned value by cos(theta), where theta can be found by calling the getSunZenith() function.
The solar flux model is based on Gueymard (2008).
Returns
Global solar radiation flux NORMAL TO THE SUN DIRECTION in W/m^2
Deprecated:
Use setAtmosphericConditions() and the parameter-free getSolarFluxPAR() instead

Definition at line 197 of file SolarPosition.cpp.

◆ getSunAzimuth()

float SolarPosition::getSunAzimuth ( ) const

Get the current sun azimuthal angle in radians for the current location. The sun angle is computed based on the current time and date set in the Helios context.

Definition at line 151 of file SolarPosition.cpp.

◆ getSunDirectionSpherical()

SphericalCoord SolarPosition::getSunDirectionSpherical ( ) const

Get a spherical coordinate vector pointing toward the sun for the current location. The sun angle is computed based on the current time and date set in the Helios context.

Definition at line 171 of file SolarPosition.cpp.

◆ getSunDirectionVector()

vec3 SolarPosition::getSunDirectionVector ( ) const

Get a unit vector pointing toward the sun for the current location. The sun angle is computed based on the current time and date set in the Helios context.

Definition at line 161 of file SolarPosition.cpp.

◆ getSunElevation()

float SolarPosition::getSunElevation ( ) const

Get the current sun elevation angle in radians for the current location. The sun angle is computed based on the current time and date set in the Helios context.

Definition at line 131 of file SolarPosition.cpp.

◆ getSunriseTime()

Time SolarPosition::getSunriseTime ( ) const

Get the approximate time of sunrise at the current location.

Definition at line 95 of file SolarPosition.cpp.

◆ getSunsetTime()

Time SolarPosition::getSunsetTime ( ) const

Get the approximate time of sunset at the current location.

Definition at line 113 of file SolarPosition.cpp.

◆ getSunZenith()

float SolarPosition::getSunZenith ( ) const

Get the current sun zenithal angle in radians for the current location. The sun angle is computed based on the current time and date set in the Helios context.

Definition at line 141 of file SolarPosition.cpp.

◆ isPragueSkyModelEnabled()

bool SolarPosition::isPragueSkyModelEnabled ( ) const

Check if Prague sky model is enabled.

Returns
True if Prague model has been enabled via enablePragueSkyModel()

Definition at line 1046 of file SolarPosition.cpp.

◆ pragueSkyModelNeedsUpdate()

bool SolarPosition::pragueSkyModelNeedsUpdate ( float  ground_albedo = 0.33f,
float  sun_tolerance = 0.01f,
float  turbidity_tolerance = 0.02f,
float  albedo_tolerance = 0.05f 
) const

Check if Prague sky model update is needed based on changed conditions.

Parameters
[in]ground_albedoCurrent ground albedo
[in]sun_toleranceThreshold for sun direction changes (default: 0.01 ≈ 0.57°)
[in]turbidity_toleranceRelative threshold for turbidity (default: 0.02 = 2%)
[in]albedo_toleranceThreshold for albedo changes (default: 0.05 = 5%)
Returns
True if updatePragueSkyModel() should be called
Note
This method enables lazy evaluation to avoid expensive Prague updates when conditions haven't changed significantly.
Reads turbidity from Context atmospheric conditions for comparison.

Definition at line 1123 of file SolarPosition.cpp.

◆ selfTest()

int SolarPosition::selfTest ( int  argc = 0,
char **  argv = nullptr 
)
static

Function to perform a self-test of model functions.

Definition at line 563 of file selfTest.cpp.

◆ setAtmosphericConditions()

void SolarPosition::setAtmosphericConditions ( float  pressure_Pa,
float  temperature_K,
float  humidity_rel,
float  turbidity 
)

Set atmospheric conditions globally in the Context.

Parameters
[in]pressure_PaAtmospheric pressure near ground surface in Pascals (must be > 0)
[in]temperature_KAir temperature near the ground surface in Kelvin (must be > 0)
[in]humidity_relAir relative humidity near the ground surface (must be between 0 and 1)
[in]turbidityÅngström's aerosol turbidity coefficient (β), representing aerosol optical depth (AOD) at 500 nm reference wavelength (must be >= 0). Typical values: 0.02 (very clear sky), 0.05 (clear sky), 0.1 (light haze), 0.2-0.3 (hazy), >0.4 (very hazy/polluted). Note: This is NOT Linke turbidity, which uses a different scale (typically 2-6).
Note
This method sets global data in the Context with labels: atmosphere_pressure_Pa, atmosphere_temperature_K, atmosphere_humidity_rel, atmosphere_turbidity
Input values are validated. Invalid values will throw helios_runtime_error.

Definition at line 446 of file SolarPosition.cpp.

◆ setSunDirection()

void SolarPosition::setSunDirection ( const helios::SphericalCoord sundirection)

Override solar position calculation based on time in the Context by using a prescribed solar position.

Parameters
[in]sundirectionSphericalCoord giving the direction of the sun

Definition at line 181 of file SolarPosition.cpp.

◆ updatePragueSkyModel()

void SolarPosition::updatePragueSkyModel ( float  ground_albedo = 0.33f)

Update Prague sky model and store spectral-angular parameters in Context.

Parameters
[in]ground_albedoGround reflectance [0-1] (default: 0.33 for vegetation)
Note
Must call after solar position changes or atmospheric conditions change.
Reads turbidity from Context atmospheric conditions (set via setAtmosphericConditions). If not set, uses default 0.02 (clear sky).
Computationally intensive (~1100 model queries with OpenMP parallelization). Use lazy evaluation via pragueSkyModelNeedsUpdate() to avoid unnecessary updates.
Stores the following in Context global data:
  • "prague_sky_spectral_params": vec<float> of size 1350 (225 wavelengths × 6 parameters)
  • "prague_sky_sun_direction": vec3 sun direction
  • "prague_sky_visibility_km": float visibility in km
  • "prague_sky_ground_albedo": float ground albedo
  • "prague_sky_valid": int validity flag (1=valid, 0=invalid)

Definition at line 1050 of file SolarPosition.cpp.


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