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

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

@@ -166,4 +166,3 @@ cython_debug/
 .qodo
 .DS_Store
 *.dump
-uv.lock

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: grid-data-models
-Version: 2.3.3
+Version: 2.3.5
 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
-Author-email: Kapil Duwadi <Kapil.Duwadi@nrel.gov>, Aadil Latif <Aadil.Latif@nrel.gov>, Tarek Elgindy <tarek.elgindy@nrel.gov>
+Author-email: Aadil Latif <Aadil.Latif@nlr.gov>, Kapil Duwadi <Kapil.Duwadi@nrel.gov>, Tarek Elgindy <tarek.elgindy@nrel.gov>
 License-Expression: BSD-3-Clause
 License-File: LICENSE.txt
 Classifier: License :: OSI Approved :: BSD License
@@ -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.1
+Requires-Dist: infrasys~=1.2
 Requires-Dist: networkx
-Requires-Dist: pandas~=3.0.2
+Requires-Dist: pandas~=3.0.3
 Requires-Dist: plotly
 Requires-Dist: pydantic
 Requires-Dist: semver
@@ -30,18 +30,18 @@ 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: jupyter-book<3,>=2.1.5; 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.27.0; 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)
+[![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)
 
 # Grid Data Models (GDM)
 

{grid_data_models-2.3.3 → grid_data_models-2.3.5}/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)
+[![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)
 
 # Grid Data Models (GDM)
 

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

@@ -11,8 +11,8 @@ requires-python = ">=3.11"
 license = "BSD-3-Clause"
 keywords = []
 authors = [
+  { name = "Aadil Latif", email = "Aadil.Latif@nlr.gov" },
   { name = "Kapil Duwadi", email = "Kapil.Duwadi@nrel.gov" },
-  { name = "Aadil Latif", email = "Aadil.Latif@nrel.gov" },
   { name = "Tarek Elgindy", email = "tarek.elgindy@nrel.gov" },
 ]
 classifiers = [
@@ -24,19 +24,19 @@ dependencies = [
   "semver",
   "networkx", 
   "pydantic",
-  "infrasys~=1.1", 
+  "infrasys~=1.2", 
   "importlib_metadata",
   "typer",
-  "pandas~=3.0.2",
+  "pandas~=3.0.3",
   "geopandas",
   "plotly",
 ]
 
 [project.optional-dependencies]
-mcp = ["mcp>=1.27.0"]
+mcp = ["mcp>=1.28.0"]
 dev = ["pre-commit", "pytest", "pytest-cov", "pytest-doctestplus", "pytest-asyncio", "ruff", "docutils"]
 doc = [
-  "jupyter-book>=2.1.4,<3",
+  "jupyter-book>=2.1.5,<3",
   "sphinx",
   "pydata-sphinx-theme",
   "myst-parser",

{grid_data_models-2.3.3 → grid_data_models-2.3.5}/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.5/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.3 → grid_data_models-2.3.5}/src/gdm/distribution/controllers/distribution_regulator_controller.py

@@ -20,6 +20,17 @@ class RegulatorController(Component):
     """Data model for a Regulator Controller."""
 
     name: Annotated[str, Field("", description="Name of the regulator controller.")]
+
+    tapped_winding: Annotated[
+        Optional[int],
+        Field(
+            2,
+            ge=1,
+            le=3,
+            description="The index of the winding on the transformer that this controller is controlling.",
+        ),
+    ]
+
     delay: Annotated[
         Optional[Time],
         PINT_SCHEMA,

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

@@ -150,3 +150,43 @@ class BillingDemandBasis(str, Enum):
     PEAK_15MIN = "peak_15min"
     PEAK_HOUR = "peak_hour"
     CONTRACT_DEMAND = "contract_demand"
+
+
+class WholesaleMarketType(str, Enum):
+    DAY_AHEAD = "day_ahead"
+    REAL_TIME = "real_time"
+
+
+class AncillaryServiceType(str, Enum):
+    REGULATION_UP = "regulation_up"
+    REGULATION_DOWN = "regulation_down"
+    SPINNING_RESERVE = "spinning_reserve"
+    NON_SPINNING_RESERVE = "non_spinning_reserve"
+    FREQUENCY_RESPONSE = "frequency_response"
+    REACTIVE_SUPPLY = "reactive_supply"
+
+
+class CapacityMarketType(str, Enum):
+    FORWARD_CAPACITY = "forward_capacity"
+    RELIABILITY_MUST_RUN = "reliability_must_run"
+    RESOURCE_ADEQUACY = "resource_adequacy"
+
+
+class PricingNodeType(str, Enum):
+    LOAD_ZONE = "load_zone"
+    GENERATOR_NODE = "generator_node"
+    HUB = "hub"
+    INTERFACE = "interface"
+
+
+class AggregatorType(str, Enum):
+    DER = "der"
+    LOAD = "load"
+    GENERIC = "generic"
+
+
+class DemandResponseType(str, Enum):
+    ECONOMIC = "economic"
+    EMERGENCY = "emergency"
+    DIRECT_LOAD_CONTROL = "direct_load_control"
+    INTERRUPTIBLE = "interruptible"

{grid_data_models-2.3.3 → grid_data_models-2.3.5}/src/gdm/distribution/market/__init__.py

@@ -1,8 +1,14 @@
 from gdm.distribution.market.tariff import (
-    DistributionTariff,
-    SeasonalTOURates,
-    TOURatePeriod,
+    AncillaryServiceRate,
+    CapacityPayment,
     DemandCharge,
+    DistributionTariff,
     FixedCharge,
+    LMPRate,
+    PricingNode,
+    SeasonalTOURates,
     TieredRate,
+    TOURatePeriod,
+    TransmissionServiceCharge,
+    WholesaleMarketTariff,
 )

grid_data_models-2.3.5/src/gdm/distribution/market/aggregator.py

@@ -0,0 +1,259 @@
+"""Data models for resource aggregation in wholesale and demand response markets."""
+
+from typing import Annotated, Optional
+
+from pydantic import Field, model_validator
+from infrasys import Component
+
+from gdm.distribution.components.distribution_battery import DistributionBattery
+from gdm.distribution.components.distribution_solar import DistributionSolar
+from gdm.distribution.components.distribution_load import DistributionLoad
+from gdm.distribution.enums import (
+    AggregatorType,
+    AncillaryServiceType,
+    DemandResponseType,
+)
+from gdm.distribution.market.tariff import DistributionTariff, WholesaleMarketTariff
+from gdm.quantities import ActivePower
+
+
+class AggregatedDER(Component):
+    """A DER resource committed to an aggregation portfolio."""
+
+    name: str = ""
+    resource: Annotated[
+        DistributionBattery | DistributionSolar,
+        Field(..., description="The DER component being aggregated."),
+    ]
+    committed_capacity: Annotated[
+        ActivePower,
+        Field(
+            ...,
+            description="Active power capacity committed to the aggregation in kW.",
+            ge=0,
+        ),
+    ]
+
+    @classmethod
+    def example(cls) -> "AggregatedDER":
+        return AggregatedDER(
+            resource=DistributionBattery.example(),
+            committed_capacity=ActivePower(50, "kilowatt"),
+        )
+
+
+class AggregatedLoad(Component):
+    """A load resource committed to demand response aggregation."""
+
+    name: str = ""
+    resource: Annotated[
+        DistributionLoad,
+        Field(..., description="The load component being aggregated."),
+    ]
+    curtailable_capacity: Annotated[
+        ActivePower,
+        Field(
+            ...,
+            description="Active power capacity available for curtailment in kW.",
+            ge=0,
+        ),
+    ]
+    response_type: Annotated[
+        DemandResponseType,
+        Field(..., description="Type of demand response program."),
+    ]
+
+    @classmethod
+    def example(cls) -> "AggregatedLoad":
+        return AggregatedLoad(
+            resource=DistributionLoad.example(),
+            curtailable_capacity=ActivePower(25, "kilowatt"),
+            response_type=DemandResponseType.ECONOMIC,
+        )
+
+
+class DERAggregator(Component):
+    """Aggregates distributed energy resources for wholesale market participation."""
+
+    name: str = Field(..., description="Name of the DER aggregator")
+    aggregator_type: AggregatorType = Field(
+        default=AggregatorType.DER,
+        description="Type of aggregator.",
+    )
+    resources: Annotated[
+        list[AggregatedDER],
+        Field(..., min_length=1, description="DER resources in the aggregation portfolio."),
+    ]
+    offered_services: Annotated[
+        list[AncillaryServiceType],
+        Field(
+            default_factory=list,
+            description="Ancillary services the aggregator can provide.",
+        ),
+    ]
+    min_dispatch: Annotated[
+        ActivePower,
+        Field(
+            ...,
+            description="Minimum dispatchable capacity in kW.",
+            ge=0,
+        ),
+    ]
+    max_dispatch: Annotated[
+        ActivePower,
+        Field(
+            ...,
+            description="Maximum dispatchable capacity in kW.",
+            ge=0,
+        ),
+    ]
+    wholesale_tariff: Annotated[
+        Optional[WholesaleMarketTariff],
+        Field(None, description="Wholesale market tariff under which the aggregator settles."),
+    ]
+
+    @model_validator(mode="after")
+    def validate_dispatch_limits(self) -> "DERAggregator":
+        if self.max_dispatch < self.min_dispatch:
+            raise ValueError("max_dispatch must be >= min_dispatch")
+        return self
+
+    @classmethod
+    def example(cls) -> "DERAggregator":
+        return DERAggregator(
+            name="DER Portfolio Alpha",
+            resources=[AggregatedDER.example()],
+            offered_services=[
+                AncillaryServiceType.REGULATION_UP,
+                AncillaryServiceType.SPINNING_RESERVE,
+            ],
+            min_dispatch=ActivePower(10, "kilowatt"),
+            max_dispatch=ActivePower(100, "kilowatt"),
+        )
+
+
+class LoadAggregator(Component):
+    """Aggregates controllable loads for demand response programs."""
+
+    name: str = Field(..., description="Name of the load aggregator")
+    aggregator_type: AggregatorType = Field(
+        default=AggregatorType.LOAD,
+        description="Type of aggregator.",
+    )
+    resources: Annotated[
+        list[AggregatedLoad],
+        Field(..., min_length=1, description="Load resources in the aggregation portfolio."),
+    ]
+    total_curtailable_capacity: Annotated[
+        ActivePower,
+        Field(
+            ...,
+            description="Total curtailable capacity across all loads in kW.",
+            ge=0,
+        ),
+    ]
+    notification_lead_time_minutes: Annotated[
+        int,
+        Field(
+            ...,
+            description="Minimum advance notice required before curtailment in minutes.",
+            ge=0,
+        ),
+    ]
+    max_curtailment_duration_hours: Annotated[
+        float,
+        Field(
+            ...,
+            description="Maximum duration of a single curtailment event in hours.",
+            gt=0,
+        ),
+    ]
+    retail_tariff: Annotated[
+        Optional[DistributionTariff],
+        Field(None, description="Retail distribution tariff defining avoided cost for DR."),
+    ]
+
+    @classmethod
+    def example(cls) -> "LoadAggregator":
+        return LoadAggregator(
+            name="DR Program Beta",
+            resources=[AggregatedLoad.example()],
+            total_curtailable_capacity=ActivePower(500, "kilowatt"),
+            notification_lead_time_minutes=30,
+            max_curtailment_duration_hours=4.0,
+        )
+
+
+class Aggregator(Component):
+    """General-purpose aggregator that can bundle both DERs and loads."""
+
+    name: str = Field(..., description="Name of the aggregator")
+    aggregator_type: AggregatorType = Field(
+        default=AggregatorType.GENERIC,
+        description="Type of aggregator.",
+    )
+    der_resources: Annotated[
+        Optional[list[AggregatedDER]],
+        Field(None, description="DER resources in the portfolio."),
+    ]
+    load_resources: Annotated[
+        Optional[list[AggregatedLoad]],
+        Field(None, description="Load resources in the portfolio."),
+    ]
+    offered_services: Annotated[
+        list[AncillaryServiceType],
+        Field(
+            default_factory=list,
+            description="Ancillary services the aggregator can provide.",
+        ),
+    ]
+    min_dispatch: Annotated[
+        ActivePower,
+        Field(
+            ...,
+            description="Minimum dispatchable capacity in kW.",
+            ge=0,
+        ),
+    ]
+    max_dispatch: Annotated[
+        ActivePower,
+        Field(
+            ...,
+            description="Maximum dispatchable capacity in kW.",
+            ge=0,
+        ),
+    ]
+    wholesale_tariff: Annotated[
+        Optional[WholesaleMarketTariff],
+        Field(None, description="Wholesale market tariff under which DER resources settle."),
+    ]
+    retail_tariff: Annotated[
+        Optional[DistributionTariff],
+        Field(None, description="Retail distribution tariff defining avoided cost for DR."),
+    ]
+
+    @model_validator(mode="after")
+    def validate_has_resources(self) -> "Aggregator":
+        if not self.der_resources and not self.load_resources:
+            raise ValueError("Aggregator must have at least one DER or load resource")
+        return self
+
+    @model_validator(mode="after")
+    def validate_dispatch_limits(self) -> "Aggregator":
+        if self.max_dispatch < self.min_dispatch:
+            raise ValueError("max_dispatch must be >= min_dispatch")
+        return self
+
+    @classmethod
+    def example(cls) -> "Aggregator":
+        return Aggregator(
+            name="Mixed Portfolio Gamma",
+            der_resources=[AggregatedDER.example()],
+            load_resources=[AggregatedLoad.example()],
+            offered_services=[
+                AncillaryServiceType.REGULATION_UP,
+                AncillaryServiceType.FREQUENCY_RESPONSE,
+            ],
+            min_dispatch=ActivePower(10, "kilowatt"),
+            max_dispatch=ActivePower(200, "kilowatt"),
+        )