v1.0.0-rc1

Frequenz Python SDK Release Notes

Summary

The most notable changes are the addition of microgrid.grid and microgrid.frequency(), as the many improvements to the MovingWindow.

Upgrading

• The battery pool metric methods no longer return None when no batteries are available. Instead, the value of the Sample or PowerMetric is set to None.

• The power distribution Result is now a union of all different types of results rather than a base class. This means we can now also use match to check for result types instead of only using isinstance(). The following example shows how Result can be used for matching power distribution results:

  from typing import assert_never
  result: Result = some_operation()
  match result:
      case Success() as success:
          print(f"Power request was successful: {success}")
      case PartialFailure() as partial_failure:
          print(f"Power request was partially successful: {partial_failure}")
      case OutOfBounds() as out_of_bounds:
          print(f"Power request was out of bounds: {out_of_bounds}")
      case Error() as error:
          print(f"Power request failed: {error}")
      case _ as unreachable:
          assert_never(unreachable)

• Averager was removed from FormulaEngine.

New Features

• 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().fuse.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.

• A new method microgrid.frequeny() was added to allow easy access to the current frequency of the grid.

• A new class Fuse has been added to represent fuses. This class has a member variable max_current which represents the maximum current that can course through the fuse. If the current flowing through a fuse is greater than this limit, then the fuse will break the circuit.

• MovingWindow and OrderedRingBuffer:

  • NaN values are treated as missing when gaps are determined in the OrderedRingBuffer.
  • Provide access to capacity (maximum number of elements) in MovingWindow.
  • Methods to retrieve oldest and newest timestamp of valid samples are added to both.
  • MovingWindow exposes underlying buffers window method.
  • len(window) and len(buffer) should be replaced with window.count_valid() and buffer.count_valid(), respectively.
  • OrderedRingBuffer.window:
    • By default returns a copy.
    • Can also return a view if the window contains None values and if force_copy is set to True.

• Now when printing FormulaEngine for debugging purposes the the formula will be shown in infix notation, which should be easier to read.

• The CI now runs cross-arch tests on arm64 architectures.

• The min and max functions in the FormulaEngine are now public. Note that the same functions have been public in the builder.

Bug Fixes

• OrderedRingBuffer.window:
  • Fixed force_copy option for specific case.
  • Removed buggy enforcement of copies when None values in queried window.
  • Fixed behavior for start equals end case.

What's Changed

• Clear release notes by @llucax in #617
• Initialize a Grid object with a given Fuse limit by @tiyash-basu-frequenz in #610
• Upgrade to repo-config v0.6.1 by @llucax in #620
• Bump polars from 0.18.15 to 0.19.1 by @dependabot in #626
• Bump the optional group with 4 updates by @dependabot in #634
• Bump types-setuptools from 68.1.0.0 to 68.1.0.1 by @dependabot in #635
• Don't return None from battery pool methods by @stefan-brus-frequenz in #612
• Clarify documentation of BatteryPool soc and capacity methods by @stefan-brus-frequenz in #637
• Document class and module attributes by @daniel-zullo-frequenz in #618
• Add microgrid.frequency() by @Marenz in #579
• Treat NaN as gap in ring buffer by @cwasicki in #641
• Replace obsolete types by @daniel-zullo-frequenz in #644
• Move "fake_time" fixture to conftest.py by @stefan-brus-frequenz in #639
• Improve formula formatting to use infix notation by @christianparpart in #613
• Merge v0.25.1 by @llucax in #652
• Add a glossary to the documentation by @llucax in #647
• Add capacity, oldest and newest timestamp to moving window by @cwasicki in #598
• [ci] Add tests for non-native architectures by @tiyash-basu-frequenz in #622
• Bump actions/checkout from 3 to 4 by @dependabot in #655
• ci: Fix publishing of documentation on push by @llucax in #657
• Add a job to join the nox matrix jobs by @llucax in #661
• Add more formula tests for min and max functions by @matthias-wende-frequenz in #623
• Fixes on copy behavior in ring buffer window method by @cwasicki in #638
• Drop formula step Averager by @christianparpart in #645
• Refactor power distribution Result by @daniel-zullo-frequenz in #659
• Adjust the glossary to 80 columns by @llucax in #666
• Replace len magic with count_valid method in ring buffer and moving window by @cwasicki in #664
• Prepare release notes for the 1.0.0-rc1 release by @llucax in #674

New Contributors

• @stefan-brus-frequenz made their first contribution in #612

Full Changelog: v0.25.1...v1.0.0-rc1