Add a module for grid connection points

Grid connection points are nodes in the component graph that abstract
grids in a microgrid. Such nodes have their own metadata, which include
their rated fuse limits. Microgrids with zero or one grid connection points
are accepted. Note that a microgrid may have zero grid connection points,
if it is configured as an island.

This commit adds a module exposing a representation of such grid connection
points. The module is named `frequenz.sdk.microgrid.grid`.

The `grid` module exposes a singleton object that represents the grid
connection point. It gets initialized when `microgrid.initialize()` is
called. It can be obtained by calling `microgrid.grid_connection.get()`.

Signed-off-by: Tiyash Basu <[email protected]>

Author: tiyash-basu-frequenz

RELEASE_NOTES.md

@@ -102,6 +102,10 @@ This release replaces the `@actor` decorator with a new `Actor` class.
 
 - `Actor`: This new class inherits from `BackgroundService` and it replaces the `@actor` decorator.
 
+- Calling `microgrid.initialize()` now also initializes the microgrid's grid connection point as a singleton object of a newly added type `Grid`. This object can be obtained by calling `microgrid.grid.get()`. This object exposes the max current that can course through the grid connection point, which is useful for the power distribution algorithm. The max current is provided by the Microgrid API, and can be obtained by calling `microgrid.grid.get().max_current`.
+
+  Note that a microgrid is allowed to have zero or one grid connection point. Microgrids configured as islands will have zero grid connection points, and microgrids configured as grid-connected will have one grid connection point.
+
 ## Bug Fixes
 
 - Fixes a bug in the ring buffer updating the end timestamp of gaps when they are outdated.

src/frequenz/sdk/microgrid/__init__.py

@@ -8,7 +8,7 @@
 """
 
 from ..actor import ResamplerConfig
-from . import _data_pipeline, client, component, connection_manager
+from . import _data_pipeline, client, component, connection_manager, grid
 from ._data_pipeline import battery_pool, ev_charger_pool, logical_meter
 from ._graph import ComponentGraph
 
@@ -22,6 +22,11 @@ async def initialize(host: str, port: int, resampler_config: ResamplerConfig) ->
         resampler_config: Configuration for the resampling actor.
     """
     await connection_manager.initialize(host, port)
+
+    api_client = connection_manager.get().api_client
+    components = await api_client.components()
+    grid.initialize(components)
+
     await _data_pipeline.initialize(resampler_config)
 
 
@@ -32,5 +37,6 @@ async def initialize(host: str, port: int, resampler_config: ResamplerConfig) ->
     "component",
     "battery_pool",
     "ev_charger_pool",
+    "grid",
     "logical_meter",
 ]

src/frequenz/sdk/microgrid/grid.py

@@ -0,0 +1,71 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Grid connection point.
+
+This module provides the `Grid` type, which represents a grid connection point
+in a microgrid.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import Iterable, Optional
+
+from .component import Component
+from .component._component import ComponentCategory
+
+
+@dataclass(frozen=True)
+class Grid:
+    """A grid connection point."""
+
+    max_current: float
+    """The maximum current that can course through the grid connection point, in Amperes."""
+
+
+_GRID: Optional[Grid] = None
+
+
+def initialize(components: Iterable[Component]) -> None:
+    """Initialize the grid connection.
+
+    Args:
+        components: The components in the microgrid.
+
+    Raises:
+        RuntimeError: If there is more than 1 grid connection point in the
+            microgrid.
+    """
+    global _GRID  # pylint: disable=global-statement
+
+    grid_connections = list(
+        component
+        for component in components
+        if component.category == ComponentCategory.GRID
+    )
+
+    grid_connections_count = len(grid_connections)
+
+    if grid_connections_count == 0:
+        logging.info(
+            "No grid connection found for this microgrid. This is normal for an islanded microgrid."
+        )
+    elif grid_connections_count > 1:
+        raise RuntimeError(
+            f"Expected at most one grid connection, got {grid_connections_count}"
+        )
+    else:
+        max_current = grid_connections[0].metadata.max_current  # type: ignore
+        _GRID = Grid(max_current)
+
+
+def get() -> Optional[Grid]:
+    """Get the grid connection.
+
+    Note that a microgrid configured as an island will not have a grid
+    connection point. For such microgrids, this function will return `None`.
+
+    Returns:
+        The grid connection.
+    """
+    return _GRID

tests/microgrid/test_grid.py

@@ -0,0 +1,59 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""
+Tests for the `Grid` module.
+"""
+
+from frequenz.sdk import microgrid
+from frequenz.sdk.microgrid.component import Component, ComponentCategory, GridMetadata
+from frequenz.sdk.microgrid.grid import Grid
+
+
+async def test_grid() -> None:
+    """Test the grid connection module."""
+
+    # The tests here need to be in this exact sequence, because the grid connection
+    # is a singleton. Once it gets created, it stays in memory for the duration of
+    # the tests, unless we explicitly delete it.
+
+    # validate that islands with no grid connection are accepted.
+    components = [
+        Component(2, ComponentCategory.METER),
+    ]
+
+    microgrid.grid.initialize(components)
+
+    grid = microgrid.grid.get()
+    assert grid is None
+
+    # validate that the microgrid initialization fails when there are multiple
+    # grid connection points.
+    components = [
+        Component(1, ComponentCategory.GRID, None, GridMetadata(123.0)),
+        Component(2, ComponentCategory.GRID, None, GridMetadata(345.0)),
+        Component(3, ComponentCategory.METER),
+    ]
+
+    try:
+        microgrid.grid.initialize(components)
+        assert False, "Expected microgrid.grid.initialize to raise a RuntimeError."
+    except RuntimeError:
+        pass
+
+    grid = microgrid.grid.get()
+    assert grid is None
+
+    # validate that microgrids with one grid connection are accepted.
+    components = [
+        Component(1, ComponentCategory.GRID, None, GridMetadata(123.0)),
+        Component(2, ComponentCategory.METER),
+    ]
+
+    microgrid.grid.initialize(components)
+
+    grid = microgrid.grid.get()
+    assert grid == Grid(max_current=123.0)
+
+    max_current = grid.max_current
+    assert max_current == 123.0