energy.estimate-read

daily average = units between the earlier and latest reads / days between them
units         = daily average x days from the latest read to the date
read          = latest read + units, wrapped past all nines

def estimate_read(earlier_read: MeterRead, latest_read: MeterRead, on_date: str, digits: int, mode: RoundingMode) -> EstimatedRead

@dataclass(frozen=True)
class MeterRead:
    """One meter read."""

    date: str
    #: the register, whole units
    value: int

@dataclass(frozen=True)
class EstimatedRead:
    """The estimate, as the meter would show it, and the units behind it."""

    #: the estimated register, wrapped past all nines if it rolls over
    read: int
    #: estimated consumption since the latest read
    units: int
    #: true when the estimate passes the top of the register
    rolled_over: bool

from fune.energy.estimate_read import estimate_read  # energy.estimate-read@^1

from .dates_days_between import days_between  ← from dates.days-between ^1.0.0 · built alongside by fune
from .energy_estimate_read_types import EstimatedRead, MeterRead
from .energy_meter_advance import meter_advance  ← from energy.meter-advance ^1.0.0 · built alongside by fune
from .math_round_div import RoundingMode, round_div  ← from math.round-div ^1.0.0 · built alongside by fune

MAX_SAFE = 9007199254740991


def estimate_read(
    earlier_read: MeterRead, latest_read: MeterRead, on_date: str, digits: int, mode: RoundingMode
) -> EstimatedRead:
    """Carry the latest read forward to ``on_date`` at the average daily
    consumption between the two reads, rounding once, and wrap past all nines.
    """
    consumption = meter_advance(earlier_read.value, latest_read.value, digits)
    history = days_between(earlier_read.date, latest_read.date)
    if history <= 0:
        raise ValueError(
            "the earlier read must be dated before the latest read, received %s and %s"
            % (earlier_read.date, latest_read.date)
        )
    ahead = days_between(latest_read.date, on_date)
    if ahead < 0:
        raise ValueError(
            "onDate must not be before the latest read, received %s and %s" % (on_date, latest_read.date)
        )
    product = consumption * ahead
    if product > MAX_SAFE:
        raise ValueError("estimate too large to calculate exactly")
    units = round_div(product, history, mode)
    span = 10**digits
    raw = latest_read.value + units
    return EstimatedRead(read=raw % span, units=units, rolled_over=raw >= span)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add energy.estimate-read

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./energy.estimate-read-1.0.0-python.fune, or fetch it from a terminal with fune pull energy.estimate-read@1.0.0:python.

The whole function, every language, is one file too: energy.estimate-read-1.0.0.fune, 14,637 bytes, sha256 bd37a314f3d4d7631725632979d80c4bbf86d74141a4ebafa8a57187faea246f. It installs into a project of any language.

# fune: before energy.estimate-read

# fune: after energy.estimate-read

# fune: replace dates.days-between in energy.estimate-read
# fune: replace energy.meter-advance in energy.estimate-read
# fune: replace math.round-div in energy.estimate-read

# fune: step energy.estimate-read after <n|label>

More from the author

It works for any cumulative meter: electricity kWh, gas units, water m³.

## Decisions

- **One rounding.** The estimate is `consumption x days ahead / days of history`, computed exactly and rounded once to a whole unit by `mode`. Rounding the daily average first (as a spreadsheet often does) drifts: 100 units over 30 days is 3.33 a day, and 30 days of "3" is 90, not 100. - **Rollover both ways.** The history can span a rollover (99,900 to 00,100 on a five-digit meter is 200 units, via `energy.meter-advance`), and so can the estimate: 99,800 plus 600 units shows as 00,400 with `rolledOver` true. - **The average is flat.** Two reads give one average. Seasonal profiles (Elexon profile classes, the gas industry's annual quantity) weigh winter days more heavily; to use one, pass reads a year apart covering the same season, or compute the units yourself. - **Dates.** The earlier read must be strictly before the latest; the target date may equal the latest read (an estimate of zero units) but not precede it. Days come from `dates.days-between`, so leap days count.

## Source

Ofgem describes estimated bills as based on the customer's previous usage; there is no prescribed formula, and this is the simplest defensible one. The rollover rule is that of `energy.meter-advance`.

Files