Sync 0.5.1 release back to develop

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
 

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"

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
 

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"

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.
 

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,