Document how to add constants to a sample stream

[matthias-wende-frequenz]

What's needed?

We can use the HigherLevelFormula to build new formulas out of existing FormalaEngines using standard arithmetic operations. That means we can write expression like.

net_power_recv = (
    (
        microgrid.logical_meter().producer_power
        + microgrid.logical_meter().consumer_power
    )
    .build("pv_excess_power")
    .new_receiver()
)

The question raised, how can we add a constant value to a stream. This is not possible using these mechanism and it turns out is not needed.

Proposed solution

We can simply transform the streamed value when it's sent into a channel by e.g. using the map function on the channels receiver.

diff_recv = (
    microgrid.logical_meter()
    .consumer_power.new_receiver()
    .map(lambda s: Sample(s.timestamp, s.value - my_const if s.value else None))
)

Furthermore if we implement arithmetic operation for the Sample type, this could be shortened as follows:

diff_recv = (
    microgrid.logical_meter()
    .consumer_power.new_receiver()
    .map(lambda s: s - my_const)
)

Since this solution doesn't involve any SDK tools but is still very useful, it should be documented.

Use cases

The use cases include scaling streams or adding offsets.

Alternatives and workarounds

We could add these operations to the higher level formulas.

[matthias-wende-frequenz]

We can add Quantity type constants now directly.