microgrid 0.1.0__tar.gz

microgrid-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Secrets: never commit.
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+
+# The documentation site's build (mkdocs.yml)
+/site/
+
+# Runtime
+/tmp/
+*.log
+
+# Agent worktrees (Claude Code)
+.claude/worktrees/
+
+# Development records: kept locally, never published (the decisions, the research,
+# their index and notes).
+/docs/adr/
+/docs/research/
+/docs/INDEX.md
+/docs/load-forecast.md

microgrid-0.1.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+Each user-visible change, under the release it ships in.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-18
+
+The first version, under the MIT license.
+
+### Added (library)
+
+- **The plant model, `microgrid.plant`.** A plant described as data (`plant/2`): PV
+  arrays of either coupling, a battery on its own inverter or on a hybrid's DC bus,
+  loads on either bus, the grid's limits, grid-charge and export windows, hold rules
+  and the meters. `Plant.project` runs it slot by slot. It stands alone: importing it
+  loads none of the price code. Four example plants (`microgrid.plant.examples`), and
+  a port for a plant model of your own (`microgrid.plant.port`: `PlantModel`,
+  `Storage`), checked by `microgrid.engine.testing.assert_plant_model_contract`.
+- **The price model, `microgrid.engine`.** Marginal prices from inputs given as time
+  series (`Inputs`: prices, PV forecast quantiles, the load forecast, the SOC, the
+  battery's lots). For each slot it gives:
+  - the marginal cost, and the same for a dull day (the PV forecast's p10);
+  - the regime, the certainties and the surplus;
+  - the supply stack;
+  - the value of a PV kWh and of a battery kWh diverted to a flexible load.
+
+  `Engine.value` gives these as a valuation (`valuation/2`). `Engine.live_session`
+  gives a live value between valuations.
+  - **A battery kWh** is priced at the running average cost of what the battery holds
+    (`Pricing.battery_value = "stored_cost"`), or by the make-up rule (`"replacement"`).
+  - **Missing or stale inputs** move values toward the import price, and the valuation
+    names them in `degraded`.
+  - **Configuration:** `engine/2`.
+- **Series and units** (`microgrid.engine.series`, `microgrid.engine.units`).
+  - Forecasts are series of issues, read as a client had them at a moment.
+  - Units are converted at the edge.
+  - Money is in the prices' currency, never converted, and no name says one.
+- **The battery's lots** (`microgrid.engine.ledger`): what the battery holds by source,
+  and what it cost.
+- **Analysis** (`microgrid.engine.analysis`): the plant model scored against its meters,
+  and valuations scored against what each kWh realised.
+
+### Added (command)
+
+- **`microgrid` on a dataset** (`dataset/1`): `value`, `live`, `replay`, `check-plant`,
+  `ledger`, `fit-battery`, `config check` and `schema`. A dataset whose prices name two
+  currencies is refused.
+- **`microgrid` on live sources** (`sources/1`, the `sources` extra): `sources`, `now` and
+  `fetch`. Each input comes from a provider's Home Assistant integration (TariffKit,
+  Solcast, EMHASS, Predbat) or an entity.
+- **The example dataset** (`examples/dataset`): a synthetic week of an example plant in
+  Europe/Berlin, across the DST change, with the outputs it is expected to give.
+
+### Added (releases)
+
+- **Versions and releases:** semantic versioning, explained beside the formats', the
+  API's and the model's versions (`docs/reference/versions.md`); `microgrid --version`
+  prints the release with the API (`engine-api/5`) and the model (`pricing/1.3`) it
+  carries. Releases are published to
+  PyPI from a tag (`vX.Y.Z`).
+
+### Added (documentation)
+
+- **The documentation:** the methodology and the library's requirements (R-1 to R-9),
+  the concepts, how-to guides and the reference, published with each release at
+  `https://eman.github.io/microgrid/`.

microgrid-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emmanuel Levijarvi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

microgrid-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: microgrid
+Version: 0.1.0
+Summary: A plant model and marginal energy prices for a solar + battery microgrid: data in, data out
+Project-URL: Homepage, https://github.com/eman/microgrid
+Project-URL: Documentation, https://eman.github.io/microgrid/
+Project-URL: Source, https://github.com/eman/microgrid
+Project-URL: Changelog, https://github.com/eman/microgrid/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/eman/microgrid/issues
+Author-email: Emmanuel Levijarvi <emansl@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: battery,energy,home energy,marginal price,microgrid,solar
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: sources
+Requires-Dist: httpx>=0.28; extra == 'sources'
+Requires-Dist: pydantic>=2.11; extra == 'sources'
+Description-Content-Type: text/markdown
+
+# microgrid
+
+`microgrid` is a library that models a solar + battery plant (`microgrid.plant`) and
+produces **marginal energy prices** from it (`microgrid.engine`): what one more kWh
+costs, slot by slot over a horizon, and the value of energy by source. The plant model
+also stands alone, without the price code.
+
+- **Data in, data out.** No I/O: a client hands in the plant's configuration
+  (`plant/2`) and its inputs as time series (prices, PV and load forecasts, the
+  meters), and gets prices, regimes, certainties and surplus back.
+- **The plant model** takes its topology as configuration: PV of either coupling,
+  a battery on its own inverter or on a hybrid's DC bus, loads on either bus, the
+  grid's limits and charge windows.
+
+The documentation is in [`docs/`](https://github.com/eman/microgrid/blob/main/docs/index.md),
+published with each release at `https://eman.github.io/microgrid/`:
+how the prices are made, the concepts, how-to guides and the reference.
+
+## Install
+
+```sh
+pip install microgrid                # or: uv add microgrid
+pip install "microgrid[sources]"     # with the readers of live sources (Home Assistant)
+```
+
+Python 3.14 or later. Before 1.0 a minor release may change a format, the API or the
+model: pin the minor release you tested with (`microgrid ~= 0.1.0`,
+[Versions](https://github.com/eman/microgrid/blob/main/docs/reference/versions.md)).
+
+## The command
+
+`microgrid` (`microgrid.cli`, installed with the library) runs it on a dataset
+(`dataset/1`: a directory of series and the plant's and engine's files), so it needs no
+plant at hand. `microgrid.cli` reads the files; the engine still does no I/O. The example
+dataset (`examples/dataset`) is one synthetic week of the library's example plant in
+Europe/Berlin, the DST change on 2026-10-25 inside it:
+
+```sh
+uv run microgrid value --data examples/dataset --at 2026-10-22T13:00   # one valuation
+uv run microgrid live --data examples/dataset --from 2026-10-22T06:00 --to 2026-10-22T20:00
+uv run microgrid replay --data examples/dataset --from 2026-10-22 --to 2026-10-25
+                                        # valuations scored against the meters
+uv run microgrid check-plant --data examples/dataset --from 2026-10-21 --to 2026-10-27
+                                        # the plant model against its meters
+uv run microgrid ledger --data examples/dataset --from 2026-10-21 --to 2026-10-27
+                                        # the battery's lots and their cost split
+uv run microgrid fit-battery --data examples/dataset --end 2026-10-28 --days 7
+                                        # the battery's conversion, fitted
+uv run microgrid config check --data examples/dataset   # its plant/2 and engine/2
+uv run microgrid schema                                 # the outputs' schema
+```
+
+With a `sources/1` file naming a provider per input (any of several, none assumed; the
+`sources` extra, `microgrid[sources]`), it reads live inputs instead of a dataset:
+
+```sh
+uv run microgrid sources --sources sources.toml   # what each input is read from, or why not
+uv run microgrid now --sources sources.toml       # a valuation now; --save DIR keeps the inputs
+uv run microgrid fetch --sources sources.toml --from 2026-10-01 --to 2026-10-08 --out DIR
+                                        # what was measured, as a dataset
+```
+
+A time without an offset is the plant's local time (an hour that repeats, the first
+time; one the clocks skip is refused).
+
+## Development
+
+Python 3.14, uv. See [AGENTS.md](https://github.com/eman/microgrid/blob/main/AGENTS.md) for the rules and conventions.
+
+```sh
+uv sync                      # .venv with the library and the dev tools
+scripts/install-hooks.sh     # pre-push runs the local gate
+scripts/ci_local.sh          # ruff, format, mypy --strict, the docs, pytest + coverage
+```
+
+## License
+
+MIT: see [LICENSE](https://github.com/eman/microgrid/blob/main/LICENSE).

microgrid-0.1.0/README.md

@@ -0,0 +1,78 @@
+# microgrid
+
+`microgrid` is a library that models a solar + battery plant (`microgrid.plant`) and
+produces **marginal energy prices** from it (`microgrid.engine`): what one more kWh
+costs, slot by slot over a horizon, and the value of energy by source. The plant model
+also stands alone, without the price code.
+
+- **Data in, data out.** No I/O: a client hands in the plant's configuration
+  (`plant/2`) and its inputs as time series (prices, PV and load forecasts, the
+  meters), and gets prices, regimes, certainties and surplus back.
+- **The plant model** takes its topology as configuration: PV of either coupling,
+  a battery on its own inverter or on a hybrid's DC bus, loads on either bus, the
+  grid's limits and charge windows.
+
+The documentation is in [`docs/`](https://github.com/eman/microgrid/blob/main/docs/index.md),
+published with each release at `https://eman.github.io/microgrid/`:
+how the prices are made, the concepts, how-to guides and the reference.
+
+## Install
+
+```sh
+pip install microgrid                # or: uv add microgrid
+pip install "microgrid[sources]"     # with the readers of live sources (Home Assistant)
+```
+
+Python 3.14 or later. Before 1.0 a minor release may change a format, the API or the
+model: pin the minor release you tested with (`microgrid ~= 0.1.0`,
+[Versions](https://github.com/eman/microgrid/blob/main/docs/reference/versions.md)).
+
+## The command
+
+`microgrid` (`microgrid.cli`, installed with the library) runs it on a dataset
+(`dataset/1`: a directory of series and the plant's and engine's files), so it needs no
+plant at hand. `microgrid.cli` reads the files; the engine still does no I/O. The example
+dataset (`examples/dataset`) is one synthetic week of the library's example plant in
+Europe/Berlin, the DST change on 2026-10-25 inside it:
+
+```sh
+uv run microgrid value --data examples/dataset --at 2026-10-22T13:00   # one valuation
+uv run microgrid live --data examples/dataset --from 2026-10-22T06:00 --to 2026-10-22T20:00
+uv run microgrid replay --data examples/dataset --from 2026-10-22 --to 2026-10-25
+                                        # valuations scored against the meters
+uv run microgrid check-plant --data examples/dataset --from 2026-10-21 --to 2026-10-27
+                                        # the plant model against its meters
+uv run microgrid ledger --data examples/dataset --from 2026-10-21 --to 2026-10-27
+                                        # the battery's lots and their cost split
+uv run microgrid fit-battery --data examples/dataset --end 2026-10-28 --days 7
+                                        # the battery's conversion, fitted
+uv run microgrid config check --data examples/dataset   # its plant/2 and engine/2
+uv run microgrid schema                                 # the outputs' schema
+```
+
+With a `sources/1` file naming a provider per input (any of several, none assumed; the
+`sources` extra, `microgrid[sources]`), it reads live inputs instead of a dataset:
+
+```sh
+uv run microgrid sources --sources sources.toml   # what each input is read from, or why not
+uv run microgrid now --sources sources.toml       # a valuation now; --save DIR keeps the inputs
+uv run microgrid fetch --sources sources.toml --from 2026-10-01 --to 2026-10-08 --out DIR
+                                        # what was measured, as a dataset
+```
+
+A time without an offset is the plant's local time (an hour that repeats, the first
+time; one the clocks skip is refused).
+
+## Development
+
+Python 3.14, uv. See [AGENTS.md](https://github.com/eman/microgrid/blob/main/AGENTS.md) for the rules and conventions.
+
+```sh
+uv sync                      # .venv with the library and the dev tools
+scripts/install-hooks.sh     # pre-push runs the local gate
+scripts/ci_local.sh          # ruff, format, mypy --strict, the docs, pytest + coverage
+```
+
+## License
+
+MIT: see [LICENSE](https://github.com/eman/microgrid/blob/main/LICENSE).

microgrid-0.1.0/examples/dataset/engine.toml

@@ -0,0 +1,3 @@
+# The example dataset's engine (engine/2): prices fetched hourly.
+schema = "engine/2"
+price_max_age_minutes = 60

microgrid-0.1.0/examples/dataset/expected/ledger-2026-10-21.txt

@@ -0,0 +1,6 @@
+the battery's lots, 2026-10-21 00:00 CEST to 2026-10-28 00:00 CET (1014 slots)
+source    charged kWh  cost USD  to load kWh      USD  exported kWh  held kWh      USD  USD/kWh
+unknown         0.000     0.000        6.000    0.000         0.000     0.000    0.000        -
+pv             40.497     2.968       34.184    2.505         0.000     6.397    0.469   0.0733
+grid           15.249     2.902       15.249    2.902         0.000     0.000    0.000        -
+unexplained: 0.084 kWh (the meters against the SOC)

microgrid-0.1.0/examples/dataset/expected/live-2026-10-25.txt

@@ -0,0 +1,49 @@
+at                         marginal   import  surplus kW  regime   degraded
+2026-10-25 01:00:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 01:05:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 01:10:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 01:15:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 01:20:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 01:25:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 01:30:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 01:35:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 01:40:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 01:45:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 01:50:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 01:55:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:00:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:05:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:10:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:15:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:20:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:25:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:30:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:35:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:40:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:45:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:50:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:55:00 CEST     0.1800   0.1800       0.000  import   -
+2026-10-25 02:00:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 02:05:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 02:10:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 02:15:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 02:20:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 02:25:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 02:30:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 02:35:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 02:40:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 02:45:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 02:50:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 02:55:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 03:00:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 03:05:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 03:10:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 03:15:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 03:20:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 03:25:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 03:30:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 03:35:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 03:40:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 03:45:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 03:50:00 CET      0.1800   0.1800       0.000  import   -
+2026-10-25 03:55:00 CET      0.1800   0.1800       0.000  import   -

microgrid-0.1.0/examples/dataset/expected/replay-2026-10-22.txt

@@ -0,0 +1,21 @@
+48 valuations every 1:00:00 scored, 7053 slots inside the span; fell back (not scored): 0; no prices: 0
+
+surplus kW against the PV exported or curtailed, by hours ahead:
+bucket       n     bias     MAE   p10 n   p10 met
+0-1h        288   +0.016   0.019      27   100.0%
+1-3h        558   +0.026   0.029      47   100.0%
+3-12h      2214   -0.006   0.038     105   100.0%
+12-48h     3993   -0.020   0.074     126   100.0%
+
+marginal cost against the price a kWh realised (USD/kWh), by hours ahead:
+bucket       n  outcomes     bias     MAE    off
+0-1h        246        11  -0.0007  0.0043   2.4%
+1-3h        474        11  -0.0011  0.0047   6.3%
+3-12h      1836        10  -0.0002  0.0041  16.5%
+12-48h     2610         6  +0.0022  0.0032   2.9%
+
+regime against the metered regime:
+  0-1h     278 of 288 agreed
+  1-3h     540 of 558 agreed
+  3-12h    2170 of 2214 agreed
+  12-48h   3907 of 3993 agreed