Metadata-Version: 2.4
Name: solarradiation-calc
Version: 0.1.2
Summary: A Python package for calculating solar radiation on tilted surfaces with atmospheric effects modeling
Home-page: https://gitverse.ru/Sergei100/SolarRadiation.git
Author: Kurzanov S.
Author-email: "Kurzanov S." <srg100@list.ru>
License: MIT
Project-URL: Homepage, https://gitverse.ru/Sergei100/SolarRadiation.git
Project-URL: Repository, https://gitverse.ru/Sergei100/SolarRadiation.git
Project-URL: BugTracker, https://gitverse.ru/Sergei100/SolarRadiation/issues
Keywords: solar,radiation,energy,renewable,atmosphere,photovoltaics,solar-engineering
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

## SolarRadiation: Solar Radiation and Atmospheric Effects Calculation

A package for modeling solar radiation on tilted surfaces, taking atmospheric conditions into account. Includes:
- Geometric parameters of the Sun's position
- Atmospheric effects (direct/diffuse radiation)
- Atmospheric transmittance coefficients
- Climatic conditions

## Main Classes:
## 1. Solar (from Solar.py module)

Calculates the astronomical geometry of solar radiation without atmospheric effects (extraterrestrial radiation).
This class is designed to calculate the amount of energy received per hour (W·h) on a plate with area S (m²);
oriented at an angle (betta) to the horizon and with a horizontal angle measured from the southern direction (gamma = 0°).
For gamma angles not equal to zero:
0° < gamma < 180° - direction west;
-180° < gamma < 0° - direction east.
The plate is positioned at latitude (phi) and longitude (psi) given in decimal degrees according to the WGS84 system, where angles:
0° < psi < 180° - east longitude;
-180° < phi < 0° - west longitude;
0° < phi < 90° - north latitude;
-90° < phi < 0° - south latitude.
By default, coordinates "phi = 56.17, psi = 37.94" are set, corresponding to the location of Moscow.
Additionally, it is possible to reassign the solar constant value G_sc = 1353 W·m⁻².

### Key Methods:
- gradus() - conversion of degrees/minutes/seconds to decimal degrees;
- delta() - solar declination angle;
- cos_Teta_hour() - zenith angle of ray incidence;
- omega() - hour angle corrected for orbital ellipticity;
- omega_s() - sunset angle;
- I_o() - extraterrestrial radiation;
- R_b() - geometric factor for tilted surfaces.

### Usage Example:
    from SolarRadiation import Solar, panel_or

    panel_1 = Solar(phi = 56.17, psi = 37.94, betta = 30, gamma=0, S = 1)
    date = '2025-05-09'
    print(f'Lw={panel_1.Lw}°; Le={panel_1.Le}°; Lst={panel_1.Lst}°;')
    print('n=', panel_1.n(date), 'days')
    print('δ=', panel_1.delta(date), '°')
    print('ω=', panel_1.omega(16, date), '°')
    print('ω_s=', panel_1.omega_s(date), '°')
    print('cosΘ=', panel_1.cos_Teta_hour(17, date))
    print('cosΘ_z=', panel_1.cos_Teta_hour_z(17, date))
    print('R_b=', panel_1.R_b(17, date))
    print('I_o=', panel_1.I_o(17, date, panel_or.inclinely), 'W·h')
    print('I_on=', panel_1.I_o(17, date, panel_or.normally), 'W·h')
    print('I_oz=', panel_1.I_o(17, date, panel_or.horizontally), 'W·h')

### Result:

    Lw=322.06°; Le=37.94°; Lst=315.0°;
    n= 128 days
    δ= 16.969452698039134 °
    ω= 53.86984592310928 °
    ω_s= 107.96328118409826 °
    cosΘ= 0.4381690047990296
    cosΘ_z= 0.43440402450071725
    R_b= 1.0086670014225574
    I_o= 581.2753381698951 W·h
    I_on= 1326.600767748286 W·h
    I_oz= 576.2807124155968 W·h

### Auxiliary Methods:
- gradus(grd, mm, ss) - conversion of degrees/minutes/seconds to decimal degrees.    gradus(55, 30, 0) → 55.5
- desgrads("degrees°minutes'seconds"") - conversion from string type to decimal degrees gradus("55°30'00"") → 55.5


## 2. AtmosphereI (from Atmosphere.py module)
Calculation of the astronomical geometry of solar radiation based on the clear sky model, taking atmospheric effects into account.
This class is designed to calculate the amount of energy received per hour (W·h) on a plate with area S (m²) as a sum of factors.
The sum of factors includes direct radiation taking into account atmospheric transmittance (transparency) on the tilted surface;
scattered radiation on the horizontal surface; diffuse reflection for total solar radiation.
The AtmosphereI class inherits from the Solar class and contains the same constructor attributes.
An additional attribute that should be set is the altitude of the plate above sea level (altitude),
default value is 134m (for Moscow).

### Key Methods:
- I_bz() - amount of energy (W·h) received from solar radiation taking into account atmospheric transmittance (transparency) for direct
radiation on a horizontal surface over 1 hour. Depends on climate_type;
- I_d() - amount of diffuse solar energy (W·h) on a horizontal surface over 1 hour;
- Hd_per_H() - fraction of diffuse radiation according to the Liu and Jordan method
        [1,4] for the period from May to August; for other months according to
        the Holland and Orgill method [1].
- r_d() - ratio of the hourly sum of diffuse radiation to the daily sum of diffuse
        radiation as a function of time and day length;
- I_d_today() - Returns the amount of diffuse solar energy on a horizontal
        surface over 1 hour (contains a random number generator for distribution operation);
- I_T() - calculates the sum of total solar radiation (W·h) on a tilted surface over 1 hour.
The sum includes direct radiation taking into account atmospheric transmittance (transparency) on the tilted surface;
diffuse radiation on the horizontal surface; diffuse reflection for total solar radiation.

### Transmittance Coefficients:
- tau_al() - light transmittance coefficient through the atmosphere - coefficient accounting for scattering on liquid droplets and dust particles,
as well as the path length of rays through the atmosphere. Calculation is based on the Ångström turbidity equation;
- tau_b() - for direct solar radiation taking into account atmospheric transmittance (transparency). Used in I_T() calculation.
Depends on climate_type;
- tau_d() - for diffuse radiation on a horizontal surface. Used in I_T() calculation;

### Modeling for different climate types (climate_type)[5]:
 
    from SolarRadiation import climate_type

- * trop - tropical;
- * temp_s/ temp_w - temperate summer/winter;
- * subar_s - subarctic summer.

### Usage Example:
    from SolarRadiation import AtmosphereI, climate_type

    panel_2 = AtmosphereI(phi = 56.17, psi = 37.94, betta = 30, gamma=0, S = 1, altitude=134)

    date = '2025-05-09'
    print('cosΘ =', panel_2.cos_Teta_hour(17, date))
    print('τ_αλ =', panel_2.tau_al(17, date, β_t=0.35, lam=0.55, h_altitude=134, α=1.3))
    print('τ_b =', panel_2.tau_b(13, date, 134, climate_type.temp_w))
    print('I_bz =', panel_2.I_bz(13, date, 134, climate_type.temp_w), 'W·h')
    print('τ_d =', panel_2.tau_d(13, date, 134, climate_type.temp_w))
    print('I_d =', panel_2.I_d(13, date, 134, climate_type.temp_w), 'W·h')

    K_T = random.random()
    print('K_T =', K_T)
    print('Hd_per_Ho =', panel_2.Hd_per_H(date, K_T))
    print('r_d =', panel_2.r_d(13, date))
    print('I_d_today =', panel_2.I_d_today(13, date), 'W·h')
    print('I_T =', panel_2.I_T(13, date, climate_type.temp_w, rho_g=0.6), 'W·h')

### Result:

    cosΘ = 0.4381690047990296
    τ_αλ = 0.17330879892046772
    τ_b = 0.3602711506795149
    I_bz = 367.32748640749026 W·h
    τ_d = 0.16508028170022265
    I_d = 168.313573867937 W·h
    K_T = 0.8784859477050895
    Hd_per_Ho = 0.175
    r_d = 0.1765188614939998
    I_d_today = 1895.658582826973 W·h
    I_T = 2326.509227393544 W·h

### Methods are based on:
Duffie-Beckman model (Solar Engineering of Thermal Processes);
Ångström turbidity equation;
Hoyt climatic coefficients.

Source URL: https://gitverse.ru/Sergei100/SolarRadiation

## Project Structure:

    SolarRadiation/
    ├── src/
    │   └── solarradiation/       # Main package
    │       ├── __init__.py
    │       ├── Solar.py
    │       └── Atmosphere.py
    ├── solarradiation-examples/  # Usage examples
    │   ├── exmpl_atmosphere.py
    │   ├── exmpl_solar.py
    │   └── exmpl_UTS.py
    ├── tests/                 # Tests
    │   ├── __init__.py
    │   ├── test_all.py
    │   ├── test_Atmosphere.py
    │   └── test_Solar.py
    ├── pyproject.toml         # Modern configuration
    ├── setup.py               # Legacy configuration (optional)
    ├── LICENSE.txt
    └── README.md

## Literature Sources:
1) [Мотулевич] - В.П.Мотулевич, Н.В.Калинин, А.Г.Спиридонов, В.В.Кухарцев, А.Н.Ратников 
        Солнечное тепло- и хладоснабжение и ветроэнергетические установки: методическое 
        пособие по курсу «Нетрадиционные и возобновляемые источники энергии». 
        Направление «Теплоэнергетика». М.: Издательство МЭИ, 2006. - 68 с. //
        V.P.Motulevich, N.V.Kalinin, A.G.Spiridonov, V.V.Kukhartsev, A.N.Ratnikov
        Solar Heating and Cooling and Wind Power Plants: methodological
        guide for the course "Non-traditional and Renewable Energy Sources".
        Direction "Thermal Power Engineering". M.: MPEI Publishing House, 2006. - 68 p.

2) [Даффи] - Даффи Дж. Бекман У. Основы солнечной теплоэнергетики, . —
        Долгопрудный: ИД Интеллект, 2013. —  889 с., ISBN 978-5-91559-141-6. // 
        Duffie J., Beckman W. Fundamentals of Solar Thermal Engineering.
        Dolgoprudny: Intellect Publishing House, 2013. - 889 p., ISBN 978-5-91559-141-6. https://viewer.rusneb.ru/ru/000199_000009_012697332?page=33&rotate=0&theme=white

3) [Duffie] - Duffie, J.A. and Beckman, W.A. (2013) Solar Engineering of Thermal Processes.
        4th Edition, John Wiley & Sons, New York. https://doi.org/10.1002/9781118671603

4) [Дуников] - Дуников Д.О. Возобновляемые источники энергии. Введение в солнечную энергетику: 
        учеб, пособие / Д.О. Дуников. - М.: Издательство МЭИ, 2021. 99 с. //
        Dunikov D.O. Renewable Energy Sources. Introduction to Solar Energy:
        textbook, manual / D.O. Dunikov. - M.: MPEI Publishing House, 2021. 99 p.

5) [Hoyt] - A simple model for estimating the transmittance of direct solar
       radiation through clear atmospheres. Hoyt C. Hottel
