utility-tariffs-lib 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- utility_tariffs_lib-0.1.0/LICENSE +21 -0
- utility_tariffs_lib-0.1.0/PKG-INFO +61 -0
- utility_tariffs_lib-0.1.0/README.md +81 -0
- utility_tariffs_lib-0.1.0/lib/README.md +41 -0
- utility_tariffs_lib-0.1.0/lib/__init__.py +0 -0
- utility_tariffs_lib-0.1.0/lib/py.typed +0 -0
- utility_tariffs_lib-0.1.0/lib/tariff/__init__.py +164 -0
- utility_tariffs_lib-0.1.0/lib/tariff/accumulator.py +195 -0
- utility_tariffs_lib-0.1.0/lib/tariff/bands.py +124 -0
- utility_tariffs_lib-0.1.0/lib/tariff/bill_days.py +73 -0
- utility_tariffs_lib-0.1.0/lib/tariff/billing.py +28 -0
- utility_tariffs_lib-0.1.0/lib/tariff/compile.py +124 -0
- utility_tariffs_lib-0.1.0/lib/tariff/config.py +208 -0
- utility_tariffs_lib-0.1.0/lib/tariff/defaults.py +16 -0
- utility_tariffs_lib-0.1.0/lib/tariff/definition.py +321 -0
- utility_tariffs_lib-0.1.0/lib/tariff/definition_parse.py +765 -0
- utility_tariffs_lib-0.1.0/lib/tariff/definition_savings.py +116 -0
- utility_tariffs_lib-0.1.0/lib/tariff/demand.py +44 -0
- utility_tariffs_lib-0.1.0/lib/tariff/engine.py +284 -0
- utility_tariffs_lib-0.1.0/lib/tariff/index.py +309 -0
- utility_tariffs_lib-0.1.0/lib/tariff/period_bill.py +136 -0
- utility_tariffs_lib-0.1.0/lib/tariff/periods.py +34 -0
- utility_tariffs_lib-0.1.0/lib/tariff/price_curve.py +142 -0
- utility_tariffs_lib-0.1.0/lib/tariff/price_series.py +137 -0
- utility_tariffs_lib-0.1.0/lib/tariff/price_stats.py +194 -0
- utility_tariffs_lib-0.1.0/lib/tariff/price_timeline.py +139 -0
- utility_tariffs_lib-0.1.0/lib/tariff/reprice.py +106 -0
- utility_tariffs_lib-0.1.0/lib/tariff/savings.py +118 -0
- utility_tariffs_lib-0.1.0/lib/tariff/slot_history.py +128 -0
- utility_tariffs_lib-0.1.0/lib/tariff/slots.py +266 -0
- utility_tariffs_lib-0.1.0/lib/tariff/stored_energy.py +64 -0
- utility_tariffs_lib-0.1.0/lib/tariff/windows.py +119 -0
- utility_tariffs_lib-0.1.0/lib/tariffranking/__init__.py +39 -0
- utility_tariffs_lib-0.1.0/lib/tariffranking/search.py +189 -0
- utility_tariffs_lib-0.1.0/lib/tariffstore/__init__.py +13 -0
- utility_tariffs_lib-0.1.0/lib/tariffstore/client.py +406 -0
- utility_tariffs_lib-0.1.0/lib/tariffstore/compile.py +157 -0
- utility_tariffs_lib-0.1.0/lib/tariffstore/index.py +188 -0
- utility_tariffs_lib-0.1.0/lib/tariffstore/layout.py +39 -0
- utility_tariffs_lib-0.1.0/lib/tariffstore/price_client.py +87 -0
- utility_tariffs_lib-0.1.0/lib/tariffstore/prices.py +127 -0
- utility_tariffs_lib-0.1.0/lib/tariffstore/schema.py +550 -0
- utility_tariffs_lib-0.1.0/lib/timeutil/__init__.py +5 -0
- utility_tariffs_lib-0.1.0/lib/timeutil/real_time.py +52 -0
- utility_tariffs_lib-0.1.0/pyproject.toml +69 -0
- utility_tariffs_lib-0.1.0/setup.cfg +4 -0
- utility_tariffs_lib-0.1.0/tests/test_build.py +124 -0
- utility_tariffs_lib-0.1.0/tests/test_client.py +388 -0
- utility_tariffs_lib-0.1.0/tests/test_compile.py +159 -0
- utility_tariffs_lib-0.1.0/tests/test_eia861_map.py +115 -0
- utility_tariffs_lib-0.1.0/tests/test_end_to_end.py +154 -0
- utility_tariffs_lib-0.1.0/tests/test_index.py +129 -0
- utility_tariffs_lib-0.1.0/tests/test_lib_release_notes.py +42 -0
- utility_tariffs_lib-0.1.0/tests/test_packaging.py +33 -0
- utility_tariffs_lib-0.1.0/tests/test_price_client.py +90 -0
- utility_tariffs_lib-0.1.0/tests/test_price_format.py +74 -0
- utility_tariffs_lib-0.1.0/tests/test_prices.py +142 -0
- utility_tariffs_lib-0.1.0/tests/test_prices_comed.py +90 -0
- utility_tariffs_lib-0.1.0/tests/test_prices_energinet.py +88 -0
- utility_tariffs_lib-0.1.0/tests/test_prices_energy_charts.py +94 -0
- utility_tariffs_lib-0.1.0/tests/test_prices_energyzero.py +75 -0
- utility_tariffs_lib-0.1.0/tests/test_prices_runner.py +34 -0
- utility_tariffs_lib-0.1.0/tests/test_repo_rules.py +112 -0
- utility_tariffs_lib-0.1.0/tests/test_schema.py +381 -0
- utility_tariffs_lib-0.1.0/tests/test_sources_dk.py +92 -0
- utility_tariffs_lib-0.1.0/tests/test_sources_electric_ireland.py +234 -0
- utility_tariffs_lib-0.1.0/tests/test_sources_gb.py +304 -0
- utility_tariffs_lib-0.1.0/tests/test_sources_hq.py +118 -0
- utility_tariffs_lib-0.1.0/tests/test_sources_ie.py +203 -0
- utility_tariffs_lib-0.1.0/tests/test_sources_other.py +380 -0
- utility_tariffs_lib-0.1.0/tests/test_sources_pt.py +165 -0
- utility_tariffs_lib-0.1.0/tests/test_sources_us.py +132 -0
- utility_tariffs_lib-0.1.0/tests/test_stored_tariffs.py +130 -0
- utility_tariffs_lib-0.1.0/tests/test_sync_core.py +275 -0
- utility_tariffs_lib-0.1.0/tests/test_sync_run.py +162 -0
- utility_tariffs_lib-0.1.0/tests/test_tariffs_through_lib.py +600 -0
- utility_tariffs_lib-0.1.0/tests/test_urdb_convert.py +263 -0
- utility_tariffs_lib-0.1.0/utility_tariffs_lib.egg-info/PKG-INFO +61 -0
- utility_tariffs_lib-0.1.0/utility_tariffs_lib.egg-info/SOURCES.txt +79 -0
- utility_tariffs_lib-0.1.0/utility_tariffs_lib.egg-info/dependency_links.txt +1 -0
- utility_tariffs_lib-0.1.0/utility_tariffs_lib.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 macuistin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: utility-tariffs-lib
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Tariff model, bill engine, price series, store client and plan ranking
|
|
5
|
+
Author: macuistin
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/macuistin/utility-tariffs
|
|
8
|
+
Project-URL: Issues, https://github.com/macuistin/utility-tariffs/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/macuistin/utility-tariffs/releases
|
|
10
|
+
Keywords: tariff,electricity,energy,billing,home-assistant
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
14
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
15
|
+
Classifier: Typing :: Typed
|
|
16
|
+
Requires-Python: >=3.14
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
Dynamic: license-file
|
|
20
|
+
|
|
21
|
+
# lib/
|
|
22
|
+
|
|
23
|
+
The store library and the bill engine. This repository is where both are written and tested, and
|
|
24
|
+
it is the source of truth for all tariff and billing code and calculations. They use only the
|
|
25
|
+
standard library, so any script, skill or integration can import or copy them.
|
|
26
|
+
|
|
27
|
+
| Folder | What it holds |
|
|
28
|
+
| --- | --- |
|
|
29
|
+
| `tariff/` | The tariff definition reader, the bill engine, band assignment, half-hourly slots and repricing. `tariff/README.md` lists the public names |
|
|
30
|
+
| `tariffstore/` | The store's own code: validator, checksum, index build, compile step and the client (`Store`) |
|
|
31
|
+
| `tariffranking/` | Prices every plan over the same measured usage and ranks them, with the current plan's rank. Imports `tariff/` only |
|
|
32
|
+
| `timeutil/` | Clock helpers that `tariff/` imports (`shift_real`, `elapsed_seconds`, `local_time_on`) |
|
|
33
|
+
|
|
34
|
+
## Using it from another project
|
|
35
|
+
|
|
36
|
+
Copy the folders as they stand and do not edit the copy. Record the commit copied, so a
|
|
37
|
+
later copy can be compared. The Home Assistant integration `macuistin/givenergy_inverter_manager`
|
|
38
|
+
does this with a script, a weekly workflow that opens a pull request, and a release check. Change
|
|
39
|
+
the code here, with its tests, and let the copy follow.
|
|
40
|
+
|
|
41
|
+
`tariff/` and `timeutil/` began in that integration and moved here on 2026-11-11, unchanged from
|
|
42
|
+
its commit `68ec1923ac68817032dfaa51cc3c82817d2ce115`.
|
|
43
|
+
|
|
44
|
+
The code uses Python 3.14 syntax (for example `except A, B:`), so it needs Python 3.14 or newer.
|
|
45
|
+
|
|
46
|
+
## Known gaps between the tariff files and the engine
|
|
47
|
+
|
|
48
|
+
Found by `tests/test_tariffs_through_lib.py`. A tariff file is not what the engine reads. The
|
|
49
|
+
compile step (`lib/tariffstore/compile.py`) builds the library's definition from a tariff file and its
|
|
50
|
+
country block, and closes most gaps itself. What remains is work in `lib/tariff`.
|
|
51
|
+
|
|
52
|
+
1. The library accepts only ISO 3166-2 region codes. Our area `region` codes (`GSP-A`,
|
|
53
|
+
`OFGEM-EASTERN`) are not, so compile leaves the region null. A customer's region is chosen by the
|
|
54
|
+
area key.
|
|
55
|
+
2. Closed. The library prices an export by time of day (export
|
|
56
|
+
`zones`), so Prime Outgoing's 16:00 to 19:00 rate is credited by band.
|
|
57
|
+
3. The library requires an `export` price in every definition. With no export file paired, compile
|
|
58
|
+
supplies 0 and adds no export line, so an unpaired tariff credits nothing. The library cannot say
|
|
59
|
+
"unknown".
|
|
60
|
+
4. A bill period is a whole number of calendar months. The library has no period of a fixed
|
|
61
|
+
number of days, and no volume tiers, demand charges or dynamic prices. `docs/design.md` lists what each would need.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Tariff prices
|
|
2
|
+
|
|
3
|
+
Open, versioned electricity tariff definitions, an index to find them by country, provider and
|
|
4
|
+
tariff, and a small library that fetches one, checks it and hands it to a bill engine. Each tariff
|
|
5
|
+
is a JSON document. No tariff contains code or formulas.
|
|
6
|
+
|
|
7
|
+
## Layout
|
|
8
|
+
|
|
9
|
+
| Path | Role |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| `tariffs/electricity/index.json` | The countries index: each country's index path, checksum and counts. Generated |
|
|
12
|
+
| `tariffs/electricity/<cc>/index.json` | One country: its shared values at the top (currency, time zone, VAT, standard bill), edited by hand, then `providers`, the tariff collection, generated. Holds no prices |
|
|
13
|
+
| `tariffs/electricity/<cc>/<provider>/<tariff>/<n>.json` | One revision of one tariff: name, provider, dates, source, bands, one row of rates per area |
|
|
14
|
+
| `lib/tariffstore/` | The format in code: validator, checksum, index build, compile step and the client. Standard library only. Scripts and clients share it |
|
|
15
|
+
| `lib/tariff/`, `lib/timeutil/` | The bill engine: the tariff model, bill maths, bands, half-hourly slots and repricing. Written here, and copied by the projects that use it. See `lib/README.md` |
|
|
16
|
+
| `scripts/` | `build` (write or check the indexes) and `sync` (read the sources). See `scripts/README.md` |
|
|
17
|
+
| `sources/` | One note per upstream source: what it covers, how it is read, how often |
|
|
18
|
+
| `.github/workflows/` | `ci.yml` checks every change. `sync.yml` runs the sources on a schedule and opens a pull request |
|
|
19
|
+
| `docs/` | `using-the-library.md` (how to use it end to end), `format.md` (the files), `diagrams.md` (the flows), `design.md` (why it is this way, what runs where, what is not built) |
|
|
20
|
+
| `tests/` | Tests for the library, the scripts and every stored tariff |
|
|
21
|
+
| `CONTRIBUTING.md`, `CLAUDE.md`, `.claude/rules/` | How to change the store, how things are named, and the rules for AI assistants (`AGENTS.md` is the same file) |
|
|
22
|
+
|
|
23
|
+
## Rules
|
|
24
|
+
|
|
25
|
+
1. **Definitions are data.** Unknown or malformed fields are refused, not repaired.
|
|
26
|
+
2. **Money is exact.** Prices are decimal strings, never floats.
|
|
27
|
+
3. **Revisions are permanent.** A price change is a new numbered file. A published file is never
|
|
28
|
+
edited, except to add `effective_to` when a tariff is withdrawn. CI enforces this.
|
|
29
|
+
4. **Every tariff names its source.** Each file carries the source id and the link it was read from.
|
|
30
|
+
5. **The indexes are built** from the files and nothing else, so the same files always give the
|
|
31
|
+
same bytes. CI fails if a committed index differs from a fresh build.
|
|
32
|
+
6. **Changes arrive as pull requests** that pass CI. A synced change is never merged without review.
|
|
33
|
+
|
|
34
|
+
## Using it from a library
|
|
35
|
+
|
|
36
|
+
`docs/using-the-library.md` takes the library from install to a ranked list of plans, including bills, price series and percentiles, and the sync and release. The short version is below.
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
from datetime import date
|
|
40
|
+
from lib.tariffstore import Store, url_reader
|
|
41
|
+
|
|
42
|
+
store = Store(url_reader("https://raw.githubusercontent.com/<owner>/<repo>/main/tariffs/electricity"))
|
|
43
|
+
store.countries() # {"GB": {"availability": "available", ...}, ...}
|
|
44
|
+
store.providers("GB") # {"octopus-energy": "Octopus Energy", ...}
|
|
45
|
+
store.tariffs("GB", "octopus-energy") # {"octopus-var-22-11-01": "Flexible Octopus", ...}
|
|
46
|
+
store.areas("GB", "octopus-energy", "octopus-var-22-11-01", date.today()) # {"a": "Eastern England (A)", ...}
|
|
47
|
+
definition = store.definition("GB", "octopus-energy", "octopus-var-22-11-01", date.today(), area="c")
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`definition` is the document `lib.tariff.load_definition` reads, so the next line prices a bill
|
|
51
|
+
(`price_bill`) or the half-hourly history (`price_period`). Every file is checked against the
|
|
52
|
+
checksum in the level above it before it is used. `docs/design.md` has the details.
|
|
53
|
+
|
|
54
|
+
Keep what is fetched on disk, so a tariff is downloaded once and still works with no network:
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
store = Store.cached("https://raw.githubusercontent.com/<owner>/<repo>/main/tariffs/electricity",
|
|
58
|
+
"/path/to/cache")
|
|
59
|
+
store.fetch_country("IE", on=date.today()) # every tariff on offer, to compare bills
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Price a tariff the store does not hold. It is written like a tariff file, and the country's
|
|
63
|
+
currency, time zone, tax and standard bill come from the store:
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
mine = {"name": "My tariff", "effective_from": "2026-01-01",
|
|
67
|
+
"bands": [{"name": "Day"}, {"name": "Night", "hours": "23:00-08:00"}],
|
|
68
|
+
"areas": {"all": {"standing": "0.90", "rates": {"Day": "0.31", "Night": "0.14"}}}}
|
|
69
|
+
definition = store.custom_definition("IE", mine, date.today())
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Working on it
|
|
73
|
+
|
|
74
|
+
python3 -m scripts.build # rewrite the indexes after editing a tariff or a country block
|
|
75
|
+
python3 -m scripts.build --check # what CI runs
|
|
76
|
+
python3 -m scripts.sync all # read every source and write new revisions
|
|
77
|
+
python3 -m pytest tests -q # needs Python 3.14 and pytest
|
|
78
|
+
|
|
79
|
+
## Licence
|
|
80
|
+
|
|
81
|
+
The code and the tariff files in this repository are under the MIT licence (`LICENSE`). See `docs/licence.md` for what that covers.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# lib/
|
|
2
|
+
|
|
3
|
+
The store library and the bill engine. This repository is where both are written and tested, and
|
|
4
|
+
it is the source of truth for all tariff and billing code and calculations. They use only the
|
|
5
|
+
standard library, so any script, skill or integration can import or copy them.
|
|
6
|
+
|
|
7
|
+
| Folder | What it holds |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| `tariff/` | The tariff definition reader, the bill engine, band assignment, half-hourly slots and repricing. `tariff/README.md` lists the public names |
|
|
10
|
+
| `tariffstore/` | The store's own code: validator, checksum, index build, compile step and the client (`Store`) |
|
|
11
|
+
| `tariffranking/` | Prices every plan over the same measured usage and ranks them, with the current plan's rank. Imports `tariff/` only |
|
|
12
|
+
| `timeutil/` | Clock helpers that `tariff/` imports (`shift_real`, `elapsed_seconds`, `local_time_on`) |
|
|
13
|
+
|
|
14
|
+
## Using it from another project
|
|
15
|
+
|
|
16
|
+
Copy the folders as they stand and do not edit the copy. Record the commit copied, so a
|
|
17
|
+
later copy can be compared. The Home Assistant integration `macuistin/givenergy_inverter_manager`
|
|
18
|
+
does this with a script, a weekly workflow that opens a pull request, and a release check. Change
|
|
19
|
+
the code here, with its tests, and let the copy follow.
|
|
20
|
+
|
|
21
|
+
`tariff/` and `timeutil/` began in that integration and moved here on 2026-11-11, unchanged from
|
|
22
|
+
its commit `68ec1923ac68817032dfaa51cc3c82817d2ce115`.
|
|
23
|
+
|
|
24
|
+
The code uses Python 3.14 syntax (for example `except A, B:`), so it needs Python 3.14 or newer.
|
|
25
|
+
|
|
26
|
+
## Known gaps between the tariff files and the engine
|
|
27
|
+
|
|
28
|
+
Found by `tests/test_tariffs_through_lib.py`. A tariff file is not what the engine reads. The
|
|
29
|
+
compile step (`lib/tariffstore/compile.py`) builds the library's definition from a tariff file and its
|
|
30
|
+
country block, and closes most gaps itself. What remains is work in `lib/tariff`.
|
|
31
|
+
|
|
32
|
+
1. The library accepts only ISO 3166-2 region codes. Our area `region` codes (`GSP-A`,
|
|
33
|
+
`OFGEM-EASTERN`) are not, so compile leaves the region null. A customer's region is chosen by the
|
|
34
|
+
area key.
|
|
35
|
+
2. Closed. The library prices an export by time of day (export
|
|
36
|
+
`zones`), so Prime Outgoing's 16:00 to 19:00 rate is credited by band.
|
|
37
|
+
3. The library requires an `export` price in every definition. With no export file paired, compile
|
|
38
|
+
supplies 0 and adds no export line, so an unpaired tariff credits nothing. The library cannot say
|
|
39
|
+
"unknown".
|
|
40
|
+
4. A bill period is a whole number of calendar months. The library has no period of a fixed
|
|
41
|
+
number of days, and no volume tiers, demand charges or dynamic prices. `docs/design.md` lists what each would need.
|
|
File without changes
|
|
File without changes
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
"""Tariff model, energy and cost accumulation, and bill maths. No knowledge of Home Assistant."""
|
|
2
|
+
|
|
3
|
+
from .accumulator import CounterMemory, EnergyAccumulator
|
|
4
|
+
from .bands import band_at, export_band_at, export_by_band, no_holidays
|
|
5
|
+
from .billing import BillBreakdown, money
|
|
6
|
+
from .compile import Locale, definition_from_config
|
|
7
|
+
from .config import TariffConfig, cheapest_period
|
|
8
|
+
from .definition import SCHEMA_VERSION, DefinitionError, TariffDefinition
|
|
9
|
+
from .definition_parse import load_definition, parse_definition
|
|
10
|
+
from .definition_savings import DefinitionSavings, SavingsOptions, definition_savings
|
|
11
|
+
from .demand import peak_kw_by_window
|
|
12
|
+
from .engine import (
|
|
13
|
+
BillInputs,
|
|
14
|
+
CheckFailed,
|
|
15
|
+
Line,
|
|
16
|
+
MissingPeak,
|
|
17
|
+
MissingSeries,
|
|
18
|
+
PricedBill,
|
|
19
|
+
price_bill,
|
|
20
|
+
verify_checks,
|
|
21
|
+
)
|
|
22
|
+
from .index import (
|
|
23
|
+
ChecksumMismatch,
|
|
24
|
+
StaticSource,
|
|
25
|
+
TariffIndex,
|
|
26
|
+
TariffSource,
|
|
27
|
+
build_index,
|
|
28
|
+
checksum_of,
|
|
29
|
+
find_tariff,
|
|
30
|
+
load_revision,
|
|
31
|
+
parse_index,
|
|
32
|
+
revision_in_force,
|
|
33
|
+
)
|
|
34
|
+
from .period_bill import (
|
|
35
|
+
PeriodBill,
|
|
36
|
+
PeriodRules,
|
|
37
|
+
bill_period_bounds,
|
|
38
|
+
months_of,
|
|
39
|
+
price_period,
|
|
40
|
+
start_day_of,
|
|
41
|
+
start_month_of,
|
|
42
|
+
)
|
|
43
|
+
from .periods import RatePeriod
|
|
44
|
+
from .price_curve import MarginalPrices, PriceSlot, marginal_prices, price_curve
|
|
45
|
+
from .price_series import (
|
|
46
|
+
MissingPrice,
|
|
47
|
+
PriceSeries,
|
|
48
|
+
feed_of,
|
|
49
|
+
series_cost,
|
|
50
|
+
series_from_days,
|
|
51
|
+
series_names,
|
|
52
|
+
series_runs,
|
|
53
|
+
)
|
|
54
|
+
from .price_stats import (
|
|
55
|
+
HistoryPercentiles,
|
|
56
|
+
PriceStats,
|
|
57
|
+
history_percentiles,
|
|
58
|
+
next_at_or_below,
|
|
59
|
+
price_level,
|
|
60
|
+
price_percentiles,
|
|
61
|
+
price_rating,
|
|
62
|
+
price_stats,
|
|
63
|
+
)
|
|
64
|
+
from .price_timeline import Revision, known_until, price_timeline, series_curve, series_factor
|
|
65
|
+
from .reprice import BillPeriod, Repriced, Rounding, import_by_band, reprice
|
|
66
|
+
from .savings import Battery, Savings, savings
|
|
67
|
+
from .slot_history import SlotHistory
|
|
68
|
+
from .slots import DEFAULT_LOADS, FLOWS, SlotDay, SlotEnergy, StoredSlotDay
|
|
69
|
+
from .stored_energy import StoredEnergy, stored_energy_change, value_per_stored_kwh
|
|
70
|
+
from .windows import Window, WindowSearch, find_window
|
|
71
|
+
|
|
72
|
+
__all__ = [
|
|
73
|
+
"SCHEMA_VERSION",
|
|
74
|
+
"ChecksumMismatch",
|
|
75
|
+
"StaticSource",
|
|
76
|
+
"TariffIndex",
|
|
77
|
+
"TariffSource",
|
|
78
|
+
"build_index",
|
|
79
|
+
"checksum_of",
|
|
80
|
+
"find_tariff",
|
|
81
|
+
"load_revision",
|
|
82
|
+
"parse_index",
|
|
83
|
+
"revision_in_force",
|
|
84
|
+
"Locale",
|
|
85
|
+
"definition_from_config",
|
|
86
|
+
"band_at",
|
|
87
|
+
"export_band_at",
|
|
88
|
+
"export_by_band",
|
|
89
|
+
"no_holidays",
|
|
90
|
+
"DefinitionSavings",
|
|
91
|
+
"SavingsOptions",
|
|
92
|
+
"definition_savings",
|
|
93
|
+
"PeriodBill",
|
|
94
|
+
"PeriodRules",
|
|
95
|
+
"bill_period_bounds",
|
|
96
|
+
"price_period",
|
|
97
|
+
"start_day_of",
|
|
98
|
+
"months_of",
|
|
99
|
+
"start_month_of",
|
|
100
|
+
"BillInputs",
|
|
101
|
+
"CheckFailed",
|
|
102
|
+
"Line",
|
|
103
|
+
"MissingPeak",
|
|
104
|
+
"MissingPrice",
|
|
105
|
+
"MissingSeries",
|
|
106
|
+
"PriceSeries",
|
|
107
|
+
"series_cost",
|
|
108
|
+
"series_from_days",
|
|
109
|
+
"PricedBill",
|
|
110
|
+
"peak_kw_by_window",
|
|
111
|
+
"price_bill",
|
|
112
|
+
"verify_checks",
|
|
113
|
+
"BillPeriod",
|
|
114
|
+
"DefinitionError",
|
|
115
|
+
"TariffDefinition",
|
|
116
|
+
"load_definition",
|
|
117
|
+
"parse_definition",
|
|
118
|
+
"MarginalPrices",
|
|
119
|
+
"PriceSlot",
|
|
120
|
+
"marginal_prices",
|
|
121
|
+
"price_curve",
|
|
122
|
+
"HistoryPercentiles",
|
|
123
|
+
"Revision",
|
|
124
|
+
"feed_of",
|
|
125
|
+
"history_percentiles",
|
|
126
|
+
"known_until",
|
|
127
|
+
"next_at_or_below",
|
|
128
|
+
"price_level",
|
|
129
|
+
"price_percentiles",
|
|
130
|
+
"price_timeline",
|
|
131
|
+
"series_curve",
|
|
132
|
+
"series_factor",
|
|
133
|
+
"series_names",
|
|
134
|
+
"series_runs",
|
|
135
|
+
"PriceStats",
|
|
136
|
+
"price_rating",
|
|
137
|
+
"price_stats",
|
|
138
|
+
"Battery",
|
|
139
|
+
"Savings",
|
|
140
|
+
"savings",
|
|
141
|
+
"Window",
|
|
142
|
+
"WindowSearch",
|
|
143
|
+
"find_window",
|
|
144
|
+
"Repriced",
|
|
145
|
+
"Rounding",
|
|
146
|
+
"import_by_band",
|
|
147
|
+
"reprice",
|
|
148
|
+
"BillBreakdown",
|
|
149
|
+
"CounterMemory",
|
|
150
|
+
"EnergyAccumulator",
|
|
151
|
+
"DEFAULT_LOADS",
|
|
152
|
+
"FLOWS",
|
|
153
|
+
"RatePeriod",
|
|
154
|
+
"SlotDay",
|
|
155
|
+
"SlotEnergy",
|
|
156
|
+
"SlotHistory",
|
|
157
|
+
"StoredSlotDay",
|
|
158
|
+
"StoredEnergy",
|
|
159
|
+
"TariffConfig",
|
|
160
|
+
"cheapest_period",
|
|
161
|
+
"money",
|
|
162
|
+
"stored_energy_change",
|
|
163
|
+
"value_per_stored_kwh",
|
|
164
|
+
]
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
"""accumulator.py: running energy and cost totals for a billing period."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
from datetime import datetime
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
@dataclass
|
|
10
|
+
class CounterMemory:
|
|
11
|
+
"""The last reading of each inverter daily counter, and which ones to stop trusting.
|
|
12
|
+
|
|
13
|
+
A daily counter drops to zero at midnight. The memory outlives the midnight reset so a
|
|
14
|
+
stale reading just after it is not added a second time. lib/guards/counter.py judges each
|
|
15
|
+
reading against this memory.
|
|
16
|
+
|
|
17
|
+
Only the AC charge baseline is saved. The other readings, their times and the list of
|
|
18
|
+
counters that jumped live in memory, so a restart starts them fresh.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
ac_charge_kwh: float = 0.0
|
|
22
|
+
readings: dict[str, tuple[float, datetime]] = field(
|
|
23
|
+
default_factory=dict, compare=False, repr=False
|
|
24
|
+
)
|
|
25
|
+
distrusted: set[str] = field(default_factory=set, compare=False, repr=False)
|
|
26
|
+
# The last reading of each counter that passed, to recognise a counter coming back.
|
|
27
|
+
last_trusted: dict[str, tuple[float, datetime]] = field(
|
|
28
|
+
default_factory=dict, compare=False, repr=False
|
|
29
|
+
)
|
|
30
|
+
# The AC charge rise the last screening allowed. It is the only rise that is booked.
|
|
31
|
+
ac_charge_rise_kwh: float = field(default=0.0, compare=False, repr=False)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@dataclass
|
|
35
|
+
class EnergyAccumulator:
|
|
36
|
+
"""
|
|
37
|
+
Tracks energy and cost accumulation over a billing period (resets at midnight).
|
|
38
|
+
|
|
39
|
+
Fields are grouped by what they enable:
|
|
40
|
+
Basic flows — solar, import, export, house, zappi, immersion
|
|
41
|
+
Rate breakdown — import split by cheap (timed) vs peak (base) rate
|
|
42
|
+
Cost attribution — cost per load type and per rate tier
|
|
43
|
+
Savings — value delivered by the integration
|
|
44
|
+
Battery health — throughput for cycle and depreciation tracking
|
|
45
|
+
"""
|
|
46
|
+
|
|
47
|
+
# ── Basic energy flows ────────────────────────────────────────────────────
|
|
48
|
+
import_kwh: float = 0.0
|
|
49
|
+
export_kwh: float = 0.0
|
|
50
|
+
solar_kwh: float = 0.0
|
|
51
|
+
battery_discharge_kwh: float = 0.0
|
|
52
|
+
battery_charge_kwh: float = 0.0
|
|
53
|
+
zappi_kwh: float = 0.0
|
|
54
|
+
immersion_kwh: float = 0.0
|
|
55
|
+
house_kwh: float = 0.0
|
|
56
|
+
# The part of import_kwh that went into the battery (the inverter's AC charge counter). It is
|
|
57
|
+
# stored, not used, so it does not count as the grid supplying the house.
|
|
58
|
+
grid_to_battery_kwh: float = 0.0
|
|
59
|
+
# What the grid energy that went into the battery cost, and the kWh that cost covers. Both
|
|
60
|
+
# are kept by the integration from the moment it prices the AC charge counter, so
|
|
61
|
+
# grid_to_battery_priced_kwh can be less than grid_to_battery_kwh on the day it is
|
|
62
|
+
# first installed. Today's accumulator only. See core/stored_energy.py.
|
|
63
|
+
grid_to_battery_cost: float = 0.0
|
|
64
|
+
grid_to_battery_priced_kwh: float = 0.0
|
|
65
|
+
# The battery's state of charge at the start of the period, None until the first reading.
|
|
66
|
+
# A bookmark, not an accumulated figure, so it is left out of equality: a period with
|
|
67
|
+
# nothing else on it still counts as empty.
|
|
68
|
+
soc_at_start_pct: float | None = field(default=None, compare=False)
|
|
69
|
+
|
|
70
|
+
# ── Rate-tier import breakdown ────────────────────────────────────────────
|
|
71
|
+
# "cheap" = any timed rate period active (Night, Nightboost, etc.)
|
|
72
|
+
# "peak" = base/day rate (no timed period active)
|
|
73
|
+
import_kwh_cheap: float = 0.0 # kWh imported at timed cheap rate
|
|
74
|
+
import_kwh_peak: float = 0.0 # kWh imported at base/peak rate
|
|
75
|
+
import_cost_cheap: float = 0.0 # cost at cheap rate
|
|
76
|
+
import_cost_peak: float = 0.0 # cost at peak rate
|
|
77
|
+
|
|
78
|
+
# ── Cost attribution per rate period and load ─────────────────────────────
|
|
79
|
+
import_cost_by_period: dict[str, float] = field(default_factory=dict)
|
|
80
|
+
# kWh imported, and kWh the house used, in each rate period. They are what the bill audit
|
|
81
|
+
# lists beside the cost, and are empty on a period that began before they were kept.
|
|
82
|
+
import_kwh_by_period: dict[str, float] = field(default_factory=dict)
|
|
83
|
+
house_kwh_by_period: dict[str, float] = field(default_factory=dict)
|
|
84
|
+
export_earnings: float = 0.0
|
|
85
|
+
zappi_cost: float = 0.0
|
|
86
|
+
immersion_cost: float = 0.0 # import cost attributable to immersion heater
|
|
87
|
+
house_cost: float = 0.0 # import cost attributable to rest-of-house load
|
|
88
|
+
|
|
89
|
+
# ── Counterfactual ────────────────────────────────────────────────────────
|
|
90
|
+
# What the house load would have cost bought from the grid at the rate in force
|
|
91
|
+
# when it ran. The saving from solar and battery is this minus what was paid.
|
|
92
|
+
grid_equivalent_load_cost: float = 0.0
|
|
93
|
+
|
|
94
|
+
# ── Integration savings ───────────────────────────────────────────────────
|
|
95
|
+
# immersion_solar_kwh: solar kWh diverted to immersion that would otherwise
|
|
96
|
+
# have been exported at the lower export rate.
|
|
97
|
+
# immersion_savings: (import_rate - export_rate) × immersion_solar_kwh
|
|
98
|
+
immersion_solar_kwh: float = 0.0
|
|
99
|
+
immersion_savings: float = 0.0
|
|
100
|
+
|
|
101
|
+
# ── Battery throughput ────────────────────────────────────────────────────
|
|
102
|
+
# Total kWh cycled through the battery (in + out). Divide by 2 × capacity
|
|
103
|
+
# to get fractional cycles. Multiply by (replacement_cost / rated_cycles)
|
|
104
|
+
# to estimate depreciation cost.
|
|
105
|
+
battery_throughput_kwh: float = 0.0
|
|
106
|
+
|
|
107
|
+
# ── Missed solar (self-consumption opportunity) ───────────────────────────
|
|
108
|
+
# kWh exported while battery is full, solar generating, and no flex load
|
|
109
|
+
# active — represents solar that could have been self-consumed.
|
|
110
|
+
missed_solar_kwh: float = 0.0
|
|
111
|
+
|
|
112
|
+
# ── Inverter derating ──────────────────────────────────────────────────────
|
|
113
|
+
# Minutes the inverter spent above the derating temperature threshold today.
|
|
114
|
+
inverter_derating_minutes: float = 0.0
|
|
115
|
+
|
|
116
|
+
@property
|
|
117
|
+
def total_import_cost(self) -> float:
|
|
118
|
+
return sum(self.import_cost_by_period.values())
|
|
119
|
+
|
|
120
|
+
@property
|
|
121
|
+
def total_cost(self) -> float:
|
|
122
|
+
"""Total import cost today (standing charges tracked separately in accrued_bill)."""
|
|
123
|
+
return self.total_import_cost
|
|
124
|
+
|
|
125
|
+
@property
|
|
126
|
+
def net_position(self) -> float:
|
|
127
|
+
"""Negative = net cost, positive = net earnings."""
|
|
128
|
+
return self.export_earnings - self.total_cost
|
|
129
|
+
|
|
130
|
+
@property
|
|
131
|
+
def peak_import_fraction(self) -> float:
|
|
132
|
+
"""Fraction of import that occurred at peak (base) rate. 0–1."""
|
|
133
|
+
total = self.import_kwh
|
|
134
|
+
return (self.import_kwh_peak / total) if total > 0 else 0.0
|
|
135
|
+
|
|
136
|
+
@property
|
|
137
|
+
def cheap_import_fraction(self) -> float:
|
|
138
|
+
"""Fraction of import that occurred at cheap (timed) rate. 0–1."""
|
|
139
|
+
total = self.import_kwh
|
|
140
|
+
return (self.import_kwh_cheap / total) if total > 0 else 0.0
|
|
141
|
+
|
|
142
|
+
@property
|
|
143
|
+
def grid_to_house_kwh(self) -> float:
|
|
144
|
+
"""Import that went to the house, not into the battery. Never negative.
|
|
145
|
+
|
|
146
|
+
Without a grid-to-battery reading the figure is the whole import.
|
|
147
|
+
"""
|
|
148
|
+
return max(0.0, self.import_kwh - self.grid_to_battery_kwh)
|
|
149
|
+
|
|
150
|
+
@property
|
|
151
|
+
def supplied_without_grid_kwh(self) -> float:
|
|
152
|
+
"""The house load not drawn from the grid at the time: solar, and battery discharge."""
|
|
153
|
+
return max(0.0, self.house_kwh - self.grid_to_house_kwh)
|
|
154
|
+
|
|
155
|
+
@property
|
|
156
|
+
def self_sufficiency_pct(self) -> float:
|
|
157
|
+
"""Percentage of the house's consumption that did not have to be drawn from the grid.
|
|
158
|
+
|
|
159
|
+
house_kwh is the whole load, EV and immersion included, so they are not added again.
|
|
160
|
+
Grid energy the battery stored (grid_to_battery_kwh) is not counted against it.
|
|
161
|
+
Later discharge of that stored energy counts as supplied from storage. EV and
|
|
162
|
+
immersion energy bought from the grid is in house_kwh, so it still counts as grid.
|
|
163
|
+
With no grid-to-battery reading, all import counts, as it did before the reading
|
|
164
|
+
existed.
|
|
165
|
+
"""
|
|
166
|
+
if self.house_kwh <= 0:
|
|
167
|
+
return 100.0
|
|
168
|
+
return max(0.0, min(100.0, (1 - self.grid_to_house_kwh / self.house_kwh) * 100))
|
|
169
|
+
|
|
170
|
+
@property
|
|
171
|
+
def solar_share_pct(self) -> float:
|
|
172
|
+
"""Percentage of the house's consumption met by solar generated and kept on site.
|
|
173
|
+
|
|
174
|
+
Solar kept on site is generation less export. It includes solar stored in the
|
|
175
|
+
battery, which counts when it is generated, not when it is later discharged.
|
|
176
|
+
It does not count battery discharge, so energy the battery took from the grid
|
|
177
|
+
never raises the figure. It ignores grid import, so buying cheap energy does not
|
|
178
|
+
lower it. Compare self_sufficiency_pct, which counts all the house did not draw from the
|
|
179
|
+
grid.
|
|
180
|
+
|
|
181
|
+
house_kwh is the whole load, EV and immersion included, so they are not added again.
|
|
182
|
+
With no consumption the share is 0, not 100 as for self-sufficiency: no solar was
|
|
183
|
+
used, and a day with nothing to power should not read as fully solar powered.
|
|
184
|
+
"""
|
|
185
|
+
if self.house_kwh <= 0:
|
|
186
|
+
return 0.0
|
|
187
|
+
solar_kept_kwh = max(0.0, self.solar_kwh - self.export_kwh)
|
|
188
|
+
return min(100.0, solar_kept_kwh / self.house_kwh * 100)
|
|
189
|
+
|
|
190
|
+
@property
|
|
191
|
+
def self_consumption_pct(self) -> float:
|
|
192
|
+
"""Percentage of solar generation consumed on-site."""
|
|
193
|
+
if self.solar_kwh == 0:
|
|
194
|
+
return 0.0
|
|
195
|
+
return min(100.0, (1 - self.export_kwh / self.solar_kwh) * 100)
|