Releases: frequenz-floss/frequenz-sdk-python
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
Quantity
by afloat
. This just scales theQuantity
value. - Allow dividing any
Quantity
by another quaintity of the same type. This just returns a ration between both quantities. - The battery pool
power
method 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_value
of aQuantity
could 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_value
is alwaysfloat
by @llucax in #874 - Remove the last reference to darglint by @llucax in #877
- Mock resampler: Improve variable names by @llucax in #879
- Allow multiplying
Quantity
byfloat
by @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 | Self
by @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_status
method now streams objects of typeBatteryPoolReport
, replacing the previousReport
objects. -
Channels
has 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_components
Result.failed_batteries
→Result.failed_components
Request.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_components
Result.failed_components
- the following fields have been renamed:
-
The
Fuse
class has been moved to thefrequenz.sdk.timeseries
module. -
microgrid.grid()
-
A
Grid
object 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
None
when 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_id
andcomponent_category
were renamed tocomponent_ids
andcomponent_categories
, respectively. -
The
GridFrequency.component
property was renamed toGridFrequency.source
-
The
microgrid.frequency()
method no longer supports passing thecomponent
parameter. Instead the best component is automatically selected. -
The
actor.ChannelRegistry
was 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
ReceiverFetcher
interface was slightly changed to makemaxsize
a keyword-only argument. This is to make it compatible with theBroadcast
channel, 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.ChannelRegistry
is now type-aware. -
A new class method
Quantity.from_string()
has been added to allow the creation ofQuantity
objects from strings.
Bug Fixes
-
0W power requests are now not adjusted to exclusion bounds by the
PowerManager
andPowerDistributor
, and are sent over to the microgrid API directly. -
microgrid.frequency()
/GridFrequency
:- Fix sent samples to use
Frequency
objects instead of rawQuantity
. - Handle
None
values in the received samples properly. - Convert
nan
values 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
None
when generating new samples, so if the result of the resampling is zero, the resampler would just produceNone
values. -
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-common
v0.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
PowerManagingActor
more 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
Quantity
by @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
GridFrequency
quantity 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
LatestValueCache
to 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
None
when generating new samples, so if the result of the resampling is zero, the resampler would just produceNone
values.
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
-
actor
package-
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_batteries
argument was removed from thePowerDistributingActor
'sRequest
. This option is no longer supported.
-
-
microgrid
package-
grid
: The grid connection is now exposed asmicrogrid.grid()
. This is more consistent with other objects exposed in themicrogrid
module, such asmicrogrid.battery_pool()
andmicrogrid.logical_meter()
. -
battery_pool()
: Theinclude_broken_batteries
argument 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 newconsumption
andproduction
formula 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_latest
can now be changed for channels owned by theChannelRegistry
. -
New formula operators for calculating
consumption()
andproduction()
were added. -
The
ConnectionManager
now fetches microgrid metadata when connecting to the microgrid and exposesmicrogrid_id
andlocation
properties of the connected microgrid.Users can access this information using
microgrid.connection_manager.get().microgrid_id
andmicrogrid.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
next
version 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_batteries
in 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
ComponentGraph
from 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=True
forBatteryPool.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
_grid
by @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_power
flag, because thePowerManagingActor
will always adjust power to fit within the available bounds.
- Original methods
-
BatteryPool
's reporting methodspower_bounds
is replaced bypower_status
- The
power_status
method 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_index
toto_internal_index
to avoid confusion between the internal index and the external index. - Add
index_to_datetime
method to convert external index to corresponding datetime. - Remove
__setitem__
method to enforce usage of dedicatedupdate
method only.
- Rename
-
In
OrderedRingBuffer
andMovingWindow
:- Support for integer indices is added.
- Add
count_covered
method to count the number of elements covered by the used time range. - Add
fill_value
option to window method to impute missing values. By default missing values are imputed withNaN
.
-
Add
at
method toMovingWindow
to 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
PowerManagingActor
implementation
Bug Fixes
- Fix rendering of diagrams in the documentation.
- The
__getitem__
magic of theMovingWindow
is fixed to support the same functionality that thewindow
method 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
actor
module 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
Introduction
toUser Guide
and moveTutorials
next 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
None
when no batteries are available. Instead, the value of theSample
orPowerMetric
is set toNone
. -
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 usematch
to check for result types instead of only usingisinstance()
. The following example shows howResult
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 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
Fuse
has been added to represent fuses. This class has a member variablemax_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
andOrderedRingBuffer
:- 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.
MovingWindow
exposes underlying bufferswindow
method.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
None
values and ifforce_copy
is set toTrue
.
- NaN values are treated as missing when gaps are determined in the
-
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
andmax
functions in theFormulaEngine
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.
- Fixed
What's Changed
- Clear release notes by @llucax in #617
- Initialize a
Grid
object with a givenFuse
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
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.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 typeOutOfBound
has been renamed toOutOfBounds
, and its member variablebound
has been renamed tobounds
. -
The
@actor
decorator was replaced by the newActor
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 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
Exception
is raised by_run()
. It will not be restarted if the_run()
method finishes normally. If an unhandledBaseException
is raised instead, it will be re-raised. For normal cancellation the_run()
method should handleasyncio.CancelledError
if the cancellation shouldn't be propagated (this is the same as with the decorator). - The
_stop()
method is public (stop()
) and willcancel()
andawait
for 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
async
context managers.
Most actors can be migrated following these steps:
- Remove the decorator
- Add
Actor
as a base class - Rename
run()
to_run()
- Forward the
name
argument (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
MovingWindow
is now aBackgroundService
, so it needs to be started manually withwindow.start()
. It is recommended to use it as anasync
context 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 newActor
class, 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_results
method has been enhanced to provide power distribution results in the form ofPower
objects, replacing the previous use offloat
values. -
In the
Request
class:- The attribute
request_timeout_sec
has been updated and is now namedrequest_timeout
and it is represented by atimedelta
object rather than afloat
. - The attribute
power
is now presented as aPower
object, as opposed to afloat
.
- The attribute
-
Within the
EVChargerPool.set_bounds
method, the parametermax_amps
has been redefined asmax_current
, and it is now represented using aCurrent
object instead of afloat
. -
The argument
nones_are_zeros
inFormulaEngine
and related classes and methods is now a keyword-only argument.
New Features
-
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 anasync
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 fromBackgroundService
and it replaces the@actor
decorator. -
Newly added
min
andmax
functions 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 -> 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
andproducer_power
similar topv_power
-
Zero value requests received by the
PowerDistributingActor
will 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
v0.24.0
Frequenz Python SDK Release Notes
Summary
Now the microgrid API v0.15.x is being used. The SDK can only connect to microgrids using this version of the API. Inclusion and exclusion bounds in the new API are now handled by the power distributor and battery pool.
Upgrading
-
Upgrade to microgrid API v0.15.1. If you're using any of the lower level microgrid interfaces, you will need to upgrade your code.
-
The argument
conf_file
of theConfigManagingActor
constructor was renamed toconfig_path
. -
The
BatteryPool.power_bounds
method now streams inclusion/exclusion bounds. The bounds are now represented byPower
objects and notfloat
s.
New Features
-
The
ConfigManagingActor
constructor now can accept apathlib.Path
asconfig_path
too (before it accepted only astr
). -
The
PowerDistributingActor
now considers exclusion bounds, when finding an optimal distribution for power between batteries.
What's Changed
- Use
Timer.periodic
in theResampler
by @jh2007github in #520 - Allow running release notes check in merge queues by @llucax in #566
- Clear release notes by @llucax in #560
- Update
frequenz-api-microgrid
to v0.15.1 by @shsms in #416 - Improvements to the
ConfigManagingActor
by @llucax in #565 - Bump brettcannon/check-for-changed-files from 294a99714e0d350b5083472a293d41bc91804e68 to 4170644959a21843b31f1181f2a1761d65ef4791 by @dependabot in #567
- Bump types-protobuf from 4.23.0.2 to 4.23.0.3 by @dependabot in #568
- Bump polars from 0.18.11 to 0.18.12 by @dependabot in #569
- Stream exclusion bounds from the battery pool by @shsms in #537
- Bump polars from 0.18.12 to 0.18.13 by @dependabot in #570
- Add docs cross-linking to APIs by @llucax in #571
- Support exclusion bounds in power distributor by @shsms in #562
- Update release notes for the v0.24.0 release by @llucax in #573
Full Changelog: v0.23.0...v0.24.0