SolarPosition.h

Go to the documentation of this file.

 
#ifndef SOLARPOSITION
#define SOLARPOSITION
 
#include "Context.h"
#include <memory>
 
// Forward declaration is in PragueSkyModelInterface.h
#include "PragueSkyModelInterface.h"
 
class SolarPosition {
public:
 
    explicit SolarPosition(helios::Context *context_ptr);
 
 
    SolarPosition(float UTC_hrs, float latitude_deg, float longitude_deg, helios::Context *context_ptr);
 
    static int selfTest(int argc = 0, char **argv = nullptr);
 
    [[nodiscard]] helios::Time getSunriseTime() const;
 
    [[nodiscard]] helios::Time getSunsetTime() const;
 
    [[nodiscard]] float getSunElevation() const;
 
    [[nodiscard]] float getSunZenith() const;
 
    [[nodiscard]] float getSunAzimuth() const;
 
    [[nodiscard]] helios::vec3 getSunDirectionVector() const;
 
    [[nodiscard]] helios::SphericalCoord getSunDirectionSpherical() const;
 
 
    void setSunDirection(const helios::SphericalCoord &sundirection);
 
 
    [[deprecated("Use setAtmosphericConditions() and parameter-free getSolarFlux() instead")]] [[nodiscard]] float getSolarFlux(float pressure_Pa, float temperature_K, float humidity_rel, float turbidity) const;
 
 
    [[deprecated("Use setAtmosphericConditions() and parameter-free getSolarFluxPAR() instead")]] [[nodiscard]] float getSolarFluxPAR(float pressure_Pa, float temperature_K, float humidity_rel, float turbidity) const;
 
 
    [[deprecated("Use setAtmosphericConditions() and parameter-free getSolarFluxNIR() instead")]] [[nodiscard]] float getSolarFluxNIR(float pressure_Pa, float temperature_K, float humidity_rel, float turbidity) const;
 
 
    [[deprecated("Use setAtmosphericConditions() and parameter-free getDiffuseFraction() instead")]] [[nodiscard]] float getDiffuseFraction(float pressure_Pa, float temperature_K, float humidity_rel, float turbidity) const;
 
 
    [[deprecated("Use setAtmosphericConditions() and parameter-free getAmbientLongwaveFlux() instead")]] [[nodiscard]] float getAmbientLongwaveFlux(float temperature_K, float humidity_rel) const;
 
 
    [[nodiscard]] float calibrateTurbidityFromTimeseries(const std::string &timeseries_shortwave_flux_label_Wm2) const;
 
 
    void enableCloudCalibration(const std::string &timeseries_shortwave_flux_label_Wm2);
 
    void disableCloudCalibration();
 
 
    void setAtmosphericConditions(float pressure_Pa, float temperature_K, float humidity_rel, float turbidity);
 
 
    void getAtmosphericConditions(float &pressure_Pa, float &temperature_K, float &humidity_rel, float &turbidity) const;
 
 
    [[nodiscard]] float getSolarFlux() const;
 
 
    [[nodiscard]] float getSolarFluxPAR() const;
 
 
    [[nodiscard]] float getSolarFluxNIR() const;
 
 
    [[nodiscard]] float getDiffuseFraction() const;
 
 
    [[nodiscard]] float getAmbientLongwaveFlux() const;
 
 
    void calculateDirectSolarSpectrum(const std::string &label, float resolution_nm = 1.0f);
 
 
    void calculateDiffuseSolarSpectrum(const std::string &label, float resolution_nm = 1.0f);
 
 
    void calculateGlobalSolarSpectrum(const std::string &label, float resolution_nm = 1.0f);
 
    // ===== Prague Sky Model =====
 
 
    void enablePragueSkyModel();
 
 
    [[nodiscard]] bool isPragueSkyModelEnabled() const;
 
 
    void updatePragueSkyModel(float ground_albedo = 0.33f);
 
 
    [[nodiscard]] bool pragueSkyModelNeedsUpdate(float ground_albedo = 0.33f, float sun_tolerance = 0.01f, float turbidity_tolerance = 0.02f, float albedo_tolerance = 0.05f) const;
 
private:
    helios::Context *context;
 
    float UTC;
    float latitude;
    float longitude;
 
    bool issolarpositionoverridden = false;
    helios::SphericalCoord sun_direction;
 
    std::string cloudcalibrationlabel;
 
    // Prague Sky Model members
    std::unique_ptr<helios::PragueSkyModelInterface> prague_model;
    bool prague_enabled = false;
 
    // Cached values for Prague lazy evaluation
    helios::vec3 cached_sun_direction;
    float cached_turbidity = -1.0f;
    float cached_albedo = -1.0f;
 
    [[nodiscard]] helios::SphericalCoord calculateSunDirection(const helios::Time &time, const helios::Date &date) const;
 
    // Prague Sky Model helper methods
    void fitAngularParametersAtWavelength(float wavelength, float visibility_km, float albedo, const helios::vec3 &sun_dir, float &L_zenith, float &circ_str, float &circ_width, float &horiz_bright, float &normalization);
 
    [[nodiscard]] float fitCircumsolarWidth(float L1, float L2, float h1, float h2, float gamma1, float gamma2) const;
 
    [[nodiscard]] float computeAngularNormalization(float circ_str, float circ_width, float horiz_bright) const;
 
    [[nodiscard]] helios::vec3 rotateDirectionTowardZenith(const helios::vec3 &dir, float angle_rad) const;
 
    [[nodiscard]] helios::vec3 getDirectionAwayFromSun(const helios::vec3 &sun_dir, float zenith_angle_deg) const;
 
    void GueymardSolarModel(float pressure, float temperature, float humidity, float turbidity, float &Eb_PAR, float &Eb_NIR, float &fdiff) const;
 
    void applyCloudCalibration(float &R_calc_Wm2, float &fdiff_calc) const;
 
    static float turbidityResidualFunction(float turbidity, std::vector<float> &parameters, const void *a_solarpositionmodel);
 
    // ===== SSolar-GOA Spectral Solar Radiation Model =====
 
    struct SpectralData {
        std::vector<float> wavelengths_nm; // 300-2600 nm (2301 points)
        std::vector<float> toa_irradiance; // Top-of-atmosphere irradiance in W/m²/nm
        std::vector<float> h2o_coef; // Water vapor absorption coefficient
        std::vector<float> h2o_exp; // Water vapor absorption exponent
        std::vector<float> o3_xsec; // Ozone cross section in cm²/molecule
        std::vector<float> o2_coef; // Oxygen absorption coefficient
 
        void loadFromDirectory(const std::string &data_path);
 
        [[nodiscard]] static float interpolate(const std::vector<float> &x, const std::vector<float> &y, float x_val);
    };
 
    [[nodiscard]] float calculateGeometricFactor(int julian_day) const;
 
    void calculateRayleighTransmittance(const std::vector<float> &wavelengths_um, float mu0, float pressure_ratio, std::vector<float> &tdir, std::vector<float> &tglb, std::vector<float> &tdif, std::vector<float> &atm_albedo) const;
 
    void calculateAerosolTransmittance(const std::vector<float> &wavelengths_um, float mu0, float alpha, float beta, float w0, float g, std::vector<float> &tdir, std::vector<float> &tglb, std::vector<float> &tdif,
                                       std::vector<float> &atm_albedo) const;
 
    void calculateMixtureTransmittance(const std::vector<float> &wavelengths_um, float mu0, float pressure_Pa, float turbidity_beta, float angstrom_alpha, float aerosol_ssa, float aerosol_g, bool coupling, std::vector<float> &tglb,
                                       std::vector<float> &tdir, std::vector<float> &tdif, std::vector<float> &atm_albedo) const;
 
    void calculateWaterVaporTransmittance(const SpectralData &data, float mu0, float water_vapor_cm, std::vector<float> &transmittance) const;
 
    void calculateOzoneTransmittance(const SpectralData &data, float mu0, float ozone_DU, std::vector<float> &transmittance) const;
 
    void calculateOxygenTransmittance(const SpectralData &data, float mu0, std::vector<float> &transmittance) const;
 
    void calculateSpectralIrradianceComponents(std::vector<helios::vec2> &global_spectrum, std::vector<helios::vec2> &direct_spectrum, std::vector<helios::vec2> &diffuse_spectrum, float resolution_nm) const;
};
 
#endif