smartgrid.util.bounded

This module defines operations on bounded quantities.

A bounded quantity is a quantity with a lower and/or upper limits (bounds). Typically, it represents a physical quantity that realistically cannot go beyond these bounds, e.g., a quantity that cannot be negative will have a lower bound of 0.

Increasing and decreasing such quantities must take their bounds into account. For example, a quantity that cannot be higher than 100: when increasing this quantity by an amount, if the quantity + the amount exceeds 100, the rest will be considered an overhead. Similarly, when decreasing, if the quantity cannot be lower than 0, the operation will return a missing quantity.

Examples: (assuming a lower bound of 0, and an upper bound of 100)

  • 30 + 30 => new=60, overhead=0

  • 60 + 50 => new=100, overhead=10

  • 100 - 50 => new=50, missing=0

  • 50 - 70 => new=0, missing=20

The increase and decrease functions return the following tuple:

  • the new quantity, after the operation on the original quantity;

  • the amount that was actually added or subtracted: may be lower than the intended amount, based on the constraints;

  • the overhead or missing amount, i.e., the quantity that could not be added or subtracted. Note that the intended amount is equal to the actual amount + the overhead or missing amount.

members:

Functions

decrease_bounded(original_quantity, amount, ...)

Decrease a bounded quantity by an amount, enforcing a lower bound.

increase_bounded(original_quantity, amount, ...)

Increase a bounded quantity by an amount, enforcing an upper bound.