frequenz-gridpool 0.3.0__tar.gz → 0.4.0__tar.gz

{frequenz_gridpool-0.3.0/src/frequenz_gridpool.egg-info → frequenz_gridpool-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-gridpool
-Version: 0.3.0
+Version: 0.4.0
 Summary: High-level interface to grid pools for the Frequenz platform.
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT
@@ -24,7 +24,10 @@ Requires-Dist: marshmallow-dataclass<9,>=8.7.1
 Requires-Dist: asyncclick<9,>=8.3.0.4
 Requires-Dist: typing-extensions<5,>=4.14.1
 Requires-Dist: frequenz-microgrid-component-graph<0.4,>=0.3.4
-Requires-Dist: frequenz-client-assets<0.3,>=0.2.0
+Requires-Dist: frequenz-client-assets<0.4,>=0.3.0
+Provides-Extra: render-graph
+Requires-Dist: matplotlib<4,>=3.7.0; extra == "render-graph"
+Requires-Dist: networkx<4,>=3.0; extra == "render-graph"
 Provides-Extra: dev-flake8
 Requires-Dist: flake8==7.3.0; extra == "dev-flake8"
 Requires-Dist: flake8-docstrings==1.7.0; extra == "dev-flake8"
@@ -35,19 +38,20 @@ Provides-Extra: dev-formatting
 Requires-Dist: black==25.11.0; extra == "dev-formatting"
 Requires-Dist: isort==7.0.0; extra == "dev-formatting"
 Provides-Extra: dev-mkdocs
-Requires-Dist: Markdown==3.10; extra == "dev-mkdocs"
+Requires-Dist: Markdown==3.10.2; extra == "dev-mkdocs"
 Requires-Dist: black==25.11.0; extra == "dev-mkdocs"
 Requires-Dist: mike==2.1.3; extra == "dev-mkdocs"
 Requires-Dist: mkdocs-gen-files==0.5.0; extra == "dev-mkdocs"
 Requires-Dist: mkdocs-literate-nav==0.6.2; extra == "dev-mkdocs"
 Requires-Dist: mkdocs-macros-plugin==1.5.0; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-material==9.7.0; extra == "dev-mkdocs"
-Requires-Dist: mkdocstrings[python]==1.0.0; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-material==9.7.3; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings[python]==1.0.3; extra == "dev-mkdocs"
 Requires-Dist: mkdocstrings-python==1.19.0; extra == "dev-mkdocs"
 Requires-Dist: frequenz-repo-config[lib]==0.13.7; extra == "dev-mkdocs"
 Provides-Extra: dev-mypy
-Requires-Dist: mypy==1.19.0; extra == "dev-mypy"
-Requires-Dist: types-Markdown==3.10.0.20251106; extra == "dev-mypy"
+Requires-Dist: mypy==1.19.1; extra == "dev-mypy"
+Requires-Dist: types-networkx>=3.6.1.20251220; extra == "dev-mypy"
+Requires-Dist: types-Markdown==3.10.2.20260211; extra == "dev-mypy"
 Requires-Dist: frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-mypy"
 Provides-Extra: dev-noxfile
 Requires-Dist: nox==2025.11.12; extra == "dev-noxfile"
@@ -55,14 +59,14 @@ Requires-Dist: frequenz-repo-config[lib]==0.13.7; extra == "dev-noxfile"
 Provides-Extra: dev-pylint
 Requires-Dist: frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
 Provides-Extra: dev-pytest
-Requires-Dist: pytest==8.4.1; extra == "dev-pytest"
-Requires-Dist: pylint==4.0.4; extra == "dev-pytest"
+Requires-Dist: pytest==9.0.2; extra == "dev-pytest"
+Requires-Dist: pylint==4.0.5; extra == "dev-pytest"
 Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.13.7; extra == "dev-pytest"
 Requires-Dist: pytest-mock==3.15.1; extra == "dev-pytest"
 Requires-Dist: pytest-asyncio==1.3.0; extra == "dev-pytest"
 Requires-Dist: async-solipsism==0.9; extra == "dev-pytest"
 Provides-Extra: dev
-Requires-Dist: frequenz-gridpool[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]; extra == "dev"
+Requires-Dist: frequenz-gridpool[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest,render-graph]; extra == "dev"
 Dynamic: license-file
 
 # Frequenz Gridpool Library
@@ -85,6 +89,50 @@ The following platforms are officially supported (tested):
 - **Operating System:** Ubuntu Linux 20.04
 - **Architectures:** amd64, arm64
 
+## CLI
+
+This package ships the `gridpool-cli` command with two subcommands.
+
+### Setup
+
+Set the Assets API credentials before running the CLI:
+
+```bash
+export ASSETS_API_URL="grpc://..."
+export ASSETS_API_AUTH_KEY="..."
+export ASSETS_API_SIGN_SECRET="..."
+```
+
+### Print component formulas
+
+```bash
+gridpool-cli print-formulas <microgrid_id>
+```
+
+Optional prefix formatting:
+
+```bash
+gridpool-cli print-formulas <microgrid_id> --prefix "{microgrid_id}.{component}"
+```
+
+### Render component graph
+
+Rendering requires optional dependencies. Install with:
+
+```bash
+pip install frequenz-gridpool[render-graph]
+```
+
+```bash
+gridpool-cli render-graph <microgrid_id>
+```
+
+To save without opening a window:
+
+```bash
+gridpool-cli render-graph <microgrid_id> --no-show --output component_graph.png
+```
+
 ## Contributing
 
 If you want to know how to build this project and contribute to it, please

{frequenz_gridpool-0.3.0 → frequenz_gridpool-0.4.0}/README.md

@@ -18,6 +18,50 @@ The following platforms are officially supported (tested):
 - **Operating System:** Ubuntu Linux 20.04
 - **Architectures:** amd64, arm64
 
+## CLI
+
+This package ships the `gridpool-cli` command with two subcommands.
+
+### Setup
+
+Set the Assets API credentials before running the CLI:
+
+```bash
+export ASSETS_API_URL="grpc://..."
+export ASSETS_API_AUTH_KEY="..."
+export ASSETS_API_SIGN_SECRET="..."
+```
+
+### Print component formulas
+
+```bash
+gridpool-cli print-formulas <microgrid_id>
+```
+
+Optional prefix formatting:
+
+```bash
+gridpool-cli print-formulas <microgrid_id> --prefix "{microgrid_id}.{component}"
+```
+
+### Render component graph
+
+Rendering requires optional dependencies. Install with:
+
+```bash
+pip install frequenz-gridpool[render-graph]
+```
+
+```bash
+gridpool-cli render-graph <microgrid_id>
+```
+
+To save without opening a window:
+
+```bash
+gridpool-cli render-graph <microgrid_id> --no-show --output component_graph.png
+```
+
 ## Contributing
 
 If you want to know how to build this project and contribute to it, please

frequenz_gridpool-0.4.0/RELEASE_NOTES.md

@@ -0,0 +1,20 @@
+# Frequenz Gridpool Library Release Notes
+
+## Summary
+
+This release adds default formulas for AC energy metrics when they are not
+explicitly configured.
+
+## Upgrading
+
+* Update assets client to v0.3.0.
+
+## New Features
+
+* Added default summation formulas for `AC_ENERGY_ACTIVE`,
+  `AC_ENERGY_ACTIVE_CONSUMED`, and `AC_ENERGY_ACTIVE_DELIVERED` when formulas are
+  not provided. The defaults are built from the component IDs configured for the
+  component type.
+
+## Bug Fixes
+

{frequenz_gridpool-0.3.0 → frequenz_gridpool-0.4.0}/pyproject.toml

@@ -3,7 +3,7 @@
 
 [build-system]
 requires = [
-  "setuptools == 80.9.0",
+  "setuptools == 80.10.1",
   "setuptools_scm[toml] == 9.2.2",
   "frequenz-repo-config[lib] == 0.13.7",
 ]
@@ -30,7 +30,7 @@ dependencies = [
   "asyncclick >= 8.3.0.4, < 9",
   "typing-extensions >= 4.14.1, < 5",
   "frequenz-microgrid-component-graph >= 0.3.4, < 0.4",
-  "frequenz-client-assets >= 0.2.0, < 0.3",
+  "frequenz-client-assets >= 0.3.0, < 0.4",
 ]
 dynamic = ["version"]
 
@@ -42,6 +42,11 @@ name = "Frequenz Energy-as-a-Service GmbH"
 email = "floss@frequenz.com"
 
 [project.optional-dependencies]
+render-graph = [
+  "matplotlib >= 3.7.0, < 4",
+  "networkx >= 3.0, < 4",
+]
+
 dev-flake8 = [
   "flake8 == 7.3.0",
   "flake8-docstrings == 1.7.0",
@@ -51,20 +56,21 @@ dev-flake8 = [
 ]
 dev-formatting = ["black == 25.11.0", "isort == 7.0.0"]
 dev-mkdocs = [
-  "Markdown == 3.10",
+  "Markdown == 3.10.2",
   "black == 25.11.0",
   "mike == 2.1.3",
   "mkdocs-gen-files == 0.5.0",
   "mkdocs-literate-nav == 0.6.2",
   "mkdocs-macros-plugin == 1.5.0",
-  "mkdocs-material == 9.7.0",
-  "mkdocstrings[python] == 1.0.0",
+  "mkdocs-material == 9.7.3",
+  "mkdocstrings[python] == 1.0.3",
   "mkdocstrings-python == 1.19.0",
   "frequenz-repo-config[lib] == 0.13.7",
 ]
 dev-mypy = [
-  "mypy == 1.19.0",
-  "types-Markdown == 3.10.0.20251106",
+  "mypy == 1.19.1",
+  "types-networkx>=3.6.1.20251220",
+  "types-Markdown == 3.10.2.20260211",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
@@ -78,15 +84,15 @@ dev-pylint = [
   "frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
 dev-pytest = [
-  "pytest == 8.4.1",
-  "pylint == 4.0.4",       # We need this to check for the examples
+  "pytest == 9.0.2",
+  "pylint == 4.0.5",       # We need this to check for the examples
   "frequenz-repo-config[extra-lint-examples] == 0.13.7",
   "pytest-mock == 3.15.1",
   "pytest-asyncio == 1.3.0",
   "async-solipsism == 0.9",
 ]
 dev = [
-  "frequenz-gridpool[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
+  "frequenz-gridpool[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest,render-graph]",
 ]
 
 [project.urls]

{frequenz_gridpool-0.3.0 → frequenz_gridpool-0.4.0}/src/frequenz/gridpool/_graph_generator.py

@@ -3,8 +3,6 @@
 
 """Formula generation from assets API component/connection configurations."""
 
-from typing import cast
-
 from frequenz.client.assets import AssetsApiClient
 from frequenz.client.assets.electrical_component import (
     ComponentConnection,
@@ -61,6 +59,6 @@ class ComponentGraphGenerator:
 
         graph = ComponentGraph[
             ElectricalComponent, ComponentConnection, ElectricalComponentId
-        ](components, cast(list[ComponentConnection], connections))
+        ](components, connections)
 
         return graph

{frequenz_gridpool-0.3.0 → frequenz_gridpool-0.4.0}/src/frequenz/gridpool/_microgrid_config.py

@@ -10,9 +10,13 @@ from dataclasses import field
 from pathlib import Path
 from typing import Any, ClassVar, Literal, Self, Type, cast, get_args
 
+from frequenz.client.assets import AssetsApiClient
+from frequenz.client.common.microgrid import MicrogridId
 from marshmallow import Schema
 from marshmallow_dataclass import dataclass
 
+from ._graph_generator import ComponentGraphGenerator
+
 _logger = logging.getLogger(__name__)
 
 ComponentType = Literal["grid", "pv", "battery", "consumption", "chp", "ev"]
@@ -47,15 +51,16 @@ class ComponentTypeConfig:
                 "please use 'AC_POWER_ACTIVE' instead."
             )
 
-        if "AC_POWER_ACTIVE" not in self.formula:
-            if "AC_ACTIVE_POWER" in self.formula:
-                self.formula["AC_POWER_ACTIVE"] = self.formula["AC_ACTIVE_POWER"]
-            else:
-                _logger.warning(
-                    "ComponentTypeConfig: No formula provided for 'AC_POWER_ACTIVE', "
-                    "using default summation formula."
-                )
-                self.formula["AC_POWER_ACTIVE"] = "+".join(
+        defaults = {
+            "AC_POWER_ACTIVE",
+            "AC_ENERGY_ACTIVE",
+            "AC_ENERGY_ACTIVE_CONSUMED",
+            "AC_ENERGY_ACTIVE_DELIVERED",
+        }
+
+        for metric in defaults:
+            if metric not in self.formula:
+                self.formula[metric] = "+".join(
                     [f"#{cid}" for cid in self._default_cids()]
                 )
 
@@ -401,3 +406,126 @@ class MicrogridConfig:
             microgrid_configs.update({str(key): value for key, value in mcfgs.items()})
 
         return microgrid_configs
+
+    @staticmethod
+    async def load_configs_with_formulas(
+        assets_url: str,
+        assets_auth_key: str,
+        assets_sign_secret: str,
+        microgrid_config_files: str | Path | list[str | Path] | None = None,
+        microgrid_config_dir: str | Path | None = None,
+    ) -> dict[str, "MicrogridConfig"]:
+        """Load microgrid configurations and ensure formulas are populated.
+
+        Loads microgrid configuration files and enriches them with automatically
+        generated formulas obtained from the Assets API. Missing formulas are filled
+        using the component graph generator while preserving any formulas already
+        defined in the configuration.
+
+        Args:
+            assets_url:
+                Base URL of the Assets API.
+            assets_auth_key:
+                Authentication key used to access the Assets API.
+            assets_sign_secret:
+                Signing secret used for authenticated API requests.
+            microgrid_config_files:
+                Optional path or list of paths to individual microgrid configuration
+                files.
+            microgrid_config_dir:
+                Optional directory containing microgrid configuration files.
+
+        Returns:
+            dict[str, MicrogridConfig]:
+                Mapping from microgrid ID (as string) to the corresponding populated
+                ``MicrogridConfig`` instance.
+
+        Notes:
+            - Configuration files are first loaded via ``MicrogridConfig.load_configs``.
+            - Any missing formulas are populated by querying the Assets API and
+            generating formulas from the microgrid component graph.
+        """
+        microgrid_configs = MicrogridConfig.load_configs(
+            microgrid_config_files=microgrid_config_files,
+            microgrid_config_dir=microgrid_config_dir,
+        )
+
+        async with AssetsApiClient(
+            assets_url, auth_key=assets_auth_key, sign_secret=assets_sign_secret
+        ) as assets_client:
+            for microgrid_id, config in microgrid_configs.items():
+                await populate_missing_formulas(
+                    microgrid_id=int(microgrid_id),
+                    config=config,
+                    assets_client=assets_client,
+                )
+
+        return microgrid_configs
+
+
+async def populate_missing_formulas(
+    microgrid_id: int,
+    config: "MicrogridConfig",
+    assets_client: AssetsApiClient,
+) -> None:
+    """Populate missing component formulas from the assets API graph.
+
+    Builds a component graph for the given microgrid and derives default formulas
+    for common component types such as consumption, generation, grid, PV, battery,
+    CHP, and EV charging. Existing formulas already present in the configuration
+    are preserved; only missing component-type entries or missing metric formulas
+    are filled in.
+
+    Args:
+        microgrid_id:
+            Identifier of the microgrid whose component graph should be used to
+            derive formulas.
+        config:
+            Microgrid configuration object to update in place.
+        assets_client:
+            Assets API client used to fetch the component graph.
+
+    Returns:
+        None. The configuration is modified in place.
+
+    Notes:
+        - Existing formulas in ``config`` are never overwritten.
+        - For missing component types, a new ``ComponentTypeConfig`` is created.
+        - The same derived formula is assigned to all supported metric keys for a
+        given component type when missing.
+    """
+    cgg = ComponentGraphGenerator(assets_client)
+    graph = await cgg.get_component_graph(MicrogridId(microgrid_id))
+
+    auto_formulas = {
+        "consumption": graph.consumer_formula(),
+        "generation": graph.producer_formula(),
+        "grid": graph.grid_formula(),
+        "pv": graph.pv_formula(None),
+        "battery": graph.battery_formula(None),
+        "chp": graph.chp_formula(None),
+        "ev": graph.ev_charger_formula(None),
+    }
+
+    metrics = (
+        "AC_POWER_ACTIVE",
+        "AC_ACTIVE_POWER",
+        "AC_ENERGY_ACTIVE",
+        "AC_ENERGY_ACTIVE_CONSUMED",
+        "AC_ENERGY_ACTIVE_DELIVERED",
+    )
+
+    for ctype, formula in auto_formulas.items():
+        cfg = config.ctype.get(ctype)
+        if cfg is None:
+            config.ctype[ctype] = ComponentTypeConfig(
+                formula={metric: formula for metric in metrics}
+            )
+            continue
+
+        if cfg.formula is None:
+            cfg.formula = {}
+
+        for metric in metrics:
+            if metric not in cfg.formula:
+                cfg.formula[metric] = formula

{frequenz_gridpool-0.3.0 → frequenz_gridpool-0.4.0}/src/frequenz/gridpool/cli/__main__.py

@@ -10,6 +10,7 @@ from frequenz.client.assets import AssetsApiClient
 from frequenz.client.common.microgrid import MicrogridId
 
 from frequenz.gridpool import ComponentGraphGenerator
+from frequenz.gridpool.cli._render_graph import ComponentGraphRenderer, RenderOptions
 
 
 @click.group()
@@ -63,6 +64,47 @@ async def print_formulas(
             )
 
 
+@cli.command("render-graph")
+@click.argument("microgrid_id", type=int)
+@click.option(
+    "--output",
+    type=click.Path(dir_okay=False, writable=True),
+    default="component_graph.png",
+    show_default=True,
+    help="Output image path.",
+)
+@click.option(
+    "--show/--no-show",
+    default=True,
+    show_default=True,
+    help="Display the graph interactively.",
+)
+async def render_graph(microgrid_id: int, output: str, show: bool) -> None:
+    """Render and save a component graph visualization for a microgrid."""
+    url = os.environ.get("ASSETS_API_URL")
+    key = os.environ.get("ASSETS_API_AUTH_KEY")
+    secret = os.environ.get("ASSETS_API_SIGN_SECRET")
+    if not url or not key or not secret:
+        raise click.ClickException(
+            "ASSETS_API_URL, ASSETS_API_AUTH_KEY, ASSETS_API_SIGN_SECRET must be set."
+        )
+
+    try:
+        async with AssetsApiClient(
+            url,
+            auth_key=key,
+            sign_secret=secret,
+        ) as client:
+            renderer = ComponentGraphRenderer(client)
+            graph = await renderer.build_graph(MicrogridId(microgrid_id))
+            if not graph.nodes:
+                raise click.ClickException("No components found for this microgrid.")
+            pos = renderer.compute_layout(graph)
+            renderer.render(graph, pos, RenderOptions(output=output, show=show))
+    except RuntimeError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
 def main() -> None:
     """Run the CLI tool."""
     cli(_anyio_backend="asyncio")

frequenz_gridpool-0.4.0/src/frequenz/gridpool/cli/_render_graph.py

@@ -0,0 +1,295 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+# pylint: disable=import-error
+
+"""Render component graphs via the Assets API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from frequenz.client.assets import AssetsApiClient
+from frequenz.client.common.microgrid import MicrogridId
+
+
+def _format_category(category: Any) -> str:
+    """Normalize a component category into a short display label."""
+    if category is None:
+        return "UNKNOWN"
+    if hasattr(category, "name"):
+        return str(category.name).replace("COMPONENT_CATEGORY_", "")
+    return str(category).replace("COMPONENT_CATEGORY_", "")
+
+
+def _require_networkx() -> Any:
+    try:
+        # pylint: disable=import-outside-toplevel
+        import networkx as nx
+    except ModuleNotFoundError as exc:
+        raise RuntimeError(
+            "Rendering requires optional dependencies. Install "
+            "`frequenz-gridpool[render-graph]`."
+        ) from exc
+    return nx
+
+
+def _require_matplotlib() -> Any:
+    try:
+        # pylint: disable=import-outside-toplevel
+        import matplotlib.pyplot as plt
+    except ModuleNotFoundError as exc:
+        raise RuntimeError(
+            "Rendering requires optional dependencies. Install "
+            "`frequenz-gridpool[render-graph]`."
+        ) from exc
+    return plt
+
+
+@dataclass(frozen=True)
+class RenderOptions:
+    """Rendering options for component graphs."""
+
+    output: str
+    show: bool = True
+    figsize: tuple[int, int] = (15, 10)
+    title: str = "Microgrid Component Graph"
+
+
+class ComponentGraphRenderer:
+    """Build and render component graphs for a microgrid."""
+
+    def __init__(self, client: AssetsApiClient) -> None:
+        """Initialize the renderer.
+
+        Args:
+            client: API client used to fetch microgrid components and their connections.
+        """
+        self._client = client
+
+    async def build_graph(self, microgrid_id: MicrogridId) -> Any:
+        """Build a directed graph representing the microgrid electrical topology.
+
+        Fetches electrical components and their connections for the given microgrid and
+        constructs a directed graph where nodes represent components and edges represent
+        connections from source to destination.
+
+        Args:
+            microgrid_id: Identifier of the microgrid to fetch and model.
+
+        Returns:
+            A directed graph containing component nodes and connection edges.
+        """
+        components = await self._client.list_microgrid_electrical_components(
+            microgrid_id
+        )
+        connections = (
+            await self._client.list_microgrid_electrical_component_connections(
+                microgrid_id
+            )
+        )
+
+        nx = _require_networkx()
+        graph = nx.DiGraph()
+
+        for component in components:
+            graph.add_node(
+                component.id,
+                name=component.name or str(component.id),
+                category=_format_category(component.category),
+                orig_id=component.id,
+            )
+
+        for connection in connections:
+            if connection is None:
+                continue
+            graph.add_edge(connection.source, connection.destination)
+
+        return graph
+
+    def compute_layout(self, graph: Any) -> dict[Any, tuple[float, float]]:
+        """Compute a layered node layout with the root on the left.
+
+        Selects a root node, groups nodes by shortest-path distance from the root, and
+        assigns (x, y) coordinates such that layers are spaced along the x-axis.
+
+        Args:
+            graph: A graph-like object containing nodes and edges.
+
+        Returns:
+            A mapping from node identifiers to (x, y) coordinates.
+        """
+        if not graph.nodes:
+            return {}
+
+        root_node = self._select_root(graph)
+        layered_nodes = self._group_by_level(graph, root_node)
+        ordered_layers = self._order_layers(graph, layered_nodes)
+        return self._build_positions(ordered_layers)
+
+    def _select_root(self, graph: Any) -> Any:
+        """Select a root node for layout.
+
+        Prefers a node with no incoming edges and at least one outgoing edge. If no such
+        node exists, falls back to an arbitrary node.
+
+        Args:
+            graph: A graph-like object containing nodes and edges.
+
+        Returns:
+            The selected root node identifier.
+        """
+        roots = [
+            node
+            for node in graph.nodes
+            if graph.in_degree(node) == 0 and graph.out_degree(node) > 0
+        ]
+        return roots[0] if roots else list(graph.nodes)[0]
+
+    def _group_by_level(self, graph: Any, root_node: Any) -> dict[int, list[Any]]:
+        """Group nodes into layers by shortest-path distance from a root node.
+
+        Nodes reachable from the root are assigned to layers based on their shortest-path
+        distance. Nodes not reachable from the root are placed into a final "orphan"
+        layer after the deepest reachable layer.
+
+        Args:
+            graph: A graph-like object containing nodes and edges.
+            root_node: The node to treat as the root for distance computation.
+
+        Returns:
+            A mapping from layer index to the list of nodes in that layer.
+        """
+        nx = _require_networkx()
+        levels = nx.single_source_shortest_path_length(graph, root_node)
+        layered_nodes: dict[int, list[Any]] = {}
+        for node, dist in levels.items():
+            layered_nodes.setdefault(dist, []).append(node)
+
+        orphans = [node for node in graph.nodes if node not in levels]
+        if orphans:
+            orphan_layer = max(layered_nodes.keys()) + 1 if layered_nodes else 0
+            layered_nodes[orphan_layer] = orphans
+        return layered_nodes
+
+    def _order_layers(
+        self, graph: Any, layered_nodes: dict[int, list[Any]]
+    ) -> dict[int, list[Any]]:
+        """Order nodes within each layer based on their parent positions.
+
+        Reorders the nodes in each layer to improve visual readability when rendering a
+        layered graph layout. The first layer is ordered deterministically (by string
+        representation). For subsequent layers, nodes are ordered primarily by the
+        lowest index of any already-ordered parent (predecessor) from the previous
+        layers, with a deterministic string-based tie-breaker.
+
+        Args:
+            graph:
+                Graph-like object providing predecessor relationships via
+                ``graph.predecessors(node)``.
+            layered_nodes:
+                Mapping from layer index to the list of nodes assigned to that layer.
+
+        Returns:
+            A new mapping with the same layer keys as ``layered_nodes``, where each
+            layer's node list is ordered to align children beneath their parents.
+        """
+        ordered_layers: dict[int, list[Any]] = {}
+        previous_order: dict[Any, int] = {}
+
+        for level in sorted(layered_nodes):
+            nodes = layered_nodes[level]
+            if level == 0:
+                ordered_nodes = sorted(nodes, key=str)
+            else:
+
+                def sort_key(node: Any) -> tuple[int, str]:
+                    parents = [
+                        parent
+                        for parent in graph.predecessors(node)
+                        if parent in previous_order
+                    ]
+                    if parents:
+                        parent_index = min(previous_order[parent] for parent in parents)
+                    else:
+                        parent_index = len(previous_order)
+                    return (parent_index, str(node))
+
+                ordered_nodes = sorted(nodes, key=sort_key)
+
+            ordered_layers[level] = ordered_nodes
+            previous_order = {node: idx for idx, node in enumerate(ordered_nodes)}
+
+        return ordered_layers
+
+    def _build_positions(
+        self, layered_nodes: dict[int, list[Any]]
+    ) -> dict[Any, tuple[float, float]]:
+        """Compute node positions from pre-grouped layers.
+
+        Assigns x-coordinates based on layer index and y-coordinates by distributing
+        nodes evenly within each layer.
+
+        Args:
+            layered_nodes: Mapping from layer index to the list of nodes in that layer.
+
+        Returns:
+            A mapping from node identifiers to (x, y) coordinates.
+        """
+        x_spacing, y_spacing = 2.5, 1.2
+        pos: dict[Any, tuple[float, float]] = {}
+        for level in sorted(layered_nodes):
+            nodes = layered_nodes[level]
+            x_pos = level * x_spacing
+            y_start = (len(nodes) - 1) * y_spacing / 2
+            for i, node in enumerate(nodes):
+                pos[node] = (x_pos, y_start - (i * y_spacing))
+        return pos
+
+    def render(
+        self, graph: Any, pos: dict[Any, tuple[float, float]], options: RenderOptions
+    ) -> None:
+        """Render a component graph to an image file and optionally display it.
+
+        This method uses NetworkX and Matplotlib to draw the given graph using the
+        provided node positions, applies basic styling (labels, colors, arrows),
+        saves the resulting figure to the path specified in ``options.output``,
+        and, if configured, opens an interactive window to show the plot.
+
+        Args:
+            graph: A NetworkX graph-like object (typically a ``DiGraph``) whose
+                nodes and edges represent the microgrid components and their
+                electrical connections.
+            pos: A mapping from node identifiers to ``(x, y)`` coordinates used
+                to place each node in the rendered figure, usually obtained from
+                :meth:`compute_layout`.
+            options: Rendering configuration, including output file path, whether
+                to show the figure interactively, figure size, and plot title.
+        """
+        nx = _require_networkx()
+        plt = _require_matplotlib()
+
+        node_labels = {
+            node: (
+                f'{graph.nodes[node].get("name", str(node))}\n'
+                f'ID: {graph.nodes[node].get("orig_id", node)}'
+            )
+            for node in graph.nodes
+        }
+
+        plt.figure(figsize=options.figsize)
+        nx.draw(
+            graph,
+            pos,
+            with_labels=True,
+            labels=node_labels,
+            node_color="lightblue",
+            edge_color="gray",
+            node_size=800,
+            font_size=8,
+        )
+        plt.title(options.title)
+        plt.tight_layout()
+        plt.savefig(options.output, dpi=300)
+        if options.show:
+            plt.show()

{frequenz_gridpool-0.3.0 → frequenz_gridpool-0.4.0/src/frequenz_gridpool.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-gridpool
-Version: 0.3.0
+Version: 0.4.0
 Summary: High-level interface to grid pools for the Frequenz platform.
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT
@@ -24,7 +24,10 @@ Requires-Dist: marshmallow-dataclass<9,>=8.7.1
 Requires-Dist: asyncclick<9,>=8.3.0.4
 Requires-Dist: typing-extensions<5,>=4.14.1
 Requires-Dist: frequenz-microgrid-component-graph<0.4,>=0.3.4
-Requires-Dist: frequenz-client-assets<0.3,>=0.2.0
+Requires-Dist: frequenz-client-assets<0.4,>=0.3.0
+Provides-Extra: render-graph
+Requires-Dist: matplotlib<4,>=3.7.0; extra == "render-graph"
+Requires-Dist: networkx<4,>=3.0; extra == "render-graph"
 Provides-Extra: dev-flake8
 Requires-Dist: flake8==7.3.0; extra == "dev-flake8"
 Requires-Dist: flake8-docstrings==1.7.0; extra == "dev-flake8"
@@ -35,19 +38,20 @@ Provides-Extra: dev-formatting
 Requires-Dist: black==25.11.0; extra == "dev-formatting"
 Requires-Dist: isort==7.0.0; extra == "dev-formatting"
 Provides-Extra: dev-mkdocs
-Requires-Dist: Markdown==3.10; extra == "dev-mkdocs"
+Requires-Dist: Markdown==3.10.2; extra == "dev-mkdocs"
 Requires-Dist: black==25.11.0; extra == "dev-mkdocs"
 Requires-Dist: mike==2.1.3; extra == "dev-mkdocs"
 Requires-Dist: mkdocs-gen-files==0.5.0; extra == "dev-mkdocs"
 Requires-Dist: mkdocs-literate-nav==0.6.2; extra == "dev-mkdocs"
 Requires-Dist: mkdocs-macros-plugin==1.5.0; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-material==9.7.0; extra == "dev-mkdocs"
-Requires-Dist: mkdocstrings[python]==1.0.0; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-material==9.7.3; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings[python]==1.0.3; extra == "dev-mkdocs"
 Requires-Dist: mkdocstrings-python==1.19.0; extra == "dev-mkdocs"
 Requires-Dist: frequenz-repo-config[lib]==0.13.7; extra == "dev-mkdocs"
 Provides-Extra: dev-mypy
-Requires-Dist: mypy==1.19.0; extra == "dev-mypy"
-Requires-Dist: types-Markdown==3.10.0.20251106; extra == "dev-mypy"
+Requires-Dist: mypy==1.19.1; extra == "dev-mypy"
+Requires-Dist: types-networkx>=3.6.1.20251220; extra == "dev-mypy"
+Requires-Dist: types-Markdown==3.10.2.20260211; extra == "dev-mypy"
 Requires-Dist: frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-mypy"
 Provides-Extra: dev-noxfile
 Requires-Dist: nox==2025.11.12; extra == "dev-noxfile"
@@ -55,14 +59,14 @@ Requires-Dist: frequenz-repo-config[lib]==0.13.7; extra == "dev-noxfile"
 Provides-Extra: dev-pylint
 Requires-Dist: frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
 Provides-Extra: dev-pytest
-Requires-Dist: pytest==8.4.1; extra == "dev-pytest"
-Requires-Dist: pylint==4.0.4; extra == "dev-pytest"
+Requires-Dist: pytest==9.0.2; extra == "dev-pytest"
+Requires-Dist: pylint==4.0.5; extra == "dev-pytest"
 Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.13.7; extra == "dev-pytest"
 Requires-Dist: pytest-mock==3.15.1; extra == "dev-pytest"
 Requires-Dist: pytest-asyncio==1.3.0; extra == "dev-pytest"
 Requires-Dist: async-solipsism==0.9; extra == "dev-pytest"
 Provides-Extra: dev
-Requires-Dist: frequenz-gridpool[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]; extra == "dev"
+Requires-Dist: frequenz-gridpool[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest,render-graph]; extra == "dev"
 Dynamic: license-file
 
 # Frequenz Gridpool Library
@@ -85,6 +89,50 @@ The following platforms are officially supported (tested):
 - **Operating System:** Ubuntu Linux 20.04
 - **Architectures:** amd64, arm64
 
+## CLI
+
+This package ships the `gridpool-cli` command with two subcommands.
+
+### Setup
+
+Set the Assets API credentials before running the CLI:
+
+```bash
+export ASSETS_API_URL="grpc://..."
+export ASSETS_API_AUTH_KEY="..."
+export ASSETS_API_SIGN_SECRET="..."
+```
+
+### Print component formulas
+
+```bash
+gridpool-cli print-formulas <microgrid_id>
+```
+
+Optional prefix formatting:
+
+```bash
+gridpool-cli print-formulas <microgrid_id> --prefix "{microgrid_id}.{component}"
+```
+
+### Render component graph
+
+Rendering requires optional dependencies. Install with:
+
+```bash
+pip install frequenz-gridpool[render-graph]
+```
+
+```bash
+gridpool-cli render-graph <microgrid_id>
+```
+
+To save without opening a window:
+
+```bash
+gridpool-cli render-graph <microgrid_id> --no-show --output component_graph.png
+```
+
 ## Contributing
 
 If you want to know how to build this project and contribute to it, please

{frequenz_gridpool-0.3.0 → frequenz_gridpool-0.4.0}/src/frequenz_gridpool.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ src/frequenz/gridpool/conftest.py
 src/frequenz/gridpool/py.typed
 src/frequenz/gridpool/cli/__init__.py
 src/frequenz/gridpool/cli/__main__.py
+src/frequenz/gridpool/cli/_render_graph.py
 src/frequenz_gridpool.egg-info/PKG-INFO
 src/frequenz_gridpool.egg-info/SOURCES.txt
 src/frequenz_gridpool.egg-info/dependency_links.txt

{frequenz_gridpool-0.3.0 → frequenz_gridpool-0.4.0}/src/frequenz_gridpool.egg-info/requires.txt

@@ -2,10 +2,10 @@ marshmallow-dataclass<9,>=8.7.1
 asyncclick<9,>=8.3.0.4
 typing-extensions<5,>=4.14.1
 frequenz-microgrid-component-graph<0.4,>=0.3.4
-frequenz-client-assets<0.3,>=0.2.0
+frequenz-client-assets<0.4,>=0.3.0
 
 [dev]
-frequenz-gridpool[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]
+frequenz-gridpool[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest,render-graph]
 
 [dev-flake8]
 flake8==7.3.0
@@ -19,20 +19,21 @@ black==25.11.0
 isort==7.0.0
 
 [dev-mkdocs]
-Markdown==3.10
+Markdown==3.10.2
 black==25.11.0
 mike==2.1.3
 mkdocs-gen-files==0.5.0
 mkdocs-literate-nav==0.6.2
 mkdocs-macros-plugin==1.5.0
-mkdocs-material==9.7.0
-mkdocstrings[python]==1.0.0
+mkdocs-material==9.7.3
+mkdocstrings[python]==1.0.3
 mkdocstrings-python==1.19.0
 frequenz-repo-config[lib]==0.13.7
 
 [dev-mypy]
-mypy==1.19.0
-types-Markdown==3.10.0.20251106
+mypy==1.19.1
+types-networkx>=3.6.1.20251220
+types-Markdown==3.10.2.20260211
 frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]
 
 [dev-noxfile]
@@ -43,9 +44,13 @@ frequenz-repo-config[lib]==0.13.7
 frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]
 
 [dev-pytest]
-pytest==8.4.1
-pylint==4.0.4
+pytest==9.0.2
+pylint==4.0.5
 frequenz-repo-config[extra-lint-examples]==0.13.7
 pytest-mock==3.15.1
 pytest-asyncio==1.3.0
 async-solipsism==0.9
+
+[render-graph]
+matplotlib<4,>=3.7.0
+networkx<4,>=3.0

frequenz_gridpool-0.3.0/RELEASE_NOTES.md

@@ -1,17 +0,0 @@
-# Frequenz Gridpool Library Release Notes
-
-## Summary
-
-<!-- Here goes a general summary of what this release is about -->
-
-## Upgrading
-
-* The minimum required version of `frequenz-microgrid-component-graph` is now `v0.3.4`.
-
-## New Features
-
-<!-- Here goes the main new features and examples or instructions on how to use them -->
-
-## Bug Fixes
-
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->