0
# Solar Position Calculation
1

2
Calculate precise solar position using multiple high-accuracy algorithms. Provides essential astronomical calculations for PV system modeling including solar zenith and azimuth angles, sunrise and sunset times, and solar transit calculations.
3

4
## Capabilities
5

6
### Main Solar Position Function
7

8
Calculate solar position using various algorithms with automatic method selection based on requirements.
9

10
```python { .api }
11
def get_solarposition(time, latitude, longitude, altitude=0, pressure=101325, 
12
                     temperature=12, method='nrel_numpy', **kwargs):
13
    """
14
    Calculate solar position using various algorithms.
15
    
16
    Parameters:
17
    - time: pandas.DatetimeIndex, times for calculation
18
    - latitude: float, decimal degrees north
19
    - longitude: float, decimal degrees east
20
    - altitude: float, meters above sea level
21
    - pressure: float, pascals atmospheric pressure
22
    - temperature: float, degrees C air temperature
23
    - method: str, calculation method ('nrel_numpy', 'nrel_c', 'pyephem', 'ephemeris')
24
    - **kwargs: additional method-specific parameters
25
    
26
    Returns:
27
    pandas.DataFrame with columns:
28
    - apparent_zenith: apparent solar zenith angle (degrees)
29
    - zenith: solar zenith angle (degrees)
30
    - apparent_elevation: apparent solar elevation angle (degrees)
31
    - elevation: solar elevation angle (degrees)
32
    - azimuth: solar azimuth angle (degrees)
33
    - equation_of_time: equation of time (minutes)
34
    """
35
```
36

37
### High-Precision SPA Algorithm
38

39
Solar Position Algorithm (SPA) providing highest accuracy solar position calculations.
40

41
```python { .api }
42
def spa_c(time, latitude, longitude, pressure=101325, altitude=0, 
43
         temperature=12, delta_t=67.0, numthreads=4, **kwargs):
44
    """
45
    Calculate solar position using SPA algorithm with C implementation.
46
    
47
    Parameters:
48
    - time: pandas.DatetimeIndex
49
    - latitude: float, decimal degrees
50
    - longitude: float, decimal degrees  
51
    - pressure: float, pascals
52
    - altitude: float, meters
53
    - temperature: float, degrees C
54
    - delta_t: float, difference between terrestrial time and UT1 (seconds)
55
    - numthreads: int, number of threads for parallel processing
56
    
57
    Returns:
58
    pandas.DataFrame with solar position data
59
    """
60

61
def spa_python(time, latitude, longitude, pressure=101325, altitude=0, 
62
              temperature=12, delta_t=67.0, numthreads=4, **kwargs):
63
    """
64
    Calculate solar position using SPA algorithm with Python implementation.
65
    
66
    Parameters:
67
    - time: pandas.DatetimeIndex
68
    - latitude: float, decimal degrees
69
    - longitude: float, decimal degrees
70
    - pressure: float, pascals
71
    - altitude: float, meters
72
    - temperature: float, degrees C
73
    - delta_t: float, difference between terrestrial time and UT1 (seconds)
74
    - numthreads: int, number of threads for parallel processing
75
    
76
    Returns:
77
    pandas.DataFrame with solar position data
78
    """
79
```
80

81
### PyEphem Algorithm
82

83
Solar position calculations using the PyEphem astronomical library.
84

85
```python { .api }
86
def pyephem(time, latitude, longitude, altitude=0, pressure=101325, 
87
           temperature=12, horizon='+0:00'):
88
    """
89
    Calculate solar position using PyEphem library.
90
    
91
    Parameters:
92
    - time: pandas.DatetimeIndex
93
    - latitude: float, decimal degrees
94
    - longitude: float, decimal degrees
95
    - altitude: float, meters
96
    - pressure: float, pascals
97
    - temperature: float, degrees C
98
    - horizon: str, horizon definition for rise/set calculations
99
    
100
    Returns:
101
    pandas.DataFrame with solar position data
102
    """
103
```
104

105
### Analytical Methods
106

107
Fast analytical solar position calculations for less demanding applications.
108

109
```python { .api }
110
def ephemeris(time, latitude, longitude, pressure=101325.0, temperature=12.0):
111
    """
112
    Calculate solar position using analytical ephemeris calculations.
113
    
114
    Parameters:
115
    - time: pandas.DatetimeIndex
116
    - latitude: float, decimal degrees
117
    - longitude: float, decimal degrees
118
    - pressure: float, pascals
119
    - temperature: float, degrees C
120
    
121
    Returns:
122
    pandas.DataFrame with solar position data
123
    """
124

125
def solar_zenith_analytical(latitude, hourangle, declination):
126
    """
127
    Calculate solar zenith angle analytically.
128
    
129
    Parameters:
130
    - latitude: numeric, decimal degrees
131
    - hourangle: numeric, hour angle in decimal degrees
132
    - declination: numeric, solar declination in decimal degrees
133
    
134
    Returns:
135
    numeric, solar zenith angle in degrees
136
    """
137

138
def solar_azimuth_analytical(latitude, hourangle, declination, zenith):
139
    """
140
    Calculate solar azimuth angle analytically.
141
    
142
    Parameters:
143
    - latitude: numeric, decimal degrees
144
    - hourangle: numeric, hour angle in decimal degrees
145
    - declination: numeric, solar declination in decimal degrees
146
    - zenith: numeric, solar zenith angle in degrees
147
    
148
    Returns:
149
    numeric, solar azimuth angle in degrees
150
    """
151
```
152

153
### Sunrise, Sunset, and Transit
154

155
Calculate sunrise, sunset, and solar transit times using various methods.
156

157
```python { .api }
158
def sun_rise_set_transit_spa(times, latitude, longitude, how='numpy', 
159
                            delta_t=67.0, numthreads=4):
160
    """
161
    Calculate sunrise, sunset, and transit using SPA algorithm.
162
    
163
    Parameters:
164
    - times: pandas.DatetimeIndex, dates for calculation
165
    - latitude: float, decimal degrees
166
    - longitude: float, decimal degrees
167
    - how: str, calculation method ('numpy', 'numba')
168
    - delta_t: float, seconds
169
    - numthreads: int, number of threads
170
    
171
    Returns:
172
    pandas.DataFrame with columns: sunrise, sunset, transit
173
    """
174

175
def sun_rise_set_transit_ephem(times, latitude, longitude, 
176
                              next_rising=False, next_setting=False, 
177
                              next_transit=False):
178
    """
179
    Calculate sunrise, sunset, and transit using PyEphem.
180
    
181
    Parameters:
182
    - times: pandas.DatetimeIndex
183
    - latitude: float, decimal degrees
184
    - longitude: float, decimal degrees
185
    - next_rising: bool, find next sunrise
186
    - next_setting: bool, find next sunset
187
    - next_transit: bool, find next transit
188
    
189
    Returns:
190
    pandas.DataFrame with columns: sunrise, sunset, transit
191
    """
192

193
def sun_rise_set_transit_geometric(times, latitude, longitude, declination, 
194
                                  equation_of_time):
195
    """
196
    Calculate sunrise, sunset, and transit using geometric approach.
197
    
198
    Parameters:
199
    - times: pandas.DatetimeIndex
200
    - latitude: float, decimal degrees
201
    - longitude: float, decimal degrees
202
    - declination: numeric, solar declination
203
    - equation_of_time: numeric, equation of time
204
    
205
    Returns:
206
    pandas.DataFrame with columns: sunrise, sunset, transit
207
    """
208
```
209

210
### Earth-Sun Distance
211

212
Calculate the distance between Earth and Sun for irradiance corrections.
213

214
```python { .api }
215
def nrel_earthsun_distance(time, how='numpy', delta_t=67.0, numthreads=4):
216
    """
217
    Calculate Earth-Sun distance using NREL algorithm.
218
    
219
    Parameters:
220
    - time: pandas.DatetimeIndex
221
    - how: str, calculation method ('numpy', 'numba')
222
    - delta_t: float, seconds
223
    - numthreads: int, number of threads
224
    
225
    Returns:
226
    pandas.Series, Earth-Sun distance in AU
227
    """
228

229
def pyephem_earthsun_distance(time):
230
    """
231
    Calculate Earth-Sun distance using PyEphem.
232
    
233
    Parameters:
234
    - time: pandas.DatetimeIndex
235
    
236
    Returns:
237
    pandas.Series, Earth-Sun distance in AU
238
    """
239
```
240

241
### Solar Declination and Equation of Time
242

243
Calculate fundamental solar parameters for position calculations.
244

245
```python { .api }
246
def declination_spencer71(dayofyear):
247
    """
248
    Calculate solar declination using Spencer 1971 formula.
249
    
250
    Parameters:
251
    - dayofyear: numeric, day of year (1-366)
252
    
253
    Returns:
254
    numeric, solar declination in degrees
255
    """
256

257
def declination_cooper69(dayofyear):
258
    """
259
    Calculate solar declination using Cooper 1969 formula.
260
    
261
    Parameters:
262
    - dayofyear: numeric, day of year (1-366)
263
    
264
    Returns:
265
    numeric, solar declination in degrees
266
    """
267

268
def equation_of_time_spencer71(dayofyear):
269
    """
270
    Calculate equation of time using Spencer 1971 formula.
271
    
272
    Parameters:
273
    - dayofyear: numeric, day of year (1-366)
274
    
275
    Returns:
276
    numeric, equation of time in minutes
277
    """
278

279
def equation_of_time_pvcdrom(dayofyear):
280
    """
281
    Calculate equation of time using PVCDROM formula.
282
    
283
    Parameters:
284
    - dayofyear: numeric, day of year (1-366)
285
    
286
    Returns:
287
    numeric, equation of time in minutes
288
    """
289
```
290

291
### Hour Angle Calculation
292

293
Calculate solar hour angle for position calculations.
294

295
```python { .api }
296
def hour_angle(times, longitude, equation_of_time):
297
    """
298
    Calculate solar hour angle.
299
    
300
    Parameters:
301
    - times: pandas.DatetimeIndex
302
    - longitude: numeric, decimal degrees east
303
    - equation_of_time: numeric, equation of time in minutes
304
    
305
    Returns:
306
    pandas.Series, hour angle in degrees
307
    """
308
```
309

310
## Usage Examples
311

312
### Basic Solar Position Calculation
313

314
```python
315
import pvlib
316
from pvlib import solarposition
317
import pandas as pd
318

319
# Define location and time range
320
latitude, longitude = 40.0583, -74.4057  # Princeton, NJ
321
times = pd.date_range('2023-06-21', periods=24, freq='H', tz='US/Eastern')
322

323
# Calculate solar position
324
solar_pos = solarposition.get_solarposition(times, latitude, longitude)
325
print(solar_pos[['elevation', 'azimuth']].head())
326
```
327

328
### High-Precision SPA Calculation
329

330
```python
331
import pvlib
332
from pvlib import solarposition
333
import pandas as pd
334

335
# Use SPA algorithm for highest precision
336
times = pd.date_range('2023-06-21 12:00', periods=1, tz='UTC')
337
latitude, longitude = 39.742, -105.178  # NREL, Golden, CO
338

339
solar_pos = solarposition.spa_c(
340
    times, latitude, longitude,
341
    pressure=82000,  # Pressure at altitude
342
    temperature=20,
343
    delta_t=67.0
344
)
345
print(f"Solar elevation: {solar_pos['elevation'].iloc[0]:.6f}°")
346
print(f"Solar azimuth: {solar_pos['azimuth'].iloc[0]:.6f}°")
347
```
348

349
### Sunrise, Sunset, and Transit Times
350

351
```python
352
import pvlib
353
from pvlib import solarposition
354
import pandas as pd
355

356
# Calculate sunrise/sunset for a week
357
dates = pd.date_range('2023-06-15', '2023-06-22', tz='US/Eastern')
358
latitude, longitude = 40.0583, -74.4057
359

360
sun_times = solarposition.sun_rise_set_transit_spa(
361
    dates, latitude, longitude
362
)
363

364
print(sun_times)
365
```