diff --git a/CHANGELOG.md b/CHANGELOG.md index bafdac5..7b4e706 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,13 @@ All notable changes to BREOS are documented here. Format follows [Keep a Changel ## [Unreleased] +## [0.5.1] - 2026-08-11 + ### Changed +- Centralized App configuration metadata in one declarative registry that now + derives defaults, allowed top-level keys, CLI options, and CLI override + handling. Historical ordering, aliases, normalization, config-file + precedence, validation messages, and simulation results are preserved. - Clarified that the deprecated article lifetime baseline is an independent approximation reconstructed from public documentation. Its generated plot legends now say "documentation-derived baseline" instead of presenting the @@ -34,8 +40,15 @@ All notable changes to BREOS are documented here. Format follows [Keep a Changel `breos validate-config configs/examples/sweep.toml` no longer rejects a shipped example that `breos sweep` runs successfully. The documented behaviour was already that `[sweep]` and `[montecarlo]` are recognised; only - `[montecarlo]` actually was. Every `configs/examples/*.toml` is now covered - by a `validate-config` regression test. + `[montecarlo]` actually was. `validate-config` now also rejects an empty or + malformed sweep grid, and every `configs/examples/*.toml` is covered by a + regression test. +- Made the public `resistance_to_efficiency()` helper match the live + resistance-fade path: both one-way efficiencies receive the same + `sqrt(1 + growth)` derating, preserving configured charge/discharge + asymmetry and removing the helper's former artificial floor. Initial and + daily simulation paths now call the helper; simulation results are + unchanged because they already used this mapping. ## [0.5.0] - 2026-08-05 diff --git a/CITATION.cff b/CITATION.cff index b43111e..94b638d 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -20,8 +20,8 @@ keywords: - solar - degradation license: BSD-3-Clause -version: 0.5.0 -date-released: "2026-08-05" +version: 0.5.1 +date-released: "2026-08-11" preferred-citation: type: article title: "A Modular, Open-Source Python Framework for Household PV-Battery Sizing: Validation, Multi-Objective Optimisation, and Uncertainty Analysis" diff --git a/ROADMAP.md b/ROADMAP.md index d634f65..8d55558 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -28,11 +28,14 @@ intentions, not commitments; reassess after each release. configuration: multi-array tracking now honours the top-level `gcr`, an out-of-range `gcr` is rejected instead of silently backtracking, and the `pvsyst-*` temperature presets model a realistic module efficiency. -- **0.5.x** — the declarative config schema (behavior-preserving, and - deliberately before TOU adds another cluster of config keys); - horizon-profile input; the cost-override seam (phase 0 of economic - scenario analysis, which TOU does not invalidate); and further internal - maintainability work if needed. +- **0.5.1** — completed maintenance release: fixed validation of the shipped + sweep example, centralized the mechanical App configuration contract, and + reconciled resistance-fade efficiency mapping without changing simulation + results. Deprecated the confirmed public dead-code surface ahead of its + planned removal in 0.6.0. +- **0.5.x** — horizon-profile input; the cost-override seam (phase 0 of + economic scenario analysis, which TOU does not invalidate); and further + internal maintainability work if needed. - **0.6.0** — the currency concept plus time-of-use tariff valuation and static presets; flat pricing preserved bit-for-bit. - **0.6.x / 0.7.0** — economic scenario and sensitivity analysis phases 1–3 @@ -130,33 +133,19 @@ must ship with a documented yield/self-consumption delta). ## Architecture -### Declarative config schema with strict validation - -The public `App` config surface is currently defined and checked in four -separate places: the `DEFAULTS` dict and imperative `validate_config` in -`breos.app_config`, plus the `argparse` flag definitions and the -`_add_override` calls in `breos.cli`. Adding one parameter means editing all -four, which is drift-prone, and the hand-rolled validation is hard to keep in -sync with the defaults. Replace it with a single declarative schema (a -dataclass with field metadata, or `pydantic`) so defaults, types, bounds, and -documentation live in one place. - -- **Full step (pending, targeted at a 0.5.x behavior-preserving release):** - collapse `DEFAULTS`, the validation rules, and the CLI flag definitions - into the schema so a new parameter is added once, not four times. This is - deliberately scheduled *before* the 0.6.0 TOU/currency work adds another - cluster of config keys, and deserves its own release slot rather than - riding along a feature release. -- **Coordination with the [function-level refactor plan](design/architecture/0.4x-refactor-plan.md):** earlier internal - validation cleanup should create reusable boundaries for the full schema, - not throwaway helpers that need another rewrite in 0.5.x. -- **The hard part is error-message parity**, not the schema itself: the - acceptance bar is the same exception types with equally actionable - "Unknown X. Available: ..." messages. Off-the-shelf pydantic messages do - not meet it, so plan for either a dataclass-with-field-metadata schema - with hand-rolled errors, or pydantic behind a message-translation layer. -- Keep all error messages actionable; preserve current behaviour for valid - configs (regression-test the example configs in `configs/examples/`). +### Declarative config registry with strict validation (completed in 0.5.1) + +One `AppConfigField` registry now derives public App defaults, allowed +top-level keys, CLI argument definitions, and CLI override handling. Adding a +mechanical configuration field no longer requires keeping four declarations in +sync, and registry invariants plus every shipped example guard against future +drift. + +Scientific and cross-field constraints deliberately remain in focused +validators. That boundary preserves the established validation order, +exception types, and actionable error messages while keeping the registry from +becoming a second scientific rules engine. The 0.6.0 TOU/currency work can add +its configuration cluster through the completed registry. ## Performance and portability diff --git a/pyproject.toml b/pyproject.toml index 7c2f074..17dcc81 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "breos" -version = "0.5.0" +version = "0.5.1" description = "Python library for PV and battery energy-system simulation and optimization" readme = "README.md" license = "BSD-3-Clause" diff --git a/uv.lock b/uv.lock index 3e41f52..e62bf17 100644 --- a/uv.lock +++ b/uv.lock @@ -101,7 +101,7 @@ wheels = [ [[package]] name = "breos" -version = "0.5.0" +version = "0.5.1" source = { editable = "." } dependencies = [ { name = "numpy" }, diff --git a/validation/REPORT.md b/validation/REPORT.md index 3004a04..3de0c98 100644 --- a/validation/REPORT.md +++ b/validation/REPORT.md @@ -1,6 +1,6 @@ # BREOS validation report -Generated by `validation/compare.py` on 2026-08-05 against BREOS 0.5.0. +Generated by `validation/compare.py` on 2026-08-11 against BREOS 0.5.1. System: 4.0 kWp (10× Generic_400W), DC/AC 1.2, inverter η 0.96, albedo 0.2, free-standing mount, BREOS default loss stack. diff --git a/validation/baselines/breos_baseline.json b/validation/baselines/breos_baseline.json index 2a35e6b..0d45e8c 100644 --- a/validation/baselines/breos_baseline.json +++ b/validation/baselines/breos_baseline.json @@ -1,6 +1,6 @@ { - "breos_version": "0.5.0", - "generated": "2026-08-05", + "breos_version": "0.5.1", + "generated": "2026-08-11", "system": { "module": "Generic_400W", "n_modules": 10,