hefty 0.0.1__tar.gz

hefty-0.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Will Hobbs
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

hefty-0.0.1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: hefty
+Version: 0.0.1
+Summary: Some (relatively) lightweight short-term energy forecasting tools for solar, wind, and load.
+Author: Will Hobbs
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/williamhobbs/hefty
+Project-URL: Issues, https://github.com/williamhobbs/hefty/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: herbie-data[extras]>=2025.11.2
+Requires-Dist: pvlib>=0.13.1
+Dynamic: license-file
+
+# hEFTy
+Some (relatively) lightweight short-term **e**nergy **f**orecasting **t**ools for solar, wind, and load.
+
+This repository currently includes solar and wind tools, but may expand one day to include electric load. Forecasts can be created using the NOAA GFS, NOAA GEFS, NOAA HRRR, and ECMWF IFS and AIFS (open data versions) models. 
+
+For solar, look at the notebook [solar_example.ipynb](examples/solar_example.ipynb) for some examples, and [more_solar_examples.ipynb](examples/more_solar_examples.ipynb) for more examples. Both of these convert the resource forecasts to power.
+
+There are also solar ensemble forecasts demonstrated in [ensemble_example.ipynb](examples/ensemble_example.ipynb).
+
+For wind, look at the notebook [wind_example.ipynb](examples/wind_example.ipynb). The wind tools are not as developed at the solar tools.
+
+The [custom.py](src/hefty/custom.py) module is intended to help with getting forecasts of "custom" weather parameters, not necessarily specific to wind or solar, which migh be useful for load forecasting.
+
+## Quick examples
+
+Here's a quick example of getting a solar resource data forecast:
+
+```python
+from hefty.solar import get_solar_forecast
+
+latitude = 33.5
+longitude = -86.8
+init_date = '2024-06-05 6:00' # datetime the forecast model was initialized
+resource_data = get_solar_forecast(
+    latitude,
+    longitude,
+    init_date,
+    run_length=18, # 18 hours are included in the forecast
+    lead_time_to_start=3, # forecast starts 3 hours out from the init_date
+    model='hrrr', # use NOAA HRRR
+)
+resource_data[
+    ['ghi','dni','dhi','temp_air','wind_speed']
+              ].plot(drawstyle='steps-mid')
+```
+
+with this output:
+
+<img src="images/output.png" width="500"/>
+
+Here's a wind resource forecast:
+
+```python
+from hefty.wind import get_wind_forecast
+
+latitude = 33.5
+longitude = -86.8
+init_date = '2024-06-05 6:00' # datetime the forecast model was initialized
+resource_data = get_wind_forecast(
+    latitude,
+    longitude,
+    init_date,
+    run_length=18, # 18 hours are included in the forecast
+    lead_time_to_start=3, # forecast starts 3 hours out from the init_date
+    model='gfs', # use NOAA GFS
+)
+resource_data[
+    ['wind_speed_10m', 'wind_speed_80m',
+    'wind_speed_100m', 'temp_air_2m', 
+    'pressure_0m']
+    ].plot(secondary_y=['pressure_0m'], drawstyle='steps-mid')
+```
+with this output (note that pressure is on the secondary y-axis):
+
+<img src="images/output_wind.png" width="500"/>
+
+## Installation
+
+A virtual environment is strongly recommended. You can install from PyPi with:
+
+```
+pip install hefty
+```
+
+To run the example jupyter notebooks:
+
+```
+pip install jupyter
+```
+
+## References
+This project uses several Python packages, including pvlib, an open-source solar PV modeling package [1, 2], and Herbie [3, 4], a package for accessing weather forecast data from NOAA. `pv_model.py` (with the `model_pv_power()` function used here) comes from [5] which leverages some functions from [6].
+
+<img src="images/pvlib_powered_logo_horiz.png" width="200"/>
+
+
+[1] Anderson, K., Hansen, C., Holmgren, W., Jensen, A., Mikofski, M., and Driesse, A. “pvlib python: 2023 project update.” Journal of Open Source Software, 8(92), 5994, (2023). [DOI: 10.21105/joss.05994](http://dx.doi.org/10.21105/joss.05994).
+
+[2] https://github.com/pvlib/pvlib-python
+
+[3] Blaylock, B. K. (2025). Herbie: Retrieve Numerical Weather Prediction Model Data (Version 2025.3.1) [Computer software]. https://doi.org/10.5281/zenodo.4567540
+
+[4] https://github.com/blaylockbk/Herbie
+
+[5] https://github.com/williamhobbs/pv-system-model
+
+[6] Hobbs, W., Anderson, K., Mikofski, M., and Ghiz, M. "An approach to modeling linear and non-linear self-shading losses with pvlib." 2024 PV Performance Modeling Collaborative (PVPMC). https://github.com/williamhobbs/2024_pvpmc_self_shade 

hefty-0.0.1/README.md

@@ -0,0 +1,97 @@
+# hEFTy
+Some (relatively) lightweight short-term **e**nergy **f**orecasting **t**ools for solar, wind, and load.
+
+This repository currently includes solar and wind tools, but may expand one day to include electric load. Forecasts can be created using the NOAA GFS, NOAA GEFS, NOAA HRRR, and ECMWF IFS and AIFS (open data versions) models. 
+
+For solar, look at the notebook [solar_example.ipynb](examples/solar_example.ipynb) for some examples, and [more_solar_examples.ipynb](examples/more_solar_examples.ipynb) for more examples. Both of these convert the resource forecasts to power.
+
+There are also solar ensemble forecasts demonstrated in [ensemble_example.ipynb](examples/ensemble_example.ipynb).
+
+For wind, look at the notebook [wind_example.ipynb](examples/wind_example.ipynb). The wind tools are not as developed at the solar tools.
+
+The [custom.py](src/hefty/custom.py) module is intended to help with getting forecasts of "custom" weather parameters, not necessarily specific to wind or solar, which migh be useful for load forecasting.
+
+## Quick examples
+
+Here's a quick example of getting a solar resource data forecast:
+
+```python
+from hefty.solar import get_solar_forecast
+
+latitude = 33.5
+longitude = -86.8
+init_date = '2024-06-05 6:00' # datetime the forecast model was initialized
+resource_data = get_solar_forecast(
+    latitude,
+    longitude,
+    init_date,
+    run_length=18, # 18 hours are included in the forecast
+    lead_time_to_start=3, # forecast starts 3 hours out from the init_date
+    model='hrrr', # use NOAA HRRR
+)
+resource_data[
+    ['ghi','dni','dhi','temp_air','wind_speed']
+              ].plot(drawstyle='steps-mid')
+```
+
+with this output:
+
+<img src="images/output.png" width="500"/>
+
+Here's a wind resource forecast:
+
+```python
+from hefty.wind import get_wind_forecast
+
+latitude = 33.5
+longitude = -86.8
+init_date = '2024-06-05 6:00' # datetime the forecast model was initialized
+resource_data = get_wind_forecast(
+    latitude,
+    longitude,
+    init_date,
+    run_length=18, # 18 hours are included in the forecast
+    lead_time_to_start=3, # forecast starts 3 hours out from the init_date
+    model='gfs', # use NOAA GFS
+)
+resource_data[
+    ['wind_speed_10m', 'wind_speed_80m',
+    'wind_speed_100m', 'temp_air_2m', 
+    'pressure_0m']
+    ].plot(secondary_y=['pressure_0m'], drawstyle='steps-mid')
+```
+with this output (note that pressure is on the secondary y-axis):
+
+<img src="images/output_wind.png" width="500"/>
+
+## Installation
+
+A virtual environment is strongly recommended. You can install from PyPi with:
+
+```
+pip install hefty
+```
+
+To run the example jupyter notebooks:
+
+```
+pip install jupyter
+```
+
+## References
+This project uses several Python packages, including pvlib, an open-source solar PV modeling package [1, 2], and Herbie [3, 4], a package for accessing weather forecast data from NOAA. `pv_model.py` (with the `model_pv_power()` function used here) comes from [5] which leverages some functions from [6].
+
+<img src="images/pvlib_powered_logo_horiz.png" width="200"/>
+
+
+[1] Anderson, K., Hansen, C., Holmgren, W., Jensen, A., Mikofski, M., and Driesse, A. “pvlib python: 2023 project update.” Journal of Open Source Software, 8(92), 5994, (2023). [DOI: 10.21105/joss.05994](http://dx.doi.org/10.21105/joss.05994).
+
+[2] https://github.com/pvlib/pvlib-python
+
+[3] Blaylock, B. K. (2025). Herbie: Retrieve Numerical Weather Prediction Model Data (Version 2025.3.1) [Computer software]. https://doi.org/10.5281/zenodo.4567540
+
+[4] https://github.com/blaylockbk/Herbie
+
+[5] https://github.com/williamhobbs/pv-system-model
+
+[6] Hobbs, W., Anderson, K., Mikofski, M., and Ghiz, M. "An approach to modeling linear and non-linear self-shading losses with pvlib." 2024 PV Performance Modeling Collaborative (PVPMC). https://github.com/williamhobbs/2024_pvpmc_self_shade 

hefty-0.0.1/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hefty"
+version = "0.0.1"
+description = "Some (relatively) lightweight short-term energy forecasting tools for solar, wind, and load."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name="Will Hobbs" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "herbie-data[extras] >= 2025.11.2",
+    "pvlib >= 0.13.1",
+]
+license = "BSD-3-Clause"
+license-files = ["LICENSE*"]
+
+[project.urls]
+Homepage = "https://github.com/williamhobbs/hefty"
+Issues = "https://github.com/williamhobbs/hefty/issues"

hefty-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hefty-0.0.1/src/hefty/custom.py

@@ -0,0 +1,204 @@
+import numpy as np
+import pandas as pd
+import xarray as xr
+from herbie import Herbie, FastHerbie
+import time
+
+
+def get_custom_forecast(latitude, longitude, init_date, run_length,
+                        lead_time_to_start=0, period=3, model='gfs',
+                        product='pgrb2.0p25', search_str=':TMP:2 m above', 
+                        member=None, attempts=2, hrrr_hour_middle=True,
+                        hrrr_coursen_window=None, priority=None):
+    """
+    Get a custom forecast for one or several sites from one of several
+    NWPs. This function uses Herbie [1]_.
+
+    Parameters
+    ----------
+    latitude : float or list of floats
+        Latitude in decimal degrees. Positive north of equator, negative
+        to south.
+
+    longitude : float or list of floats
+        Longitude in decimal degrees. Positive east of prime meridian,
+        negative to west.
+
+    init_date : pandas-parsable datetime
+        Model initialization datetime.
+
+    run_length : int
+        Length of the forecast in hours - number of hours forecasted
+
+    search_str : string
+        regex search string for grib files. See [2]_ for more info.
+
+    lead_time_to_start : int, optional
+        Number of hours between init_date (initialization) and
+        the first forecasted interval. NOAA GFS data goes out
+        384 hours, so run_length + lead_time_to_start must be less
+        than or equal to 384.
+
+    model : string, default 'gfs'
+        Forecast model. Default is NOAA GFS ('gfs'), but can also be
+        ECMWF IFS ('ifs'), NOAA HRRR ('hrrr'), or NOAA GEFS ('gefs).
+
+    member: string or int
+        For models that are ensembles, pass an appropriate single member label.
+
+    attempts : int, optional
+        Number of times to try getting forecast data. The function will pause
+        for n^2 minutes after each n attempt, e.g., 1 min after the first
+        attempt, 4 minutes after the second, etc.
+
+    hrrr_hour_middle : bool, default True
+        If model is 'hrrr', setting this False keeps the forecast at the
+        native instantaneous top-of-hour format. True (default) shifts
+        the forecast to middle of the hour, more closely representing an
+        integrated hourly forecast that is centered in the middle of the
+        hour.
+
+    hrrr_coursen_window : int or None, default None
+        If model is 'hrrr', optional setting that is the x and y window size
+        for coarsening the xarray dataset, effectively applying spatial
+        smoothing to the HRRR model. The HRRR has a native resolution of
+        about 3 km, so a value of 10 results in approx. 30 x 30 km grid.
+
+    priority : list or string
+        List of model sources to get the data in the order of download
+        priority, or string for a single source. See Herbie docs.
+        Typical values would be 'aws' or 'google'.
+
+    Returns
+    -------
+    data : pandas.DataFrane
+        timeseries forecasted weather data
+
+    References
+    ----------
+
+    .. [1] `Blaylock, B. K. (YEAR). Herbie: Retrieve Numerical Weather
+       Prediction Model Data (Version 20xx.x.x) [Computer software].
+       <https://doi.org/10.5281/zenodo.4567540>`_
+    .. [2] <https://herbie.readthedocs.io/en/latest/user_guide/tutorial/search.html> # noqa
+    """
+
+# variable formatting
+    # if lat, lon are single values, convert to lists for pickpoints later
+    if type(latitude) is float or type(latitude) is int:
+        latitude = [latitude]
+        longitude = [longitude]
+    # convert init_date to datetime
+    init_date = pd.to_datetime(init_date)
+
+    # get model-specific Herbie inputs
+    date = init_date
+    fxx_max = run_length + lead_time_to_start
+    fxx_range = range(lead_time_to_start, fxx_max, period)
+
+    i = []
+    for fxx in fxx_range:
+        # get solar, 10m wind, and 2m temp data
+        # try n times based loosely on
+        # https://thingspython.wordpress.com/2021/12/05/how-to-try-something-n-times-in-python/
+        for attempts_remaining in reversed(range(attempts)):
+            attempt_num = attempts - attempts_remaining
+            try:
+                if attempt_num == 1:
+                    # try downloading
+                    ds = Herbie(
+                        date,
+                        model=model,
+                        product=product,
+                        fxx=fxx,
+                        member=member,
+                        priority=priority
+                        ).xarray(search_str)
+                else:
+                    # after first attempt, set overwrite=True to overwrite
+                    # partial files
+                    ds = Herbie(
+                        date,
+                        model=model,
+                        product=product,
+                        fxx=fxx,
+                        member=member,
+                        priority=priority
+                        ).xarray(search_str, overwrite=True)
+            except Exception:
+                if attempts_remaining:
+                    print('attempt ' + str(attempt_num) + ' failed, pause for '
+                          + str((attempt_num)**2) + ' min')
+                    time.sleep(60*(attempt_num)**2)
+            else:
+                break
+        else:
+            raise ValueError('download failed, ran out of attempts')
+
+        # merge - override avoids hight conflict between 2m temp and 10m wind
+        ds = xr.merge(ds, compat='override')
+        # calculate wind speed from u and v components
+        ds = ds.herbie.with_wind('both')
+
+        if model == 'hrrr' and hrrr_coursen_window is not None:
+            ds = ds.coarsen(x=hrrr_coursen_window,
+                            y=hrrr_coursen_window,
+                            boundary='trim').mean()
+
+        # use pick_points for single point or list of points
+        i.append(
+            ds.herbie.pick_points(
+                pd.DataFrame(
+                    {
+                        "latitude": latitude,
+                        "longitude": longitude,
+                    }
+                )
+            )
+        )
+    ts = xr.concat(i, dim="valid_time")  # concatenate
+
+    # convert to dataframe
+    df_temp = ts.to_dataframe()
+
+    # work through sites
+    dfs = {}  # empty list of dataframes
+    if type(latitude) is float or type(latitude) is int:
+        num_sites = 1
+    else:
+        num_sites = len(latitude)
+
+    for j in range(num_sites):
+        df = df_temp[df_temp.index.get_level_values('point') == j]
+        df = df.droplevel('point')
+
+        if model == 'hrrr' and hrrr_hour_middle is False:
+            # keep top of hour instantaneous HRRR convention
+            dfs[j] = df
+        else:
+            # 60min version of data, centered at bottom of the hour
+            # 1min interpolation, then 60min mean
+            df_60min = (
+                df
+                .resample('1min')
+                .interpolate()
+                .resample('60min').mean()
+            )
+            df_60min.index = df_60min.index + pd.Timedelta('30min')
+            dfs[j] = df_60min
+
+    # concatenate creating multiindex with keys of the list of point numbers
+    # assigned to 'point', reorder indices, and sort by valid_time
+    df_60min = (
+        pd.concat(dfs, keys=list(range(num_sites)), names=['point'])
+        .reorder_levels(["valid_time", "point"])
+        .sort_index(level='valid_time')
+    )
+
+    # set "point" index as a column
+    df_60min = df_60min.reset_index().set_index('valid_time')
+
+    # drop unneeded columns if they exist
+    # df_60min = df_60min.drop(['t2m', 'sdswrf'], axis=1, errors='ignore')
+
+    return df_60min