Sun Position

Compute solar azimuth, elevation, and daily data-collection windows for any site, date, and elevation threshold.

Solar position and illumination timing.

Computes solar elevation thresholds and data collection windows.

Solar position is computed via the Skyfield library using JPL’s DE421 planetary ephemeris, which is bundled with hyplan at hyplan/data/de421.bsp so calculations work fully offline.

Sun references

Reda, I. and Andreas, A. (2004). Solar position algorithm for solar radiation applications. Solar Energy, 76(5), 577-589. doi:10.1016/j.solener.2003.12.003

Folkner, W. M., Williams, J. G., & Boggs, D. H. (2009). The Planetary and Lunar Ephemeris DE 421. JPL Interoffice Memorandum 343R-08-003, NASA Jet Propulsion Laboratory. https://ssd.jpl.nasa.gov/planets/eph_export.html

Rhodes, B. (2019). Skyfield: High precision research-grade positions for planets and Earth satellites generator. Astrophysics Source Code Library, ascl:1907.024.

sunpos(dt, latitude, longitude, elevation=0, radians=False)[source]

Compute solar azimuth and zenith via Skyfield.

Drop-in replacement for sunposition.sunpos covering the input shapes used in hyplan: scalar datetime + scalar lat/lon, pd.DatetimeIndex + scalar lat/lon, and arrays of datetimes + arrays of lat/lon (broadcast elementwise).

Parameters:

  • dt – Datetime(s). Naive datetimes are assumed UTC.

  • latitude – Latitude in degrees (scalar or array).

  • longitude – Longitude in degrees (scalar or array).

  • elevation – Elevation in meters above WGS-84 (scalar or array).

  • radians – If True, return values in radians; otherwise degrees.

Returns:

Tuple (azimuth, zenith, ra, dec, h) to mirror sunposition.sunpos. Only azimuth and zenith are populated; the remaining slots are arrays of NaN of matching shape, kept so that existing call sites can unpack with *_.

solar_threshold_times(latitude, longitude, start_date, end_date, thresholds, timezone_offset=0, timezone=None)[source]

Find times when the solar elevation crosses specified thresholds.

Parameters:

  • latitude (float) – Latitude of the location.

  • longitude (float) – Longitude of the location.

  • start_date (str) – Start date in ‘YYYY-MM-DD’ format.

  • end_date (str) – End date in ‘YYYY-MM-DD’ format.

  • thresholds (list) – List of 1 or 2 solar elevation thresholds in degrees (e.g., [35] or [35, 50]).

  • timezone_offset (int) – Fixed timezone offset from UTC in hours (e.g., -8 for PST, 1 for CET). Ignored if timezone is given.

  • timezone (str, optional) – IANA timezone name (e.g. "America/Los_Angeles"). When supplied, takes precedence over timezone_offset and is DST-aware — recommended for any date range that may cross a DST transition. Pair with hyplan.geometry.get_timezone() to look up the zone from a lat/lon.

Returns:

DataFrame with reordered columns: [‘Date’, ‘Rise_<lower>’, ‘Rise_<upper>’, ‘Set_<upper>’, ‘Set_<lower>’].

Return type:

pandas.DataFrame

solar_azimuth(latitude, longitude, dt, elevation=0)[source]

Return the solar azimuth (in degrees) at a given latitude, longitude, and datetime.

Parameters:

  • latitude (float) – Latitude of the location.

  • longitude (float) – Longitude of the location.

  • dt (datetime) – The datetime for which to calculate the solar azimuth. This should be in UTC.

  • elevation (float, optional) – Elevation to use in the sunpos calculation (default 0).

Returns:

Solar azimuth in degrees.

Return type:

float

solar_position_increments(latitude, longitude, date, min_elevation, timezone_offset=0, increment='10min', timezone=None)[source]

Return the solar azimuth and solar elevation at user-specified increments for a given date and location, but only for times when the solar elevation exceeds the specified minimum.

Parameters:

  • latitude (float) – Latitude of the location.

  • longitude (float) – Longitude of the location.

  • date (str or datetime.date) – Date in ‘YYYY-MM-DD’ format or as a date object.

  • min_elevation (float) – Minimum solar elevation (in degrees) required to include the time.

  • timezone_offset (int, optional) – Fixed timezone offset from UTC in hours (e.g., -8 for PST). Ignored if timezone is given. Default is 0.

  • increment (str, optional) – Frequency increment for sampling times (e.g., ‘10min’). Default is ‘10min’.

  • timezone (str, optional) – IANA timezone name (e.g. "America/Los_Angeles"). When supplied, takes precedence over timezone_offset and is DST-aware. Pair with hyplan.geometry.get_timezone() to look up the zone from a lat/lon.

Returns:

DataFrame with columns:

  • ’Time’: Local time (HH:MM:SS),

  • ’Solar Azimuth’: Solar azimuth in degrees,

  • ’Solar Elevation’: Solar elevation in degrees.

Return type:

pandas.DataFrame

plot_solar_positions(df_positions)[source]

Plot the solar azimuth and elevation for a given day.

Parameters:

df_positions (pd.DataFrame) – DataFrame containing the ‘Solar Azimuth’, ‘Time’, and ‘Elevation’ columns.

Return type:

None

Data and attribution

Solar position is computed via the Skyfield library using NASA JPL’s DE421 planetary ephemeris, which is bundled with hyplan at hyplan/data/de421.bsp so calculations work fully offline.

DE421 is in the public domain. Please cite:

Folkner, W. M., Williams, J. G., & Boggs, D. H. (2009). The Planetary and Lunar Ephemeris DE 421. JPL Interoffice Memorandum 343R-08-003, NASA Jet Propulsion Laboratory. https://ssd.jpl.nasa.gov/planets/eph_export.html

Rhodes, B. (2019). Skyfield: High precision research-grade positions for planets and Earth satellites generator. Astrophysics Source Code Library, ascl:1907.024.