grid-data-models 2.3.1__tar.gz → 2.3.3__tar.gz

{grid_data_models-2.3.1 → grid_data_models-2.3.3}/.gitignore

@@ -7,6 +7,8 @@ __pycache__/
 *.so
 *.code-workspace
 *.sqlite
+*.db
+*.sql
 *.ruff_cache/
 
 # Distribution / packaging
@@ -164,3 +166,4 @@ cython_debug/
 .qodo
 .DS_Store
 *.dump
+uv.lock

{grid_data_models-2.3.1 → grid_data_models-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grid-data-models
-Version: 2.3.1
+Version: 2.3.3
 Project-URL: Documentation, https://github.com/NREL-Distribution-Suites/grid-data-models#readme
 Project-URL: Issues, https://github.com/NREL-Distribution-Suites/grid-data-models/issues
 Project-URL: Source, https://github.com/NREL-Distribution-Suites/grid-data-models
@@ -13,9 +13,9 @@ Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.11
 Requires-Dist: geopandas
 Requires-Dist: importlib-metadata
-Requires-Dist: infrasys~=1.0
+Requires-Dist: infrasys~=1.1
 Requires-Dist: networkx
-Requires-Dist: pandas~=2.2.3
+Requires-Dist: pandas~=3.0.2
 Requires-Dist: plotly
 Requires-Dist: pydantic
 Requires-Dist: semver
@@ -30,12 +30,13 @@ Requires-Dist: pytest-doctestplus; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Provides-Extra: doc
 Requires-Dist: autodoc-pydantic[erdantic]; extra == 'doc'
+Requires-Dist: jupyter-book<3,>=2.1.4; extra == 'doc'
 Requires-Dist: myst-parser; extra == 'doc'
 Requires-Dist: pydata-sphinx-theme; extra == 'doc'
 Requires-Dist: sphinx; extra == 'doc'
 Requires-Dist: sphinxcontrib-mermaid; extra == 'doc'
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Requires-Dist: mcp>=1.27.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 
@@ -61,7 +62,7 @@ In an effort to reduce code duplication and provide client packages a standard i
 - **Built-in validation layer:** Use of [pydantic](https://docs.pydantic.dev/latest/) allows us to validate model fields.
 - **Time series data management:** GDM uses [infrasys](https://github.nrel.gov/CADET/infrastructure_systems) package which enables [efficient time series data management](https://nrel.github.io/infrasys/explanation/time_series.html) by sharing arrays across components and offloading system memory. For example, we can attach time series power consumption data to a load profile.
 - **Built-in unit conversion:** GDM leverages [pint](https://pint.readthedocs.io/en/stable/) for unit conversion for power system quantities. For example, power, voltage, time, etc.
-- **JSON serialization/deserialization:** GDM uses [infrasys](https://github.com/NREL/infrasys) to serialize and deserialize distribution system components to/from JSON.
+- **JSON serialization/deserialization:** GDM uses [infrasys](https://github.com/NatLabRockies/infrasys) to serialize and deserialize distribution system components to/from JSON.
 - **Track System Changes:** Supports tracking changes within a distribution model (both temporal and scenario-based static updates), enabling powerful scenario management capabilities.
 - **Graph-Based Analysis:** Exposes a connectivity graph using NetworkX, allowing advanced graph-based algorithms and visualizations.
 - **Interoperability:** Easily integrates with existing tools.

{grid_data_models-2.3.1 → grid_data_models-2.3.3}/README.md

@@ -21,7 +21,7 @@ In an effort to reduce code duplication and provide client packages a standard i
 - **Built-in validation layer:** Use of [pydantic](https://docs.pydantic.dev/latest/) allows us to validate model fields.
 - **Time series data management:** GDM uses [infrasys](https://github.nrel.gov/CADET/infrastructure_systems) package which enables [efficient time series data management](https://nrel.github.io/infrasys/explanation/time_series.html) by sharing arrays across components and offloading system memory. For example, we can attach time series power consumption data to a load profile.
 - **Built-in unit conversion:** GDM leverages [pint](https://pint.readthedocs.io/en/stable/) for unit conversion for power system quantities. For example, power, voltage, time, etc.
-- **JSON serialization/deserialization:** GDM uses [infrasys](https://github.com/NREL/infrasys) to serialize and deserialize distribution system components to/from JSON.
+- **JSON serialization/deserialization:** GDM uses [infrasys](https://github.com/NatLabRockies/infrasys) to serialize and deserialize distribution system components to/from JSON.
 - **Track System Changes:** Supports tracking changes within a distribution model (both temporal and scenario-based static updates), enabling powerful scenario management capabilities.
 - **Graph-Based Analysis:** Exposes a connectivity graph using NetworkX, allowing advanced graph-based algorithms and visualizations.
 - **Interoperability:** Easily integrates with existing tools.

{grid_data_models-2.3.1 → grid_data_models-2.3.3}/pyproject.toml

@@ -24,18 +24,19 @@ dependencies = [
   "semver",
   "networkx", 
   "pydantic",
-  "infrasys~=1.0", 
+  "infrasys~=1.1", 
   "importlib_metadata",
   "typer",
-  "pandas~=2.2.3",
+  "pandas~=3.0.2",
   "geopandas",
   "plotly",
 ]
 
 [project.optional-dependencies]
-mcp = ["mcp>=1.0.0"]
+mcp = ["mcp>=1.27.0"]
 dev = ["pre-commit", "pytest", "pytest-cov", "pytest-doctestplus", "pytest-asyncio", "ruff", "docutils"]
 doc = [
+  "jupyter-book>=2.1.4,<3",
   "sphinx",
   "pydata-sphinx-theme",
   "myst-parser",

{grid_data_models-2.3.1 → grid_data_models-2.3.3}/src/gdm/cli/reducer.py

@@ -28,9 +28,11 @@ def reduce(
     reducer: Annotated[
         ReducerType, typer.Option("-r", "--reducer", help="Reducer type to apply.")
     ] = ReducerType.three_phase,
-    timeseries: Annotated[
+    time_series: Annotated[
         bool,
-        typer.Option("-ts", "--timeseries", help="Include timeseries data in the reduced system."),
+        typer.Option(
+            "-ts", "--time-series", help="Include time series data in the reduced system."
+        ),
     ] = False,
 ):
     """Reduce a GDM distribution system."""
@@ -46,6 +48,6 @@ def reduce(
     sys = DistributionSystem.from_json(gdm_file)
     reducer_func = {"three_phase": reduce_to_three_phase_system}
     new_sys_name = sys.name + "_reduced" if sys.name else None
-    new_sys = reducer_func[reducer.value](sys, new_sys_name, timeseries)
+    new_sys = reducer_func[reducer.value](sys, new_sys_name, time_series)
     new_sys.to_json(target_path)
     typer.echo(str(target_path))

{grid_data_models-2.3.1 → grid_data_models-2.3.3}/src/gdm/distribution/components/base/distribution_branch_base.py

@@ -41,15 +41,6 @@ class DistributionBranchBase(InServiceDistributionComponentBase, ABC):
                 msg = f"Conductor phase ({phase=}) does not match bus phases ({bus.phases=})"
                 raise ValueError(msg)
 
-        num_branch_phases = len(self.phases)
-        if not any(num_branch_phases == len(bus.phases) for bus in self.buses):
-            bus_phase_counts = {bus.name: len(bus.phases) for bus in self.buses}
-            msg = (
-                f"Number of branch phases ({num_branch_phases}) must match the number of phases "
-                f"of at least one connected bus. Connected bus phase counts: {bus_phase_counts}"
-            )
-            raise ValueError(msg)
-
         if self.buses[0].name == self.buses[1].name:
             msg = (
                 f"From bus {self.buses[0].name=} and to bus"

{grid_data_models-2.3.1 → grid_data_models-2.3.3}/src/gdm/distribution/distribution_system.py

@@ -276,8 +276,10 @@ class DistributionSystem(System):
         self,
         bus_names: list[str],
         name: str,
-        keep_timeseries: bool = False,
+        keep_time_series: bool = False,
+        keep_timeseries: bool | None = None,
         time_series_type: Type[TimeSeriesData] = SingleTimeSeries,
+        directed_graph: nx.DiGraph | None = None,
     ) -> "DistributionSystem":
         """Method to get subsystem from list of buses.
 
@@ -287,15 +289,23 @@ class DistributionSystem(System):
             List of bus names
         name: str
             Name of the subsystem.
-        keep_timeseries: bool
-            Set this flag to retain timeseries data associated with the component.
+        keep_time_series: bool
+            Set this flag to retain time series data associated with the component.
+        keep_timeseries: bool | None
+            Deprecated alias for keep_time_series.
         time_series_type: Type[TimeSeriesData]
             Type of time series data. Defaults to: SingleTimeSeries
+        directed_graph: nx.DiGraph | None
+            Optional precomputed directed graph for this system. When provided,
+            it is reused instead of rebuilding the directed graph.
         Returns
         -------
         DistributionSystem
         """
-        tree = self.get_directed_graph()
+        if keep_timeseries is not None:
+            keep_time_series = keep_timeseries
+
+        tree = directed_graph if directed_graph is not None else self.get_directed_graph()
         subtree = tree.subgraph(bus_names)
         subtree_system = DistributionSystem(auto_add_composed_components=True, name=name)
         for u, v, _ in subtree.edges(data=True):
@@ -308,7 +318,7 @@ class DistributionSystem(System):
             parent_components = self.list_parent_components(self.get_component(DistributionBus, u))
             self._add_to_subsystem(subtree_system, parent_components, bus_names)
 
-        if keep_timeseries:
+        if keep_time_series:
             for comp in subtree_system.get_components(
                 Component,
                 filter_func=lambda x: self.has_time_series(x, time_series_type=time_series_type),
@@ -470,7 +480,6 @@ class DistributionSystem(System):
             bus_1 = cycle[i]
             bus_2 = cycle[(i + 1) % len(cycle)]
             edge_data = self.get_undirected_graph().get_edge_data(bus_1, bus_2)
-            print(bus_1, bus_2, edge_data)
             if edge_data:
                 for key, data in edge_data.items():
                     if issubclass(data.get("type"), MatrixImpedanceSwitch):
@@ -480,7 +489,10 @@ class DistributionSystem(System):
                         break
         return list(set(switch_buses))
 
-    def get_split_phase_mapping(self) -> dict[str, set[Phase]]:
+    def get_split_phase_mapping(
+        self,
+        directed_graph: nx.DiGraph | None = None,
+    ) -> dict[str, set[Phase]]:
         """Generates a mapping of components to their split-phase configurations.
 
         This method identifies distribution transformers with center-tapped windings and
@@ -494,6 +506,12 @@ class DistributionSystem(System):
             A dictionary where keys are component names and values are sets of phases
             associated with the high-voltage bus.
 
+        Parameters
+        ----------
+        directed_graph: nx.DiGraph | None
+            Optional precomputed directed graph for this system. When provided,
+            it is reused instead of rebuilding the directed graph.
+
         Notes
         -----
         - The method uses the directed graph representation of the distribution system to
@@ -505,7 +523,7 @@ class DistributionSystem(System):
         - Logs the process of identifying and mapping split-phase transformers.
         """
         split_phase_map = {}
-        original_tree = self.get_directed_graph()
+        original_tree = directed_graph if directed_graph is not None else self.get_directed_graph()
         split_phase_trs: list[DistributionTransformer] = list(
             self.get_components(
                 DistributionTransformer,
@@ -518,7 +536,9 @@ class DistributionSystem(System):
             }.pop()
             hv_bus = (set([bus.name for bus in tr.buses]) - set([lv_bus])).pop()
             lv_system = self.get_subsystem(
-                list(nx.descendants(original_tree, lv_bus)) + [lv_bus], name=""
+                list(nx.descendants(original_tree, lv_bus)) + [lv_bus],
+                name="",
+                directed_graph=original_tree,
             )
             bus_model_types = self.get_model_types_with_field_type(DistributionBus)
             for model_type in bus_model_types:

{grid_data_models-2.3.1 → grid_data_models-2.3.3}/src/gdm/distribution/enums.py

@@ -118,6 +118,21 @@ class TOUPeriodType(str, Enum):
     MID_PEAK = "mid_peak"
 
 
+class Month(str, Enum):
+    JANUARY = "january"
+    FEBRUARY = "february"
+    MARCH = "march"
+    APRIL = "april"
+    MAY = "may"
+    JUNE = "june"
+    JULY = "july"
+    AUGUST = "august"
+    SEPTEMBER = "september"
+    OCTOBER = "october"
+    NOVEMBER = "november"
+    DECEMBER = "december"
+
+
 class Season(str, Enum):
     SUMMER = "summer"
     WINTER = "winter"
@@ -128,6 +143,7 @@ class CustomerClass(str, Enum):
     RESIDENTIAL = "residential"
     COMMERCIAL = "commercial"
     INDUSTRIAL = "industrial"
+    UTILITY = "utility"
 
 
 class BillingDemandBasis(str, Enum):

{grid_data_models-2.3.1 → grid_data_models-2.3.3}/src/gdm/distribution/equipment/phase_capacitor_equipment.py

@@ -54,13 +54,22 @@ class PhaseCapacitorEquipment(Component):
     def aggregate(
         cls, instances: list["PhaseCapacitorEquipment"], name: str
     ) -> "PhaseCapacitorEquipment":
+        resistance_inverse_sum = sum(
+            1 / inst.resistance for inst in instances if inst.resistance.magnitude
+        )
+        reactance_inverse_sum = sum(
+            1 / inst.reactance for inst in instances if inst.reactance.magnitude
+        )
+
         return PhaseCapacitorEquipment(
             name=name,
             rated_reactive_power=sum(inst.rated_reactive_power for inst in instances),
-            resistance=1
-            / sum(1 / inst.resistance if inst.resistance.magnitude else 0 for inst in instances),
-            reactance=1
-            / sum(1 / inst.reactance if inst.reactance.magnitude else 0 for inst in instances),
+            resistance=(
+                1 / resistance_inverse_sum if resistance_inverse_sum else Resistance(0, "ohm")
+            ),
+            reactance=(
+                1 / reactance_inverse_sum if reactance_inverse_sum else Reactance(0, "ohm")
+            ),
             num_banks=sum(inst.num_banks for inst in instances),
             num_banks_on=sum(inst.num_banks_on for inst in instances),
         )

{grid_data_models-2.3.1 → grid_data_models-2.3.3}/src/gdm/distribution/market/tariff.py

@@ -4,7 +4,7 @@ from pydantic import Field, model_validator
 from typing import List, Optional
 from infrasys import Component
 
-from gdm.distribution.enums import BillingDemandBasis, CustomerClass, TOUPeriodType, Season
+from gdm.distribution.enums import BillingDemandBasis, CustomerClass, Month, TOUPeriodType
 
 
 class TOURatePeriod(Component):
@@ -31,6 +31,9 @@ class TOURatePeriod(Component):
 
 class DemandCharge(Component):
     name: str = ""
+    months: List[Month] = Field(
+        ..., min_length=1, description="Months for which this demand charge applies"
+    )
     rate: float = Field(..., gt=0, description="Rate for demand charge in $/kW")
     billing_demand_basis: BillingDemandBasis = Field(
         ..., description="Basis for billing demand calculation"
@@ -39,9 +42,16 @@ class DemandCharge(Component):
         ..., description="Time periods when the demand charge applies"
     )
 
+    @model_validator(mode="after")
+    def check_no_duplicate_months(self) -> "DemandCharge":
+        if len(self.months) != len(set(self.months)):
+            raise ValueError("Duplicate months are not allowed within a single DemandCharge")
+        return self
+
     @classmethod
     def example(cls) -> "DemandCharge":
         return DemandCharge(
+            months=[Month.JUNE, Month.JULY, Month.AUGUST],
             rate=12.50,
             billing_demand_basis=BillingDemandBasis.PEAK_15MIN,
             time_applicability=[TOURatePeriod.example()],
@@ -50,13 +60,23 @@ class DemandCharge(Component):
 
 class SeasonalTOURates(Component):
     name: str = ""
-    season: Season = Field(..., description="Season for the TOU rates")
-    tou_periods: List[TOURatePeriod] = Field(..., description="List of TOU periods for the season")
+    months: List[Month] = Field(
+        ..., min_length=1, description="Months for which these TOU rates apply"
+    )
+    tou_periods: List[TOURatePeriod] = Field(
+        ..., description="List of TOU periods for the specified months"
+    )
+
+    @model_validator(mode="after")
+    def check_no_duplicate_months(self) -> "SeasonalTOURates":
+        if len(self.months) != len(set(self.months)):
+            raise ValueError("Duplicate months are not allowed within a single SeasonalTOURates")
+        return self
 
     @classmethod
     def example(cls) -> "SeasonalTOURates":
         return SeasonalTOURates(
-            season=Season.SUMMER,
+            months=[Month.JUNE, Month.JULY, Month.AUGUST],
             tou_periods=[
                 TOURatePeriod.example(),
                 TOURatePeriod(
@@ -81,7 +101,7 @@ class TieredRate(Component):
 
 class FixedCharge(Component):
     name: str = ""
-    amount: float = Field(..., gt=0, description="Amount of the fixed charge in $/month")
+    amount: float = Field(..., ge=0, description="Amount of the fixed charge in $/month")
     description: Optional[str] = Field(None, description="Description of the fixed charge")
 
     @classmethod
@@ -93,7 +113,7 @@ class DistributionTariff(Component):
     name: str = Field(..., description="Name of the tariff")
     utility: str = Field(..., description="Name of the utility company")
     customer_class: CustomerClass = Field(..., description="Customer class for the tariff")
-    fixed_charge: FixedCharge = Field(..., description="Fixed charge for the tariff")
+    fixed_charge: Optional[FixedCharge] = Field(None, description="Fixed charge for the tariff")
     seasonal_tou: List[SeasonalTOURates] = Field(
         ..., description="Seasonal TOU rates for the tariff"
     )
@@ -104,6 +124,13 @@ class DistributionTariff(Component):
         None, description="List of tiered energy charges for the tariff"
     )
 
+    @model_validator(mode="after")
+    def check_no_overlapping_months(self) -> "DistributionTariff":
+        all_months = [m for entry in self.seasonal_tou for m in entry.months]
+        if len(all_months) != len(set(all_months)):
+            raise ValueError("A month must not appear in more than one SeasonalTOURates entry")
+        return self
+
     @classmethod
     def example(cls) -> "DistributionTariff":
         return DistributionTariff(
@@ -114,7 +141,7 @@ class DistributionTariff(Component):
             seasonal_tou=[
                 SeasonalTOURates.example(),
                 SeasonalTOURates(
-                    season=Season.WINTER,
+                    months=[Month.DECEMBER, Month.JANUARY, Month.FEBRUARY],
                     tou_periods=[
                         TOURatePeriod.example(),
                         TOURatePeriod(

{grid_data_models-2.3.1 → grid_data_models-2.3.3}/src/gdm/distribution/model_reduction/reducer.py

@@ -14,9 +14,9 @@ from gdm.distribution.distribution_system import (
 )
 from gdm.distribution.enums import Phase
 from gdm.distribution.sys_functools import (
-    get_aggregated_load_timeseries,
-    get_aggregated_solar_timeseries,
-    get_aggregated_battery_timeseries,
+    get_aggregated_load_time_series,
+    get_aggregated_solar_time_series,
+    get_aggregated_battery_time_series,
 )
 
 
@@ -74,23 +74,28 @@ def _reduce_system(
     dist_system: DistributionSystem,
     bus_subset: list[DistributionBus],
     name: str,
-    agg_timeseries: bool = False,
+    agg_time_series: bool = False,
+    agg_timeseries: bool | None = None,
     time_series_type: Type[TimeSeriesData] = SingleTimeSeries,
 ) -> DistributionSystem:
+    if agg_timeseries is not None:
+        agg_time_series = agg_timeseries
+
+    original_tree = dist_system.get_directed_graph()
     reduced_system = dist_system.get_subsystem(
         bus_subset,
         name,
-        keep_timeseries=agg_timeseries,
+        keep_time_series=agg_time_series,
         time_series_type=time_series_type,
+        directed_graph=original_tree,
     )
 
-    split_phase_mapping = dist_system.get_split_phase_mapping()
-    original_tree = dist_system.get_directed_graph()
+    split_phase_mapping = dist_system.get_split_phase_mapping(directed_graph=original_tree)
     reduced_network_tree = original_tree.subgraph(bus_subset)
     ts_agg_func_mapper: dict[Union[Type[DistributionLoad], Type[DistributionSolar]], Callable] = {
-        DistributionLoad: get_aggregated_load_timeseries,
-        DistributionSolar: get_aggregated_solar_timeseries,
-        DistributionBattery: get_aggregated_battery_timeseries,
+        DistributionLoad: get_aggregated_load_time_series,
+        DistributionSolar: get_aggregated_solar_time_series,
+        DistributionBattery: get_aggregated_battery_time_series,
     }
     for node in reduced_network_tree.nodes():
         if reduced_network_tree.out_degree(node) < original_tree.out_degree(node):
@@ -103,7 +108,11 @@ def _reduce_system(
                 for snode in nx.descendants(original_tree, successor)
             ] + list(sucessors_diff)
             subtree = original_tree.subgraph(successors_descendants)
-            subtree_system = dist_system.get_subsystem(subtree.nodes, "")
+            subtree_system = dist_system.get_subsystem(
+                list(subtree.nodes),
+                "",
+                directed_graph=original_tree,
+            )
             model_types = subtree_system.get_model_types_with_field_type(DistributionBus)
             for model_type in model_types:
                 agg_component = _get_aggregated_bus_component(
@@ -112,10 +121,9 @@ def _reduce_system(
                     model_type=model_type,
                     split_phase_mapping=split_phase_mapping,
                 )
-                # print(model_type.__name__, agg_component)
                 reduced_system.add_component(agg_component)
                 agg_comp = reduced_system.get_component(model_type, agg_component.name)
-                if agg_timeseries:
+                if agg_time_series:
                     comps = list(subtree_system.get_components(model_type))
                     ts_metadata = dist_system.list_time_series_metadata(
                         comps[0], time_series_type=time_series_type
@@ -135,18 +143,34 @@ def _reduce_system(
 def reduce_to_three_phase_system(
     dist_system: DistributionSystem,
     name: str,
-    agg_timeseries: bool = False,
+    agg_time_series: bool = False,
+    agg_timeseries: bool | None = None,
     time_series_type: Type[TimeSeriesData] = SingleTimeSeries,
 ) -> DistributionSystem:
     three_phase_buses = _get_three_phase_buses(dist_system)
-    return _reduce_system(dist_system, three_phase_buses, name, agg_timeseries, time_series_type)
+    return _reduce_system(
+        dist_system,
+        three_phase_buses,
+        name,
+        agg_time_series,
+        agg_timeseries,
+        time_series_type,
+    )
 
 
 def reduce_to_primary_system(
     dist_system: DistributionSystem,
     name: str,
-    agg_timeseries: bool = False,
+    agg_time_series: bool = False,
+    agg_timeseries: bool | None = None,
     time_series_type: Type[TimeSeriesData] = SingleTimeSeries,
 ) -> DistributionSystem:
     primary_buses = _get_primary_buses(dist_system)
-    return _reduce_system(dist_system, primary_buses, name, agg_timeseries, time_series_type)
+    return _reduce_system(
+        dist_system,
+        primary_buses,
+        name,
+        agg_time_series,
+        agg_timeseries,
+        time_series_type,
+    )