Improve consumer power formula

.cookiecutter-replay.json

@@ -1,5 +1,6 @@
 {
   "cookiecutter": {
+    "Introduction": "]\n\nWelcome to repo-config Cookiecutter template!\n\nThis template will help you to create a new repository for your project. You will be asked to provide some information about your project.\n\nHere is an explanation of what each variable is for and will be used for:\n\n* `type`: The type of repository. It must be chosen from the list.\n\n* `name`: The name of the project. This will be used to build defaults for\n  other inputs, such as `title`, `python_package`, etc. It should be one word,\n  using only alphanumeric characters (and starting with a letter). It can\n  include also `_` and `-` which will be handled differently when building\n  other variables from it (replaced by spaces in titles for example).\n\n* `description`: A short description of the project. It will be used as the\n  description in the `README.md`, `pyproject.toml`, `mkdocs.yml`, etc.\n\n* `title`: A human-readable name or title for the project. It will be used in\n  the `README.md`, `CONTRIBUTING.md`, and other files to refer to the project,\n  as well as the site title in `mkdocs.yml`.\n\n* `keywords`: A comma-separated list of keywords that will be used in the\n  `pyproject.toml` file. If left untouched, it will use only some predefined\n  keywords. If anything else is entered, it will be **added** to the default\n  keywords.\n\n* `github_org`: The GitHub handle of the organization where the project will\n  reside. This will be used to generate links to the project on GitHub.\n\n* `license`: Currently, only two options are provided: `MIT`, which should be\n  used for open-source projects, and `Proprietary`, which should be used for\n  closed-source projects. This will be added to file headers and used as the\n  license in `pyproject.toml`.\n\n* `author_name`, `author_email`: The name and email address of the author of\n  the project. They will be used in the copyright notice in file headers and\n  as the author in `pyproject.toml`.\n\n* `python_package`: The Python package in which this project will reside. All\n  files provided by this project should be located in this package. This needs\n  to be a list of valid Python identifiers separated by dots. The source file\n  structure will be derived from this. For example, `frequenz.actor.example`\n  will generate files in `src/frequenz/actor/example`.\n\n* `pypi_package_name`: The name of the PyPI/wheel/distribution package. This\n  should be consistent with the `python_package`, usually replacing `.` with\n  `-`. For example, `frequenz-actor-example`.\n\n* `github_repo_name`: The handle of the GitHub repository where the project\n  will reside. This will be used to generate links to the project on GitHub and\n  as the top-level directory name.\n\n* `default_codeowners`: A space-separated list of GitHub teams (`@org/team`) or\n  users (`@user`) that will be the default code owners for this project. This\n  will be used to build the `CODEOWNERS` file. Please refer to the [code owners\n  documentation] for more details on the valid syntax.\n\n[code owners documentation]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners\n\n\n[Please press any key to continue",
     "type": "lib",
     "name": "sdk",
     "description": "A development kit to interact with the Frequenz development platform",
@@ -15,14 +16,41 @@
     "default_codeowners": "@frequenz-floss/python-sdk-team",
     "_extensions": [
       "jinja2_time.TimeExtension",
+      "local_extensions.as_identifier",
       "local_extensions.default_codeowners",
       "local_extensions.github_repo_name",
+      "local_extensions.introduction",
       "local_extensions.keywords",
       "local_extensions.pypi_package_name",
       "local_extensions.python_package",
       "local_extensions.src_path",
       "local_extensions.title"
     ],
-    "_template": "gh:frequenz-floss/frequenz-repo-config-python"
+    "_template": "gh:frequenz-floss/frequenz-repo-config-python",
+  },
+  "_cookiecutter": {
+    "Introduction": "{{cookiecutter | introduction}}",
+    "type": [
+      "actor",
+      "api",
+      "app",
+      "lib",
+      "model"
+    ],
+    "name": null,
+    "description": null,
+    "title": "{{cookiecutter | title}}",
+    "keywords": "(comma separated: 'frequenz', <type> and <name> are included automatically)",
+    "github_org": "frequenz-floss",
+    "license": [
+      "MIT",
+      "Proprietary"
+    ],
+    "author_name": "Frequenz Energy-as-a-Service GmbH",
+    "author_email": "[email protected]",
+    "python_package": "{{cookiecutter | python_package}}",
+    "pypi_package_name": "{{cookiecutter | pypi_package_name}}",
+    "github_repo_name": "{{cookiecutter | github_repo_name}}",
+    "default_codeowners": "(like @some-org/some-team; defaults to a team based on the repo type)"
   }
-}
+}

.github/containers/test-installation/Dockerfile

@@ -0,0 +1,10 @@
+# This dockerfile is used to test the installation of the python package in
+# multiple platforms in the CI. It is not used to build the package itself.
+
+FROM --platform=${TARGETPLATFORM} python:3.11-slim
+
+RUN python -m pip install --upgrade --no-cache-dir pip
+
+COPY dist dist
+RUN pip install dist/*.whl && \
+    rm -rf dist

.github/workflows/ci.yaml

@@ -50,7 +50,7 @@ jobs:
           python -m pip install -e .[dev-noxfile]
 
       - name: Run nox
-        # To speed things up a bit we use the speciall ci_checks_max session
+        # To speed things up a bit we use the special ci_checks_max session
         # that uses the same venv to run multiple linting sessions
         run: nox -e ci_checks_max pytest_min
         timeout-minutes: 10
@@ -83,6 +83,31 @@ jobs:
           path: dist/
           if-no-files-found: error
 
+  test-installation:
+    name: Test package installation in different architectures
+    needs: ["build"]
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Fetch sources
+        uses: actions/checkout@v3
+      - name: Download package
+        uses: actions/download-artifact@v3
+        with:
+          name: dist-packages
+          path: dist
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v2
+      - name: Set up docker-buildx
+        uses: docker/setup-buildx-action@v2
+      - name: Test Installation
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          file: .github/containers/test-installation/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          tags: localhost/test-installation
+          push: false
+
   test-docs:
     name: Test documentation website generation
     if: github.event_name != 'push'
@@ -121,7 +146,7 @@ jobs:
 
   publish-docs:
     name: Publish documentation website to GitHub pages
-    needs: ["nox", "build"]
+    needs: ["nox", "test-installation"]
     if: github.event_name == 'push'
     runs-on: ubuntu-20.04
     permissions:

.github/workflows/release_notes_check.yml

@@ -0,0 +1,28 @@
+name: Release Notes Check
+
+on:
+  merge_group:
+  pull_request:
+    types:
+      # On by default if you specify no types.
+      - "opened"
+      - "reopened"
+      - "synchronize"
+      # For `skip-label` only.
+      - "labeled"
+      - "unlabeled"
+
+
+jobs:
+  check-release-notes:
+    name: Check release notes are updated
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for a release notes update
+        if: github.event_name == 'pull_request'
+        uses: brettcannon/check-for-changed-files@4170644959a21843b31f1181f2a1761d65ef4791 # v1.2.0
+        with:
+          file-pattern: "RELEASE_NOTES.md"
+          prereq-pattern: "src/**"
+          skip-label: "cmd:skip-release-notes"
+          failure-message: "Missing a release notes update. Please add one or apply the ${skip-label} label to the pull request"

RELEASE_NOTES.md

@@ -2,22 +2,110 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+This release replaces the `@actor` decorator with a new `Actor` class.
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
 
-- `Channels` has been upgraded to version 0.16.0, for information on how to upgrade visit https://github.com/frequenz-floss/frequenz-channels-python/releases/tag/v0.16.0
+- The `frequenz.sdk.power` package contained the power distribution algorithm, which is for internal use in the sdk, and is no longer part of the public API.
+
+- `PowerDistributingActor`'s result type `OutOfBound` has been renamed to `OutOfBounds`, and its member variable `bound` has been renamed to `bounds`.
+
+- The `@actor` decorator was replaced by the new `Actor` class. The main differences between the new class and the old decorator are:
+
+  * It doesn't start automatically, `start()` needs to be called to start an actor (using the `frequenz.sdk.actor.run()` function is recommended).
+  * The method to implement the main logic was renamed from `run()` to `_run()`, as it is not intended to be run externally.
+  * Actors can have an optional `name` (useful for debugging/logging purposes).
+  * The actor will only be restarted if an unhandled `Exception` is raised by `_run()`. It will not be restarted if the `_run()` method finishes normally. If an unhandled `BaseException` is raised instead, it will be re-raised. For normal cancellation the `_run()` method should handle `asyncio.CancelledError` if the cancellation shouldn't be propagated (this is the same as with the decorator).
+  * The `_stop()` method is public (`stop()`) and will `cancel()` and `await` for the task to finish, catching the `asyncio.CancelledError`.
+  * The `join()` method is renamed to `wait()`, but they can also be awaited directly ( `await actor`).
+  * For deterministic cleanup, actors can now be used as `async` context managers.
+
+  Most actors can be migrated following these steps:
+
+  1. Remove the decorator
+  2. Add `Actor` as a base class
+  3. Rename `run()` to `_run()`
+  4. Forward the `name` argument (optional but recommended)
+
+  For example, this old actor:
+
+  ```python
+  from frequenz.sdk.actor import actor
+
+  @actor
+  class TheActor:
+      def __init__(self, actor_args) -> None:
+          # init code
+
+      def run(self) -> None:
+          # run code
+  ```
+
+  Can be migrated as:
+
+  ```python
+  import asyncio
+  from frequenz.sdk.actor import Actor
+
+  class TheActor(Actor):
+      def __init__(self, actor_args,
+          *,
+          name: str | None = None,
+      ) -> None:
+          super().__init__(name=name)
+          # init code
+
+      def _run(self) -> None:
+          # run code
+  ```
+
+  Then you can instantiate all your actors first and then run them using:
+
+  ```python
+  from frequenz.sdk.actor import run
+  # Init code
+  actor = TheActor()
+  other_actor = OtherActor()
+  # more setup
+  await run(actor, other_actor)  # Start and await for all the actors
+  ```
+
+- The `MovingWindow` is now a `BackgroundService`, so it needs to be started manually with `await window.start()`. It is recommended to use it as an `async` context manager if possible though:
+
+    ```python
+    async with MovingWindow(...) as window:
+        # The moving windows is started here
+        use(window)
+    # The moving window is stopped here
+    ```
+
+- The base actors (`ConfigManagingActor`, `ComponentMetricsResamplingActor`, `DataSourcingActor`, `PowerDistributingActor`) now inherit from the new `Actor` class, if you are using them directly, you need to start them manually with `await actor.start()` and you might need to do some other adjustments.
 
 ## New Features
 
-- Add quantity class `Frequency` for frequency values.
-- Add `abs()` support for quantities.
+- Added `DFS` to the component graph
+
+- `BackgroundService`: This new abstract base class can be used to write other classes that runs one or more tasks in the background. It provides a consistent API to start and stop these services and also takes care of the handling of the background tasks. It can also work as an `async` context manager, giving the service a deterministic lifetime and guaranteed cleanup.
+
+  All classes spawning tasks that are expected to run for an indeterminate amount of time are likely good candidates to use this as a base class.
+
+- `Actor`: This new class inherits from `BackgroundService` and it replaces the `@actor` decorator.
 
 ## Bug Fixes
 
-- Fix formatting issue for `Quantity` objects with zero values.
-- Fix formatting isuse for `Quantity` when the base value is float.inf or float.nan.
+- Fixes a bug in the ring buffer updating the end timestamp of gaps when they are outdated.
+
+- Properly handles PV configurations with no or only some meters before the PV component.
+
+  So far we only had configurations like this: `Meter -> Inverter -> PV`. However the scenario with `Inverter -> PV` is also possible and now handled correctly.
+
+- Fix `consumer_power()` not working certain configurations.
+
+  In microgrids without consumers and no main meter, the formula would never return any values.
+
+- Fix `pv_power` not working in setups with 2 grid meters by using a new reliable function to search for components in the components graph
+
+- Fix `consumer_power` and `producer_power` similar to `pv_power`
 
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+- Zero value requests received by the `PowerDistributingActor` will now always be accepted, even when there are non-zero exclusion bounds.

benchmarks/power_distribution/power_distributor.py

@@ -17,7 +17,7 @@
 from frequenz.sdk.actor.power_distributing import (
     BatteryStatus,
     Error,
-    OutOfBound,
+    OutOfBounds,
     PartialFailure,
     PowerDistributingActor,
     Request,
@@ -75,7 +75,7 @@ def parse_result(result: List[List[Result]]) -> Dict[str, float]:
         Error: 0,
         Success: 0,
         PartialFailure: 0,
-        OutOfBound: 0,
+        OutOfBounds: 0,
     }
 
     for result_list in result:
@@ -86,7 +86,7 @@ def parse_result(result: List[List[Result]]) -> Dict[str, float]:
         "success_num": result_counts[Success],
         "failed_num": result_counts[PartialFailure],
         "error_num": result_counts[Error],
-        "out_of_bound": result_counts[OutOfBound],
+        "out_of_bounds": result_counts[OutOfBounds],
     }
 
 
@@ -108,19 +108,16 @@ async def run_test(  # pylint: disable=too-many-locals
     power_request_channel = Broadcast[Request]("power-request")
     battery_status_channel = Broadcast[BatteryStatus]("battery-status")
     channel_registry = ChannelRegistry(name="power_distributor")
-    distributor = PowerDistributingActor(
+    async with PowerDistributingActor(
         channel_registry=channel_registry,
         requests_receiver=power_request_channel.new_receiver(),
         battery_status_sender=battery_status_channel.new_sender(),
-    )
-
-    tasks: List[Coroutine[Any, Any, List[Result]]] = []
-    tasks.append(send_requests(batteries, num_requests))
-
-    result = await asyncio.gather(*tasks)
-    exec_time = timeit.default_timer() - start
+    ):
+        tasks: List[Coroutine[Any, Any, List[Result]]] = []
+        tasks.append(send_requests(batteries, num_requests))
 
-    await distributor._stop()  # type: ignore # pylint: disable=no-member, protected-access
+        result = await asyncio.gather(*tasks)
+        exec_time = timeit.default_timer() - start
 
     summary = parse_result(result)
     summary["num_requests"] = num_requests

benchmarks/timeseries/benchmark_datasourcing.py

@@ -70,7 +70,7 @@ async def benchmark_data_sourcing(
         num_ev_chargers * len(COMPONENT_METRIC_IDS) * num_msgs_per_battery
     )
     mock_grid = MockMicrogrid(
-        grid_side_meter=False, num_values=num_msgs_per_battery, sample_rate_s=0.0
+        grid_meter=False, num_values=num_msgs_per_battery, sample_rate_s=0.0
     )
 
     mock_grid.add_ev_chargers(num_ev_chargers)
@@ -113,23 +113,22 @@ async def consume(channel: Receiver[Any]) -> None:
             await request_sender.send(request)
             consume_tasks.append(asyncio.create_task(consume(recv_channel)))
 
-    DataSourcingActor(request_receiver, channel_registry)
+    async with DataSourcingActor(request_receiver, channel_registry):
+        await asyncio.gather(*consume_tasks)
 
-    await asyncio.gather(*consume_tasks)
+        time_taken = perf_counter() - start_time
 
-    time_taken = perf_counter() - start_time
+        await mock_grid.cleanup()
 
-    await mock_grid.cleanup()
-
-    print(f"Samples Sent: {samples_sent}, time taken: {time_taken}")
-    print(f"Samples per second: {samples_sent / time_taken}")
-    print(
-        "Expected samples: "
-        f"{num_expected_messages}, missing: {num_expected_messages - samples_sent}"
-    )
-    print(
-        f"Missing per EVC: {(num_expected_messages - samples_sent) / num_ev_chargers}"
-    )
+        print(f"Samples Sent: {samples_sent}, time taken: {time_taken}")
+        print(f"Samples per second: {samples_sent / time_taken}")
+        print(
+            "Expected samples: "
+            f"{num_expected_messages}, missing: {num_expected_messages - samples_sent}"
+        )
+        print(
+            f"Missing per EVC: {(num_expected_messages - samples_sent) / num_ev_chargers}"
+        )
 
 
 def parse_args() -> Tuple[int, int, bool]: