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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grid-data-models
-Version: 2.3.4
+Version: 2.3.6
 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
@@ -36,12 +36,12 @@ 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.27.2; extra == 'mcp'
+Requires-Dist: mcp>=1.28.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 
 
-[![Upload to PyPi](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/publish_to_pypi.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/publish_to_pypi.yml) •  [![Pytest](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/pull_request_tests.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/pull_request_tests.yml) •  [![deploy-book](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/deploy.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/deploy.yml) • ![PyPI - Downloads](https://img.shields.io/pypi/dm/grid-data-models) •  [![codecov](https://codecov.io/github/NLR-Distribution-Suite/grid-data-models/branch/main/graph/badge.svg?token=K0X11EXOX8)](https://codecov.io/github/NLR-Distribution-Suite/grid-data-models) •  [![CodeFactor](https://www.codefactor.io/repository/github/nlr-distribution-suite/grid-data-models/badge)](https://www.codefactor.io/repository/github/nlr-distribution-suite/grid-data-models) • ![MCP Server](https://img.shields.io/badge/MCP_Server-enabled-brightgreen) • ![MCP Tools](https://img.shields.io/badge/MCP_Tools-20-blue) • [![GitHub issues](https://img.shields.io/github/issues/NLR-Distribution-Suite/grid-data-models)](https://github.com/NLR-Distribution-Suite/grid-data-models/issues) • [![License](https://img.shields.io/github/license/NLR-Distribution-Suite/grid-data-models)](https://github.com/NLR-Distribution-Suite/grid-data-models/blob/main/LICENSE.txt) •  [![PyPI Downloads](https://static.pepy.tech/personalized-badge/grid-data-models?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/grid-data-models)
+[![Upload to PyPi](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/publish_to_pypi.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/publish_to_pypi.yml) •  [![Pytest](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/pull_request_tests.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/pull_request_tests.yml) •  [![deploy-book](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/deploy.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/deploy.yml) • ![PyPI - Downloads](https://img.shields.io/pypi/dm/grid-data-models) •  [![codecov](https://codecov.io/github/NLR-Distribution-Suite/grid-data-models/branch/main/graph/badge.svg?token=K0X11EXOX8)](https://codecov.io/github/NLR-Distribution-Suite/grid-data-models) •  [![CodeFactor](https://www.codefactor.io/repository/github/nlr-distribution-suite/grid-data-models/badge)](https://www.codefactor.io/repository/github/nlr-distribution-suite/grid-data-models) • ![MCP Server](https://img.shields.io/badge/MCP_Server-enabled-brightgreen) • ![MCP Tools](https://img.shields.io/badge/MCP_Tools-20-blue) • [![GitHub issues](https://img.shields.io/github/issues/NLR-Distribution-Suite/grid-data-models)](https://github.com/NLR-Distribution-Suite/grid-data-models/issues) • [![License](https://img.shields.io/github/license/NLR-Distribution-Suite/grid-data-models)](https://github.com/NLR-Distribution-Suite/grid-data-models/blob/main/LICENSE.txt) •  [![PyPI Downloads](https://static.pepy.tech/personalized-badge/grid-data-models?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/grid-data-models) • [![Generate LinkedIn Post Draft](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/linkedin_draft.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/linkedin_draft.yml)
 
 # Grid Data Models (GDM)
 

{grid_data_models-2.3.4 → grid_data_models-2.3.6}/README.md

@@ -1,6 +1,6 @@
 
 
-[![Upload to PyPi](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/publish_to_pypi.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/publish_to_pypi.yml) •  [![Pytest](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/pull_request_tests.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/pull_request_tests.yml) •  [![deploy-book](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/deploy.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/deploy.yml) • ![PyPI - Downloads](https://img.shields.io/pypi/dm/grid-data-models) •  [![codecov](https://codecov.io/github/NLR-Distribution-Suite/grid-data-models/branch/main/graph/badge.svg?token=K0X11EXOX8)](https://codecov.io/github/NLR-Distribution-Suite/grid-data-models) •  [![CodeFactor](https://www.codefactor.io/repository/github/nlr-distribution-suite/grid-data-models/badge)](https://www.codefactor.io/repository/github/nlr-distribution-suite/grid-data-models) • ![MCP Server](https://img.shields.io/badge/MCP_Server-enabled-brightgreen) • ![MCP Tools](https://img.shields.io/badge/MCP_Tools-20-blue) • [![GitHub issues](https://img.shields.io/github/issues/NLR-Distribution-Suite/grid-data-models)](https://github.com/NLR-Distribution-Suite/grid-data-models/issues) • [![License](https://img.shields.io/github/license/NLR-Distribution-Suite/grid-data-models)](https://github.com/NLR-Distribution-Suite/grid-data-models/blob/main/LICENSE.txt) •  [![PyPI Downloads](https://static.pepy.tech/personalized-badge/grid-data-models?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/grid-data-models)
+[![Upload to PyPi](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/publish_to_pypi.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/publish_to_pypi.yml) •  [![Pytest](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/pull_request_tests.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/pull_request_tests.yml) •  [![deploy-book](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/deploy.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/deploy.yml) • ![PyPI - Downloads](https://img.shields.io/pypi/dm/grid-data-models) •  [![codecov](https://codecov.io/github/NLR-Distribution-Suite/grid-data-models/branch/main/graph/badge.svg?token=K0X11EXOX8)](https://codecov.io/github/NLR-Distribution-Suite/grid-data-models) •  [![CodeFactor](https://www.codefactor.io/repository/github/nlr-distribution-suite/grid-data-models/badge)](https://www.codefactor.io/repository/github/nlr-distribution-suite/grid-data-models) • ![MCP Server](https://img.shields.io/badge/MCP_Server-enabled-brightgreen) • ![MCP Tools](https://img.shields.io/badge/MCP_Tools-20-blue) • [![GitHub issues](https://img.shields.io/github/issues/NLR-Distribution-Suite/grid-data-models)](https://github.com/NLR-Distribution-Suite/grid-data-models/issues) • [![License](https://img.shields.io/github/license/NLR-Distribution-Suite/grid-data-models)](https://github.com/NLR-Distribution-Suite/grid-data-models/blob/main/LICENSE.txt) •  [![PyPI Downloads](https://static.pepy.tech/personalized-badge/grid-data-models?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/grid-data-models) • [![Generate LinkedIn Post Draft](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/linkedin_draft.yml/badge.svg)](https://github.com/NLR-Distribution-Suite/grid-data-models/actions/workflows/linkedin_draft.yml)
 
 # Grid Data Models (GDM)
 

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

@@ -33,7 +33,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-mcp = ["mcp>=1.27.2"]
+mcp = ["mcp>=1.28.0"]
 dev = ["pre-commit", "pytest", "pytest-cov", "pytest-doctestplus", "pytest-asyncio", "ruff", "docutils"]
 doc = [
   "jupyter-book>=2.1.5,<3",

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

@@ -7,6 +7,7 @@ from gdm.distribution.components.distribution_solar import DistributionSolar
 from gdm.distribution.components.distribution_transformer import DistributionTransformer
 from gdm.distribution.components.distribution_vsource import DistributionVoltageSource
 from gdm.distribution.components.geometry_branch import GeometryBranch
+from gdm.distribution.components.geometry_switch import GeometrySwitch
 from gdm.distribution.components.matrix_impedance_branch import MatrixImpedanceBranch
 from gdm.distribution.components.matrix_impedance_fuse import MatrixImpedanceFuse
 from gdm.distribution.components.matrix_impedance_recloser import MatrixImpedanceRecloser

{grid_data_models-2.3.4 → grid_data_models-2.3.6}/src/gdm/distribution/components/base/distribution_transformer_base.py

@@ -44,6 +44,14 @@ class DistributionTransformerBase(InServiceDistributionComponentBase, ABC):
             order defined in the DistributionTransformerModel""",
         ),
     ]
+    tap_positions: Annotated[
+        list[list[float]] | None,
+        Field(
+            default=None,
+            description="Current tap position (per-unit) for each phase in each winding, "
+            "matching the order of winding_phases. Defaults to 1.0 for all phases.",
+        ),
+    ]
 
     equipment: Annotated[
         DistributionTransformerEquipment,
@@ -67,6 +75,26 @@ class DistributionTransformerBase(InServiceDistributionComponentBase, ABC):
                     "Center tapped transformer must have same bus on the secondary side (bus 2 and 3)."
                 )
 
+    def _validate_tap_positions(self) -> None:
+        """Validate and default tap_positions field."""
+        if self.tap_positions is None:
+            self.tap_positions = [[1.0] * len(phases) for phases in self.winding_phases]
+
+        if len(self.tap_positions) != len(self.winding_phases):
+            msg = (
+                f"Number of tap_positions entries {len(self.tap_positions)} must equal "
+                f"number of windings {len(self.winding_phases)}"
+            )
+            raise ValueError(msg)
+
+        for i, (taps, phases) in enumerate(zip(self.tap_positions, self.winding_phases)):
+            if len(taps) != len(phases):
+                msg = (
+                    f"tap_positions[{i}] has {len(taps)} entries but "
+                    f"winding_phases[{i}] has {len(phases)} phases"
+                )
+                raise ValueError(msg)
+
     @model_validator(mode="after")
     def validate_fields_base(self) -> "DistributionTransformerBase":
         """Custom validator for distribution transformer."""
@@ -77,6 +105,8 @@ class DistributionTransformerBase(InServiceDistributionComponentBase, ABC):
             )
             raise ValueError(msg)
 
+        self._validate_tap_positions()
+
         for wdg, pw_phases in zip(self.equipment.windings, self.winding_phases):
             pw_phases_length = len(pw_phases) - 1 if Phase.N in pw_phases else len(pw_phases)
 

{grid_data_models-2.3.4 → grid_data_models-2.3.6}/src/gdm/distribution/components/distribution_capacitor.py

@@ -3,7 +3,7 @@
 from collections import defaultdict
 from typing import Annotated
 
-from pydantic import Field, model_validator
+from pydantic import Field, computed_field, model_validator
 
 from gdm.distribution.components.distribution_bus import DistributionBus
 from gdm.distribution.equipment.capacitor_equipment import CapacitorEquipment
@@ -49,6 +49,19 @@ class DistributionCapacitor(InServiceDistributionComponentBase):
     ]
 
     equipment: Annotated[CapacitorEquipment, Field(..., description="Capacitor model.")]
+    state: Annotated[
+        list[bool],
+        Field(
+            ...,
+            description="List of boolean states indicating whether each bank is on (True) or off (False).",
+        ),
+    ]
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def num_banks(self) -> int:
+        """Number of banks in the capacitor."""
+        return len(self.state)
 
     @classmethod
     def aggregate(
@@ -86,6 +99,7 @@ class DistributionCapacitor(InServiceDistributionComponentBase):
                 rated_voltage=bus.rated_voltage,
                 voltage_type=bus.voltage_type,
             ),
+            state=[True] * len(phase_caps),
         )
 
     @model_validator(mode="after")
@@ -126,9 +140,8 @@ class DistributionCapacitor(InServiceDistributionComponentBase):
             feeder=DistributionFeeder.example(),
             phases=[Phase.A, Phase.B, Phase.C],
             equipment=CapacitorEquipment.example(),
+            state=[True, True, True],
             controllers=[
                 VoltageCapacitorController.example(),
-                VoltageCapacitorController.example(),
-                VoltageCapacitorController.example(),
             ],
         )

{grid_data_models-2.3.4 → grid_data_models-2.3.6}/src/gdm/distribution/components/distribution_regulator.py

@@ -63,6 +63,7 @@ class DistributionRegulator(DistributionTransformerBase):
                 ),
             ],
             winding_phases=[[Phase.A, Phase.B, Phase.C], [Phase.A, Phase.B, Phase.C]],
+            tap_positions=[[1.0, 1.0, 1.0], [1.0, 1.0, 1.0]],
             equipment=DistributionTransformerEquipment.example(),
             controllers=[
                 RegulatorController.example(),

{grid_data_models-2.3.4 → grid_data_models-2.3.6}/src/gdm/distribution/components/distribution_transformer.py

@@ -42,5 +42,6 @@ class DistributionTransformer(DistributionTransformerBase):
             substation=DistributionSubstation.example(),
             feeder=DistributionFeeder.example(),
             winding_phases=[[Phase.A, Phase.B, Phase.C], [Phase.A, Phase.B, Phase.C]],
+            tap_positions=[[1.0, 1.0, 1.0], [1.0, 1.0, 1.0]],
             equipment=DistributionTransformerEquipment.example(),
         )

grid_data_models-2.3.6/src/gdm/distribution/components/geometry_switch.py

@@ -0,0 +1,122 @@
+"""This module contains geometry branch."""
+
+from typing import Annotated
+
+from pydantic import Field
+
+from gdm.distribution.components.base.distribution_switch_base import (
+    DistributionSwitchBase,
+)
+from gdm.distribution.equipment.geometry_branch_equipment import (
+    GeometryBranchEquipment,
+)
+from gdm.distribution.components.distribution_feeder import DistributionFeeder
+from gdm.distribution.components.distribution_substation import (
+    DistributionSubstation,
+)
+from gdm.distribution.components.distribution_bus import DistributionBus
+from gdm.distribution.enums import Phase
+from gdm.quantities import Voltage, Distance
+
+from gdm.distribution.components.matrix_impedance_switch import MatrixImpedanceSwitch
+from gdm.distribution.equipment import (
+    ConcentricCableEquipment,
+)
+from gdm.distribution.equipment.matrix_impedance_switch_equipment import (
+    MatrixImpedanceSwitchEquipment,
+)
+
+
+class GeometrySwitch(DistributionSwitchBase):
+    """Data model for distribution branches based on line geometry."""
+
+    equipment: Annotated[
+        GeometryBranchEquipment,
+        Field(..., description="Geometry branch equipment."),
+    ]
+
+    def validate_fields(self) -> "GeometrySwitch":
+        """Custom validator for geometry branch fields."""
+        if len(self.phases) != len(self.equipment.conductors):
+            msg = "Number of phases is not equal to number of wires."
+            raise ValueError(msg)
+        return self
+
+    def to_matrix_representation(
+        self, frequency_hz: float = 60, soil_resistivity_ohm_m: float = 100
+    ) -> MatrixImpedanceSwitch:
+        """
+        Converts the geometry-based branch model to a matrix impedance representation.
+
+        This method transforms the current `GeometryBranch` instance into a `MatrixImpedanceBranch`
+        by calculating the impedance matrix based on the specified frequency and soil resistivity.
+        The conversion process involves using the equipment's matrix representation method to obtain
+        the necessary impedance data.
+
+        Parameters
+        ----------
+        frequency_hz : float, optional
+            The frequency in hertz used for impedance calculations. Defaults to 60 Hz.
+        soil_resistivity_ohm_m : float, optional
+            The soil resistivity in ohm-meters used for impedance calculations. Defaults to 100 ohm-m.
+
+        Returns
+        -------
+        MatrixImpedanceBranch
+            A new instance of `MatrixImpedanceBranch` representing the converted geometry branch.
+
+        Notes
+        -----
+        - The method uses the number of neutral phases to assist in the impedance calculation.
+        - This conversion is essential for systems that require matrix impedance representations
+            for detailed electrical analysis.
+
+        """
+        equipment = self.equipment.to_matrix_representation(
+            frequency_hz,
+            soil_resistivity_ohm_m,
+            n_neutrals=len([phs for phs in self.phases if phs == Phase.N]),
+        )
+        if isinstance(self.equipment.conductors[0], ConcentricCableEquipment):
+            phases = self.phases + [Phase.N for _ in self.phases]
+            equipment.kron_reduce(phases)
+
+        switch_equipment = MatrixImpedanceSwitchEquipment(
+            **equipment.model_dump(exclude_none=True)
+        )
+
+        return MatrixImpedanceSwitch(
+            buses=self.buses,
+            length=self.length,
+            phases=self.phases,
+            substation=self.substation,
+            feeder=self.feeder,
+            name=self.name,
+            equipment=switch_equipment,
+            is_closed=self.is_closed,
+        )
+
+    @classmethod
+    def example(cls) -> "GeometrySwitch":
+        """Example for geometry branch."""
+        buses = [
+            DistributionBus(
+                voltage_type="line-to-ground",
+                phases=[Phase.A, Phase.B, Phase.C],
+                rated_voltage=Voltage(400, "volt"),
+                substation=DistributionSubstation.example(),
+                feeder=DistributionFeeder.example(),
+                name=bus_name,
+            )
+            for bus_name in ["Branch-DistBus1", "Branch-DistBus2"]
+        ]
+        return GeometrySwitch(
+            buses=buses,
+            length=Distance(130.2, "meter"),
+            phases=[Phase.A, Phase.B, Phase.C],
+            substation=DistributionSubstation.example(),
+            feeder=DistributionFeeder.example(),
+            name="DistBranch1",
+            is_closed=[True, True, True],
+            equipment=GeometryBranchEquipment.example(),
+        )

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

@@ -7,6 +7,7 @@ from pathlib import Path
 import tempfile
 import random
 
+from gdm.distribution.components.geometry_switch import GeometrySwitch
 from infrasys.time_series_models import TimeSeriesData, SingleTimeSeries
 from shapely import Point, LineString, union_all
 from infrasys import Component, System
@@ -951,7 +952,7 @@ 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))
+        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/src/gdm/distribution/upgrade_handler/from__2_3_4__to__2_3_5.py

@@ -0,0 +1,15 @@
+from loguru import logger
+from infrasys.migrations.metadata_migration import migrate_component_metadata
+
+
+def from__2_3_4__to__2_3_5(data: dict, from_version: str, to_version: str) -> dict:
+    logger.info(f"Upgrading DistributionSystem from verion {from_version} to {to_version}")
+    data["data_format_version"] = str(to_version)
+    number_of_components_before = len(data["components"])
+    data["components"] = migrate_component_metadata(data["components"])
+    number_of_components_after = len(data["components"])
+    assert (
+        number_of_components_before == number_of_components_after
+    ), "Number of components should be the same before and after model upgrade"
+
+    return data

grid_data_models-2.3.6/src/gdm/distribution/upgrade_handler/from__2_3_5__to__2_3_6.py

@@ -0,0 +1,70 @@
+from loguru import logger
+from infrasys.migrations.metadata_migration import migrate_component_metadata
+
+
+TRANSFORMER_TYPES = {"DistributionTransformer", "DistributionRegulator"}
+CAPACITOR_TYPE = "DistributionCapacitor"
+
+
+def _get_component_type(component: dict) -> str | None:
+    metadata = component.get("__metadata__", {})
+    if "fields" in metadata:
+        return metadata["fields"].get("type")
+    return metadata.get("type")
+
+
+def _add_tap_positions(obj: dict) -> None:
+    """Add tap_positions field to transformer-based components if missing."""
+    component_type = _get_component_type(obj)
+    if component_type in TRANSFORMER_TYPES:
+        if "tap_positions" not in obj:
+            winding_phases = obj.get("winding_phases", [])
+            obj["tap_positions"] = [[1.0] * len(phases) for phases in winding_phases]
+            logger.debug(f"Migrated {component_type}: added default tap_positions")
+
+    # Recurse into nested dicts/lists
+    for value in obj.values():
+        if isinstance(value, dict):
+            _add_tap_positions(value)
+        elif isinstance(value, list):
+            for item in value:
+                if isinstance(item, dict):
+                    _add_tap_positions(item)
+
+
+def _add_capacitor_state(obj: dict) -> None:
+    """Add state field to DistributionCapacitor components if missing."""
+    component_type = _get_component_type(obj)
+    if component_type == CAPACITOR_TYPE:
+        if "state" not in obj:
+            # Default: all banks on, one per phase
+            phases = obj.get("phases", [])
+            obj["state"] = [True] * len(phases)
+            logger.debug("Migrated DistributionCapacitor: added default state (all True)")
+
+    # Recurse into nested dicts/lists
+    for value in obj.values():
+        if isinstance(value, dict):
+            _add_capacitor_state(value)
+        elif isinstance(value, list):
+            for item in value:
+                if isinstance(item, dict):
+                    _add_capacitor_state(item)
+
+
+def from__2_3_5__to__2_3_6(data: dict, from_version: str, to_version: str) -> dict:
+    logger.info(f"Upgrading DistributionSystem from verion {from_version} to {to_version}")
+    data["data_format_version"] = str(to_version)
+    number_of_components_before = len(data["components"])
+
+    for component in data["components"]:
+        _add_tap_positions(component)
+        _add_capacitor_state(component)
+
+    data["components"] = migrate_component_metadata(data["components"])
+    number_of_components_after = len(data["components"])
+    assert (
+        number_of_components_before == number_of_components_after
+    ), "Number of components should be the same before and after model upgrade"
+
+    return data

{grid_data_models-2.3.4 → grid_data_models-2.3.6}/src/gdm/distribution/upgrade_handler/upgrade_handler.py

@@ -22,6 +22,8 @@ from gdm.distribution.upgrade_handler.from__2_3_0__to__2_3_1 import from__2_3_0_
 from gdm.distribution.upgrade_handler.from__2_3_1__to__2_3_2 import from__2_3_1__to__2_3_2
 from gdm.distribution.upgrade_handler.from__2_3_2__to__2_3_3 import from__2_3_2__to__2_3_3
 from gdm.distribution.upgrade_handler.from__2_3_3__to__2_3_4 import from__2_3_3__to__2_3_4
+from gdm.distribution.upgrade_handler.from__2_3_4__to__2_3_5 import from__2_3_4__to__2_3_5
+from gdm.distribution.upgrade_handler.from__2_3_5__to__2_3_6 import from__2_3_5__to__2_3_6
 
 
 def fix_version(version):
@@ -124,6 +126,16 @@ class UpgradeHandler(BaseModel):
             from_version="2.3.3",
             to_version="2.3.4",
         ),
+        UpgradeSchema(
+            method=from__2_3_4__to__2_3_5,
+            from_version="2.3.4",
+            to_version="2.3.5",
+        ),
+        UpgradeSchema(
+            method=from__2_3_5__to__2_3_6,
+            from_version="2.3.5",
+            to_version="2.3.6",
+        ),
     ]
 
     @model_validator(mode="after")

grid_data_models-2.3.6/src/gdm/distribution/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Distribution utility functions."""
+
+from gdm.distribution.utils.aggregate_components import aggregate_single_phase_transformers
+
+__all__ = ["aggregate_single_phase_transformers"]

grid_data_models-2.3.6/src/gdm/distribution/utils/aggregate_components.py

@@ -0,0 +1,181 @@
+"""Utility to aggregate parallel single-phase transformer-based components into three-phase."""
+
+from collections import defaultdict
+from typing import TypeVar
+
+from gdm.distribution import DistributionSystem
+from gdm.distribution.components.base.distribution_transformer_base import (
+    DistributionTransformerBase,
+)
+from gdm.distribution.components.distribution_transformer import DistributionTransformer
+from gdm.distribution.components.distribution_regulator import DistributionRegulator
+from gdm.distribution.equipment.distribution_transformer_equipment import (
+    DistributionTransformerEquipment,
+    WindingEquipment,
+)
+
+T = TypeVar("T", bound=DistributionTransformerBase)
+
+
+def _bus_key(component: DistributionTransformerBase) -> tuple[str, ...]:
+    """Return a hashable key of bus names for grouping parallel components."""
+    return tuple(bus.name for bus in component.buses)
+
+
+def _is_single_phase(component: DistributionTransformerBase) -> bool:
+    """Check if all windings are single-phase."""
+    return all(wdg.num_phases == 1 for wdg in component.equipment.windings)
+
+
+def _merge_windings(components: list[DistributionTransformerBase]) -> list[WindingEquipment]:
+    """Merge single-phase windings into three-phase windings.
+
+    Assumes all components have the same number of windings and compatible equipment.
+    Rated power is summed; resistance and tap bounds are averaged.
+    """
+    num_windings = len(components[0].equipment.windings)
+    merged = []
+    for wdg_idx in range(num_windings):
+        ref_wdg = components[0].equipment.windings[wdg_idx]
+        total_power = sum(comp.equipment.windings[wdg_idx].rated_power for comp in components)
+        avg_resistance = sum(
+            comp.equipment.windings[wdg_idx].resistance for comp in components
+        ) / len(components)
+        all_taps = [comp.equipment.windings[wdg_idx].tap_positions[0] for comp in components]
+        merged.append(
+            WindingEquipment(
+                name=ref_wdg.name,
+                resistance=avg_resistance,
+                is_grounded=ref_wdg.is_grounded,
+                rated_voltage=ref_wdg.rated_voltage,
+                voltage_type=ref_wdg.voltage_type,
+                rated_power=total_power,
+                num_phases=len(components),
+                connection_type=ref_wdg.connection_type,
+                tap_positions=all_taps,
+                total_taps=ref_wdg.total_taps,
+                min_tap_pu=ref_wdg.min_tap_pu,
+                max_tap_pu=ref_wdg.max_tap_pu,
+            )
+        )
+    return merged
+
+
+def _merge_group(components: list[T]) -> T:
+    """Merge a group of parallel single-phase components into one three-phase component.
+
+    Parameters
+    ----------
+    components : list[T]
+        List of single-phase components connected to the same buses.
+
+    Returns
+    -------
+    T
+        A single three-phase component of the same type.
+    """
+    ref = components[0]
+    component_type = type(ref)
+
+    merged_windings = _merge_windings(components)
+
+    # Build merged winding_phases and tap_positions from each component's per-winding phases
+    merged_winding_phases = []
+    merged_tap_positions = []
+    for wdg_idx in range(len(ref.equipment.windings)):
+        phases = []
+        taps = []
+        for comp in components:
+            phases.extend(comp.winding_phases[wdg_idx])
+            if comp.tap_positions is not None:
+                taps.extend(comp.tap_positions[wdg_idx])
+            else:
+                taps.extend([1.0] * len(comp.winding_phases[wdg_idx]))
+        merged_winding_phases.append(phases)
+        merged_tap_positions.append(taps)
+
+    merged_equipment = DistributionTransformerEquipment(
+        name=f"{ref.equipment.name}_merged",
+        mounting=ref.equipment.mounting,
+        pct_no_load_loss=ref.equipment.pct_no_load_loss,
+        pct_full_load_loss=ref.equipment.pct_full_load_loss,
+        windings=merged_windings,
+        coupling_sequences=ref.equipment.coupling_sequences,
+        winding_reactances=ref.equipment.winding_reactances,
+        is_center_tapped=False,
+    )
+
+    kwargs = {
+        "name": f"{ref.name}_merged",
+        "buses": ref.buses,
+        "winding_phases": merged_winding_phases,
+        "tap_positions": merged_tap_positions,
+        "equipment": merged_equipment,
+    }
+
+    # Preserve substation/feeder if present
+    if hasattr(ref, "substation") and ref.substation is not None:
+        kwargs["substation"] = ref.substation
+    if hasattr(ref, "feeder") and ref.feeder is not None:
+        kwargs["feeder"] = ref.feeder
+
+    # For regulators, merge controllers
+    if component_type is DistributionRegulator:
+        controllers = []
+        for comp in components:
+            controllers.extend(comp.controllers)
+        kwargs["controllers"] = controllers
+
+    return component_type(**kwargs)
+
+
+def aggregate_single_phase_transformers(
+    system: DistributionSystem,
+) -> DistributionSystem:
+    """Replace groups of parallel single-phase transformer-based components with
+    a single three-phase equivalent.
+
+    Finds all DistributionTransformer and DistributionRegulator components that are:
+    - Single-phase (all windings have num_phases == 1)
+    - Connected to the same set of buses
+
+    Groups of 3 such components are merged into one three-phase component.
+    The original single-phase components are removed and the merged component is added.
+
+    Parameters
+    ----------
+    system : DistributionSystem
+        Input distribution system (will be modified in place).
+
+    Returns
+    -------
+    DistributionSystem
+        The same system reference, modified with merged components.
+    """
+    for component_type in (DistributionTransformer, DistributionRegulator):
+        # Group single-phase components by their bus connections
+        groups: dict[tuple[str, ...], list] = defaultdict(list)
+        for comp in system.get_components(component_type):
+            if _is_single_phase(comp):
+                groups[_bus_key(comp)].append(comp)
+
+        # Merge groups of exactly 3 parallel single-phase components
+        for key, group in groups.items():
+            if len(group) != 3:
+                continue
+
+            merged = _merge_group(group)
+
+            # Remove originals and add merged.
+            # cascade_down=False because grouped components share children (buses, equipment)
+            # that the merged component still references.
+            for comp in group:
+                system.remove_component(comp, cascade_down=False)
+
+            # Add composed children (windings, equipment) before the merged component
+            for winding in merged.equipment.windings:
+                system.add_component(winding)
+            system.add_component(merged.equipment)
+            system.add_component(merged)
+
+    return system

{grid_data_models-2.3.4 → grid_data_models-2.3.6}/src/gdm/version.py

@@ -3,7 +3,7 @@ import subprocess
 import platform
 import sys
 
-VERSION = "2.3.4"
+VERSION = "2.3.6"
 SUPPORTED_VERSIONS = [VERSION]