breos 0.3.0__tar.gz

breos-0.3.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,30 @@
+name: Bug Report
+description: Report a bug in BREOS
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened? What did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal code or steps to reproduce the issue
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Python version, OS, BREOS version
+      placeholder: |
+        Python: 3.13
+        OS: Ubuntu 24.04
+        breos: 0.2.0
+    validations:
+      required: true

breos-0.3.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,18 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What would you like to see added or changed?
+    validations:
+      required: true
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Use Case
+      description: How would this help your workflow?
+    validations:
+      required: false

breos-0.3.0/.github/pull_request_template.md

@@ -0,0 +1,6 @@
+## Summary
+<!-- Brief description of what this PR does -->
+
+## Test plan
+<!-- How was this tested? -->
+- [ ] Tests pass (`uv run pytest tests/ -v`)

breos-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,84 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Check release tag points at main
+        if: github.event_name == 'push'
+        run: |
+          git fetch origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "Refusing to publish: tag ${GITHUB_REF_NAME} is not on main." >&2
+            exit 1
+          fi
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Verify release artifacts
+        run: uv run python tools/verify_release_artifacts.py
+
+      - name: Build distributions
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/breos
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/breos
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

breos-0.3.0/.github/workflows/tests.yml

@@ -0,0 +1,46 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra docs
+
+      - name: Lint
+        run: uv run ruff check breos/ tests/ tools/
+
+      - name: Check formatting
+        run: uv run ruff format --check breos/ tests/ tools/
+
+      - name: Run tests
+        run: uv run pytest tests/ -v
+
+      - name: Verify release artifacts
+        run: uv run python tools/verify_release_artifacts.py
+
+      - name: Build docs
+        run: uv run --extra docs sphinx-build -b html docs docs/_build/html

breos-0.3.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.cache/
+*.egg
+.venv/
+.env
+results/
+dev/
+*.csv
+!breos/data/rlp/*.csv
+.codex
+.claude/
+.DS_Store
+
+# Sphinx
+docs/_build/
+docs/api/generated/

breos-0.3.0/.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

breos-0.3.0/AGENTS.md

@@ -0,0 +1,31 @@
+# Agent Guide
+
+This repository is the open-source core of BREOS. Keep changes scoped and preserve the `breos.App` facade as the most stable public entrypoint.
+
+## Project map
+
+- `breos/app.py` - public facade that wires weather, PV, load, battery, economics, and emissions.
+- `breos/load_profiles.py` - bundled demandlib H0 profile support plus user-supplied external RLPs.
+- `breos/battery.py`, `breos/solar.py`, `breos/weather.py` - core simulation models.
+- `breos/economics.py`, `breos/emissions.py`, `breos/optimization.py` - analysis and sizing helpers.
+- `breos/data/` - packaged presets and redistributable sample data used after installation.
+- `configs/` - editable example and template configuration files for users.
+- `tests/` - pytest coverage for public behavior and lower-level modules.
+- `docs/` - Sphinx/MyST source; generated output lives in `docs/_build/` and is ignored.
+
+## Common commands
+
+```bash
+uv sync --extra dev --extra docs
+uv run pytest -q
+uv run ruff check breos tests
+uv run ruff format --check breos tests
+uv build
+```
+
+## Change guidance
+
+- Prefer extending `breos.App` through backwards-compatible config keys.
+- Avoid repo-relative runtime paths; packaged resources should be loaded through `breos.resources`.
+- Keep generated files out of git unless they are intentional release assets.
+- Add focused tests for public API behavior when touching defaults, packaged data, or serialization.

breos-0.3.0/ATTRIBUTIONS.md

@@ -0,0 +1,85 @@
+# Attributions and Third-Party Notices
+
+BREOS bundles or relies on third-party data, services, software, and published
+methods. This document lists each source, its license posture, and any
+redistribution, commercial-use, citation, or attribution caveats.
+
+This is a project-maintainer note, not legal advice.
+
+## Bundled reference load profiles
+
+| File | Source | License / Terms |
+|------|--------|-----------------|
+| `breos/data/rlp/h0SLP_demandlib_1000kwh_hourly.csv`, `breos/data/rlp/h0SLP_demandlib_1000kwh_15min.csv` | Generated with [demandlib](https://demandlib.readthedocs.io/) H0 logic | demandlib documents itself as MIT-licensed free software. Preserve demandlib attribution and license notices when redistributing derived profile examples. |
+
+## Supported but not redistributed
+
+BREOS can load the following profile families when users provide their own licensed local copies through `breos.load_profile(..., rlp_directory="...")`:
+
+| Profile family | Why not bundled in this public release |
+|----------------|-----------------------------------------|
+| Direct BDEW Standardlastprofile exports (`h0_SLP.csv`, `bdew_h0_2025_15min.csv`) | BDEW publishes downloadable SLP files, but its public site terms reserve copyright rights and limit downloads/copies to private, non-commercial use unless written permission is granted. |
+| E-REDES BTN profiles (`EREDES_2025_BTN_*.csv`) | Public website terms reviewed for this release do not provide a clear redistribution grant for bundling derived CSVs in an OSS package. |
+| REE 2.0TD profiles (`REE_2026_2.0TD_*.csv`) | REE legal terms reserve intellectual-property rights and do not clearly authorize republishing derived CSV datasets in this package. |
+
+Users can still provide these files locally through `rlp_directory` when their source terms permit their use case. If written redistribution permission is granted, store the permission text with the release record before adding the files back to package data.
+
+## Runtime data sources (fetched on demand)
+
+| Service | Used by | License | Caveats |
+|---------|---------|---------|---------|
+| **Open-Meteo** Historical & Forecast API | `breos/weather.py` (`fetch_*_openmeteo`) | Data licensed **CC-BY 4.0**. | **Free API tier is non-commercial.** Commercial workloads require a paid Open-Meteo subscription. Attribution required: "Weather data by Open-Meteo.com". |
+| **NREL NSRDB** (via pvlib) | `breos/weather.py:fetch_tmy_nsrdb` | NSRDB data is a U.S. government work, generally in the public domain in the U.S. | Citation requested by NREL. Refer to the NSRDB "How to cite" page for the current canonical citation. Users must obtain their own NREL API key. |
+| **PVGIS** (JRC) | `breos/weather.py` (PVGIS endpoints) | Governed by Commission Decision 2011/833/EU on reuse of Commission documents — free reuse including commercial, with attribution. | Attribution: "© European Union, [year], PVGIS". |
+
+## Python dependencies
+
+BREOS's Python dependencies are open-source packages under their respective
+licenses. See `pyproject.toml`, `uv.lock`, and each package's own metadata for
+the authoritative license text. Core and optional dependencies currently include:
+
+- **geopy** — MIT
+- **joblib** — BSD 3-Clause
+- **matplotlib** — Matplotlib / PSF-style license terms
+- **numba** — BSD
+- **numpy** — BSD 3-Clause
+- **openpyxl** — MIT
+- **openmeteo-requests** — MIT
+- **pandas** — BSD 3-Clause
+- **pyarrow** — Apache 2.0
+- **NREL-PySAM** — BSD 3-Clause. Refer to the NREL-PySAM license and SAM
+  notices for bundled model details.
+- **pvlib** — BSD 3-Clause
+- **pymoo** — Apache 2.0
+- **rainflow** — MIT
+- **requests-cache** — BSD 2-Clause
+- **scipy** — BSD 3-Clause
+- **timezonefinder** — MIT
+
+## Scientific and model credits
+
+BREOS implements or wraps methods from the photovoltaic, battery, optimization,
+and reliability literature. These credits are separate from software-license
+requirements, but they should be preserved in papers, reports, and downstream
+documentation where the relevant models affect results.
+
+| Area | Used by | Credit / citation note |
+|------|---------|------------------------|
+| PV modelling | `breos/solar.py`, `breos/weather.py` | BREOS uses [pvlib python](https://pvlib-python.readthedocs.io/) for solar position, irradiance transposition, temperature, CEC/SAM-style module fitting, PVWatts losses, tracking, and inverter helpers. Cite pvlib in published work that relies on these calculations. |
+| SAM / CEC PV parameters | `breos/solar.py`, `breos/pv_modules.py` | CEC/SAM-style single-diode parameters and NREL SAM documentation inform module modelling assumptions. |
+| Multi-objective optimization | `breos/optimization.py` | BREOS uses [pymoo](https://pymoo.org/) for NSGA-II multi-objective optimization. Cite pymoo where optimizer behavior is material to the study. |
+| Rainflow cycle counting | `breos/battery.py` | BREOS uses the `rainflow` Python package and ASTM E1049-style rainflow counting for battery cycle detection in the reference path. |
+| Battery cycle and calendar ageing | `breos/battery.py`, `breos/constants.py`, `breos/numba_kernels.py` | Naumann et al. (2020) parameterization and equations are used for cycle ageing and selected calendar/resistance ageing behavior. |
+| LFP calendar ageing calibration | `breos/constants.py`, `breos/battery.py` | Lam et al. (2025) LFP calendar ageing behavior informs the `naumann_lam*` calendar-model variants and field-calibrated defaults. |
+| Polysun-style degradation comparison | `breos/polysun_degradation.py`, `breos/plotting.py` | The comparison baseline follows Polysun / Vela Solaris battery-lifetime methodology: Woehler curve, Miner's linear damage accumulation, DOD histograms, fixed calendar lifetime, and no continuous SOH feedback. |
+| PerMod comparison context | `breos/polysun_degradation.py` | Weniger et al., "Performance Model for PV-Battery Systems (PerMod)", HTW Berlin, 2023, is used as a comparison reference for PV-battery performance modelling. |
+| Linear damage accumulation | `breos/polysun_degradation.py` | Palmgren-Miner linear damage accumulation is used for Polysun-style cycle damage aggregation. |
+
+## Notes for downstream users
+
+If you redistribute BREOS or derived datasets:
+
+1. Preserve attributions above.
+2. If you call Open-Meteo from a commercial deployment, obtain a paid Open-Meteo subscription.
+3. Do not assume a public download page grants redistribution rights; keep externally sourced RLPs outside public package artifacts unless the source license is explicit.
+4. Cite the scientific/model references that materially affect published or customer-facing results.

breos-0.3.0/CHANGELOG.md

@@ -0,0 +1,198 @@
+# Changelog
+
+All notable changes to BREOS are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.3.0] - 2026-06-24
+
+### Fixed
+- **TMY timezone misalignment (results-changing):** `fetch_tmy_weather_data`
+  relabeled PVGIS's UTC-ordered rows with local-time labels, shifting
+  irradiance against the computed solar position by the location's UTC offset
+  (~1 h for Berlin, ~10 h for Melbourne; UTC+0 locations were unaffected).
+  Rows are now rolled to start at local midnight while each timestamp keeps
+  its correct UTC instant.
+- **Battery phantom export (results-changing):** when temperature derating or
+  daily SOH decline shrank `Emax` below the stored energy, the negative
+  charge room silently drained the battery into `Sell_To_Grid`. Stored energy
+  is now clamped into the derated window, mirroring the Numba kernel.
+- Load profiles are pinned to the location's wall clock instead of the UTC
+  clock, so H0 morning/evening peaks land at the correct local hours across
+  DST (previously ~1 h off in Iberia during summer).
+- `optimize_tilt`/`optimize_tilt_brent` reported "kWh" without accounting for
+  the timestep (4x off at 15-minute resolution; ranking was unaffected).
+- `BatteryConfig.initial_resistance_growth` was never read by
+  `simulate_energy_balance`; it now seeds the resistance state when the
+  continuation argument is not supplied.
+- `get_module_info` printed the efficiency fraction as a percent and crashed
+  on modules without efficiency metadata.
+- Removed three dead, shadowed plotting functions and an undefined
+  `MONTH_LABELS` reference that crashed the TMY-vs-historical monthly plot.
+
+### Added
+- Inverter AC clipping in the `App` energy pipeline: PV output, export, and
+  battery discharge now saturate at the AC rating implied by
+  `inverter_loading_ratio` — the same rating used for inverter CAPEX. DC
+  surplus above the rating still charges a DC-coupled battery
+  (`BatteryConfig.inverter_ac_capacity_w`, `None` = legacy uncapped model).
+- Configurable PVWatts system losses: `breos.solar.DEFAULT_PVWATTS_LOSSES`
+  (~14.1% combined) with a `loss_overrides` hook on the production functions
+  and a `pv_loss_overrides` App config key.
+- Battery operating parameters as App config keys: `battery_min_soc`,
+  `battery_max_soc`, `battery_eol_percentage`, and `battery_rte` (previously
+  hardcoded to 0.10/0.90/0.70/sqrt(0.95)).
+- `enable_resistance_fade` now feeds the resistance-derated round-trip
+  efficiency back into the energy loop (previously tracking-only).
+- Battery degradation calibration variants are explicit for the 0.3.0
+  release: `naumann_lam_field_calibrated` remains the default v1 field
+  calibration, `naumann_lam_field_calibrated_v1` is an equivalent explicit
+  alias, and `naumann_lam_field_calibrated_v2` exposes the v2
+  field-calibrated fit with Lam `Ea`/`n` fixed and `k0`/`b` fitted to field
+  data.
+- Parity tests for the optional Numba kernels: the duplicated LFP derate
+  constants against `battery.lfp_capacity_factor`, and the energy-balance
+  kernel against the reference path under shared-model conditions.
+- CLI discovery and inspection commands: `breos list
+  {locations,modules,cost-presets,emissions,load-profiles}` prints packaged
+  option keys, `breos validate-config <config>` checks a config file and
+  summarizes the resolved choices, and `breos run --dry-run` writes the
+  resolved configuration as JSON without running a simulation. `list` and
+  `validate-config` accept `--json` for machine-readable output.
+- PyPI distribution: 0.3.0 is the first release installable with
+  `pip install breos`. Tagged `v*` releases on `main` now publish to PyPI
+  through GitHub Actions trusted publishing (OIDC), running the release
+  artifact verifier before upload, with a manually triggered TestPyPI
+  dry-run path.
+- Projection-based LCOE support:
+  `breos.economics.calculate_lcoe_from_projection` computes LCOE from the
+  simulated multi-year cost projection, and the batch location comparison
+  tool now writes `lcoe_eur_kwh` plus LCOE heatmaps.
+
+### Changed
+- Renamed remaining pre-release "PVBAT" branding to BREOS in the Polysun
+  comparison plots: the `plot_degradation_methodology_comparison` first
+  argument is now `breos_soh`, the scenario/location dicts passed to
+  `plot_lifetime_prediction_comparison` and
+  `plot_temperature_sensitivity_comparison` use the `breos_eol_year` key,
+  legend labels read "BREOS (Naumann)", and the SOH comparison figure is
+  saved as `polysun_breos_soh_comparison*.png`.
+- Cost defaults are single-sourced from the `CostParams` dataclass:
+  `cost_params_from_config` and the App preset fallbacks no longer carry
+  their own diverging literals (packaged presets are unaffected).
+- Config validation rejects out-of-range values at load time: negative
+  `battery_kwh`, top-level `tilt`/`azimuth`, `inverter_efficiency`,
+  `inverter_loading_ratio`, `projection_years`, `pv_degradation_rate`, and
+  the new battery keys.
+- PV-only App runs construct an explicit inverter model, so a configured
+  `inverter_efficiency` now applies without a battery (previously ignored).
+- `App.result()["lcoe_eur_kwh"]` now uses the simulated projection, including
+  O&M and battery replacement costs, instead of the simpler CAPEX + fixed
+  annual O&M helper.
+- Library progress messages (weather file discovery, saved files, CSV
+  conversions) go through `logging` under `breos.*` logger names instead of
+  unconditional `print()`. Functions with a `verbose` flag still print.
+- Slimmed the default runtime dependency set to the BREOS core simulation
+  stack and moved heavier workflow packages behind extras: `plots`,
+  `optimization`, `weather`, `fast`, `validation`, and `location-tools`.
+  NREL-PySAM stays in the core set because the default PV model fits CEC
+  single-diode parameters at runtime via pvlib's `fit_cec_sam`.
+- The `dev` extra now installs optional feature dependencies so contributor
+  test runs continue to cover optional paths.
+
+### Documentation
+- Install snippets in the README and docs point at PyPI (`pip install breos`)
+  instead of git tag installs, and the quickstart gained a "10-minute first
+  run" walkthrough with a pip-friendly inline config, the matching
+  `configs/examples/quickstart.toml` source-checkout example, the new
+  option-discovery commands, and a representative output excerpt with
+  plausibility ranges.
+- New recipes page with validated copy-paste configs: PV-only home, PV plus
+  battery, custom latitude/longitude/timezone, east-west roof with
+  `pv_arrays`, 15-minute resolution, external E-REDES/BDEW/REE load
+  profiles, and offline runs with cached weather.
+- New generated "Packaged options" reference page listing locations, PV
+  modules, cost presets, emissions factors, and load profiles. It is built
+  by `tools/generate_option_docs.py` from the packaged data and source
+  constants, and a test fails CI when the page drifts.
+- README documents the fixed PVWatts loss components, the inverter clipping
+  convention, the `weather/` working-directory override, the Open-Meteo
+  `.cache.sqlite` file, logging configuration, and the new config keys.
+- README describes the Numba kernels honestly as approximate standalone
+  screening engines that `breos.App` does not use; the module docstring
+  carries the same warning.
+- Clarified that the `bdew_h0` alias maps to the bundled demandlib
+  BDEW-H0-shaped profile `"1"`, distinct from the external BDEW H0 2025
+  dataset (profile `"7"`).
+- Replaced stream-of-consciousness working notes in `economics`,
+  `optimization`, and `plotting` with factual comments, and
+  fixed mislabeled docstrings (`total_pv` is post-inverter AC; the Suntech
+  NOMT catalog entry documents its NMOT-condition rating).
+
+## [0.2.3] - 2026-06-08
+
+### Changed
+- Lowered the minimum supported Python from 3.13 to 3.11 — the real floor, set by
+  pandas, timezonefinder, and stdlib `tomllib`. CI now runs a 3.11/3.12/3.13 matrix.
+- Relaxed the pvlib constraint from `==0.14.0` to `>=0.14.0,<0.16` after verifying
+  the full API surface and the test suite against pvlib 0.15.1.
+- `breos.__version__` is now resolved from installed package metadata
+  (`importlib.metadata`) instead of a hardcoded literal, so it can no longer drift
+  from `pyproject.toml`.
+
+### Added
+- `CITATION.cff`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` for open-source release
+  readiness.
+
+### Removed
+- Duplicate top-level `rlp/*.csv` load-profile files (byte-identical to the
+  packaged `breos/data/rlp/` copies that runtime actually uses). `rlp/README.md` is
+  retained as external-RLP guidance.
+
+### Documentation
+- README badge and installation docs now state Python 3.11+.
+- Trimmed `ATTRIBUTIONS.md` to reference only the packaged load-profile paths.
+
+## [0.2.2] - 2026-06-07
+
+### Documentation
+- Expanded third-party notices with dependency credits, runtime data-source
+  caveats, and scientific/model attribution guidance.
+
+## [0.2.1] - 2026-06-03
+
+### Documentation
+- Updated installation guidance to use the stable GitHub tag until PyPI
+  publishing is available.
+- Added PyPI trusted publishing to the roadmap.
+- Documented the full CI/release validation gates in the contributor guide.
+- Standardized API documentation wording around domain areas.
+
+## [0.2.0] - 2026-06-03
+
+### Changed
+- Narrowed the top-level `breos.__all__` release surface to the stable facade,
+  key configuration/result objects, and core composition helpers. Lower-level
+  module APIs remain importable from their modules.
+
+## [0.1.0] - 2026-04-30
+
+### Added
+- Public API facade (`breos.App`) — single entry point for simulations: config dict in, plain dict out.
+- Command line entry point (`breos run`) for running simulations from shell flags or TOML/JSON config files.
+- Test suite — pytest coverage of the public API, battery, economics, emissions, and solar modules (all offline).
+- GitHub Actions CI on every push/PR.
+- `cost_params_from_config()` — config parser for `CostParams`.
+- Marginal grid carbon intensity support in `EmissionsParams` for more accurate CO₂ avoidance accounting.
+
+### Changed
+- Renamed PV `slope` → `tilt` everywhere: function parameters, dataclass fields, docstrings, CLI/config keys, public API. Includes `optimize_slope()` → `optimize_tilt()` and the `tools/azitilt_optimizer.py` script.
+- Calendar model name canonicalized to `naumann_lam_field_calibrated` (the legacy alias `naumann_lam_calibrated` has been removed).
+- Constants renamed: `LAM_NAUMANN_FIELD_CALIBRATED_*` → `NAUMANN_LAM_FIELD_CALIBRATED_*`; alias indirections (`LAM_CAL_K0_FRAC` …) dropped.
+- Configs modernized: per-unit cost keys (`maintenance_cost_per_panel`, `other_cost_per_module`); emissions schema renamed and country list expanded.
+- Polysun degradation now tracks the actual `last_replacement_year` instead of approximating with `n_replacements × int(total_life)` — handles fractional lifetimes and cycle-driven replacements correctly.
+- Numba degradation kernel now treats SOC reversals as half-cycles (rainflow-aligned) and applies LFP temperature derating per timestep, matching the Python reference path.
+
+### Fixed
+- NPV discount factor now uses `(1 + r) ** Year` (time-0 NPV) instead of `(1 + r) ** (Year - 1)`. Affects all `cost_analysis_projection` outputs.
+
+### Removed
+- Out-of-scope kernels (`combined_energy_balance_kernel`, `batch_combined_energy_balance_kernel`) and non-core energy-system code paths. BREOS focuses on PV + battery simulation.

breos-0.3.0/CITATION.cff

@@ -0,0 +1,24 @@
+cff-version: 1.2.0
+title: "BREOS: Building Renewable Energy Optimization Software"
+message: "If you use BREOS in your research, please cite it as below."
+type: software
+authors:
+  - given-names: Leonardo
+    family-names: Rodrigues
+    email: lrodrigues@fe.up.pt
+repository-code: "https://github.com/Str4vinci/breos"
+url: "https://github.com/Str4vinci/breos"
+abstract: >-
+  A Python library for PV and battery energy-system simulation and
+  optimization, designed for research and engineering applications.
+keywords:
+  - photovoltaic
+  - battery
+  - energy
+  - simulation
+  - optimization
+  - solar
+  - degradation
+license: BSD-3-Clause
+version: 0.3.0
+date-released: "2026-06-24"

breos-0.3.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,37 @@
+# Code of Conduct
+
+BREOS is an open-source project for energy-system simulation and optimization.
+Contributions are welcome from people with different backgrounds, levels of
+experience, and perspectives.
+
+## Expected Behavior
+
+- Be respectful and constructive in issues, pull requests, discussions, and
+  other project spaces.
+- Focus criticism on ideas, code, data, documentation, and project decisions,
+  not on people.
+- Assume good intent when possible, and ask for clarification when something is
+  ambiguous.
+- Respect maintainers' time by keeping reports actionable and discussions
+  relevant to the project.
+
+## Unacceptable Behavior
+
+The project does not tolerate harassment, threats, insults, intimidation,
+discriminatory language, sexualized attention, doxxing, sustained disruption, or
+other conduct that makes participation unsafe or unwelcome.
+
+## Reporting
+
+Report conduct concerns to the maintainer at lrodrigues@fe.up.pt. Include the
+relevant context, links, screenshots, or timestamps when available. Reports will
+be handled with discretion and shared only with people needed to review and
+respond to the situation.
+
+## Enforcement
+
+Maintainers may take action to protect the project community, including editing
+or removing comments, closing threads, requesting a change in behavior, issuing
+temporary restrictions, or banning participation in project spaces. Enforcement
+decisions should be proportionate to the conduct and focused on maintaining a
+productive, respectful environment.