Mirrors/EOS
1
0
Fork 0
mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2026-10-08 23:46:38 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

feat(devices): add bounded slot physics for GENETIC (#1327)

Browse Source 
* feat: adapt configuration for multi optimization algorithms

Decouple configuration from optimization algorithm parameters. Add to_[algorithm]_param() methods
to the configuration that derive optimization algorithm specific parameters from the configuration.
Add x-scope tags to the configuration options that describe for which specific algorithms the
configuration option is for.

The whole device settings are restructured. There are now general settings for the device classes
with the afore mentioned to_[algorithm]_param() methods. The general device settings got their own
directory `devices/settings`. By this the parameter class also does not have to be a pydantic model
which can be used for future optimization/ simulations speed up.

Also the parameter class for a device is now part of the device module. This better decouples and
also is the natural place for parameters of a device.

Besides this feature there are also fixes and improvements:

* feat: extend home appliance time window settings and simulation

  Home appliance can now be configured for multiple runs with per-cycle allowed time windows. The
  number of remaining cycles to plan is determined at runtime by reading the
  ``cycles_completed_measurement_key`` from the measurement store.

* feat: specialiced CycleTimeWindowSequence for time window sequences

  Sequence of time windows associated to cycles.

  This model specializes ``ValueTimeWindowSequence`` so that the ``value``
  field of each ``ValueTimeWindow`` encodes the **cycle index** (0-based
  integer) the window belongs to.

  Typical use: an appliance that must run ``n`` times per day, each run
  constrained to a distinct time window.  Assign ``value=0`` to windows
  for the first cycle, ``value=1`` for the second, and so on.  Multiple
  windows may share the same cycle index (their allowed regions are unioned).
  Windows with ``value=None`` are silently ignored by all cycle-aware methods.

* fix: Make test_configmigrate also regard the _ANY_SENTENIEL in key values

* chore: Make devices configurations a map instead of a list

  This makes config paths stable regardless of declaration order and lets each device settings
  class build its own config path from ``self.device_id`` without needing an external index.
  Tests are adapted likewise.

  Devices configurations are automatically migrated from lists to maps.

* chore: rename levelized_cost_of_storage_kwh to levelized_cost_of_storage_amt kwh

  This better fits in the naming scheme and also makes clear the costs are money.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

* fix: runtime config update ignored by config file

Runtime settings were handed back to pydantic-settings as init settings,
which rank below the config file and the environment. Any key already
present in EOS.config.json or in the environment silently discarded the
update, so a bulk PUT /v1/config returned 200 without applying anything,
while the granular PUT /v1/config/{path} endpoint kept working.

Add a dedicated runtime settings source ranked directly below the command
line arguments and record granular updates there as well, so both
endpoints share one store that survives re-evaluation of the settings
sources. Environment variables keep precedence over the config file for
all keys that were not set at runtime.

Also repairs revert_settings() and update(), which passed their data
through the same init settings.

Closes #1303

* fix: env vars ignored on first config build

ConfigEOS.__init__ passed self as first positional argument to _setup,
which forwards it to pydantic_settings.BaseSettings.__init__. Its first
positional parameter is _case_sensitive, so the environment source
matched the upper case variable names against the lower case field names
and returned nothing. Environment settings only took effect after the
next configuration setup.

* docs: changelog for config priority fixes

* fix(config): preserve device identities and storage costs during migration

* fix(devices): preserve charge-rate typing and public import compatibility

* ruff format fix

* feat(devices): port slot-aware battery export and direct-use physics

Port scoped device changes from d2e2d58237. Keep PR #1256 parameter conversion structure and separate GENETIC0 devices. Validate physical flows and reprice changed simulation results.

Co-authored-by: Andreas <drbacke@gmx.de>

Co-authored-by: Christin <info@bikinibottom.capital>

* fix(cache): distinguish callables in the shared EMS cache

Include the function object in cache keys so methods of one interpolator cannot reuse a probability as a power value. Cover both call orders, keyword arguments, cache hits and separate closures with identical qualified names.

* fix(devices): constrain the physics port and validate export levels

Defer inactive EV deadline fields to the optimizer port, reject nonfinite export rates, and document the hourly Optimize boundary. Verify converter IDs, rates and LCOS, separate GENETIC0 interpolation, physical boundary flows and independent GENETIC repricing.

* docs(devices): regenerate slot-physics configuration and OpenAPI schemas

* fix(config): satisfy typed device conversion and migration contracts

* docs(config): refresh validated configuration prerequisite schemas

* test(devices): align physics regressions with strict type checking

* docs(devices): refresh API version after prerequisite merge

* docs(interpolator): use portable reStructuredText markup

* docs(devices): refresh API version after docstring compatibility fix

---------

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
Co-authored-by: Bobby Noelte <b0661n0e17e@gmail.com>
Co-authored-by: r0b2g1t <r0b2g1t@users.noreply.github.com>
Co-authored-by: Christin <info@bikinibottom.capital>
This commit is contained in:
Andreas
2026-09-17 19:14:01 +02:00
committed by GitHub
co-authored by Andreas Christin Bobby Noelte r0b2g1t
parent 1a18935667
commit 3c862543a1
17 changed files with 1043 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/_generated/configdevices.md
+26 -2
View File
@@ -57,7 +57,13 @@ config path from ``self.device_id`` without needing an external index.
1.0
],
"min_soc_percentage": 0,
"max_soc_percentage": 100
"max_soc_percentage": 100,
"grid_export_rates": [
0.25,
0.5,
0.75,
1.0
]
}
},
"max_batteries": 1,
@@ -86,7 +92,13 @@ config path from ``self.device_id`` without needing an external index.
1.0
],
"min_soc_percentage": 0,
"max_soc_percentage": 100
"max_soc_percentage": 100,
"grid_export_rates": [
0.25,
0.5,
0.75,
1.0
]
}
},
"max_electric_vehicles": 1,
@@ -143,6 +155,12 @@ config path from ``self.device_id`` without needing an external index.
],
"min_soc_percentage": 0,
"max_soc_percentage": 100,
"grid_export_rates": [
0.25,
0.5,
0.75,
1.0
],
"measurement_key_soc_factor": "bat0-soc-factor",
"measurement_key_power_l1_w": "bat0-power-l1-w",
"measurement_key_power_l2_w": "bat0-power-l2-w",
@@ -184,6 +202,12 @@ config path from ``self.device_id`` without needing an external index.
],
"min_soc_percentage": 0,
"max_soc_percentage": 100,
"grid_export_rates": [
0.25,
0.5,
0.75,
1.0
],
"measurement_key_soc_factor": "ev0-soc-factor",
"measurement_key_power_l1_w": "ev0-power-l1-w",
"measurement_key_power_l2_w": "ev0-power-l2-w",
docs/_generated/configexample.md
+14 -2
View File
@@ -61,7 +61,13 @@
1.0
],
"min_soc_percentage": 0,
"max_soc_percentage": 100
"max_soc_percentage": 100,
"grid_export_rates": [
0.25,
0.5,
0.75,
1.0
]
}
},
"max_batteries": 1,
@@ -90,7 +96,13 @@
1.0
],
"min_soc_percentage": 0,
"max_soc_percentage": 100
"max_soc_percentage": 100,
"grid_export_rates": [
0.25,
0.5,
0.75,
1.0
]
}
},
"max_electric_vehicles": 1,
docs/_generated/openapi.md
+1 -1
View File
@@ -1,6 +1,6 @@
# Akkudoktor-EOS
**Version**: `v0.3.0.dev2609171537448705`
**Version**: `v0.3.0.dev2609171651094774`
<!-- pyml disable line-length -->
**Description**: This project provides a comprehensive solution for simulating and optimizing an energy system based on renewable energy sources. With a focus on photovoltaic (PV) systems, battery storage (batteries), load management (consumer requirements), heat pumps, electric vehicles, and consideration of electricity price data, this system enables forecasting and optimization of energy flow and costs over a specified period.
docs/development/device-physics.md
+41
View File
@@ -0,0 +1,41 @@
# Slot-aware GENETIC device physics
This package depends on the device-map and algorithm-converter configuration work
from PR #1256 and the runtime settings foundation from PR #1305. Parameter classes
remain in `devices/genetic`; settings remain in `devices/settings`.
Battery and inverter models accept a slot duration, apply power limits as energy
per slot, and preserve the total battery charge/discharge budget across multiple
calls within that slot. Battery export is an explicit device-simulation operation;
setting export rates does not by itself activate optimizer export states. The
converter carries stable device IDs, charge/export levels and LCOS unchanged.
Configuration LCOS uses amount/kWh; no Wh conversion is applied by the converter.
The GENETIC inverter now computes expected direct PV-to-load power from the
minute-load distribution, then converts power to interval energy. This changes
GENETIC simulation economics even at the default hourly interval. The probability
table was calibrated with hourly mean loads: use with quarter-hour means remains
an approximation, not a separately calibrated quarter-hour model. Its legacy
cumulative-probability API now clamps values at the table boundary and to [0, 1].
The GENETIC0 inverter uses a separate implementation and separate interpolation
data file; this package does not change either. Existing GENETIC0 optimization
and PDF golden tests remain required.
The shared in-memory cache must include callable identity in each key. Otherwise
the legacy cumulative probability and new direct-power method on the same object
can return each other's cached results for identical arguments. This package
includes that prerequisite fix and verifies both call orders and cache reuse.
This package alone does **not** make an Optimize mode quarter-hour capable.
GENETIC parameter preparation still forces the interval to 3600 seconds, and
`/optimize` still selects the separate GENETIC0 algorithm. Quarter-hour scheduling,
warm-start alignment, forecast/control horizons, terminal values, export states,
EV deadlines and flexible-consumer planning require the later optimizer port.
No inactive EV-deadline fields are introduced here.
Validation covers charge/discharge budgets, inverter/export limits, efficiencies,
energy conservation, interpolation boundaries, converter fields, both algorithms'
short optimization/PDF runs and unchanged GENETIC0 monetary goldens. GENETIC runs
use independent repricing of grid energy, schema checks and physical bounds rather
than requiring the previous direct-consumption model's monetary golden. Long
`--finalize` optimization runs and pinned CI environments remain separate checks.
openapi.json
+131 -1
View File
@@ -8,7 +8,7 @@
"name": "Apache 2.0",
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
},
"version": "v0.3.0.dev2609171537448705"
"version": "v0.3.0.dev2609171651094774"
},
"paths": {
"/v1/measurement/battery-capacity/{battery_id}": {
@@ -3360,6 +3360,39 @@
"examples": [
100
]
},
"grid_export_rates": {
"anyOf": [
{
"items": {
"type": "number"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Grid Export Rates",
"description": "Battery-to-grid export rates as factor of maximum discharge power ]0.00 ... 1.00]. Available to algorithms that explicitly enable battery-to-grid export; configuring rates alone does not enable export. [1.0] selects full-power export. None uses the default export rates.",
"default": [
0.25,
0.5,
0.75,
1.0
],
"examples": [
[
0.25,
0.5,
0.75,
1.0
],
[
1.0
],
null
]
}
},
"type": "object",
@@ -3535,6 +3568,39 @@
100
]
},
"grid_export_rates": {
"anyOf": [
{
"items": {
"type": "number"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Grid Export Rates",
"description": "Battery-to-grid export rates as factor of maximum discharge power ]0.00 ... 1.00]. Available to algorithms that explicitly enable battery-to-grid export; configuring rates alone does not enable export. [1.0] selects full-power export. None uses the default export rates.",
"default": [
0.25,
0.5,
0.75,
1.0
],
"examples": [
[
0.25,
0.5,
0.75,
1.0
],
[
1.0
],
null
]
},
"measurement_key_soc_factor": {
"type": "string",
"title": "Measurement Key Soc Factor",
@@ -5378,6 +5444,33 @@
],
null
]
},
"grid_export_rates": {
"anyOf": [
{
"items": {
"type": "number"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Grid Export Rates",
"description": "Battery-to-grid export rates as factor of maximum discharge power ]0.00 ... 1.00]. These levels are available to algorithms that explicitly enable battery-to-grid export. None leaves the choice of export levels to the caller.",
"examples": [
[
0.25,
0.5,
0.75,
1.0
],
[
1.0
],
null
]
}
},
"additionalProperties": false,
@@ -14327,6 +14420,43 @@
],
null
]
},
"grid_export_rates": {
"anyOf": [
{
"items": {
"type": "number"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Grid Export Rates",
"description": "Battery-to-grid export rates as factor of maximum discharge power ]0.00 ... 1.00]. These levels are available to algorithms that explicitly enable battery-to-grid export. None leaves the choice of export levels to the caller.",
"examples": [
[
0.25,
0.5,
0.75,
1.0
],
[
1.0
],
null
]
},
"levelized_cost_of_storage_kwh": {
"type": "number",
"minimum": 0.0,
"title": "Levelized Cost Of Storage Kwh",
"description": "Levelized cost of storage applied once to each kWh delivered by the battery [EUR/kWh].",
"default": 0.0,
"examples": [
0.12
]
}
},
"additionalProperties": false,
src/akkudoktoreos/core/cache.py
+3
View File
@@ -228,6 +228,9 @@ def cache_energy_management(
cached_wrapper = cachebox.cached(
cache=CacheEnergyManagementStore().cache,
# This store is shared by all decorated callables, including methods
# on the same instance. Arguments alone cannot identify their results.
key_maker=lambda *args, **kwargs: cachebox.make_key(func, *args, **kwargs),
callback=cache_energy_management_store_callback,
)(wrapper)
src/akkudoktoreos/devices/genetic/battery.py
+84 -7
View File
@@ -80,11 +80,34 @@ class BaseBatteryParameters(DeviceParameters):
"examples": [[0.0, 0.25, 0.5, 0.75, 1.0], None],
},
)
grid_export_rates: Optional[list[float]] = Field(
default=None,
json_schema_extra={
"description": (
"Battery-to-grid export rates as factor of maximum discharge "
"power ]0.00 ... 1.00]. These levels are available to algorithms "
"that explicitly enable battery-to-grid export. None leaves the "
"choice of export levels to the caller."
),
"examples": [[0.25, 0.5, 0.75, 1.0], [1.0], None],
},
)
class SolarPanelBatteryParameters(BaseBatteryParameters):
"""PV battery device simulation configuration."""
levelized_cost_of_storage_kwh: float = Field(
default=0.0,
ge=0.0,
json_schema_extra={
"description": (
"Levelized cost of storage applied once to each kWh delivered "
"by the battery [EUR/kWh]."
),
"examples": [0.12],
},
)
max_charge_power_w: Optional[float] = max_charging_power_field()
@@ -103,9 +126,20 @@ class ElectricVehicleParameters(BaseBatteryParameters):
class Battery:
"""Represents a battery device with methods to simulate energy charging and discharging."""
def __init__(self, parameters: BaseBatteryParameters, prediction_hours: int):
def __init__(
self,
parameters: BaseBatteryParameters,
prediction_hours: int,
slot_duration_h: float = 1.0,
):
# `prediction_hours` is the number of optimization slots, not hours. At
# the default optimization interval of 3600 s, slot_duration_h is 1.0 and
# the slot count equals the hour count, so existing callers are
# unaffected. At 900 s (15 min) slot_duration_h is 0.25 and there are 4x
# as many slots, each able to move a quarter of the hourly energy.
self.parameters = parameters
self.prediction_hours = prediction_hours
self.slot_duration_h = slot_duration_h
self._setup()
def _setup(self) -> None:
@@ -114,6 +148,11 @@ class Battery:
self.initial_soc_percentage = self.parameters.initial_soc_percentage
self.charging_efficiency = self.parameters.charging_efficiency
self.discharging_efficiency = self.parameters.discharging_efficiency
self.levelized_cost_of_storage_kwh = (
self.parameters.levelized_cost_of_storage_kwh
if isinstance(self.parameters, SolarPanelBatteryParameters)
else 0.0
)
# Charge rates, in case of None use default
self.charge_rates = np.array(BATTERY_DEFAULT_CHARGE_RATES, dtype=float)
@@ -138,6 +177,8 @@ class Battery:
self.max_charge_power_w = self.capacity_wh # TODO this should not be equal capacity_wh
self.discharge_array = np.full(self.prediction_hours, 0)
self.charge_array = np.full(self.prediction_hours, 0)
self._discharged_raw_wh_per_slot = np.zeros(self.prediction_hours, dtype=float)
self._charged_raw_wh_per_slot = np.zeros(self.prediction_hours, dtype=float)
self.soc_wh = (self.initial_soc_percentage / 100) * self.capacity_wh
self.min_soc_wh = (self.min_soc_percentage / 100) * self.capacity_wh
self.max_soc_wh = (self.max_soc_percentage / 100) * self.capacity_wh
@@ -181,6 +222,30 @@ class Battery:
self.soc_wh = min(self.soc_wh, self.max_soc_wh) # Only clamp to max
self.discharge_array = np.full(self.prediction_hours, 0)
self.charge_array = np.full(self.prediction_hours, 0)
self._discharged_raw_wh_per_slot = np.zeros(self.prediction_hours, dtype=float)
self._charged_raw_wh_per_slot = np.zeros(self.prediction_hours, dtype=float)
def rated_discharge_energy_wh(self) -> float:
"""Return the DC energy one full-power discharge slot delivers.
This is the reference a grid-export rate is applied to: a rate of 0.5
exports at most half the battery's rated discharge power, independent of
how much of the slot budget self-consumption already used.
"""
return self.max_charge_power_w * self.slot_duration_h * self.discharging_efficiency
def remaining_discharge_energy_wh(self, hour: int) -> float:
"""Return DC energy still deliverable within one optimization slot."""
raw_power_budget_wh = self.max_charge_power_w * self.slot_duration_h
raw_power_remaining_wh = max(
raw_power_budget_wh - self._discharged_raw_wh_per_slot[hour], 0.0
)
raw_soc_available_wh = max(self.soc_wh - self.min_soc_wh, 0.0)
return min(raw_power_remaining_wh, raw_soc_available_wh) * self.discharging_efficiency
def discharged_energy_wh(self, hour: int) -> float:
"""Return DC energy delivered by the battery in one optimization slot."""
return self._discharged_raw_wh_per_slot[hour] * self.discharging_efficiency
def set_discharge_per_hour(self, discharge_array: np.ndarray) -> None:
"""Sets the discharge values for each hour."""
@@ -228,8 +293,13 @@ class Battery:
# Raw extractable energy above minimum SoC
raw_available_wh = max(self.soc_wh - self.min_soc_wh, 0.0)
# Maximum raw discharge due to power limit
max_raw_wh = self.max_charge_power_w # TODO rename to max_discharge_power_w
# Maximum raw discharge due to power limit, scaled to the slot duration.
# max_charge_power_w is a power [W]; energy movable in one slot is
# power x slot_duration_h.
max_raw_wh = max(
self.max_charge_power_w * self.slot_duration_h - self._discharged_raw_wh_per_slot[hour],
0.0,
) # TODO rename to max_discharge_power_w
# Actual raw withdrawal (internal)
raw_withdrawal_wh = min(raw_available_wh, max_raw_wh)
@@ -246,6 +316,7 @@ class Battery:
# Update SoC
self.soc_wh -= raw_used_wh
self.soc_wh = max(self.soc_wh, self.min_soc_wh)
self._discharged_raw_wh_per_slot[hour] += raw_used_wh
# Losses
losses_wh = raw_used_wh - delivered_wh
@@ -320,7 +391,12 @@ class Battery:
# Provide fast (3x..5x) local read access (vs. self.xxx) for repetitive read access
soc_wh_fast = self.soc_wh
max_charge_power_w_fast = self.max_charge_power_w
# Scale the power cap [W] to a per-slot energy cap [Wh] (W x slot hours).
# At slot_duration_h=1.0 (hourly) this equals the legacy power value.
max_charge_per_slot_wh_fast = max(
self.max_charge_power_w * self.slot_duration_h - self._charged_raw_wh_per_slot[hour],
0.0,
)
charging_efficiency_fast = self.charging_efficiency
# Decide mode & determine raw_request_wh and raw_charge_wh
@@ -328,13 +404,13 @@ class Battery:
raw_request_wh = wh
raw_charge_wh = max(self.max_soc_wh - soc_wh_fast, 0.0) / charging_efficiency_fast
elif wh is None and charge_factor > 0.0: # mode 2
raw_request_wh = max_charge_power_w_fast * charge_factor
raw_request_wh = max_charge_per_slot_wh_fast * charge_factor
raw_charge_wh = max(self.max_soc_wh - soc_wh_fast, 0.0) / charging_efficiency_fast
if raw_request_wh > raw_charge_wh:
# Use a lower charge factor
lower_charge_factors = self._lower_charge_rates_desc(charge_factor)
for charge_factor in lower_charge_factors:
raw_request_wh = max_charge_power_w_fast * charge_factor
raw_request_wh = max_charge_per_slot_wh_fast * charge_factor
if raw_request_wh <= raw_charge_wh:
self.charge_array[hour] = charge_factor
break
@@ -349,7 +425,7 @@ class Battery:
)
# Remaining capacity
max_raw_wh = min(raw_charge_wh, max_charge_power_w_fast)
max_raw_wh = min(raw_charge_wh, max_charge_per_slot_wh_fast)
# Actual raw intake
raw_input_wh = raw_request_wh if raw_request_wh < max_raw_wh else max_raw_wh
@@ -364,6 +440,7 @@ class Battery:
)
self.soc_wh = new_soc
self._charged_raw_wh_per_slot[hour] += raw_input_wh
losses_wh = raw_input_wh - stored_wh
return stored_wh, losses_wh
src/akkudoktoreos/devices/genetic/inverter.py
+119 -92
View File
@@ -63,9 +63,11 @@ class Inverter:
self,
parameters: InverterParameters,
battery: Optional[Battery] = None,
slot_duration_h: float = 1.0,
):
self.parameters: InverterParameters = parameters
self.battery: Optional[Battery] = battery
self.slot_duration_h: float = slot_duration_h
self._setup()
def _setup(self) -> None:
@@ -74,110 +76,135 @@ class Inverter:
logger.error(error_msg)
raise ValueError(error_msg)
self.self_consumption_predictor = get_eos_load_interpolator()
self.max_power_wh = (
self.parameters.max_power_wh
) # Maximum power that the inverter can handle
# max_power_wh is supplied as power [W] but used as the maximum energy
# the inverter can move during one optimization slot.
self.max_power_wh = self.parameters.max_power_wh * self.slot_duration_h
self.dc_to_ac_efficiency = self.parameters.dc_to_ac_efficiency
self.ac_to_dc_efficiency = self.parameters.ac_to_dc_efficiency
# This value remains a power [W]. GeneticSimulation converts it into a
# slot-independent charge-factor limit.
self.max_ac_charge_power_w = self.parameters.max_ac_charge_power_w
def _discharge_battery_to_ac(self, requested_ac_wh: float, hour: int) -> tuple[float, float]:
"""Discharge battery energy and convert it to AC energy."""
if not self.battery or requested_ac_wh <= 0.0:
return 0.0, 0.0
dc_request = requested_ac_wh / self.dc_to_ac_efficiency
battery_discharge_dc, discharge_losses = self.battery.discharge_energy(dc_request, hour)
battery_discharge_ac = battery_discharge_dc * self.dc_to_ac_efficiency
inverter_discharge_losses = battery_discharge_dc - battery_discharge_ac
return battery_discharge_ac, discharge_losses + inverter_discharge_losses
def process_energy(
self, generation: float, consumption: float, hour: int
self,
generation: float,
consumption: float,
hour: int,
allow_battery_grid_export: bool = False,
battery_grid_export_factor: float = 1.0,
) -> tuple[float, float, float, float]:
"""Process one slot using probabilistic direct PV-to-load overlap.
``generation`` and ``consumption`` are interval energies. The load
probability table is evaluated in watts and yields the expected direct
PV-to-load power. The remaining load and PV surplus are then handled
independently, because both can occur during different sub-intervals of
the same hourly or 15-minute slot.
Args:
generation: PV energy of the slot [Wh].
consumption: Load energy of the slot [Wh].
hour: Slot index.
allow_battery_grid_export: Whether the battery may discharge into the
grid in this slot (direct marketing).
battery_grid_export_factor: Export level as a factor of the battery's
rated discharge power [0.0 ... 1.0]. 1.0 exports as much as the
battery and the inverter allow, which is the behaviour when no
export rates are configured.
"""
losses = 0.0
grid_export = 0.0
grid_import = 0.0
self_consumption = 0.0
generation = max(float(generation), 0.0)
consumption = max(float(consumption), 0.0)
# Cache inverter DC→AC efficiency for discharge path
dc_to_ac_eff = self.dc_to_ac_efficiency
if generation >= consumption:
if consumption > self.max_power_wh:
# If consumption exceeds maximum inverter power
losses += generation - self.max_power_wh
remaining_power = self.max_power_wh - consumption
grid_import = -remaining_power # Negative indicates feeding into the grid
self_consumption = self.max_power_wh
else:
# Calculate scr using cached results per energy management/optimization run
scr = self.self_consumption_predictor.calculate_self_consumption(
consumption, generation
# Convert interval energy [Wh] to mean power [W] for the probability
# lookup, then convert its expected direct power back to slot energy.
if generation > 0.0 and consumption > 0.0:
expected_direct_power_w = (
self.self_consumption_predictor.calculate_expected_direct_consumption(
consumption / self.slot_duration_h,
generation / self.slot_duration_h,
)
# Remaining power after consumption
remaining_power = (generation - consumption) * scr # EVQ
# Remaining load Self Consumption not perfect
remaining_load_evq = (generation - consumption) * (1.0 - scr)
if remaining_load_evq > 0:
# The battery must cover the remaining consumption
if self.battery:
# Request more DC from battery to account for DC→AC conversion loss
dc_request = remaining_load_evq / dc_to_ac_eff
from_battery_dc, discharge_losses = self.battery.discharge_energy(
dc_request, hour
)
# Convert DC output to AC
from_battery_ac = from_battery_dc * dc_to_ac_eff
inverter_discharge_losses = from_battery_dc - from_battery_ac
remaining_load_evq -= from_battery_ac
losses += discharge_losses + inverter_discharge_losses
else:
from_battery_ac = 0.0
# If the battery cannot fully cover the remaining consumption, the rest is drawn from the grid
if remaining_load_evq > 0:
grid_import += remaining_load_evq
remaining_load_evq = 0
else:
from_battery_ac = 0.0
if remaining_power > 0:
# Load battery with excess energy (DC path, no inverter conversion needed)
charge_losses = 0.0
if self.battery:
charged_energie, charge_losses = self.battery.charge_energy(
remaining_power, hour
)
remaining_surplus = remaining_power - (charged_energie + charge_losses)
else:
remaining_surplus = remaining_power
# Feed-in to the grid based on remaining capacity
if remaining_surplus > self.max_power_wh - consumption:
grid_export = self.max_power_wh - consumption
losses += remaining_surplus - grid_export
else:
grid_export = remaining_surplus
losses += charge_losses
self_consumption = (
consumption + from_battery_ac
) # Self-consumption is equal to the load
)
direct_pv_energy = expected_direct_power_w * self.slot_duration_h
else:
# Case 2: Insufficient generation, cover shortfall
shortfall = consumption - generation
available_ac_power = max(self.max_power_wh - generation, 0)
direct_pv_energy = 0.0
# Discharge battery to cover shortfall, if possible
if self.battery:
# Need shortfall in AC, request more DC from battery for DC→AC conversion
ac_needed = min(shortfall, available_ac_power)
dc_request = ac_needed / dc_to_ac_eff
battery_discharge_dc, discharge_losses = self.battery.discharge_energy(
dc_request, hour
)
# Convert DC output to AC
battery_discharge_ac = battery_discharge_dc * dc_to_ac_eff
inverter_discharge_losses = battery_discharge_dc - battery_discharge_ac
losses += discharge_losses + inverter_discharge_losses
else:
battery_discharge_ac = 0
# Direct PV is bounded by both input energies and by the AC energy the
# inverter can move during this slot.
direct_pv_energy = min(
max(direct_pv_energy, 0.0),
generation,
consumption,
self.max_power_wh,
)
remaining_load = max(consumption - direct_pv_energy, 0.0)
pv_surplus = max(generation - direct_pv_energy, 0.0)
remaining_inverter_ac_capacity = max(self.max_power_wh - direct_pv_energy, 0.0)
# Draw remaining required power from the grid (discharge_losses are already subtracted in the battery)
grid_import = shortfall - battery_discharge_ac
self_consumption = generation + battery_discharge_ac
# Load gaps and PV surplus may both occur within the same coarse slot.
# Cover the load gap first; this preserves the existing chronological
# approximation and can create headroom for later PV charging.
battery_discharge_ac = 0.0
if remaining_load > 0.0 and self.battery and remaining_inverter_ac_capacity > 0.0:
requested_ac_wh = min(remaining_load, remaining_inverter_ac_capacity)
battery_discharge_ac, battery_discharge_losses = self._discharge_battery_to_ac(
requested_ac_wh, hour
)
remaining_load = max(remaining_load - battery_discharge_ac, 0.0)
remaining_inverter_ac_capacity = max(
remaining_inverter_ac_capacity - battery_discharge_ac, 0.0
)
losses += battery_discharge_losses
grid_import = remaining_load
# Charge from the probabilistic PV surplus on the DC path. Stored energy
# plus charge losses equals the PV energy accepted by the battery.
remaining_surplus = pv_surplus
if remaining_surplus > 0.0 and self.battery:
charged_energy, charge_losses = self.battery.charge_energy(remaining_surplus, hour)
remaining_surplus = max(remaining_surplus - charged_energy - charge_losses, 0.0)
losses += charge_losses
pv_grid_export = min(remaining_surplus, remaining_inverter_ac_capacity)
grid_export += pv_grid_export
remaining_inverter_ac_capacity = max(remaining_inverter_ac_capacity - pv_grid_export, 0.0)
# PV which can neither charge the battery nor pass through the inverter
# is curtailed and reported as a loss.
losses += max(remaining_surplus - pv_grid_export, 0.0)
if allow_battery_grid_export and self.battery and remaining_inverter_ac_capacity > 0.0:
export_factor = min(max(float(battery_grid_export_factor), 0.0), 1.0)
remaining_battery_ac = (
self.battery.remaining_discharge_energy_wh(hour) * self.dc_to_ac_efficiency
)
# The rate caps the export against the battery's *rated* discharge
# power, so it stays a plain power setpoint ("export at 50 %") that
# does not silently grow when self-consumption used less of the slot.
# At factor 1.0 this bound never binds; behaviour is unchanged.
rated_export_ac = (
self.battery.rated_discharge_energy_wh() * export_factor * self.dc_to_ac_efficiency
)
export_capacity = min(
remaining_inverter_ac_capacity, remaining_battery_ac, rated_export_ac
)
battery_export_ac, battery_export_losses = self._discharge_battery_to_ac(
export_capacity, hour
)
grid_export += battery_export_ac
losses += battery_export_losses
self_consumption = direct_pv_energy + battery_discharge_ac
return grid_export, grid_import, losses, self_consumption
src/akkudoktoreos/devices/settings/batterysettings.py
+48
View File
@@ -31,6 +31,9 @@ if TYPE_CHECKING:
BATTERY_DEFAULT_CHARGE_RATES: list[float] = [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]
BATTERY_DEFAULT_GRID_EXPORT_RATES: list[float] = [0.25, 0.5, 0.75, 1.0]
class BatteriesCommonSettings(DevicesBaseSettings):
"""Battery and electric vehicle device settings.
@@ -130,6 +133,48 @@ class BatteriesCommonSettings(DevicesBaseSettings):
# GENETIC domain conversion
# ------------------------------------------------------------------
grid_export_rates: Optional[list[float]] = Field(
default=BATTERY_DEFAULT_GRID_EXPORT_RATES,
json_schema_extra={
"description": (
"Battery-to-grid export rates as factor of maximum discharge "
"power ]0.00 ... 1.00]. Available to algorithms that explicitly "
"enable battery-to-grid export; configuring rates alone does not "
"enable export. [1.0] selects full-power export. None uses the "
"default export rates."
),
"examples": [[0.25, 0.5, 0.75, 1.0], [1.0], None],
},
)
@field_validator("grid_export_rates", mode="before")
def validate_and_sort_grid_export_rates(cls, v: Any) -> list[float]:
"""Normalize export rates to a finite, sorted, duplicate-free list in ]0, 1]."""
# None means fallback to default values
if v is None:
return BATTERY_DEFAULT_GRID_EXPORT_RATES.copy()
if isinstance(v, str):
numbers = re.split(r"[,\s]+", v.strip("[]"))
arr = np.array([float(x) for x in numbers if x])
else:
arr = np.array(v, dtype=float)
if arr.ndim != 1 or arr.size == 0:
raise ValueError("grid_export_rates must be a nonempty one-dimensional list.")
if not np.isfinite(arr).all():
raise ValueError("grid_export_rates must contain finite values.")
# A rate of 0.0 is not an export level - "no export" is expressed by the
# other battery states - so the lower bound is exclusive.
if (arr <= 0.0).any() or (arr > 1.0).any():
raise ValueError("grid_export_rates must be within ]0.0, 1.0].")
arr = np.unique(arr)
arr.sort()
return arr.tolist()
def to_genetic_pv_bat_param(self) -> "SolarPanelBatteryParameters":
"""Return SolarPanelBatteryParameters for the GENETIC optimizer."""
from akkudoktoreos.devices.genetic.battery import SolarPanelBatteryParameters
@@ -142,6 +187,9 @@ class BatteriesCommonSettings(DevicesBaseSettings):
max_charge_power_w=self.max_charge_power_w,
min_soc_percentage=self.min_soc_percentage,
max_soc_percentage=self.max_soc_percentage,
charge_rates=self.charge_rates,
grid_export_rates=self.grid_export_rates,
levelized_cost_of_storage_kwh=self.levelized_cost_of_storage_amt_kwh,
)
def to_genetic_ev_bat_param(self) -> "ElectricVehicleParameters":
src/akkudoktoreos/prediction/interpolator.py
+92 -10
View File
@@ -15,31 +15,113 @@ class SelfConsumptionProbabilityInterpolator:
# Load the RegularGridInterpolator
with open(self.filepath, "rb") as file:
self.interpolator: RegularGridInterpolator = pickle.load(file) # noqa: S301
self.load_power_min_w = float(self.interpolator.grid[0][0])
self.load_power_max_w = float(self.interpolator.grid[0][-1])
self.minute_load_levels_w = np.asarray(self.interpolator.grid[1], dtype=float)
self.minute_load_max_w = float(self.interpolator.grid[1][-1])
def _load_distribution(self, mean_load_power_w: float) -> tuple[np.ndarray, np.ndarray]:
"""Return the conditional minute-load distribution for a mean load.
The table stores one probability mass for each 50 W minute-load bin.
Linear interpolation between its mean-load rows can introduce very small
numerical deviations, so negative masses are removed and the result is
normalized explicitly.
"""
bounded_mean_load_w = float(
np.clip(mean_load_power_w, self.load_power_min_w, self.load_power_max_w)
)
points = np.column_stack(
(
np.full(self.minute_load_levels_w.shape, bounded_mean_load_w),
self.minute_load_levels_w,
)
)
probabilities = np.maximum(np.asarray(self.interpolator(points), dtype=float), 0.0)
probability_sum = float(probabilities.sum())
if probability_sum <= 0.0:
return self.minute_load_levels_w, probabilities
return self.minute_load_levels_w, probabilities / probability_sum
def _generate_points(
self, load_1h_power: float, pv_power: float
self, mean_load_power_w: float, pv_power_w: float
) -> tuple[np.ndarray, np.ndarray]:
"""Generate the grid points for interpolation."""
partial_loads = np.arange(0, pv_power + 50, 50)
points = np.array([np.full_like(partial_loads, load_1h_power), partial_loads]).T
"""Generate in-bounds grid points for interpolation.
The bundled probability table was calibrated from a one-hour mean load
and one-minute samples. Sub-hourly optimization still passes *power* in
watts here; a native 15-minute mean is therefore a documented
approximation until a separately calibrated table is available.
"""
bounded_mean_load_w = float(
np.clip(mean_load_power_w, self.load_power_min_w, self.load_power_max_w)
)
bounded_pv_power_w = float(np.clip(pv_power_w, 0.0, self.minute_load_max_w))
partial_loads = np.arange(0.0, bounded_pv_power_w + 1.0, 50.0)
points = np.column_stack((np.full(partial_loads.shape, bounded_mean_load_w), partial_loads))
return points, partial_loads
@cache_energy_management
def calculate_self_consumption(self, load_1h_power: float, pv_power: float) -> float:
"""Calculate the PV self-consumption rate using RegularGridInterpolator.
def calculate_self_consumption(self, mean_load_power_w: float, pv_power_w: float) -> float:
"""Return the legacy cumulative minute-load probability.
This method is retained for API compatibility. Its result is the
probability that the minute load is no greater than ``pv_power_w``;
it is not an energy self-consumption ratio. New energy-flow code must
use ``calculate_expected_direct_consumption``.
The results are cached until the start of the next energy management run/ optimization.
Args:
- last_1h_power: 1h power levels (W).
- pv_power: Current PV power output (W).
- mean_load_power_w: Mean load power for the current forecast interval (W).
- pv_power_w: Current PV power output (W).
Returns:
- Self-consumption rate as a float.
"""
points, partial_loads = self._generate_points(load_1h_power, pv_power)
points, _ = self._generate_points(mean_load_power_w, pv_power_w)
probabilities = self.interpolator(points)
return probabilities.sum()
return float(np.clip(probabilities.sum(), 0.0, 1.0))
@cache_energy_management
def calculate_expected_direct_consumption(
self, mean_load_power_w: float, pv_power_w: float
) -> float:
"""Calculate expected direct PV-to-load power in watts.
For conditional minute-load probabilities ``p_i`` and load-bin powers
``L_i``, the expected direct consumption is
``sum(p_i * min(L_i, pv_power_w))``.
The tabulated load-bin powers are rescaled to preserve the supplied
forecast mean exactly. This compensates for discretization and the
finite upper table boundary while retaining the distribution shape.
Args:
mean_load_power_w: Mean load power of the forecast interval [W].
pv_power_w: Mean PV power of the forecast interval [W].
Returns:
Expected direct PV-to-load power [W].
"""
mean_load_power_w = max(float(mean_load_power_w), 0.0)
pv_power_w = max(float(pv_power_w), 0.0)
if mean_load_power_w == 0.0 or pv_power_w == 0.0:
return 0.0
load_levels_w, probabilities = self._load_distribution(mean_load_power_w)
modeled_mean_load_w = float(np.dot(probabilities, load_levels_w))
if modeled_mean_load_w <= 0.0:
return 0.0
# Preserve the requested mean load while keeping the conditional shape
# from the probability table.
normalized_load_levels_w = load_levels_w * (mean_load_power_w / modeled_mean_load_w)
expected_direct_power_w = float(
np.dot(probabilities, np.minimum(normalized_load_levels_w, pv_power_w))
)
return float(np.clip(expected_direct_power_w, 0.0, min(mean_load_power_w, pv_power_w)))
# def calculate_self_consumption(self, load_1h_power: float, pv_power: float) -> float:
# """Calculate the PV self-consumption rate using RegularGridInterpolator.
tests/test_battery.py
+104
View File
@@ -1,6 +1,8 @@
import numpy as np
import pytest
from pydantic import ValidationError
from akkudoktoreos.devices.devices import BatteriesCommonSettings
from akkudoktoreos.devices.genetic.battery import Battery, SolarPanelBatteryParameters
@@ -294,3 +296,105 @@ def test_car_and_pv_battery_discharge_and_max_charge_power(setup_pv_battery, set
assert car_battery.parameters.max_charge_power_w == 7000, (
"Car battery max charge power should remain as defined"
)
def test_quarter_hour_charge_calls_share_one_power_budget():
params = SolarPanelBatteryParameters(
device_id="battery1",
capacity_wh=10_000,
initial_soc_percentage=0,
min_soc_percentage=0,
max_soc_percentage=100,
max_charge_power_w=1_000,
charging_efficiency=1.0,
discharging_efficiency=1.0,
)
battery = Battery(params, prediction_hours=4, slot_duration_h=0.25)
battery.set_charge_per_hour(np.ones(4))
first_stored, _ = battery.charge_energy(200.0, 0)
second_stored, _ = battery.charge_energy(200.0, 0)
assert first_stored == pytest.approx(200.0)
assert second_stored == pytest.approx(50.0)
assert battery.soc_wh == pytest.approx(250.0)
def test_quarter_hour_discharge_calls_share_one_power_budget():
params = SolarPanelBatteryParameters(
device_id="battery1",
capacity_wh=10_000,
initial_soc_percentage=100,
min_soc_percentage=0,
max_soc_percentage=100,
max_charge_power_w=1_000,
charging_efficiency=1.0,
discharging_efficiency=1.0,
)
battery = Battery(params, prediction_hours=4, slot_duration_h=0.25)
battery.set_discharge_per_hour(np.ones(4))
first_delivered, _ = battery.discharge_energy(200.0, 0)
second_delivered, _ = battery.discharge_energy(200.0, 0)
assert first_delivered == pytest.approx(200.0)
assert second_delivered == pytest.approx(50.0)
assert battery.discharged_energy_wh(0) == pytest.approx(250.0)
assert battery.soc_wh == pytest.approx(9_750.0)
battery.reset()
assert battery.discharged_energy_wh(0) == 0.0
def test_grid_export_rates_are_sorted_and_deduplicated():
"""Export rates are normalized like the charge rates."""
settings = BatteriesCommonSettings(
device_id="battery1", grid_export_rates=[1.0, 0.5, 0.5, 0.25]
)
assert settings.grid_export_rates == [0.25, 0.5, 1.0]
def test_grid_export_rates_default_and_override():
"""None falls back to the defaults; [1.0] restores all-or-nothing export."""
assert BatteriesCommonSettings(device_id="battery1").grid_export_rates == [
0.25,
0.5,
0.75,
1.0,
]
fallback = BatteriesCommonSettings(device_id="battery1", grid_export_rates=None)
assert fallback.grid_export_rates == [0.25, 0.5, 0.75, 1.0]
full_export = BatteriesCommonSettings(device_id="battery1", grid_export_rates=[1.0])
assert full_export.grid_export_rates == [1.0]
@pytest.mark.parametrize("rates", [[0.0, 0.5], [1.5], [-0.25], [], [np.nan], [np.inf], [[0.5]], 0.5])
def test_grid_export_rates_reject_invalid_values(rates):
"""0.0 is not an export level, and rates above the rated power are rejected."""
with pytest.raises(ValidationError):
BatteriesCommonSettings(device_id="battery1", grid_export_rates=rates)
def test_rated_discharge_energy_scales_with_slot_duration(setup_pv_battery):
"""The rate reference is the rated discharge energy of one slot."""
battery = setup_pv_battery
expected = battery.max_charge_power_w * battery.slot_duration_h * battery.discharging_efficiency
assert battery.rated_discharge_energy_wh() == pytest.approx(expected)
def test_pv_converter_preserves_id_lcos_charge_and_export_rates():
settings = BatteriesCommonSettings(
device_id="house",
charge_rates=[0.0, 0.5, 1.0],
grid_export_rates=[1.0, 0.25],
levelized_cost_of_storage_amt_kwh=0.123,
)
assert isinstance(BatteriesCommonSettings.validate_and_sort_charge_rates(None), np.ndarray)
parameters = settings.to_genetic_pv_bat_param()
assert parameters.device_id == "house"
assert parameters.charge_rates == [0.0, 0.5, 1.0]
assert parameters.grid_export_rates == [0.25, 1.0]
assert parameters.levelized_cost_of_storage_kwh == pytest.approx(0.123)
battery = Battery(parameters, prediction_hours=4, slot_duration_h=0.25)
assert battery.levelized_cost_of_storage_kwh == pytest.approx(0.123)
tests/test_cache.py
+49
View File
@@ -88,6 +88,55 @@ class TestCacheUntilUpdateDecorators:
assert CacheEnergyManagementStore.hit_count == 1
assert result1 == result2
@pytest.mark.parametrize("reverse", [False, True])
@pytest.mark.parametrize("use_kwargs", [False, True])
def test_methods_with_identical_arguments_keep_separate_results(
self, cache_energy_management_store, reverse, use_kwargs
):
calls = []
class Model:
@cache_energy_management
def fraction(self, value):
calls.append("fraction")
return value / 1000
@cache_energy_management
def energy(self, value):
calls.append("energy")
return value * 1000
model = Model()
cases = [(model.fraction, 0.005), (model.energy, 5000)]
if reverse:
cases.reverse()
for _ in range(2):
for method, expected in cases:
result = method(value=5) if use_kwargs else method(5)
assert result == expected
assert sorted(calls) == ["energy", "fraction"]
assert CacheEnergyManagementStore.miss_count == 2
assert CacheEnergyManagementStore.hit_count == 2
def test_distinct_closures_with_same_name_do_not_share_results(
self, cache_energy_management_store
):
def make_function(factor):
@cache_energy_management
def compute(value):
return value * factor
return compute
double = make_function(2)
triple = make_function(3)
assert double.__qualname__ == triple.__qualname__
assert double(4) == 8
assert triple(4) == 12
assert double(4) == 8
assert triple(4) == 12
assert CacheEnergyManagementStore.miss_count == 2
assert CacheEnergyManagementStore.hit_count == 2
def test_cache_energy_management(self, cache_energy_management_store):
"""Test that cache_energy_management caches function results."""
tests/test_geneticoptimize.py
+24 -8
View File
@@ -4,6 +4,7 @@ from pathlib import Path
from typing import Any
from unittest.mock import patch
import numpy as np
import pytest
from pydantic import ValidationError
from pypdf import PdfReader
@@ -140,14 +141,29 @@ async def test_optimize(
f"cp {TESTDATA_FILE} {solution_file}\n"
)
assert genetic_solution.result.Gesamtbilanz_Euro == pytest.approx(
expected_result.result.Gesamtbilanz_Euro
)
# Assert that the output contains all expected entries.
# This does not assert that the optimization always gives the same result!
# Reproducibility and mathematical accuracy should be tested on the level of individual components.
compare_dict(genetic_solution.model_dump(), expected_result.model_dump())
# Keep the output contract, but do not demand an identical stochastic
# schedule or monetary golden from the previous direct-consumption model.
assert set(genetic_solution.model_dump()) == set(expected_result.model_dump())
result = genetic_solution.result
expected_slots = len(input_data.ems.pv_forecast_wh) - fixed_start_hour
assert len(result.grid_consumption_wh_per_hour) == expected_slots
assert len(result.grid_feed_in_wh_per_hour) == expected_slots
prices = np.asarray(genetic_solution.parameters.ems.electricity_price_per_wh)[fixed_start_hour:]
tariffs = np.asarray(genetic_solution.parameters.ems.feed_in_tariff_per_wh)
if tariffs.ndim > 0:
tariffs = tariffs[fixed_start_hour:]
expected_costs = np.asarray(result.grid_consumption_wh_per_hour) * prices
expected_revenues = np.asarray(result.grid_feed_in_wh_per_hour) * tariffs
np.testing.assert_allclose(result.costs_per_hour, expected_costs)
np.testing.assert_allclose(result.revenue_per_hour, expected_revenues)
assert result.total_costs == pytest.approx(sum(expected_costs))
assert result.total_revenue == pytest.approx(sum(expected_revenues))
assert result.total_balance == pytest.approx(sum(expected_costs) - sum(expected_revenues))
assert result.total_losses == pytest.approx(sum(result.losses_per_hour))
assert all(value >= 0 for value in result.grid_consumption_wh_per_hour)
assert all(value >= 0 for value in result.grid_feed_in_wh_per_hour)
assert all(0 <= value <= 100 for value in result.battery_soc_per_hour)
assert all(0 <= value <= 100 for value in result.ev_soc_per_hour)
# Check the correct generic optimization solution is created
optimization_solution = await genetic_solution.optimization_solution()
tests/test_geneticsimulation.py
+7 -12
View File
@@ -334,18 +334,13 @@ def test_simulation(genetic_simulation):
"The value at index 1 of 'Netzbezug_Wh_pro_Stunde' should be 1527.13."
)
# Verify the total balance
assert abs(result["Gesamtbilanz_Euro"] - 6.612835813556755) < 1e-5, (
"Total balance should be 6.612835813556755."
)
# Check total revenue and total costs
assert abs(result["Gesamteinnahmen_Euro"] - 1.964301131937134) < 1e-5, (
"Total revenue should be 1.964301131937134."
)
assert abs(result["Gesamtkosten_Euro"] - 8.577136945493889) < 1e-5, (
"Total costs should be 8.577136945493889 ."
)
# Reprice the physical grid flows independently. The new direct-use
# probability model changes the old aggregate monetary golden values.
costs = np.dot(result["Netzbezug_Wh_pro_Stunde"], simulation.elect_price_hourly[start_hour:])
revenues = np.dot(result["Netzeinspeisung_Wh_pro_Stunde"], simulation.elect_revenue_per_hour_arr[start_hour:])
assert result["Gesamtkosten_Euro"] == pytest.approx(costs)
assert result["Gesamteinnahmen_Euro"] == pytest.approx(revenues)
assert result["Gesamtbilanz_Euro"] == pytest.approx(costs - revenues)
# Check the losses
assert abs(result["Gesamt_Verluste"] - 1620.0) < 1e-5, (
tests/test_interpolator.py
+105
View File
@@ -0,0 +1,105 @@
import numpy as np
import pytest
from akkudoktoreos.prediction.interpolator import get_eos_load_interpolator
def test_quarter_hour_energy_is_converted_back_to_same_mean_power():
"""Splitting hourly energy must not change the minute-load probability lookup."""
interpolator = get_eos_load_interpolator()
hourly_load_wh = 800.0
hourly_pv_wh = 1200.0
slot_duration_h = 0.25
hourly = interpolator.calculate_expected_direct_consumption(hourly_load_wh, hourly_pv_wh)
quarter_hour = interpolator.calculate_expected_direct_consumption(
(hourly_load_wh / 4) / slot_duration_h,
(hourly_pv_wh / 4) / slot_duration_h,
)
assert quarter_hour == pytest.approx(hourly)
def test_load_above_probability_grid_uses_highest_supported_distribution():
"""Out-of-range household load must not make self-consumption jump to zero."""
interpolator = get_eos_load_interpolator()
at_boundary = interpolator.calculate_self_consumption(3450.0, 5000.0)
above_boundary = interpolator.calculate_self_consumption(4000.0, 5000.0)
assert above_boundary == pytest.approx(at_boundary)
assert above_boundary > 0.99
def test_expected_direct_consumption_accounts_for_subhourly_load_variation():
"""Expected overlap must be below the optimistic overlap of interval means."""
interpolator = get_eos_load_interpolator()
direct_power_w = interpolator.calculate_expected_direct_consumption(800.0, 1200.0)
assert direct_power_w == pytest.approx(621.0, abs=2.0)
assert 0.0 < direct_power_w < 800.0
@pytest.mark.parametrize(
("mean_load_power_w", "pv_power_w"),
[(800.0, 1200.0), (1000.0, 500.0), (1500.0, 1500.0)],
)
def test_expected_direct_consumption_produces_conservative_energy_balance(
mean_load_power_w, pv_power_w
):
"""Direct use, residual load and surplus must conserve both mean powers."""
interpolator = get_eos_load_interpolator()
direct_power_w = interpolator.calculate_expected_direct_consumption(
mean_load_power_w, pv_power_w
)
residual_load_w = mean_load_power_w - direct_power_w
pv_surplus_w = pv_power_w - direct_power_w
assert 0.0 <= direct_power_w <= min(mean_load_power_w, pv_power_w)
assert direct_power_w + residual_load_w == pytest.approx(mean_load_power_w)
assert direct_power_w + pv_surplus_w == pytest.approx(pv_power_w)
def test_expected_direct_consumption_preserves_forecast_mean_at_high_pv():
"""A PV level above every normalized load bin covers the complete mean load."""
interpolator = get_eos_load_interpolator()
direct_power_w = interpolator.calculate_expected_direct_consumption(3000.0, 10000.0)
assert direct_power_w == pytest.approx(3000.0)
@pytest.mark.parametrize("load,pv", [(4000.0, 5000.0), (10000.0, 20000.0), (0.0, 0.0)])
def test_genetic_interpolator_boundaries_are_finite_and_physical(load, pv):
interpolator = get_eos_load_interpolator()
fraction = interpolator.calculate_self_consumption(load, pv)
direct = interpolator.calculate_expected_direct_consumption(load, pv)
assert np.isfinite(fraction)
assert 0.0 <= fraction <= 1.0
assert np.isfinite(direct)
assert 0.0 <= direct <= min(load, pv)
def test_genetic0_inverter_keeps_its_independent_interpolator():
from akkudoktoreos.devices.genetic0.genetic0inverter import (
Genetic0Inverter,
Genetic0InverterParameters,
)
from akkudoktoreos.optimization.genetic0.genetic0loadinterpolator import (
get_genetic0_load_interpolator,
)
inverter = Genetic0Inverter(Genetic0InverterParameters(device_id="legacy", max_power_wh=10000))
assert inverter.self_consumption_predictor is get_genetic0_load_interpolator()
assert inverter.self_consumption_predictor is not get_eos_load_interpolator()
@pytest.mark.parametrize("load,pv", [(4000.0, 5000.0), (10000.0, 20000.0)])
def test_genetic_inverter_boundary_flows_remain_nonnegative(load, pv):
from akkudoktoreos.devices.genetic.inverter import Inverter, InverterParameters
inverter = Inverter(InverterParameters(device_id="boundary", max_power_wh=25000))
flows = inverter.process_energy(generation=pv, consumption=load, hour=0)
assert all(np.isfinite(value) and value >= 0.0 for value in flows)
tests/test_inverter.py
+177 -28
View File
@@ -1,7 +1,12 @@
from unittest.mock import Mock, patch
from unittest.mock import Mock, call, patch
import numpy as np
import pytest
from akkudoktoreos.devices.genetic.battery import (
Battery,
SolarPanelBatteryParameters,
)
from akkudoktoreos.devices.genetic.inverter import Inverter, InverterParameters
@@ -10,6 +15,9 @@ def mock_battery() -> Mock:
mock_battery = Mock()
mock_battery.charge_energy = Mock(return_value=(0.0, 0.0))
mock_battery.discharge_energy = Mock(return_value=(0.0, 0.0))
# Rated discharge energy of one slot - the reference a grid-export rate is
# applied to. Large enough to never bind at the default factor of 1.0.
mock_battery.rated_discharge_energy_wh = Mock(return_value=1e9)
mock_battery.parameters.device_id = "battery1"
return mock_battery
@@ -17,7 +25,7 @@ def mock_battery() -> Mock:
@pytest.fixture
def inverter(mock_battery) -> Inverter:
mock_self_consumption_predictor = Mock()
mock_self_consumption_predictor.calculate_self_consumption.return_value = 1.0
mock_self_consumption_predictor.calculate_expected_direct_consumption.side_effect = min
with patch(
"akkudoktoreos.devices.genetic.inverter.get_eos_load_interpolator",
return_value=mock_self_consumption_predictor,
@@ -26,11 +34,51 @@ def inverter(mock_battery) -> Inverter:
InverterParameters(
device_id="iv1", max_power_wh=500.0, battery_id=mock_battery.parameters.device_id
),
battery = mock_battery
battery=mock_battery,
)
return iv
def test_quarter_hour_load_and_grid_export_share_discharge_power_limit():
"""Local supply plus direct export may not exceed one slot's battery budget."""
battery = Battery(
SolarPanelBatteryParameters(
device_id="battery",
capacity_wh=10000,
charging_efficiency=1.0,
discharging_efficiency=1.0,
max_charge_power_w=7000,
initial_soc_percentage=100,
),
prediction_hours=1,
slot_duration_h=0.25,
)
battery.set_discharge_per_hour(np.array([1]))
quarter_hour_inverter = Inverter(
InverterParameters(
device_id="inverter",
max_power_wh=10000,
battery_id="battery",
dc_to_ac_efficiency=1.0,
ac_to_dc_efficiency=1.0,
),
battery=battery,
slot_duration_h=0.25,
)
initial_soc_wh = battery.soc_wh
grid_export, grid_import, _, _ = quarter_hour_inverter.process_energy(
generation=0.0,
consumption=1000.0,
hour=0,
allow_battery_grid_export=True,
)
assert grid_import == 0.0
assert grid_export == pytest.approx(750.0)
assert initial_soc_wh - battery.soc_wh == pytest.approx(1750.0)
def test_process_energy_excess_generation(inverter, mock_battery):
# Battery charges 100 Wh with 10 Wh loss
mock_battery.charge_energy.return_value = (100.0, 10.0)
@@ -48,7 +96,7 @@ def test_process_energy_excess_generation(inverter, mock_battery):
assert self_consumption == 200.0 # All consumption is met
mock_battery.charge_energy.assert_called_once_with(400.0, hour)
mock_battery.discharge_energy.assert_not_called()
inverter.self_consumption_predictor.calculate_self_consumption.assert_called_once_with(
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_called_once_with(
consumption, generation
)
@@ -57,7 +105,8 @@ def test_process_energy_excess_generation_interpolator(inverter, mock_battery):
# Battery charges 100 Wh with 10 Wh loss
mock_battery.charge_energy.return_value = (100.0, 10.0)
mock_battery.discharge_energy.return_value = (20.0, 2.0)
inverter.self_consumption_predictor.calculate_self_consumption.return_value = 0.95
inverter.self_consumption_predictor.calculate_expected_direct_consumption.side_effect = None
inverter.self_consumption_predictor.calculate_expected_direct_consumption.return_value = 180.0
generation = 600.0
consumption = 200.0
@@ -67,19 +116,71 @@ def test_process_energy_excess_generation_interpolator(inverter, mock_battery):
generation, consumption, hour
)
assert grid_export == pytest.approx(
270.0, rel=1e-2
) # 290 Wh feed-in - 5% of generation-consumption self consumption after battery charges
assert grid_export == pytest.approx(300.0, rel=1e-2)
assert grid_import == pytest.approx(0.0, rel=1e-2) # No grid draw
assert losses == 12.0 # Battery charging losses
assert self_consumption == 220.0 # All consumption is met
mock_battery.charge_energy.assert_called_once_with(pytest.approx(380.0, rel=1e-2), hour)
assert losses == 22.0 # Battery/inverter losses plus curtailed PV
assert self_consumption == 200.0 # 180 Wh direct PV + 20 Wh battery
mock_battery.charge_energy.assert_called_once_with(pytest.approx(420.0, rel=1e-2), hour)
mock_battery.discharge_energy.assert_called_once_with(pytest.approx(20.0, rel=1e-2), hour)
inverter.self_consumption_predictor.calculate_self_consumption.assert_called_once_with(
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_called_once_with(
consumption, generation
)
def test_probabilistic_bypass_conserves_energy_without_battery():
predictor = Mock()
predictor.calculate_expected_direct_consumption.return_value = 150.0
with patch(
"akkudoktoreos.devices.genetic.inverter.get_eos_load_interpolator",
return_value=predictor,
):
inverter_without_battery = Inverter(
InverterParameters(device_id="inverter", max_power_wh=1000.0)
)
generation = 600.0
consumption = 200.0
grid_export, grid_import, losses, self_consumption = (
inverter_without_battery.process_energy(generation, consumption, hour=0)
)
assert self_consumption == pytest.approx(150.0)
assert grid_import == pytest.approx(50.0)
assert grid_export == pytest.approx(450.0)
assert losses == 0.0
assert generation + grid_import == pytest.approx(
consumption + grid_export + losses
)
def test_probabilistic_bypass_conserves_energy_on_quarter_hour_grid():
predictor = Mock()
predictor.calculate_expected_direct_consumption.return_value = 600.0
with patch(
"akkudoktoreos.devices.genetic.inverter.get_eos_load_interpolator",
return_value=predictor,
):
inverter_without_battery = Inverter(
InverterParameters(device_id="inverter", max_power_wh=2000.0),
slot_duration_h=0.25,
)
generation = 300.0 # 1200 W over 15 minutes
consumption = 200.0 # 800 W over 15 minutes
grid_export, grid_import, losses, self_consumption = (
inverter_without_battery.process_energy(generation, consumption, hour=0)
)
predictor.calculate_expected_direct_consumption.assert_called_once_with(800.0, 1200.0)
assert self_consumption == pytest.approx(150.0)
assert grid_import == pytest.approx(50.0)
assert grid_export == pytest.approx(150.0)
assert losses == 0.0
assert generation + grid_import == pytest.approx(
consumption + grid_export + losses
)
def test_process_energy_generation_equals_consumption(inverter, mock_battery):
generation = 300.0
consumption = 300.0
@@ -96,7 +197,7 @@ def test_process_energy_generation_equals_consumption(inverter, mock_battery):
mock_battery.charge_energy.assert_not_called()
mock_battery.discharge_energy.assert_not_called()
inverter.self_consumption_predictor.calculate_self_consumption.assert_called_once_with(
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_called_once_with(
consumption, generation
)
@@ -120,7 +221,49 @@ def test_process_energy_battery_discharges(inverter, mock_battery):
assert self_consumption == 200.0 # Generation + battery discharge
mock_battery.charge_energy.assert_not_called()
mock_battery.discharge_energy.assert_called_once_with(150.0, hour)
inverter.self_consumption_predictor.calculate_self_consumption.assert_not_called()
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_called_once_with(
consumption, generation
)
def test_process_energy_allows_battery_grid_export(inverter, mock_battery):
mock_battery.max_charge_power_w = 300.0
mock_battery.remaining_discharge_energy_wh.return_value = 200.0
mock_battery.discharge_energy.side_effect = [(100.0, 0.0), (200.0, 0.0)]
grid_export, grid_import, losses, self_consumption = inverter.process_energy(
generation=0.0,
consumption=100.0,
hour=12,
allow_battery_grid_export=True,
)
assert grid_export == pytest.approx(200.0, rel=1e-2)
assert grid_import == 0.0
assert losses == 0.0
assert self_consumption == 100.0
mock_battery.discharge_energy.assert_has_calls([call(100.0, 12), call(200.0, 12)])
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_not_called()
def test_process_energy_grid_export_rate_limits_export(inverter, mock_battery):
"""An export rate caps the export at that share of the rated discharge power."""
mock_battery.max_charge_power_w = 300.0
mock_battery.remaining_discharge_energy_wh.return_value = 200.0
mock_battery.rated_discharge_energy_wh.return_value = 300.0
mock_battery.discharge_energy.side_effect = [(100.0, 0.0), (150.0, 0.0)]
grid_export, grid_import, losses, self_consumption = inverter.process_energy(
generation=0.0,
consumption=100.0,
hour=12,
allow_battery_grid_export=True,
battery_grid_export_factor=0.5,
)
# 0.5 * 300 Wh rated = 150 Wh, below the 200 Wh the battery could still give.
assert grid_export == pytest.approx(150.0)
mock_battery.discharge_energy.assert_has_calls([call(100.0, 12), call(150.0, 12)])
def test_process_energy_battery_empty(inverter, mock_battery):
@@ -140,7 +283,9 @@ def test_process_energy_battery_empty(inverter, mock_battery):
assert self_consumption == 100.0 # Only generation is consumed
mock_battery.charge_energy.assert_not_called()
mock_battery.discharge_energy.assert_called_once_with(200.0, hour)
inverter.self_consumption_predictor.calculate_self_consumption.assert_not_called()
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_called_once_with(
consumption, generation
)
def test_process_energy_battery_full_at_start(inverter, mock_battery):
@@ -162,7 +307,7 @@ def test_process_energy_battery_full_at_start(inverter, mock_battery):
assert self_consumption == 200.0 # Only consumption is met
mock_battery.charge_energy.assert_called_once_with(300.0, hour)
mock_battery.discharge_energy.assert_not_called()
inverter.self_consumption_predictor.calculate_self_consumption.assert_called_once_with(
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_called_once_with(
consumption, generation
)
@@ -184,7 +329,9 @@ def test_process_energy_insufficient_generation_no_battery(inverter, mock_batter
assert self_consumption == 100.0 # Only generation is consumed
mock_battery.charge_energy.assert_not_called()
mock_battery.discharge_energy.assert_called_once_with(400.0, hour)
inverter.self_consumption_predictor.calculate_self_consumption.assert_not_called()
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_called_once_with(
consumption, generation
)
def test_process_energy_insufficient_generation_battery_assists(inverter, mock_battery):
@@ -209,7 +356,9 @@ def test_process_energy_insufficient_generation_battery_assists(inverter, mock_b
assert self_consumption == 250.0 # Generation + battery discharge
mock_battery.charge_energy.assert_not_called()
mock_battery.discharge_energy.assert_called_once_with(200.0, hour)
inverter.self_consumption_predictor.calculate_self_consumption.assert_not_called()
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_called_once_with(
consumption, generation
)
def test_process_energy_zero_generation(inverter, mock_battery):
@@ -232,7 +381,7 @@ def test_process_energy_zero_generation(inverter, mock_battery):
assert self_consumption == 100.0 # Only battery discharge is consumed
mock_battery.charge_energy.assert_not_called()
mock_battery.discharge_energy.assert_called_once_with(300.0, hour)
inverter.self_consumption_predictor.calculate_self_consumption.assert_not_called()
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_not_called()
def test_process_energy_zero_consumption(inverter, mock_battery):
@@ -252,9 +401,7 @@ def test_process_energy_zero_consumption(inverter, mock_battery):
assert self_consumption == 0.0 # Zero consumption
mock_battery.charge_energy.assert_called_once_with(500.0, hour)
mock_battery.discharge_energy.assert_not_called()
inverter.self_consumption_predictor.calculate_self_consumption.assert_called_once_with(
consumption, generation
)
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_not_called()
def test_process_energy_zero_generation_zero_consumption(inverter, mock_battery):
@@ -272,9 +419,7 @@ def test_process_energy_zero_generation_zero_consumption(inverter, mock_battery)
assert self_consumption == 0.0 # No consumption
mock_battery.charge_energy.assert_not_called()
mock_battery.discharge_energy.assert_not_called()
inverter.self_consumption_predictor.calculate_self_consumption.assert_called_once_with(
consumption, generation
)
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_not_called()
def test_process_energy_partial_battery_discharge(inverter, mock_battery):
@@ -295,7 +440,9 @@ def test_process_energy_partial_battery_discharge(inverter, mock_battery):
assert self_consumption == 250.0 # Generation + battery discharge
mock_battery.charge_energy.assert_not_called()
mock_battery.discharge_energy.assert_called_once_with(200.0, 12)
inverter.self_consumption_predictor.calculate_self_consumption.assert_not_called()
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_called_once_with(
consumption, generation
)
def test_process_energy_consumption_exceeds_max_no_battery(inverter, mock_battery):
@@ -315,7 +462,9 @@ def test_process_energy_consumption_exceeds_max_no_battery(inverter, mock_batter
assert self_consumption == 100.0 # Only the generation is consumed, maxing out the inverter
mock_battery.charge_energy.assert_not_called()
mock_battery.discharge_energy.assert_called_once_with(400.0, hour)
inverter.self_consumption_predictor.calculate_self_consumption.assert_not_called()
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_called_once_with(
consumption, generation
)
def test_process_energy_zero_generation_full_battery_high_consumption(inverter, mock_battery):
@@ -337,4 +486,4 @@ def test_process_energy_zero_generation_full_battery_high_consumption(inverter,
assert self_consumption == 500.0 # Battery fully discharges to meet consumption
mock_battery.charge_energy.assert_not_called()
mock_battery.discharge_energy.assert_called_once_with(500.0, hour)
inverter.self_consumption_predictor.calculate_self_consumption.assert_not_called()
inverter.self_consumption_predictor.calculate_expected_direct_consumption.assert_not_called()
tests/test_inverter_efficiency.py
+18 -14
View File
@@ -21,10 +21,7 @@ from akkudoktoreos.devices.genetic.battery import (
Battery,
SolarPanelBatteryParameters,
)
from akkudoktoreos.devices.genetic.inverter import (
Inverter,
InverterParameters,
)
from akkudoktoreos.devices.genetic.inverter import Inverter, InverterParameters
# ---------------------------------------------------------------------------
# Helpers / Fixtures
@@ -40,7 +37,7 @@ def _make_inverter(
) -> Inverter:
"""Create an Inverter with custom efficiency parameters and a mock battery."""
mock_self_consumption_predictor = Mock()
mock_self_consumption_predictor.calculate_self_consumption.return_value = 1.0
mock_self_consumption_predictor.calculate_expected_direct_consumption.side_effect = min
params = InverterParameters(
device_id="inv1",
@@ -167,12 +164,14 @@ class TestDcToAcEfficiency:
assert losses == pytest.approx(10.0, rel=1e-5) # Only battery losses
def test_discharge_surplus_path_with_efficiency(self, mock_battery):
"""When generation > consumption but SCR < 1, discharge goes through inverter."""
mock_battery.discharge_energy.return_value = (50.0, 5.0)
"""A probabilistic load gap discharges through the inverter."""
mock_battery.discharge_energy.return_value = (30.0 / 0.90, 5.0)
mock_battery.charge_energy.return_value = (100.0, 10.0)
inv = _make_inverter(dc_to_ac_efficiency=0.90, mock_battery=mock_battery)
cast(Mock, inv.self_consumption_predictor).calculate_self_consumption.return_value = 0.90
predictor = cast(Mock, inv.self_consumption_predictor)
predictor.calculate_expected_direct_consumption.side_effect = None
predictor.calculate_expected_direct_consumption.return_value = 170.0
generation = 500.0
consumption = 200.0
@@ -182,18 +181,23 @@ class TestDcToAcEfficiency:
generation, consumption, hour
)
# surplus = 300, remaining_power = 300*0.9 = 270, remaining_load_evq = 300*0.1 = 30
# DC request for discharge = 30 / 0.90 = 33.333
# Expected direct PV is 170 Wh, leaving 30 Wh of load gap and
# 330 Wh of PV surplus within different sub-periods of the slot.
# DC request for discharge = 30 / 0.90 = 33.333 Wh.
expected_dc_request = 30.0 / 0.90
mock_battery.discharge_energy.assert_called_once_with(
pytest.approx(expected_dc_request, rel=1e-3), hour
)
# Battery delivers 50 Wh DC → 45 Wh AC
from_battery_ac = 50.0 * 0.90 # 45 Wh
inverter_discharge_loss = 50.0 - from_battery_ac # 5 Wh
# Battery delivers 33.333 Wh DC -> 30 Wh AC.
from_battery_dc = 30.0 / 0.90
from_battery_ac = from_battery_dc * 0.90
inverter_discharge_loss = from_battery_dc - from_battery_ac
assert self_consumption == pytest.approx(consumption + from_battery_ac, rel=1e-5)
assert self_consumption == pytest.approx(170.0 + from_battery_ac, rel=1e-5)
assert grid_import == pytest.approx(0.0)
assert grid_export == pytest.approx(220.0)
assert losses == pytest.approx(5.0 + inverter_discharge_loss + 10.0)
# ===================================================================