grid-data-models 2.3.6__tar.gz → 2.3.8__tar.gz

{grid_data_models-2.3.6 → grid_data_models-2.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: grid-data-models
-Version: 2.3.6
+Version: 2.3.8
 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.2
+Requires-Dist: infrasys==1.2.1
 Requires-Dist: networkx
-Requires-Dist: pandas~=3.0.3
+Requires-Dist: pandas~=3.0.5
 Requires-Dist: plotly
 Requires-Dist: pydantic
 Requires-Dist: semver
@@ -30,13 +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.5; extra == 'doc'
+Requires-Dist: jupyter-book<3,>=2.1.6; 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.28.0; extra == 'mcp'
+Requires-Dist: mcp>=2.1.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 

{grid_data_models-2.3.6 → grid_data_models-2.3.8}/pyproject.toml

@@ -24,19 +24,19 @@ dependencies = [
   "semver",
   "networkx", 
   "pydantic",
-  "infrasys~=1.2", 
+  "infrasys==1.2.1", 
   "importlib_metadata",
   "typer",
-  "pandas~=3.0.3",
+  "pandas~=3.0.5",
   "geopandas",
   "plotly",
 ]
 
 [project.optional-dependencies]
-mcp = ["mcp>=1.28.0"]
+mcp = ["mcp>=2.1.0"]
 dev = ["pre-commit", "pytest", "pytest-cov", "pytest-doctestplus", "pytest-asyncio", "ruff", "docutils"]
 doc = [
-  "jupyter-book>=2.1.5,<3",
+  "jupyter-book>=2.1.6,<3",
   "sphinx",
   "pydata-sphinx-theme",
   "myst-parser",

{grid_data_models-2.3.6 → grid_data_models-2.3.8}/src/gdm/distribution/__init__.py

@@ -5,6 +5,7 @@ __version__ = VERSION
 # from gdm.tracked_changes import apply_tracked_changes, apply_update_scenario, get_distribution_system_on_date
 from gdm.distribution.model_reduction.reducer import (
     reduce_to_primary_system,
+    reduce_to_radial_network,
     reduce_to_three_phase_system,
 )
 from gdm.distribution.distribution_graph import build_graph_from_system

{grid_data_models-2.3.6 → grid_data_models-2.3.8}/src/gdm/distribution/distribution_system.py

@@ -213,6 +213,9 @@ class DistributionSystem(System):
                 "type": edge.__class__,
                 "is_closed": True,
                 "in_service": edge.in_service,
+                "phases": [phase.value for phase in edge.winding_phases[0]]
+                if isinstance(edge, DistributionTransformerBase)
+                else [phase.value for phase in edge.phases],
             }
             if isinstance(edge, DistributionSwitchBase):
                 data["is_closed"] = True if len(edge.is_closed) == sum(edge.is_closed) else False
@@ -408,13 +411,20 @@ class DistributionSystem(System):
             cycles = self.get_cycles(dfs_tree)
             while cycles:
                 cycle = cycles[0]
-                switch_buses = self.find_switch_buses_in_cycle(cycle)
-                logger.debug(f"  Cycle found: {cycle}, switch buses in cycle: {switch_buses}")
-                if switch_buses:
-                    try:
-                        dfs_tree.remove_edge(*switch_buses)
-                    except Exception:
-                        dfs_tree.remove_edge(*switch_buses[::-1])
+                switch_edges = self.find_switch_buses_in_cycle(cycle)
+                logger.debug(f"  Cycle found: {cycle}, switch edges in cycle: {switch_edges}")
+                if switch_edges:
+                    bus_1, bus_2 = switch_edges[0]
+                    if dfs_tree.has_edge(bus_1, bus_2):
+                        dfs_tree.remove_edge(bus_1, bus_2)
+                    elif dfs_tree.has_edge(bus_2, bus_1):
+                        dfs_tree.remove_edge(bus_2, bus_1)
+                    else:
+                        logger.warning(
+                            f"  Switch edge ({bus_1}, {bus_2}) not present in DFS tree; skipping."
+                        )
+                        cycles.pop(0)
+                        continue
                 else:
                     bus_1 = random.choice(cycle)
                     if cycle.index(bus_1) == len(cycle) - 1:
@@ -454,12 +464,12 @@ class DistributionSystem(System):
         dfs_tree.add_edges_from(pruned_edges_tuples)
         return dfs_tree
 
-    def find_switch_buses_in_cycle(self, cycle: list[str]) -> list[str]:
-        """Finds the switch buses in a given cycle.
+    def find_switch_buses_in_cycle(self, cycle: list[str]) -> list[tuple[str, str]]:
+        """Finds the switch edges in a given cycle.
 
-        This method identifies the switch buses that are part of a cycle in the directed graph.
-        It checks for edges in the cycle that correspond to open switches and returns the names
-        of the buses associated with those switches.
+        This method identifies the switch edges that are part of a cycle in the directed graph.
+        It checks for edges in the cycle that correspond to switches and returns the
+        (bus_1, bus_2) pairs for each switch edge found.
 
         Parameters
         ----------
@@ -468,27 +478,27 @@ class DistributionSystem(System):
 
         Returns
         -------
-        list[str]
-            A list of bus names that are associated with open switches in the cycle.
+        list[tuple[str, str]]
+            A list of (bus_1, bus_2) tuples for each switch edge found in the cycle.
 
         Notes
         -----
-        - The method iterates through the edges in the cycle and checks for any open switches.
-        - It returns the names of the buses that are connected by these open switches.
+        - The method iterates through the edges in the cycle and checks for any switches.
+        - It returns the bus pairs that are connected by these switches.
         """
-        switch_buses = []
+        switch_edges: list[tuple[str, str]] = []
+        ugraph = self.get_undirected_graph()
         for i in range(len(cycle)):
             bus_1 = cycle[i]
             bus_2 = cycle[(i + 1) % len(cycle)]
-            edge_data = self.get_undirected_graph().get_edge_data(bus_1, bus_2)
+            edge_data = ugraph.get_edge_data(bus_1, bus_2)
             if edge_data:
-                for key, data in edge_data.items():
+                for _, data in edge_data.items():
                     if issubclass(data.get("type"), MatrixImpedanceSwitch):
-                        switch_buses.append(bus_1)
-                        switch_buses.append(bus_2)
+                        switch_edges.append((bus_1, bus_2))
                         logger.info(f"Switch found between {bus_1} and {bus_2}")
                         break
-        return list(set(switch_buses))
+        return switch_edges
 
     def get_split_phase_mapping(
         self,
@@ -952,7 +962,9 @@ class DistributionSystem(System):
         logger.info("Converting models from GeometryBranch to MatrixImpedanceBranch...")
         auto_add = self.auto_add_composed_components
         self.auto_add_composed_components = True
-        branches = list(self.get_components(GeometryBranch)) + list(self.get_components(GeometrySwitch))
+        branches = list(self.get_components(GeometryBranch)) + list(
+            self.get_components(GeometrySwitch)
+        )
         for branch in branches:
             impedence_branch = branch.to_matrix_representation(
                 frequency_hz, soil_resistivity_ohm_m

{grid_data_models-2.3.6 → grid_data_models-2.3.8}/src/gdm/distribution/model_reduction/__init__.py

@@ -1,2 +1,3 @@
 from gdm.distribution.model_reduction.reducer import reduce_to_primary_system
+from gdm.distribution.model_reduction.reducer import reduce_to_radial_network
 from gdm.distribution.model_reduction.reducer import reduce_to_three_phase_system

grid_data_models-2.3.8/src/gdm/distribution/model_reduction/reducer.py

@@ -0,0 +1,408 @@
+import uuid
+from typing import Type, Union, Callable
+
+from infrasys.time_series_models import SingleTimeSeries, TimeSeriesData
+from infrasys import Component
+import networkx as nx
+
+from gdm.distribution.components.base.distribution_branch_base import DistributionBranchBase
+from gdm.distribution.components.base.distribution_switch_base import DistributionSwitchBase
+from gdm.distribution.components.distribution_bus import DistributionBus
+from gdm.distribution.components.distribution_load import DistributionLoad
+from gdm.distribution.components.distribution_solar import DistributionSolar
+from gdm.distribution.components.distribution_battery import DistributionBattery
+from gdm.distribution.components.geometry_branch import GeometryBranch
+from gdm.distribution.components.matrix_impedance_branch import MatrixImpedanceBranch
+from gdm.distribution.components.matrix_impedance_switch import MatrixImpedanceSwitch
+from gdm.distribution.distribution_system import (
+    DistributionSystem,
+    UserAttributes,
+)
+from gdm.distribution.equipment.matrix_impedance_switch_equipment import (
+    MatrixImpedanceSwitchEquipment,
+)
+from gdm.distribution.enums import Phase
+from gdm.distribution.sys_functools import (
+    get_aggregated_load_time_series,
+    get_aggregated_solar_time_series,
+    get_aggregated_battery_time_series,
+)
+
+
+def _get_three_phase_buses(
+    dist_system: DistributionSystem,
+) -> list[str]:
+    three_phase_buses = [
+        bus.name
+        for bus in dist_system.get_components(
+            DistributionBus,
+            filter_func=lambda x: set((Phase.A, Phase.B, Phase.C)).issubset(x.phases),
+        )
+    ]
+    graph = dist_system.get_undirected_graph()
+
+    subgraph = graph.subgraph(three_phase_buses)
+    connected_components = list(nx.connected_components(subgraph))
+
+    max_size = 0
+    max_size_set = three_phase_buses
+    for island in connected_components:
+        if len(island) > max_size:
+            max_size = len(island)
+            max_size_set = island
+
+    return max_size_set
+
+
+def _get_primary_buses(dist_system: DistributionSystem) -> list[str]:
+    return [
+        bus.name
+        for bus in dist_system.get_components(
+            DistributionBus,
+            filter_func=lambda x: x.rated_voltage.to("kilovolt").magnitude > 1.0,
+        )
+    ]
+
+
+def _get_aggregated_bus_component(
+    subtree_system: DistributionSystem,
+    bus: DistributionBus,
+    model_type: DistributionLoad | DistributionSolar,
+    split_phase_mapping: dict[str, set[Phase]],
+    model_components: list[DistributionLoad | DistributionSolar] | None = None,
+) -> DistributionLoad | DistributionSolar:
+    if model_components is None:
+        model_components = subtree_system.get_components(model_type)
+    return model_type.aggregate(
+        instances=list(model_components),
+        bus=bus,
+        name=str(uuid.uuid4()),
+        split_phase_mapping=split_phase_mapping,
+    )
+
+
+def _aggregate_subtree_components(
+    subtree_system: DistributionSystem,
+    dist_system: DistributionSystem,
+    reduced_system: DistributionSystem,
+    model_types: list[Type[Component]],
+    source_bus_names: list[str],
+    aggregated_component_uuids: set[uuid.UUID],
+    target_bus: DistributionBus,
+    split_phase_mapping: dict[str, set[Phase]],
+    agg_time_series: bool,
+    time_series_type: Type[TimeSeriesData],
+    ts_agg_func_mapper: dict[Type[Component], Callable],
+) -> None:
+    for model_type in model_types:
+        model_components = [
+            component
+            for component in subtree_system.get_components(model_type)
+            if component.uuid not in aggregated_component_uuids
+            and getattr(component, "bus", None).name in source_bus_names
+        ]
+        aggregated_component_uuids.update(component.uuid for component in model_components)
+        if not model_components:
+            continue
+        agg_component = _get_aggregated_bus_component(
+            subtree_system,
+            target_bus,
+            model_type=model_type,
+            split_phase_mapping=split_phase_mapping,
+            model_components=model_components,
+        )
+        reduced_system.add_component(agg_component)
+        if not agg_time_series:
+            continue
+        agg_comp = reduced_system.get_component(model_type, agg_component.name)
+        ts_metadata = dist_system.list_time_series_metadata(
+            model_components[0], time_series_type=time_series_type
+        )
+        for metadata in ts_metadata:
+            ts_aggregate = ts_agg_func_mapper[model_type](
+                dist_system, model_components, metadata.name, time_series_type
+            )
+            user_attr = UserAttributes.model_validate(metadata.features)
+            user_attr.use_actual = True
+            reduced_system.add_time_series(ts_aggregate, agg_comp, **user_attr.model_dump())
+
+
+def _reduce_system(
+    dist_system: DistributionSystem,
+    bus_subset: list[DistributionBus],
+    name: str,
+    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
+
+    closed_graph = _closed_edge_graph(dist_system)
+    if nx.cycle_basis(nx.Graph(closed_graph)):
+        raise ValueError("The system contains closed loops; run reduce_to_radial_network first.")
+
+    original_tree = dist_system.get_directed_graph()
+    reduced_system = dist_system.get_subsystem(
+        bus_subset,
+        name,
+        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(directed_graph=original_tree)
+    reduced_network_tree = original_tree.subgraph(bus_subset)
+    retained_bus_names = set(bus_subset)
+    aggregated_bus_names: set[str] = set()
+    aggregated_component_uuids: set[uuid.UUID] = set()
+    ts_agg_func_mapper: dict[Union[Type[DistributionLoad], Type[DistributionSolar]], Callable] = {
+        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):
+            sucessors_diff = set(original_tree.successors(node)) - set(
+                reduced_network_tree.successors(node)
+            )
+            successors_descendants = [
+                snode
+                for successor in sucessors_diff
+                for snode in nx.descendants(original_tree, successor)
+            ] + list(sucessors_diff)
+            successors_descendants = list(
+                set(successors_descendants) - retained_bus_names - aggregated_bus_names
+            )
+            aggregated_bus_names.update(successors_descendants)
+            if not successors_descendants:
+                continue
+            subtree = original_tree.subgraph(successors_descendants)
+            subtree_system = dist_system.get_subsystem(
+                list(subtree.nodes),
+                "",
+                directed_graph=original_tree,
+            )
+            model_types = subtree_system.get_model_types_with_field_type(DistributionBus)
+            _aggregate_subtree_components(
+                subtree_system,
+                dist_system,
+                reduced_system,
+                model_types,
+                successors_descendants,
+                aggregated_component_uuids,
+                reduced_system.get_component(DistributionBus, node),
+                split_phase_mapping,
+                agg_time_series,
+                time_series_type,
+                ts_agg_func_mapper,
+            )
+
+    return reduced_system
+
+
+def reduce_to_three_phase_system(
+    dist_system: DistributionSystem,
+    name: str,
+    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_time_series,
+        agg_timeseries,
+        time_series_type,
+    )
+
+
+def reduce_to_primary_system(
+    dist_system: DistributionSystem,
+    name: str,
+    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_time_series,
+        agg_timeseries,
+        time_series_type,
+    )
+
+
+def _normalize_cycle(cycle: list[str]) -> tuple[str, ...]:
+    """Rotate a cycle so that it starts at its lexicographically smallest bus."""
+    start = min(range(len(cycle)), key=cycle.__getitem__)
+    return tuple(cycle[start:] + cycle[:start])
+
+
+def _closed_edge_graph(system: DistributionSystem) -> nx.MultiGraph:
+    """Build an undirected graph containing only electrically closed edges.
+
+    Mirrors the edge filtering performed by ``get_directed_graph``: open switch
+    edges (any phase open) are excluded, while all other branches and
+    transformers count as closed.
+    """
+    graph = system.get_undirected_graph()
+    closed_graph = nx.MultiGraph()
+    for node in graph.nodes():
+        closed_graph.add_node(node)
+    for u, v, key, data in graph.edges(data=True, keys=True):
+        if data.get("is_closed"):
+            closed_graph.add_edge(u, v, key=key, **data)
+    return closed_graph
+
+
+def _cycle_components(
+    system: DistributionSystem,
+    cycle: tuple[str, ...],
+    graph: nx.MultiGraph,
+    is_candidate: Callable[[type], bool],
+) -> list[DistributionBranchBase]:
+    """Resolve the branch components on a cycle that match ``is_candidate``.
+
+    Components are deduplicated and returned sorted by name so that any
+    downstream selection is deterministic.
+    """
+    seen: dict[uuid.UUID, DistributionBranchBase] = {}
+    for i in range(len(cycle)):
+        bus_1, bus_2 = cycle[i], cycle[(i + 1) % len(cycle)]
+        if not graph.has_edge(bus_1, bus_2):
+            continue
+        for data in graph[bus_1][bus_2].values():
+            component_type = data["type"]
+            if is_candidate(component_type):
+                component = system.get_component(component_type, data["name"])
+                seen.setdefault(component.uuid, component)
+    return sorted(seen.values(), key=lambda component: component.name)
+
+
+def _switch_equipment_from_branch(
+    line: DistributionBranchBase,
+) -> MatrixImpedanceSwitchEquipment:
+    """Build switch equipment from a branch's impedance data."""
+    if isinstance(line, GeometryBranch):
+        line = line.to_matrix_representation(frequency_hz=60)
+    if not isinstance(line, MatrixImpedanceBranch):
+        msg = (
+            f"Cannot convert {line.__class__.__name__} to a switch. Only "
+            "MatrixImpedanceBranch and GeometryBranch lines are supported."
+        )
+        raise ValueError(msg)
+    return MatrixImpedanceSwitchEquipment(**line.equipment.model_dump(exclude_none=True))
+
+
+def _convert_line_to_open_switch(
+    system: DistributionSystem, line: DistributionBranchBase
+) -> MatrixImpedanceSwitch:
+    """Replace ``line`` with an open switch between the same buses."""
+    name = f"{line.name}_switch"
+    existing_names = {switch.name for switch in system.get_components(MatrixImpedanceSwitch)}
+    suffix = 1
+    while name in existing_names:
+        suffix += 1
+        name = f"{line.name}_switch_{suffix}"
+
+    switch = MatrixImpedanceSwitch(
+        buses=line.buses,
+        length=line.length,
+        phases=list(line.phases),
+        substation=line.substation,
+        feeder=line.feeder,
+        name=name,
+        is_closed=[False] * len(line.phases),
+        equipment=_switch_equipment_from_branch(line),
+        uuid=uuid.uuid5(uuid.NAMESPACE_URL, f"gdm.radial_switch.{name}"),
+    )
+    system.remove_component(line)
+    system.add_component(switch)
+    return switch
+
+
+def reduce_to_radial_network(dist_system: DistributionSystem, name: str) -> DistributionSystem:
+    """Reduce a looped distribution system to a radial network.
+
+    Every electrical loop in the input is broken deterministically: if a loop
+    contains a closed switch, that switch is opened; otherwise the shortest
+    line on the loop (ties broken by component name) is replaced with an open
+    ``MatrixImpedanceSwitch`` between the same buses. The input system is not
+    modified; a reduced copy is returned.
+
+    Parameters
+    ----------
+    dist_system : DistributionSystem
+        Source distribution system, possibly containing loops. Must be a single
+        connected component fed from one voltage source (the same requirement
+        as ``get_source_bus``).
+    name : str
+        Name of the reduced system.
+
+    Returns
+    -------
+    DistributionSystem
+        A radial copy of the input system in which no closed loop remains, so
+        that ``get_directed_graph`` prunes no edges and emits no "pruned from
+        DFS tree" warnings.
+
+    Notes
+    -----
+    - Geometry-based lines are converted to their matrix representation at
+      60 Hz when they are selected for conversion.
+    - Only cycle edges are touched, so the reduced network stays connected.
+    """
+    system = dist_system.deepcopy()
+    system.name = name
+    closed_graph = _closed_edge_graph(system)
+
+    while True:
+        cycles = sorted(
+            _normalize_cycle(cycle) for cycle in DistributionSystem.get_cycles(closed_graph)
+        )
+        if not cycles:
+            break
+        cycle = cycles[0]
+
+        switches = _cycle_components(
+            system, cycle, closed_graph, lambda t: issubclass(t, DistributionSwitchBase)
+        )
+        if switches:
+            switch = switches[0]
+            switch.is_closed = [False] * len(switch.phases)
+            bus_1, bus_2 = switch.buses[0].name, switch.buses[1].name
+            for key in [
+                k for k, data in closed_graph[bus_1][bus_2].items() if data["name"] == switch.name
+            ]:
+                closed_graph.remove_edge(bus_1, bus_2, key=key)
+            continue
+
+        lines = _cycle_components(
+            system,
+            cycle,
+            closed_graph,
+            lambda t: (
+                issubclass(t, DistributionBranchBase) and not issubclass(t, DistributionSwitchBase)
+            ),
+        )
+        if not lines:
+            msg = (
+                f"Cycle {list(cycle)} contains no branches or switches that can be "
+                "opened to break the loop; cannot reduce the system to a radial network."
+            )
+            raise ValueError(msg)
+
+        line = min(lines, key=lambda b: (b.length.to("meter").magnitude, b.name))
+        _convert_line_to_open_switch(system, line)
+        bus_1, bus_2 = line.buses[0].name, line.buses[1].name
+        for key in [
+            k for k, data in closed_graph[bus_1][bus_2].items() if data["name"] == line.name
+        ]:
+            closed_graph.remove_edge(bus_1, bus_2, key=key)
+
+    return system