Releases: frequenz-floss/frequenz-sdk-python
v1.0.0-rc6
Frequenz Python SDK Release Notes
Summary
The most notable features for this release is the addition of the PVPool (exposed via microgrid.pv_pool()), which can be used to manage PV arrays as a single entity and the EVChargerPool (microgrid.ev_charger_pool()) learning to manage power for the whole pool (before it could only be used to control chargers individually).
Another notable change is the microgrid API client being moved to its own repository.
Upgrading
-
The SDK is now using the microgrid API client from
frequenz-client-microgrid. You should update your code if you are using the microgrid API client directly. -
The minimum required
frequenz-channelsversion is nowv1.0.0-rc1. -
The set of battery IDs managed by a battery pool are now available through
BatteryPool.component_ids, and no longer throughBatteryPool.battery_ids. This is done to have a consistent interface with other*Pools. -
The
maxsizeparameter in calls toBatteryPool.{soc/capacity/temperature}.new_receiver()methods have now been renamed tolimit, to be consistent with the channels repository. -
Support for per-component interaction in
EVChargerPoolhas been removed. Please use the newpropose_power()method to manage power for the whole pool. If you still need to manage power of chargers individually, you can create one pool per charger. -
PV power is now available from
microgrid.pv_pool().power, and no longer frommicrogrid.logical_meter().pv_power.
New Features
-
EVChargerPool/microgrid.ev_charger_pool(): Newpropose_powerandpower_statusmethods have been added, similar to theBatteryPool. These method interface with thePowerManagerandPowerDistributor, which currently uses a first-come-first-serve algorithm to distribute power to EVs. -
A PV pool (
PVPool/microgrid.pv_pool()) was added, withpropose_power,power_statusandpowermethods similar to Battery and EV pools. -
The microgrid API client now exposes the reactive power for inverters, meters and EV chargers.
Enhancements
-
Warning messages are logged when multiple instances of
*Pools are created for the same set of batteries, with the same priority values. -
A warning message will now be logged if no relevant samples are found in a component for resampling.
Bug Fixes
-
A bug was fixed where the grid fuse was not created properly and would end up with a
max_currentwith typefloatinstead ofCurrent. -
BatteryPool.propose_dischargenow converts power values to the passive-sign convention. Earlier it was not doing this and that was causing it to charge instead of discharge. -
Fix a bug that was causing the power managing actor to crash and restart when cleaning up old proposals.
What's Changed
- Clear release notes by @llucax in #617
- Initialize a
Gridobject with a givenFuselimit 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
Nonefrom 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
noxmatrix 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
- Clear the release notes by @llucax in #675
- Bump the optional group with 9 updates by @dependabot in #683
- Bump docker/setup-buildx-action from 2 to 3 by @dependabot in #680
- Bump docker/setup-qemu-action from 2 to 3 by @dependabot in #681
- Bump docker/build-push-action from 4 to 5 by @dependabot in #682
- Add mkdocs-macros plugin by @llucax in #667
- docs: Add an introduction to actors by @llucax in #679
- mkdocs: Fix numbered code annotations by @llucax in #684
- Add getting started tutorial and tutorial section by @matthias-wende-frequenz in #656
- Remove setitem magic from ring buffer by @cwasicki in #670
- Allow using macros in docstrings by @llucax in #687
- Rename datetime_to_index to to_internal_index by @cwasicki in #686
- Fix mermaid diagrams custom renderer by @llucax in #690
- Update obsolete comment about networkx-stubs by @daniel-zullo-frequenz in #685
- Move Actors documentation to the
actormodule by @llucax in #688 - Don't use generics unnecessarily by @llucax in #698
- Improve Actors documentation by @llucax in #689
- Increment port in microgrid API client tests by @llucax in #699
- Support int indices and slice index behavior in ring buffer and moving window by @cwasicki in #668
- Fix single element access for moving window by @cwasicki in #672
- Rename
IntroductiontoUser Guideand moveTutorialsnext to it by @llucax in #701 - Bump types-pytz from 2023.3.1.0 to 2023.3.1.1 by @dependabot in #695
- Bump types-protobuf from 4.24.0.1 to 4.24.0.2 by @dependabot in #696
- Bump types-pyyaml from 6.0.12.11 to 6.0.12.12 by @dependabot in #694
- PowerDistributing: Add support for n:m relations in invs:bats by @Marenz in #660
- Fix bug in how failed batteries are tracked in PowerDistributor by @shsms in #705
- Update pydantic to v2.3 by @daniel-zullo-frequenz in #703
- Add option to impute missing values in window method for moving windo...
v1.0.0-rc5
Frequenz Python SDK Release Notes
Summary
This is a minor non-breaking release that adds new features and fixes a few bug.
New Features
- Allow multiplying and dividing any
Quantityby afloat. This just scales theQuantityvalue. - Allow dividing any
Quantityby another quaintity of the same type. This just returns a ration between both quantities. - The battery pool
powermethod now supports scenarios where one or more inverters can have multiple batteries connected to it and one or more batteries can have multiple inverters connected to it.
Bug Fixes
- Fix grid current formula generator to add the operator
+to the engine only when the component category is handled. - Fix bug where sometimes the
base_valueof aQuantitycould be of a different type thanfloat.
What's Changed
- Clear release notes by @llucax in #871
- Fetch and stream 3-phase power by @daniel-zullo-frequenz in #847
- Remove remaining traces of darglint by @llucax in #873
- Make sure
base_valueis alwaysfloatby @llucax in #874 - Remove the last reference to darglint by @llucax in #877
- Mock resampler: Improve variable names by @llucax in #879
- Allow multiplying
Quantitybyfloatby @llucax in #875 - Remove unnecessary send adapter by @llucax in #878
- Bump actions/{up,down}load-artifact from 3 to 4 by @dependabot in #833
- Allow all quantities division by
float | Selfby @llucax in #876 - Cleanup and modularization of Power Manager, Power Distributor and DataPipeline by @shsms in #881
- More updates for n:m support - battery pool's power formula by @Marenz in #730
- Prepare release notes for 1.0.0-rc5 by @llucax in #884
Full Changelog: v1.0.0-rc4...v1.0.0-rc5
v1.0.0-rc4
Frequenz Python SDK Release Notes
Summary
This release represents 3 months of work so it includes a lot of changes. Most of them are (breaking) API changes, in the hopes to make a more consistent and easier to use SDK 1.0. There are also quite a few bug fixes and a couple of new features.
Upgrading
-
The
BatteryPool.power_statusmethod now streams objects of typeBatteryPoolReport, replacing the previousReportobjects. -
Channelshas been upgraded to version 1.0.0b2, for information on how to upgrade please read Channels release notes. -
In
BatteryPoolReport.distribution_result,- the following fields have been renamed:
Result.succeeded_batteries→Result.succeeded_componentsResult.failed_batteries→Result.failed_componentsRequest.batteries→Request.component_ids
- and the following fields are now type-hinted as
collections.abc.Set, to clearly indicate that they are read-only:Result.succeeded_componentsResult.failed_components
- the following fields have been renamed:
-
The
Fuseclass has been moved to thefrequenz.sdk.timeseriesmodule. -
microgrid.grid()-
A
Gridobject is always instantiated now, even if the microgrid is not connected to the grid (islanded microgrids). -
The rated current of the grid fuse is set to
Current.zero()in case of islanded microgrids. -
The grid fuse is set to
Nonewhen the grid connection component metadata lacks information about the fuse. -
Grid power and current metrics were moved from
microgrid.logical_meter()tomicrogrid.grid().Previously,
logical_meter = microgrid.logical_meter() grid_power_recv = logical_meter.grid_power.new_receiver() grid_current_recv = logical_meter.grid_current.new_receiver()
Now,
grid = microgrid.grid() grid_power_recv = grid.power.new_receiver() grid_current_recv = grid.current.new_receiver()
-
-
Consumer and producer power formulas were moved from
microgrid.logical_meter()tomicrogrid.consumer()andmicrogrid.producer(), respectively.Previously,
logical_meter = microgrid.logical_meter() consumer_power_recv = logical_meter.consumer_power.new_receiver() producer_power_recv = logical_meter.producer_power.new_receiver()
Now,
consumer_power_recv = microgrid.consumer().power.new_receiver() producer_power_recv = microgrid.producer().power.new_receiver()
-
The
ComponentGraph.components()parameterscomponent_idandcomponent_categorywere renamed tocomponent_idsandcomponent_categories, respectively. -
The
GridFrequency.componentproperty was renamed toGridFrequency.source -
The
microgrid.frequency()method no longer supports passing thecomponentparameter. Instead the best component is automatically selected. -
The
actor.ChannelRegistrywas rewritten to be type-aware and just a container of channels. You now need to provide the type of message that will be contained by the channel and use theget_or_create()method to get a channel and thestop_and_remove()method to stop and remove a channel. Once you get a channel you can create new senders and receivers, or set channel options, as usual. Please read the docs for a full description, but in general this:r = registry.new_receiver(name) s = registry.new_sender(name)
Should be replaced by:
r = registry.get_or_create(T, name).new_receiver() s = registry.get_or_create(T, name).new_sender()
-
The
ReceiverFetcherinterface was slightly changed to makemaxsizea keyword-only argument. This is to make it compatible with theBroadcastchannel, so it can be considered aReceiverFetcher.
New Features
-
A new method
microgrid.voltage()was added to allow easy access to the phase-to-neutral 3-phase voltage of the microgrid. -
The
actor.ChannelRegistryis now type-aware. -
A new class method
Quantity.from_string()has been added to allow the creation ofQuantityobjects from strings.
Bug Fixes
-
0W power requests are now not adjusted to exclusion bounds by the
PowerManagerandPowerDistributor, and are sent over to the microgrid API directly. -
microgrid.frequency()/GridFrequency:- Fix sent samples to use
Frequencyobjects instead of rawQuantity. - Handle
Nonevalues in the received samples properly. - Convert
nanvalues in the received samples toNone.
- Fix sent samples to use
-
The resampler now properly handles sending zero values.
A bug made the resampler interpret zero values as
Nonewhen generating new samples, so if the result of the resampling is zero, the resampler would just produceNonevalues. -
The PowerManager no longer holds on to proposals from dead actors forever. If an actor hasn't sent a new proposal in 60 seconds, the available proposal from that actor is dropped.
-
Fix
Quantity.__format__()sometimes skipping the number for very small values. -
Not strictly a bug fix, but the microgrid API version was bumped to v0.15.3, which indirectly bumps the common API dependency to v0.5.x, so the SDK can be compatible with other APIs using a newer version of the common API.
Downstream projects that require a
frequenz-api-commonv0.5.x and want to ensure proper dependency resolution should update their minimum SDK version to this release.
What's Changed
- Clear release notes by @llucax in #777
- Make
PowerManagingActormore modular and generic by @shsms in #773 - Fix type hint errors in microgrid client by @daniel-zullo-frequenz in #778
- Use custom loggers for each module by @daniel-zullo-frequenz in #780
- Bump types-protobuf from 4.24.0.3 to 4.24.0.4 by @dependabot in #749
- Modularize status tracking for pools of components in the power distributing actor by @shsms in #779
- Generalize PowerDistributingActor by @shsms in #786
- Move Fuse to timeseries module by @daniel-zullo-frequenz in #781
- Move grid power and current metrics to Grid by @daniel-zullo-frequenz in #758
- Bump frequenz-channels from 0.16 to 1.0.0b2 by @christianparpart in #764
- Rename
ComponentGraph.components()parameters to be plural by @Marenz in #791 - Update some tests to use time machine by @matthias-wende-frequenz in #798
- Un-Peekable-ification of the PowerDistributingActor by @shsms in #800
- Pass through 0W requests to the microgrid API independent of exclusion bounds by @shsms in #801
- Update
frequency()to no longer have parameters by @Marenz in #788 - Fix frequency sending
Quantityby @Marenz in #804 - Fix the resampler handling of output zeros by @llucax in #811
- Fetch and stream 3-phase voltage by @daniel-zullo-frequenz in #815
- Speedup tests by lowering the actors restart delay by @llucax in #828
- Bump actions/setup-python from 4 to 5 by @dependabot in #834
- Add missing type hints to instance members by @llucax in #809
- Fix bug in
GridFrequencyquantity conversion by @llucax in #807 - Improve (and fix some) test finalization by @llucax in #838
- Make the registry type-aware by @llucax in #830
- Improve BatteryPool's SoC accuracy at the edges by @shsms in #843
- Some component status cleanup by @shsms in #839
- Drop old propsals from the PowerManager by @shsms in #845
- Improvements to EVChargerData coming from the microgrid API by @shsms in #848
- Use a sentinel in
LatestValueCacheto denote if the cache is empty by @shsms in #846 - Move consumer and producer formulas out from logical meter by @daniel-zullo-frequenz in #799
- Parse Quantity Strings by @Marenz in #824
- Bump frequenz-api-microgrid to 0.15.3 by @llucax in #855
- Bump the optional group with 14 updates by @dependabot in #837
- Bump types-protobuf from 4.24.0.4 to 4.24.0.20240129 by @dependabot in #867
- Bump flake8 from 6.1.0 to 7.0.0 by @dependabot in #860
- Bump setuptools re...
v0.25.2
Frequenz Python SDK Release Notes
Bug Fixes
-
The resampler now properly handles sending zero values.
A bug made the resampler interpret zero values as
Nonewhen generating new samples, so if the result of the resampling is zero, the resampler would just produceNonevalues.
What's Changed
- Reset release notes by @matthias-wende-frequenz in #653
- Fix the resampler handling of output zeros by @llucax in #812
Full Changelog: v0.25.1...v0.25.2
v1.0.0-rc3
Frequenz Python SDK Release Notes
Summary
The microgrid package now exposes grid connections uniformly and introduces formula operators for consumption and production, replacing the logical_meter.*_{production,consumption}() formulas. The actor package restarts crashed actors with a delay, and the ConnectionManager exposes the microgrid_id and location details.
There are also a few bug fixes, documentation improvements and other minor breaking changes.
Upgrading
-
actorpackage-
Actors are now restarted after a small delay when they crash to avoid a busy loop and spamming the logs if the actor keeps failing to start.
-
The
include_broken_batteriesargument was removed from thePowerDistributingActor'sRequest. This option is no longer supported.
-
-
microgridpackage-
grid: The grid connection is now exposed asmicrogrid.grid(). This is more consistent with other objects exposed in themicrogridmodule, such asmicrogrid.battery_pool()andmicrogrid.logical_meter(). -
battery_pool(): Theinclude_broken_batteriesargument was removed from thepropose_*()methods (it was also removed from the underlying type,timeseries.BatteryPool). This option is no longer supported. -
ComponentGraph: The component graph is now exposed asmicrogrid.component_graph.ComponentGraph. -
logical_meter(): The*_consumption()and*_production()methods were removed. You should use the newconsumptionandproductionformula operators instead.For example:
# Old: pv_consumption = logical_meter.pv_consumption_power() production = (logical_meter.pv_production_power() + logical_meter.chp_production_power()).build() # New: pv_consumption = logical_meter.pv_power().consumption().build() production = (logical_meter.pv_power().production() + logical_meter.chp_power().production()).build()
-
New Features
-
The configuration flag
resend_latestcan now be changed for channels owned by theChannelRegistry. -
New formula operators for calculating
consumption()andproduction()were added. -
The
ConnectionManagernow fetches microgrid metadata when connecting to the microgrid and exposesmicrogrid_idandlocationproperties of the connected microgrid.Users can access this information using
microgrid.connection_manager.get().microgrid_idandmicrogrid.connection_manager.get().location. -
The documentation has been improved to:
- Display signatures with types.
- Show inherited members.
- Publish documentation for pre-releases.
- Present the full tag name as the documentation version.
- Ensure all development branches have their documentation published (the
nextversion has been removed). - Fix the order of the documentation versions.
Bug Fixes
-
Fixed incorrect grid current calculations in locations where the calculations depended on current measurements from an inverter.
-
Corrected the power failure report to exclude any failed power calculations from the successful ones.
What's Changed
- Remove support for
include_broken_batteriesin control commands by @shsms in #713 - Improve code reusability/modularity in PowerDistributor by @Marenz in #717
- Document microgrid concepts from an SDK perspective by @shsms in #722
- Documentation for the FormulaEngine by @shsms in #731
- Bump types-protobuf from 4.24.0.2 to 4.24.0.3 by @dependabot in #734
- Expose
ComponentGraphfrom its own module by @shsms in #738 - Document methods for creating data pipeline interface objects by @shsms in #739
- Add a restart delay to actors to avoid spam-restarting of buggy actors by @christianparpart in #741
- Rename datetime to timestamp variables by @daniel-zullo-frequenz in #742
- Redesign access to migrogrid.grid() by @christianparpart in #707
- Set
resent_latest=TrueforBatteryPool.power_status's channels by @shsms in #743 - Clean warnings in tests by @daniel-zullo-frequenz in #744
- Add consumtion and production operations to Formula Engine by @matthias-wende-frequenz in #746
- Use exclusion bounds while calculating target powers in PowerManager by @shsms in #755
- Remove the consumption and production power formulas by @matthias-wende-frequenz in #697
- Change internal presense of the Grid, eliminating
_gridby @christianparpart in #747 - Update DataSourcingActor to accept current requests for inverters by @shsms in #759
- Remove unused paranthesis in formula generators by @shsms in #761
- Fix bug in inverter current data extractor by @shsms in #762
- Rename nitrogen to Microgrid service by @andrew-stevenson-frequenz in #760
- Add try/finally to decorated context managers yield statement by @christianparpart in #757
- Fix power failure report by @daniel-zullo-frequenz in #763
- Update to repo-config v0.7.4 by @llucax in #752
- Make the SDK's representation of bounds data internal by @shsms in #756
- Bump mike from 1.1.2 to 2.0.0 by @dependabot in #766
- Use a custom logger in the data sourcing actor by @shsms in #769
- Fetch and expose microgrid ID and location by @daniel-zullo-frequenz in #708
- Prepare release notes for the v1.0.0-rc3 release by @llucax in #775
New Contributors
- @andrew-stevenson-frequenz made their first contribution in #760
Full Changelog: v1.0.0-rc2...v1.0.0-rc3
v1.0.0-rc2
Frequenz Python SDK Release Notes
Summary
This version ships an experimental version of the Power Manager and includes user documentation.
Upgrading
-
microgrid.battery_pool()method now accepts a priority value. -
BatteryPool's control methods- Original methods
{set_power/charge/discharge}are now replaced bypropose_{power/charge/discharge} - The
propose_*methods send power proposals to thePowerManagingActor, where it can be overridden by proposals from other actors. - They no longer have the
adjust_powerflag, because thePowerManagingActorwill always adjust power to fit within the available bounds.
- Original methods
-
BatteryPool's reporting methodspower_boundsis replaced bypower_status- The
power_statusmethod streams objects containing:- bounds adjusted to the actor's priorities
- the latest target power for the set of batteries
- the results from the power distributor for the last request
New Features
-
New and improved documentation.
-
A new User Guide section was added, with:
- A glossary.
- An introduction to actors.
-
A new Tutorials section was added, with:
- A getting started tutorial.
-
-
In
OrderedRingBuffer:- Rename
datetime_to_indextoto_internal_indexto avoid confusion between the internal index and the external index. - Add
index_to_datetimemethod to convert external index to corresponding datetime. - Remove
__setitem__method to enforce usage of dedicatedupdatemethod only.
- Rename
-
In
OrderedRingBufferandMovingWindow:- Support for integer indices is added.
- Add
count_coveredmethod to count the number of elements covered by the used time range. - Add
fill_valueoption to window method to impute missing values. By default missing values are imputed withNaN.
-
Add
atmethod toMovingWindowto access a single element and use it in__getitem__magic to fully support single element access. -
The PowerDistributingActor now supports n:m relations between inverters and batteries.
This means that one or more inverters can be connected to one or more batteries.
-
A
PowerManagingActorimplementation
Bug Fixes
- Fix rendering of diagrams in the documentation.
- The
__getitem__magic of theMovingWindowis fixed to support the same functionality that thewindowmethod provides. - Fixes incorrect implementation of single element access in
__getitem__magic ofMovingWindow.
What's Changed
- Clear the release notes by @llucax in #675
- Bump the optional group with 9 updates by @dependabot in #683
- Bump docker/setup-buildx-action from 2 to 3 by @dependabot in #680
- Bump docker/setup-qemu-action from 2 to 3 by @dependabot in #681
- Bump docker/build-push-action from 4 to 5 by @dependabot in #682
- Add mkdocs-macros plugin by @llucax in #667
- docs: Add an introduction to actors by @llucax in #679
- mkdocs: Fix numbered code annotations by @llucax in #684
- Add getting started tutorial and tutorial section by @matthias-wende-frequenz in #656
- Remove setitem magic from ring buffer by @cwasicki in #670
- Allow using macros in docstrings by @llucax in #687
- Rename datetime_to_index to to_internal_index by @cwasicki in #686
- Fix mermaid diagrams custom renderer by @llucax in #690
- Update obsolete comment about networkx-stubs by @daniel-zullo-frequenz in #685
- Move Actors documentation to the
actormodule by @llucax in #688 - Don't use generics unnecessarily by @llucax in #698
- Improve Actors documentation by @llucax in #689
- Increment port in microgrid API client tests by @llucax in #699
- Support int indices and slice index behavior in ring buffer and moving window by @cwasicki in #668
- Fix single element access for moving window by @cwasicki in #672
- Rename
IntroductiontoUser Guideand moveTutorialsnext to it by @llucax in #701 - Bump types-pytz from 2023.3.1.0 to 2023.3.1.1 by @dependabot in #695
- Bump types-protobuf from 4.24.0.1 to 4.24.0.2 by @dependabot in #696
- Bump types-pyyaml from 6.0.12.11 to 6.0.12.12 by @dependabot in #694
- PowerDistributing: Add support for n:m relations in invs:bats by @Marenz in #660
- Fix bug in how failed batteries are tracked in PowerDistributor by @shsms in #705
- Update pydantic to v2.3 by @daniel-zullo-frequenz in #703
- Add option to impute missing values in window method for moving window by @cwasicki in #669
- Bump pydoclint from 0.3.2 to 0.3.3 by @dependabot in #710
- Implement the PowerManagingActor by @shsms in #692
- Prepare release notes for v1.0.0-rc2 by @llucax in #723
Full Changelog: v1.0.0-rc1...v1.0.0-rc2
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
Nonewhen no batteries are available. Instead, the value of theSampleorPowerMetricis set toNone. -
The power distribution
Resultis now a union of all different types of results rather than a base class. This means we can now also usematchto check for result types instead of only usingisinstance(). The following example shows howResultcan 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)
-
Averagerwas removed fromFormulaEngine.
New Features
-
Calling
microgrid.initialize()now also initializes the microgrid's grid connection point as a singleton object of a newly added typeGrid. This object can be obtained by callingmicrogrid.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 callingmicrogrid.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
Fusehas been added to represent fuses. This class has a member variablemax_currentwhich 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. -
MovingWindowandOrderedRingBuffer:- NaN values are treated as missing when gaps are determined in the
OrderedRingBuffer. - Provide access to
capacity(maximum number of elements) inMovingWindow. - Methods to retrieve oldest and newest timestamp of valid samples are added to both.
MovingWindowexposes underlying bufferswindowmethod.len(window)andlen(buffer)should be replaced withwindow.count_valid()andbuffer.count_valid(), respectively.OrderedRingBuffer.window:- By default returns a copy.
- Can also return a view if the window contains
Nonevalues and ifforce_copyis set toTrue.
- NaN values are treated as missing when gaps are determined in the
-
Now when printing
FormulaEnginefor 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
arm64architectures. -
The
minandmaxfunctions in theFormulaEngineare now public. Note that the same functions have been public in the builder.
Bug Fixes
OrderedRingBuffer.window:- Fixed
force_copyoption for specific case. - Removed buggy enforcement of copies when None values in queried window.
- Fixed behavior for start equals end case.
- Fixed
What's Changed
- Clear release notes by @llucax in #617
- Initialize a
Gridobject with a givenFuselimit 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
Nonefrom 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
noxmatrix 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
v0.25.1
Frequenz Python SDK Release Notes
Bug Fixes
-
Fix the API Reference link in the documentation website navigation bar.
-
Fix the consumer power formula
What's Changed
- Fix mkdocs navigation bar API link by @llucax in #642
- Fix consumer power formula by @matthias-wende-frequenz in #649
Full Changelog: v0.25.0...v0.25.1
v0.25.0
Frequenz Python SDK Release Notes
Summary
This release replaces the @actor decorator with a new Actor class.
Upgrading
-
The
frequenz.sdk.powerpackage 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 typeOutOfBoundhas been renamed toOutOfBounds, and its member variableboundhas been renamed tobounds. -
The
@actordecorator was replaced by the newActorclass. 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 thefrequenz.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
Exceptionis raised by_run(). It will not be restarted if the_run()method finishes normally. If an unhandledBaseExceptionis raised instead, it will be re-raised. For normal cancellation the_run()method should handleasyncio.CancelledErrorif the cancellation shouldn't be propagated (this is the same as with the decorator). - The
_stop()method is public (stop()) and willcancel()andawaitfor the task to finish, catching theasyncio.CancelledError. - The
join()method is renamed towait(), but they can also be awaited directly (await actor). - For deterministic cleanup, actors can now be used as
asynccontext managers.
Most actors can be migrated following these steps:
- Remove the decorator
- Add
Actoras a base class - Rename
run()to_run() - Forward the
nameargument (optional but recommended)
For example, this old actor:
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:
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:
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
- It doesn't start automatically,
-
The
MovingWindowis now aBackgroundService, so it needs to be started manually withwindow.start(). It is recommended to use it as anasynccontext manager if possible though: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 newActorclass, if you are using them directly, you need to start them manually withactor.start()and you might need to do some other adjustments. -
The
BatteryPool.power_distribution_resultsmethod has been enhanced to provide power distribution results in the form ofPowerobjects, replacing the previous use offloatvalues. -
In the
Requestclass:- The attribute
request_timeout_sechas been updated and is now namedrequest_timeoutand it is represented by atimedeltaobject rather than afloat. - The attribute
poweris now presented as aPowerobject, as opposed to afloat.
- The attribute
-
Within the
EVChargerPool.set_boundsmethod, the parametermax_ampshas been redefined asmax_current, and it is now represented using aCurrentobject instead of afloat. -
The argument
nones_are_zerosinFormulaEngineand related classes and methods is now a keyword-only argument.
New Features
-
Added
DFSto 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 anasynccontext 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 fromBackgroundServiceand it replaces the@actordecorator. -
Newly added
minandmaxfunctions for Formulas. They can be used as follows:formula1.min(formula2)
Bug Fixes
-
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 withInverter -> PVis 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_powernot working in setups with 2 grid meters by using a new reliable function to search for components in the components graph -
Fix
consumer_powerandproducer_powersimilar topv_power -
Zero value requests received by the
PowerDistributingActorwill now always be accepted, even when there are non-zero exclusion bounds. -
Hold on to a reference to all streaming tasks in the microgrid API client, so they don't get garbage collected.
What's Changed
- Fix ring buffer gap cleanup code by @matthias-wende-frequenz in #578
- Amend deficit calculation in the power distributor by @daniel-zullo-frequenz in #577
- Clear release notes by @llucax in #574
- Bump types-protobuf from 4.23.0.3 to 4.24.0.0 by @dependabot in #576
- Bump mypy from 1.4.1 to 1.5.0 by @dependabot in #580
- Support PV configurations with no or only some meters by @Marenz in #584
- Bump mypy from 1.5.0 to 1.5.1 by @dependabot in #585
- Bump types-protobuf from 4.24.0.0 to 4.24.0.1 by @dependabot in #581
- Bump time-machine from 2.11.0 to 2.12.0 by @dependabot in #582
- Some very small fixes by @Marenz in #590
- Bump mkdocs-material from 9.1.21 to 9.2.1 by @dependabot in #592
- Fix
consumer_power()not working certain configurations. by @Marenz in #589 - Add depth first search for components by @matthias-wende-frequenz in #595
- [ci] Add test for installation in multiple architectures by @tiyash-basu-frequenz in #597
- Improve formula generators by @matthias-wende-frequenz in #599
- Forward zero power requests always to the microgrid API by @shsms in #591
- Implement BackgroundService and new Actor class by @llucax in #564
- Replace absolute imports with relative imports by @tiyash-basu-frequenz in #604
- Drop example to private PowerDistributor API by @christianparpart in #605
- Bump mkdocs-material from 9.2.1 to 9.2.5 by @dependabot in #608
- Improve consumer power formula by @matthias-wende-frequenz in #609
- Update high-level public interfaces to concrete types by @daniel-zullo-frequenz in #607
- Make nones_are_zeros a keyword-only parameter by @daniel-zullo-frequenz in #611
- Improve error message for incorrect component graphs by @tiyash-basu-frequenz in #602
- DataPipeline: Fix resampling/ds/power actors not started by @Marenz in #603
- Bump polars from 0.18.13 to 0.18.15 by @dependabot in #583
- Add module to easily create component graphs by @Marenz in #606
- Upgrade to repo-config v0.5.2 by @llucax in #587
- Store references to streaming tasks by @shsms in #615
- Add min and max operations to formula engine by @matthias-wende-frequenz in #561
New Contributors
- @tiyash-basu-frequenz made their first contribution in #597
Full Changelog: https://github.com/frequenz...
v0.16.4
Release Notes
Bug Fixes
- Hold on to a reference to all streaming tasks in the microgrid API client, so they don't get garbage collected.
What's Changed
Full Changelog: v0.16.3...v0.16.4