dwind 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

dwind/cli/utils.py

@@ -0,0 +1,166 @@
+"""Provides shared utilities among the CLI subcommand modules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+import pandas as pd
+from rich.style import Style
+from rich.table import Table
+from rich.console import Console
+
+from dwind.config import Year
+
+
+DWIND = Path("/projects/dwind/agents")
+
+console = Console()
+
+
+def year_callback(ctx: typer.Context, param: typer.CallbackParam, value: int):
+    """Typer helper to validate the year input.
+
+    Parameters
+    ----------
+    ctx : typer.Context
+        The Typer context.
+    param : typer.CallbackParam
+        The Typer parameter.
+    value : int
+        User input for the analysis year basis, must be one of 2022, 2024, or 2025.
+
+    Returns:
+    -------
+    int
+        The input :py:param:`value`, if it is a valid input.
+
+    Raises:
+    ------
+    typer.BadParameter
+        Raised if the input is not one of 2022, 2024, or 2025.
+    """
+    if ctx.resilient_parsing:
+        return
+    try:
+        year = Year(value)
+    except ValueError as e:
+        raise typer.BadParameter(
+            f"Only {Year.values()} are valid options for `year`, not {value}."
+        ) from e
+    return year
+
+
+def load_agents(
+    file_name: Path | None = None,
+    location: str | None = None,
+    sector: str | None = None,
+    model_config: str | Path | None = None,
+    *,
+    prepare: bool = False,
+) -> pd.DataFrame:
+    """Load the agent file based on a filename or the location and sector to a Pandas DataFrame,
+    and return the data frame.
+
+    Args:
+        file_name (Path | None, optional): Name of the agent file, if not auto-generating from
+            the :py:attr:`location` and :py:attr:`sector` inputs. Defaults to None.
+        location (str | None, optional): The name of the location or grouping, such as
+            "colorado_larimer" or "priority1". Defaults to None.
+        sector (str | None, optional): The name of the section. Must be one of "btm" or "fom".
+            Defaults to None.
+        model_config: (str | Path, optional): The file name and path for the overarching model
+            configuration containing SQL and file references, scenario configurations, and etc.
+            Defaults to None.
+        prepare (bool, optional): True if loading pre-chunked and prepared agent data, which should
+            bypass the standard column checking for additional joins, by default False.
+
+    Returns:
+        pd.DataFrame: The agent DataFrame.
+    """
+    from dwind.model import Agents
+
+    if file_name is None and (location is None or sector is None):
+        raise ValueError("One of `file_name` or `location` and `sector` must be provided.")
+
+    f_agents = (
+        file_name if file_name is not None else DWIND / f"{location}/agents_dwind_{sector}.parquet"
+    )
+    if not isinstance(f_agents, Path):
+        f_agents = Path(f_agents).resolve()
+
+    alternative_suffix = (".pqt", ".parquet", ".pkl", ".pickle", ".csv")
+    base_style = Style.parse("cyan")
+    if not f_agents.exists():
+        for suffix in alternative_suffix:
+            if (new_fn := f_agents.with_suffix(suffix)).exists():
+                if new_fn != f_agents:
+                    msg = (
+                        f"Using alternative agent file: {new_fn}\n\t"
+                        f"Requested agent file: {f_agents}"
+                    )
+                    console.print(msg, style=base_style)
+                    f_agents = new_fn
+                    break
+
+    if prepare:
+        return Agents.load_and_prepare_agents(
+            agent_file=f_agents, sector=sector, model_config=model_config
+        )
+    return Agents.load_agents(agent_file=f_agents)
+
+
+def print_status_table(
+    summary: pd.DataFrame,
+    id_col: str = "job",
+    chunk_col: str | None = None,
+    status_col: str = "status",
+) -> None:
+    """Prints a nicely formatted pandas DataFrame to the console.
+
+    Args:
+        summary (pd.DataFrame): Summary DataFrame of the job (:py:attr:`id_col`), chunk
+            (:py:attr:`chunk_col`), and status (:py:attr:`status_col`).
+        id_col (str): Name of the job ID column.
+        chunk_col (str): Name of the chunk index column.
+        status_col (str): Name of the final job status column.
+    """
+    table = Table()
+    table.add_column("Job ID")
+    if chunk_col is not None:
+        table.add_column("Agent Chunk")
+    table.add_column("Status")
+
+    if chunk_col is None:
+        cols = [id_col, status_col]
+        secondary_sort = status_col
+    else:
+        cols = [id_col, chunk_col, status_col]
+        secondary_sort = chunk_col
+    summary = summary[cols].astype({c: str for c in cols})
+    for _, row in summary.sort_values([status_col, secondary_sort]).iterrows():
+        table.add_row(*row.tolist())
+
+    console.print(table)
+
+
+def cleanup_chunks(dir_out: str | None, which: str) -> None:
+    """Deletes the temporary agent chunk files, typically in
+    ``/path/to/analysis_scenario/chunk_files/agents``, and of the form ``agents_{ix}.pqt``.
+
+    Args:
+        dir_out (str | None): The same :py:attr:`dir_out` passed to the run command. The
+            ``chunk_files/agent_chunks`` will be automatically added to the path.
+        which (str): One of "agents" or "results" to indicate which chunked files should be deleted.
+    """
+    dir_out = Path.cwd() if dir_out is None else Path(dir_out).resolve()
+    out_path = dir_out / "chunk_files"
+    if which == "agents":
+        out_path = out_path / "agent_chunks"
+    elif which != "results":
+        raise ValueError("`which` must be one 'agents' or 'results'.")
+
+    for f in out_path.iterdir():
+        if f.suffix == ".pqt":
+            f.unlink()
+            print(f"Removed: {f}")

dwind/config.py

@@ -1,11 +1,13 @@
 """Custom configuration data class to allow for dictionary style and dot notation calling of
-attributes.
+attributes and Enums for validating configuration data.
 """
 
 from __future__ import annotations
 
 import re
 import sys
+from enum import Enum, IntEnum
+from typing import Any, Annotated
 from pathlib import Path
 
 
@@ -17,54 +19,193 @@ else:
 # fmt: on
 
 
+class ValuesMixin:
+    """Mixin class providing `.values()` for Enum classes."""
+
+    @staticmethod
+    def values() -> list[str]:
+        """Generate a list of the valid input strings."""
+        return [*Sector._value2member_map_]
+
+
+class Sector(str, ValuesMixin, Enum):
+    """Enum validator for sector inputs."""
+
+    FOM: Annotated[str, "Front-of-meter"] = "fom"
+    BTM: Annotated[str, "Behind-the-meter"] = "btm"
+
+
+class Technology(str, ValuesMixin, Enum):
+    """Enum validator for technology inputs."""
+
+    WIND: Annotated[str, "Wind generation model"] = "wind"
+    SOLAR: Annotated[str, "Solar generation model"] = "solar"
+
+
+class Scenario(str, ValuesMixin, Enum):
+    """Enum validator for the scenario to run."""
+
+    BASELINE: Annotated[str, "Standard scenario to compare alternatives."] = "baseline"
+    METERING: Annotated[str, "TODO."] = "metering"
+    BILLING: Annotated[str, "TODO."] = "billing"
+    HIGHRECOST: Annotated[str, "High renewable adoption"] = "highrecost"
+    RE100: Annotated[str, "100% renewable adoption"] = "highrecost"
+    LOWRECOST: Annotated[str, "Low renewable adoption"] = "lowrecost"
+
+
+class Year(ValuesMixin, IntEnum):
+    """Enum validator for analysis year."""
+
+    _2022 = 2022
+    _2025 = 2025
+    _2035 = 2035
+    _2040 = 2040
+
+
+class Optimization(str, ValuesMixin, Enum):
+    """Enum validator for breakeven cost optimization strategies."""
+
+    BISECT = "bisect"
+    BRENTQ = "brentq"
+    GRID_SEARCH = "grid_search"
+    NEWTON = "newton"
+
+
+class CRBModel(Enum):
+    """Convert between integers and "crb_model" data for efficient storage and retrieval."""
+
+    full_service_restaurant = 0
+    hospital = 1
+    large_hotel = 2
+    large_office = 3
+    medium_office = 4
+    midrise_apartment = 5
+    out_patient = 6
+    primary_school = 7
+    quick_service_restaurant = 8
+    reference = 9
+    secondary_school = 10
+    small_hotel = 11
+    small_office = 12
+    stand_alone_retail = 13
+    strip_mall = 14
+    supermarket = 15
+    warehouse = 16
+
+    @staticmethod
+    def model_map() -> dict[str, int]:
+        """Create a dictionary of name: int values for each crb model."""
+        return {el.name: el.value for el in CRBModel}
+
+    @staticmethod
+    def str_model_map() -> dict[str, str]:
+        """Create a dictionary of name: str(int) values for each crb model."""
+        return {el.name: str(el.value) for el in CRBModel}
+
+    @staticmethod
+    def int_map() -> dict[str, int]:
+        """Create a dictionary of int: name for each crb model."""
+        return {el.value: el.name for el in CRBModel}
+
+
 class Mapping(dict):
     """Dict-like class that allows for the use of dictionary style attribute calls on class
     attributes.
     """
 
-    def __setitem__(self, key, item):
+    def __setitem__(self, key: Any, item: Any):
+        """Creates a new key, value pair in :py:attr:`__dict__`.
+
+        Args:
+            key (Any): A hashable dictionary key.
+            item (Any): A value to be retrieved when the :py:attr:`key` is called.
+        """
         self.__dict__[key] = item
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: Any) -> Any:
+        """Retrieve :py:attr:`key`'s value from :py:attr:`__dict__`.
+
+        Args:
+            key (Any): An existing key in :py:attr:`__dict__`.
+
+        Returns:
+            Any: The value paired to :py:attr:`key`.
+        """
         return self.__dict__[key]
 
     def __repr__(self):
+        """Returns the ``repr(self.__dict__)``."""
         return repr(self.__dict__)
 
-    def __len__(self):
+    def __len__(self) -> int:
+        """Returns the number of keys in :py:attr:`__dict__`.
+
+        Returns:
+            int: The number of keys in :py:attr:`__dict__`.
+        """
         return len(self.__dict__)
 
-    def __delitem__(self, key):
+    def __delitem__(self, key: Any):
+        """Delete's :py:attr:`key` from :py:attr:`__dict__`."""
         del self.__dict__[key]
 
     def clear(self):
+        """Deletes all entries in :py:attr:`__dict__`."""
         return self.__dict__.clear()
 
-    def copy(self):
+    def copy(self) -> dict:
+        """Returns an unlinked copy of :py:attr:`__dict__`."""
         return self.__dict__.copy()
 
     def update(self, *args, **kwargs):
+        """Updates the provided args and keyword arguments of :py:attr:`__dict__`.
+
+        Args:
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         return self.__dict__.update(*args, **kwargs)
 
     def keys(self):
+        """Returns the keys of :py:attr:`__dict__`."""
         return self.__dict__.keys()
 
     def values(self):
+        """Returns the :py:attr:`__dict__` values."""
         return self.__dict__.values()
 
     def items(self):
+        """Returns the keys and values of :py:attr:`__dict__`."""
         return self.__dict__.items()
 
     def pop(self, *args):
+        """Removes and returns the desired argments from :py:attr:`__dict__` if they exist.
+
+        Args:
+            *args: Variable length argument list.
+
+        Returns:
+            Any: values of :py:attr:`__dict__` from keys :py:attr:`*args`.
+        """
         return self.__dict__.pop(*args)
 
     def __cmp__(self, dict_):
+        """Compares :py:attr:`_dict` to :py:attr:`__dict__`.
+
+        Args:
+            dict_ (dict): Dictionary for object comparison.
+
+        Returns:
+            bool: Result of the comparison between :py:attr:`_dict` and :py:attr:`__dict__`.
+        """
         return self.__cmp__(self.__dict__, dict_)
 
     def __contains__(self, item):
+        """Checks if :py:attr:`item` is in :py:attr:`__dict__`."""
         return item in self.__dict__
 
     def __iter__(self):
+        """Custom iterator return the :py:attr:`__dict__`."""
         return iter(self.__dict__)
 
 

dwind/main.py

@@ -0,0 +1,20 @@
+"""Enables running dwind as a CLI tool, the primary interface for working with dwind."""
+
+import typer
+
+from dwind.cli import run, debug, collect
+
+
+app = typer.Typer()
+
+app.add_typer(
+    run.app, name="run", help="Run a dwind analysis via sbatch or in an interactive session."
+)
+
+app.add_typer(debug.app, name="debug", help="Help identify issues with analyses that were run.")
+
+app.add_typer(collect.app, name="collect", help="Gather results from a run or rerun analysis.")
+
+
+if __name__ == "__main__":
+    app()