dwind 0.3__py3-none-any.whl

dwind/__init__.py

@@ -0,0 +1,3 @@
+from .config import Configuration
+
+__version__ = "0.3"

dwind/btm_sizing.py

@@ -0,0 +1,129 @@
+"""Provides the behind the meter sizing methods."""
+
+import logging
+
+import numpy as np
+import pandas as pd
+
+from dwind import Configuration, helper
+
+
+log = logging.getLogger("dwfs")
+
+
+def sizer(agents: pd.DataFrame, config: Configuration):
+    """Finalize system sizes.
+    Calculates BTM system sizes.
+    Evaluates wind first to downselect to a single row.
+    """
+
+    def find_optimal_size(row):
+        techpot = row["wind_size_kw_fom"]
+        height = row["turbine_height_m"]
+        load_kwh = row["load_kwh"]
+        naep = row["wind_naep"]
+        instances = row["turbine_instances"]
+
+        # set the target kwh according to NEM availability
+        target_kwh = load_kwh * config.btm.SYS_SIZE_TARGET_NO_NEM
+        # also set the oversize limit according to NEM availability
+        oversize_limit_kwh = load_kwh * config.btm.SYS_OVERSIZE_LIMIT_NO_NEM
+
+        # save techpot system sizes - equal to FOM size for wind
+        # NOTE: techpot sizes are NOT constrained by config-supplied system size limits
+        row["wind_size_kw_techpot"] = techpot
+
+        # find the optimal btm system size according to 'wind_size_kw_techpot'
+        sizes = [2.5, 5, 10, 20, 50, 100, 250, 500, 750, 1000, 1500]
+
+        aep_btm = {}
+        scoe_btm = {}
+
+        for size in sizes:
+            if size <= techpot:
+                # calculate the system generation from naep and kw size
+                aep = size * naep
+
+                # calculate scoe
+                scoe = np.absolute(aep - target_kwh)
+
+                aep_btm[size] = aep
+                scoe_btm[size] = scoe
+
+                # handle special cases
+                # buildings requiring more electricity than can be generated by the largest turbine
+                # (1.5 MW) return very low rank score and the optimal continuous number of turbines
+                if size == 1500 and aep < target_kwh:
+                    scoe_btm[size] = 0.0
+
+                # identify oversized projects and zero production turbines
+                # where either condition is true, set a high score and zero turbines
+                if aep > oversize_limit_kwh or aep == 0:
+                    scoe_btm[size] = np.array([1e8]) + size * 100 + height
+
+        # for each agent, find the optimal turbine
+        optimal_size = min(scoe_btm, key=scoe_btm.get)
+        optimal_aep = aep_btm[optimal_size]
+
+        # handle BTM max system sizes
+        max_size = config.siting.wind.max_btm_size_kw
+        if optimal_size > max_size:
+            optimal_size = max_size
+            optimal_aep = naep * optimal_size
+
+        row["wind_size_kw_btm"] = optimal_size * instances
+        row["wind_turbine_kw_btm"] = optimal_size
+        row["wind_aep_btm"] = optimal_aep
+
+        return row
+
+    try:
+        if "wind" in config.project.settings.TECHS:
+            agents = agents.apply(find_optimal_size, axis=1)
+
+            # drop columns to avoid duplicates in full dataframe
+            # and get rid of unnecessary/intermediate columns
+            agents.drop(columns=["wind_turbine_kw", "wind_size_kw"], inplace=True, errors="ignore")
+            agents.drop_duplicates(subset=["gid"], inplace=True)
+
+        if "solar" in config.project.settings.TECHS:
+            # max system size is either load-limited or roof-limited
+            # (already calculated as 'solar_size_kw')
+            solar_map = config.siting.solar.capacity_density_kw_per_sqft
+            agents["pv_kw_per_sqft"] = agents["sector_abbr"].map(solar_map)
+            agents["solar_size_kw_btm"] = np.minimum(
+                agents["load_kwh"] / agents["solar_naep"],
+                agents["developable_roof_sqft"] * agents["pv_kw_per_sqft"],
+            )
+            agents["solar_aep_btm"] = agents["solar_size_kw_btm"] * agents["solar_naep"]
+
+            # handle BTM max system sizes
+            max_size = config.siting.solar.max_btm_size_kw
+            solar_size_limit_mask = agents["solar_size_kw_btm"] > max_size
+            agents.loc[solar_size_limit_mask, "solar_size_kw_btm"] = max_size
+            agents.loc[solar_size_limit_mask, "solar_aep_btm"] = (
+                agents["solar_naep"] * agents["solar_size_kw_btm"]
+            )
+
+            # save techpot system sizes - equal to roof-constrained size for solar
+            # NOTE: techpot sizes are NOT constrained by config-supplied system size limits
+            agents["solar_size_kw_techpot"] = (
+                agents["developable_roof_sqft"] * agents["pv_kw_per_sqft"]
+            )
+
+            # drop columns to avoid duplicates in full dataframe
+            # and get rid of unnecessary/intermediate columns
+            agents.drop(columns=["pv_kw_per_sqft"], inplace=True, errors="ignore")
+            agents.drop_duplicates(subset=["gid"], inplace=True)
+
+        # make small
+        agents = helper.memory_downcaster(agents)
+
+        return agents
+
+    except Exception as e:
+        log.exception(e)
+        log.info("\n")
+        log.info("BTM sizing failed")
+
+        return pd.DataFrame()

dwind/config.py

@@ -0,0 +1,118 @@
+"""Custom configuration data class to allow for dictionary style and dot notation calling of
+attributes.
+"""
+
+import re
+import tomllib
+from pathlib import Path
+
+
+class Mapping(dict):
+    """Dict-like class that allows for the use of dictionary style attribute calls on class
+    attributes.
+    """
+
+    def __setitem__(self, key, item):
+        self.__dict__[key] = item
+
+    def __getitem__(self, key):
+        return self.__dict__[key]
+
+    def __repr__(self):
+        return repr(self.__dict__)
+
+    def __len__(self):
+        return len(self.__dict__)
+
+    def __delitem__(self, key):
+        del self.__dict__[key]
+
+    def clear(self):
+        return self.__dict__.clear()
+
+    def copy(self):
+        return self.__dict__.copy()
+
+    def update(self, *args, **kwargs):
+        return self.__dict__.update(*args, **kwargs)
+
+    def keys(self):
+        return self.__dict__.keys()
+
+    def values(self):
+        return self.__dict__.values()
+
+    def items(self):
+        return self.__dict__.items()
+
+    def pop(self, *args):
+        return self.__dict__.pop(*args)
+
+    def __cmp__(self, dict_):
+        return self.__cmp__(self.__dict__, dict_)
+
+    def __contains__(self, item):
+        return item in self.__dict__
+
+    def __iter__(self):
+        return iter(self.__dict__)
+
+
+class Configuration(Mapping):
+    """Configuration class for reading and converting nested dictionaries to allow for both
+    namespace style and dot notation when collecting attributes.
+
+    Customizations of the input data:
+      - All fields containing "DIR" will be converted to a ``pathlib.Path`` object.
+      - All nested data will be able to be called with dot notation and dictionary-style calls.
+      - The `rev.turbine_class_dict` is converted to float data automatically.
+      - All data in the `[sql]` section will get converted to proper constructor strings with the
+        associated username and password data autopopulated with the match ``{USER}`` and
+        ``PASSWORD`` fields in the same configuration section.
+    """
+
+    def __init__(self, config: str | Path | dict, *, initial: bool = True):
+        """Create a hybrid dictionary and name space object for a given :py:attr:`config` and
+        where all keys (including nested) are acessible with dictionary-style and dot notation.
+
+        Args:
+            config (str | Path | dict): A configuration dictionary or filename to the dictionary
+                to read and convert. If passing a filename, it must be a TOML file.
+            initial (bool, optional): Option to disable post-processing of configuration data.
+        """
+        if isinstance(config, str | Path):
+            config = Path(config).resolve()
+            with config.open("rb") as f:
+                config = tomllib.load(f)
+
+        for key, value in config.items():
+            if isinstance(value, dict):
+                self.__setattr__(key, Configuration(value, initial=False))
+            else:
+                if "DIR" in key:
+                    self.__setattr__(key, Path(value).resolve())
+                else:
+                    self.__setattr__(key, value)
+
+        if initial:
+            self._convert_sql()
+            self._convert_rev()
+
+    def _convert_sql(self):
+        """Replaces the "{USER}" and "{PASSWORD} portions of the sql constructor strings with
+        the actual user and password information for ease of configuration reuse between users.
+        """
+        if "sql" in self:
+            for key, value in self.sql.items():
+                if key.startswith(("USER", "PASSWORD")):
+                    continue
+                for target in re.findall(r"\{(.*?)\}", value):
+                    value = value.replace(target, self.sql[target])
+                value = re.sub("[{}]", "", value)
+                self.sql[key] = value
+
+    def _convert_rev(self):
+        if "rev" in self:
+            self.rev.turbine_class_dict = {
+                float(k): v for k, v in self.rev.turbine_class_dict.items()
+            }

dwind/helper.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def memory_downcaster(df):
+    assert isinstance(df, pd.DataFrame) | isinstance(df, pd.Series)
+
+    NAlist = []
+    for col in df.select_dtypes(include=[np.number]).columns:
+        IsInt = False
+        mx = df[col].max()
+        mn = df[col].min()
+
+        # integer does not support na; fill na
+        if not np.isfinite(df[col]).all():
+            NAlist.append(col)
+            df[col].fillna(mn - 1, inplace=True)
+
+        # test if column can be converted to an integer
+        asint = df[col].fillna(0).astype(np.int64)
+        result = df[col] - asint
+        result = result.sum()
+        if result > -0.01 and result < 0.01:
+            IsInt = True
+
+        # make integer/unsigned integer datatypes
+        if IsInt:
+            try:
+                if mn >= 0:
+                    if mx < 255:
+                        df[col] = df[col].astype(np.uint8)
+                    elif mx < 65535:
+                        df[col] = df[col].astype(np.uint16)
+                    elif mx < 4294967295:
+                        df[col] = df[col].astype(np.uint32)
+                    else:
+                        df[col] = df[col].astype(np.uint64)
+                else:
+                    if mn > np.iinfo(np.int8).min and mx < np.iinfo(np.int8).max:
+                        df[col] = df[col].astype(np.int8)
+                    elif mn > np.iinfo(np.int16).min and mx < np.iinfo(np.int16).max:
+                        df[col] = df[col].astype(np.int16)
+                    elif mn > np.iinfo(np.int32).min and mx < np.iinfo(np.int32).max:
+                        df[col] = df[col].astype(np.int32)
+                    elif mn > np.iinfo(np.int64).min and mx < np.iinfo(np.int64).max:
+                        df[col] = df[col].astype(np.int64)
+            except:  # noqa: E722
+                df[col] = df[col].astype(np.float32)
+
+        # make float datatypes 32 bit
+        else:
+            df[col] = df[col].astype(np.float32)
+
+    return df
+
+
+def interpolate_array(row, col_1, col_2, col_in, col_out):
+    if row[col_in] != 0:
+        interpolated = row[col_in] * (row[col_2] - row[col_1]) + row[col_1]
+    else:
+        interpolated = row[col_1]
+
+    row[col_out] = interpolated
+
+    return row
+
+
+def scale_array_precision(df: pd.DataFrame, hourly_col: str, prec_offset_col: str):
+    """Scales the precision of :py:attr:`hourly_col` by the :py:attr:`prec_offset_col`.
+
+    Args:
+        df (pd.DataFrame): A Pandas DataFrame containing :py:att:`hourly_col` and
+            :py:att:`prec_offset_col`.
+        hourly_col (str) The column to adjust the precision.
+        prec_offset_col (str): The column for scaling the precison of :py:attr:`hourly_col`.
+
+    Returns:
+        pd.DataFrame: The input :py:attr:`df` with the precision of :py:attr:`hourly_col` scaled.
+    """
+    df[hourly_col] = (
+        np.array(df[hourly_col].values.tolist(), dtype="float64")
+        / df[prec_offset_col].values.reshape(-1, 1)
+    ).tolist()
+    return df
+
+
+def scale_array_deprecision(df: pd.DataFrame, col: str | list[str]) -> pd.DataFrame:
+    """Rounds the column(s) :py:attr:`col` to the nearest 2nd decimal and converts to NumPy's
+    float32.
+
+    Args:
+        df (pd.DataFrame): A Pandas DataFrame containing :py:att:`col`.
+        col (str | list[str]): The column(s) to have reduced precision.
+
+    Returns:
+        pd.DataFrame: The input :py:attr:`df` with the precision of :py:attr:`col` lowered.
+    """
+    df[col] = np.round(np.round(df[col], 2).astype(np.float32), 2)
+    return df
+
+
+def scale_array_sum(df: pd.DataFrame, hourly_col: str, scale_col: str) -> pd.DataFrame:
+    """Scales the :py:attr:`hourly_col` by its sum and multiples by the :py:attr:`scale_col`.
+
+    Args:
+        df (pd.DataFrame): Pandas DataFrame containing the :py:attr:`hourly_col` and
+            :py:attr:`scale_col`.
+        hourly_col (str): The name of the column to be scaled whose values are lists.
+        scale_col (str): The column to scale the :py:attr:`hourly_col`.
+
+    Returns:
+        pandas.DataFrame: The input dataframe, but with the values of the :py:attr:`hourly_col`
+            scaled appropriately.
+    """
+    hourly_array = np.array(df[hourly_col].values.tolist())
+    df[hourly_col] = (
+        hourly_array / hourly_array.sum(axis=1).reshape(-1, 1) * df[scale_col].values.reshape(-1, 1)
+    ).tolist()
+    return df
+
+
+def scale_array_multiplier(
+    df: pd.DataFrame, hourly_col: str, multiplier_col: str, col_out: str
+) -> pd.DataFrame:
+    """Scales the :py:attr:hourly_col` values by the :py:attr:`multiplier_col`, and places it in
+    the :py:attr:`col_out`.
+
+    Args:
+        df (pd.DataFrame): The Pandas DataFrame containing the :py:attr:`hourly_col` and
+            :py:attr:`multiplier_col`.
+        hourly_col (str): A column of hourly values as a list of floats in each cell.
+        multiplier_col (str): The column used to scale the :py:attr:`hourly_col`.
+        col_out (str): A new column that will contain the scaled data.
+
+    Returns:
+        pd.DataFrame: A new copy of the original data (:py:attr:`df`) containing the
+            :py:attr:`col_out` column.
+    """
+    hourly_array = np.array(df[hourly_col].values.tolist())
+    df[col_out] = (hourly_array * df[multiplier_col].values.reshape(-1, 1)).tolist()
+    return df
+
+
+def split_by_index(
+    arr: pd.DataFrame | np.ndarray | pd.Series, n_splits: int
+) -> tuple[np.ndarray, np.ndarray]:
+    """Split a DataFrame, Series, or array like with np.array_split, but only return the start and
+    stop indices, rather than chunks. For Pandas objects, this are equivalent to
+    ``arr.iloc[start: end]`` and for NumPy: ``arr[start: end]``. Splits are done according
+    to the 0th dimension.
+
+    Args:
+        arr(pd.DataFrame | pd.Series | np.ndarray): The array, data frame, or series to split.
+        n_splits(:obj:`int`): The number of near equal or equal splits.
+
+    Returns:
+        tuple[np.ndarray, np.ndarray]
+    """
+    size = arr.shape[0]
+    base = np.arange(n_splits)
+    split_size = size // n_splits
+    extra = size % n_splits
+
+    starts = base * split_size
+    ends = starts + split_size
+
+    for i in range(extra):
+        ends[i:] += 1
+        starts[i + 1 :] += 1
+    return starts, ends

dwind/loader.py

@@ -0,0 +1,59 @@
+from pathlib import Path
+
+import pandas as pd
+from sqlalchemy import create_engine
+
+
+def load_df(file_or_table: str | Path, year: str | None = None, sql_constructor: str | None = None):
+    """Loads data from either a SQL table or file to a pandas ``DataFrame``.
+
+    Args:
+        file_or_table (str | Path): File name or path object, or SQL table where the data are
+            located.
+        year (int | None, optional): If used, only extracts the single year from a column called
+            "year". Defaults to None.
+        sql_constructor (str | None, optional): The SQL engine constructor string. Required if
+            extracting from SQL. Defaults to None.
+    """
+    valid_extenstions = (".csv", ".pqt", ".parquet", ".pkl", ".pickle")
+    if str(file_or_table).endswith(valid_extenstions):
+        return _load_from_file(filename=file_or_table, year=year)
+
+    return _load_from_sql(table=file_or_table, sql_constructor=sql_constructor, year=year)
+
+
+def _load_from_file(filename: str | Path, year: str | int | None) -> pd.DataFrame:
+    """Loads tabular data from a file to a ``pandas.DataFrame``."""
+    if isinstance(filename, str):
+        filename = Path(filename).resolve()
+    if not isinstance(filename, Path):
+        raise TypeError(f"`filename` must be a valid path, not {filename=}")
+
+    if filename.suffix == ".csv":
+        df = pd.read_csv(filename)
+    elif filename.suffix in (".parquet", ".pqt"):
+        df = pd.read_parquet(filename)
+    elif filename.suffix in (".pickle", ".pkl"):
+        df = pd.read_pickle(filename)
+    else:
+        raise ValueError(f"Only CSV, Parquet, and Pickle files allowed, not {filename=}")
+
+    if year is not None:
+        year = int(year)
+        df = df.loc[df.year == year]
+
+    return df
+
+
+def _load_from_sql(table: str, sql_constructor: str, year: str | int | None) -> pd.DataFrame:
+    """Load tabular data from SQL."""
+    if year is not None:
+        year = int(year)
+    where = f"where year = {year}" if year is not None else ""
+    sql = f"""select * from diffusion_shared."{table}" {where};"""
+    atlas_engine = create_engine(sql_constructor)
+
+    with atlas_engine.connect() as conn:
+        pd.read_sql(sql, con=conn.connection)
+
+    atlas_engine.dispose()