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

{frequenz_gridpool-0.3.1/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.1
+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,7 @@ 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"
@@ -38,20 +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.1; extra == "dev-mkdocs"
-Requires-Dist: mkdocstrings[python]==1.0.1; 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.1; extra == "dev-mypy"
 Requires-Dist: types-networkx>=3.6.1.20251220; extra == "dev-mypy"
-Requires-Dist: types-Markdown==3.10.0.20251106; 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"
@@ -60,7 +60,7 @@ Provides-Extra: dev-pylint
 Requires-Dist: frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
 Provides-Extra: dev-pytest
 Requires-Dist: pytest==9.0.2; extra == "dev-pytest"
-Requires-Dist: pylint==4.0.4; 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"

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.1 → frequenz_gridpool-0.4.0}/pyproject.toml

@@ -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"]
 
@@ -56,21 +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.1",
-  "mkdocstrings[python] == 1.0.1",
+  "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.1",
   "types-networkx>=3.6.1.20251220",
-  "types-Markdown == 3.10.0.20251106",
+  "types-Markdown == 3.10.2.20260211",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
@@ -85,7 +85,7 @@ dev-pylint = [
 ]
 dev-pytest = [
   "pytest == 9.0.2",
-  "pylint == 4.0.4",       # We need this to check for the examples
+  "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",

{frequenz_gridpool-0.3.1 → 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.1 → 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.1 → 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.1
+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,7 @@ 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"
@@ -38,20 +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.1; extra == "dev-mkdocs"
-Requires-Dist: mkdocstrings[python]==1.0.1; 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.1; extra == "dev-mypy"
 Requires-Dist: types-networkx>=3.6.1.20251220; extra == "dev-mypy"
-Requires-Dist: types-Markdown==3.10.0.20251106; 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"
@@ -60,7 +60,7 @@ Provides-Extra: dev-pylint
 Requires-Dist: frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
 Provides-Extra: dev-pytest
 Requires-Dist: pytest==9.0.2; extra == "dev-pytest"
-Requires-Dist: pylint==4.0.4; 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"

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

@@ -2,7 +2,7 @@ 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,render-graph]
@@ -19,21 +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.1
-mkdocstrings[python]==1.0.1
+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.1
 types-networkx>=3.6.1.20251220
-types-Markdown==3.10.0.20251106
+types-Markdown==3.10.2.20260211
 frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]
 
 [dev-noxfile]
@@ -45,7 +45,7 @@ frequenz-gridpool[dev-mkdocs,dev-noxfile,dev-pytest]
 
 [dev-pytest]
 pytest==9.0.2
-pylint==4.0.4
+pylint==4.0.5
 frequenz-repo-config[extra-lint-examples]==0.13.7
 pytest-mock==3.15.1
 pytest-asyncio==1.3.0

frequenz_gridpool-0.3.1/RELEASE_NOTES.md

@@ -1,19 +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
-
-* Added `gridpool-cli render-graph` to visualize microgrid component graphs using the
-  Assets API credentials (`ASSETS_API_URL`, `ASSETS_API_AUTH_KEY`, and
-  `ASSETS_API_SIGN_SECRET`).
-
-## Bug Fixes
-
-- Fixed component graph rendering so children follow the vertical order of their parents, keeping upper-level branches above lower ones in the layered layout.