0
# Atmospheric Models
1

2
Model atmospheric effects including airmass calculations, precipitable water, aerosol optical depth, and atmospheric parameters essential for accurate irradiance and clear sky modeling.
3

4
## Capabilities
5

6
### Airmass Calculations
7

8
Calculate relative and absolute airmass using various models.
9

10
```python { .api }
11
def get_relative_airmass(zenith, model='kastenyoung1989'):
12
    """
13
    Calculate relative airmass.
14
    
15
    Parameters:
16
    - zenith: numeric, solar zenith angle in degrees
17
    - model: str, airmass model ('simple', 'kasten1966', 'kastenyoung1989', 
18
             'gueymard1993', 'young1994', 'pickering2002')
19
    
20
    Returns:
21
    numeric, relative airmass
22
    """
23

24
def get_absolute_airmass(airmass_relative, pressure=101325.0):
25
    """
26
    Calculate absolute airmass.
27
    
28
    Parameters:
29
    - airmass_relative: numeric, relative airmass
30
    - pressure: numeric, atmospheric pressure in pascals
31
    
32
    Returns:
33
    numeric, absolute airmass
34
    """
35
```
36

37
### Pressure and Altitude Conversions
38

39
Convert between atmospheric pressure and altitude.
40

41
```python { .api }
42
def pres2alt(pressure):
43
    """
44
    Convert atmospheric pressure to altitude.
45
    
46
    Parameters:
47
    - pressure: numeric, atmospheric pressure in pascals
48
    
49
    Returns:
50
    numeric, altitude in meters above sea level
51
    """
52

53
def alt2pres(altitude):
54
    """
55
    Convert altitude to atmospheric pressure.
56
    
57
    Parameters:
58
    - altitude: numeric, altitude in meters above sea level
59
    
60
    Returns:
61
    numeric, atmospheric pressure in pascals
62
    """
63
```
64

65
### Precipitable Water
66

67
Calculate precipitable water content in the atmosphere.
68

69
```python { .api }
70
def gueymard94_pw(temp_air, relative_humidity):
71
    """
72
    Calculate precipitable water using Gueymard 1994 formula.
73
    
74
    Parameters:
75
    - temp_air: numeric, air temperature in degrees C
76
    - relative_humidity: numeric, relative humidity (0-100)
77
    
78
    Returns:
79
    numeric, precipitable water in cm
80
    """
81
```
82

83
### Humidity Calculations
84

85
Convert between relative humidity and dew point temperature.
86

87
```python { .api }
88
def rh_from_tdew(temp_air, temp_dew, coeff=(6.112, 17.62, 243.12)):
89
    """
90
    Calculate relative humidity from dew point temperature.
91
    
92
    Parameters:
93
    - temp_air: numeric, air temperature in degrees C
94
    - temp_dew: numeric, dew point temperature in degrees C
95
    - coeff: tuple, coefficients for Magnus formula
96
    
97
    Returns:
98
    numeric, relative humidity (0-100)
99
    """
100

101
def tdew_from_rh(temp_air, relative_humidity, coeff=(6.112, 17.62, 243.12)):
102
    """
103
    Calculate dew point temperature from relative humidity.
104
    
105
    Parameters:
106
    - temp_air: numeric, air temperature in degrees C
107
    - relative_humidity: numeric, relative humidity (0-100)
108
    - coeff: tuple, coefficients for Magnus formula
109
    
110
    Returns:
111
    numeric, dew point temperature in degrees C
112
    """
113
```
114

115
### Aerosol Optical Depth
116

117
Calculate aerosol optical depth parameters.
118

119
```python { .api }
120
def bird_hulstrom80_aod_bb(aod380, aod500):
121
    """
122
    Calculate broadband aerosol optical depth using Bird-Hulstrom model.
123
    
124
    Parameters:
125
    - aod380: numeric, aerosol optical depth at 380 nm
126
    - aod500: numeric, aerosol optical depth at 500 nm
127
    
128
    Returns:
129
    numeric, broadband aerosol optical depth
130
    """
131

132
def angstrom_aod_at_lambda(aod0, lambda0, alpha=1.14, lambda1=700.0):
133
    """
134
    Calculate aerosol optical depth at specific wavelength using Angstrom formula.
135
    
136
    Parameters:
137
    - aod0: numeric, aerosol optical depth at reference wavelength
138
    - lambda0: numeric, reference wavelength in nm
139
    - alpha: numeric, Angstrom alpha parameter
140
    - lambda1: numeric, target wavelength in nm
141
    
142
    Returns:
143
    numeric, aerosol optical depth at target wavelength
144
    """
145

146
def angstrom_alpha(aod1, lambda1, aod2, lambda2):
147
    """
148
    Calculate Angstrom alpha parameter.
149
    
150
    Parameters:
151
    - aod1: numeric, aerosol optical depth at wavelength 1
152
    - lambda1: numeric, wavelength 1 in nm
153
    - aod2: numeric, aerosol optical depth at wavelength 2
154
    - lambda2: numeric, wavelength 2 in nm
155
    
156
    Returns:
157
    numeric, Angstrom alpha parameter
158
    """
159
```
160

161
### Linke Turbidity
162

163
Calculate Linke turbidity factor for clear sky modeling.
164

165
```python { .api }
166
def kasten96_lt(airmass_absolute, precipitable_water, aod_bb):
167
    """
168
    Calculate Linke turbidity factor using Kasten 1996 model.
169
    
170
    Parameters:
171
    - airmass_absolute: numeric, absolute airmass
172
    - precipitable_water: numeric, precipitable water in cm
173
    - aod_bb: numeric, broadband aerosol optical depth
174
    
175
    Returns:
176
    numeric, Linke turbidity factor
177
    """
178
```
179

180
### Wind Speed Modeling
181

182
Calculate wind speed at different heights using power law.
183

184
```python { .api }
185
def windspeed_powerlaw(wind_speed_reference, height_reference, 
186
                      height_target, alpha=0.14):
187
    """
188
    Calculate wind speed at different height using power law.
189
    
190
    Parameters:
191
    - wind_speed_reference: numeric, wind speed at reference height (m/s)
192
    - height_reference: numeric, reference height in meters
193
    - height_target: numeric, target height in meters
194
    - alpha: numeric, power law exponent
195
    
196
    Returns:
197
    numeric, wind speed at target height (m/s)
198
    """
199
```
200

201
## Constants
202

203
### Airmass Models
204

205
```python { .api }
206
APPARENT_ZENITH_MODELS = (
207
    'simple', 'kasten1966', 'kastenyoung1989', 'gueymard1993', 
208
    'young1994', 'pickering2002'
209
)
210

211
TRUE_ZENITH_MODELS = (
212
    'simple', 'kasten1966', 'kastenyoung1989', 'gueymard1993', 
213
    'young1994', 'pickering2002'
214
)
215

216
AIRMASS_MODELS = APPARENT_ZENITH_MODELS + TRUE_ZENITH_MODELS
217
```
218

219
### Surface Type Exponents
220

221
```python { .api }
222
HELLMANN_SURFACE_EXPONENTS = {
223
    'water': 0.10,
224
    'smooth': 0.13,
225
    'open': 0.16,
226
    'roughlyopen': 0.20,
227
    'rough': 0.25,
228
    'veryrough': 0.40,
229
    'closed': 0.60
230
}
231
```
232

233
## Usage Examples
234

235
### Basic Airmass Calculation
236

237
```python
238
import pvlib
239
from pvlib import atmosphere, solarposition
240
import pandas as pd
241

242
# Location and time
243
lat, lon = 40.0583, -74.4057
244
times = pd.date_range('2023-06-21 06:00', '2023-06-21 18:00', 
245
                     freq='H', tz='US/Eastern')
246

247
# Solar position
248
solar_pos = solarposition.get_solarposition(times, lat, lon)
249

250
# Calculate relative airmass
251
am_rel = atmosphere.get_relative_airmass(
252
    solar_pos['zenith'], 
253
    model='kastenyoung1989'
254
)
255

256
# Calculate absolute airmass (at sea level pressure)
257
am_abs = atmosphere.get_absolute_airmass(am_rel, pressure=101325)
258

259
print("Time, Zenith, Relative AM, Absolute AM")
260
for i in range(len(times)):
261
    print(f"{times[i].strftime('%H:%M')}, {solar_pos['zenith'].iloc[i]:.1f}°, "
262
          f"{am_rel.iloc[i]:.2f}, {am_abs.iloc[i]:.2f}")
263
```
264

265
### Precipitable Water Calculation
266

267
```python
268
import pvlib
269
from pvlib import atmosphere
270
import numpy as np
271

272
# Meteorological conditions
273
temp_air = 25  # degrees C
274
relative_humidity = 65  # percent
275

276
# Calculate precipitable water
277
pw = atmosphere.gueymard94_pw(temp_air, relative_humidity)
278
print(f"Precipitable water: {pw:.2f} cm")
279

280
# Array of conditions
281
temps = np.array([10, 15, 20, 25, 30, 35])
282
rh = np.array([40, 50, 60, 70, 80, 90])
283

284
pw_array = atmosphere.gueymard94_pw(temps, rh)
285
print("\nTemperature (°C), RH (%), PW (cm)")
286
for i in range(len(temps)):
287
    print(f"{temps[i]}, {rh[i]}, {pw_array[i]:.2f}")
288
```
289

290
### Aerosol Optical Depth Calculations
291

292
```python
293
import pvlib
294
from pvlib import atmosphere
295
import numpy as np
296

297
# Measured AOD values
298
aod380 = 0.25
299
aod500 = 0.15
300

301
# Calculate broadband AOD
302
aod_bb = atmosphere.bird_hulstrom80_aod_bb(aod380, aod500)
303
print(f"Broadband AOD: {aod_bb:.3f}")
304

305
# Calculate Angstrom alpha parameter
306
alpha = atmosphere.angstrom_alpha(aod380, 380, aod500, 500)
307
print(f"Angstrom alpha: {alpha:.3f}")
308

309
# Calculate AOD at different wavelengths
310
wavelengths = np.array([400, 550, 700, 900, 1020])
311
aod_spectrum = atmosphere.angstrom_aod_at_lambda(
312
    aod500, 500, alpha, wavelengths
313
)
314

315
print("\nWavelength (nm), AOD")
316
for i, wl in enumerate(wavelengths):
317
    print(f"{wl}, {aod_spectrum[i]:.3f}")
318
```
319

320
### Wind Speed Profile
321

322
```python
323
import pvlib
324
from pvlib import atmosphere
325
import numpy as np
326

327
# Reference wind speed at 10m height
328
wind_10m = 5.0  # m/s
329
ref_height = 10.0  # meters
330

331
# Target heights
332
heights = np.array([2, 5, 10, 20, 50, 100])
333

334
# Calculate wind speeds using power law
335
wind_speeds = atmosphere.windspeed_powerlaw(
336
    wind_10m, ref_height, heights, alpha=0.14
337
)
338

339
print("Height (m), Wind Speed (m/s)")
340
for i, h in enumerate(heights):
341
    print(f"{h}, {wind_speeds[i]:.2f}")
342
```
343

344
### Humidity Conversions
345

346
```python
347
import pvlib
348
from pvlib import atmosphere
349
import numpy as np
350

351
# Temperature and humidity data
352
temp_air = np.array([15, 20, 25, 30])
353
relative_humidity = np.array([60, 65, 70, 75])
354

355
# Calculate dew point temperatures
356
dew_points = atmosphere.tdew_from_rh(temp_air, relative_humidity)
357

358
print("Temp (°C), RH (%), Dew Point (°C)")
359
for i in range(len(temp_air)):
360
    print(f"{temp_air[i]}, {relative_humidity[i]}, {dew_points[i]:.1f}")
361

362
# Verify by calculating RH from dew point
363
rh_calc = atmosphere.rh_from_tdew(temp_air, dew_points)
364
print("\nVerification - calculated RH should match input:")
365
for i in range(len(temp_air)):
366
    print(f"Input: {relative_humidity[i]}%, Calculated: {rh_calc[i]:.1f}%")
367
```