mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2026-11-13 01:03:45 +01:00
feat(devices): add inverter profiles
An inverter profile describes the technical data of an inverter model: its nominal AC power, the DC→AC and AC→DC efficiency curves over the load fraction (AC power relative to the nominal power), the AC charge power limit of the model, whether that limit also limits PV charging, and an optional power derating over the ambient temperature. Curves are read linearly and clamped at their ends, so every lookup yields a value. The packaged profile generic-hybrid has typical hybrid inverter efficiencies, no nominal power (the inverter device has to provide it) and full power up to 45 degC. Inverter settings name their profile (inverter_profile, default generic-hybrid) and hold the differences of the unit in profile_adjustment: nominal_power_w (replaces the profile value, required for a generic profile), max_power_w and max_ac_charge_power_w (installation limits that can only lower; an AC charge limit of 0 disables AC charging). The effective parameters are resolved at the ambient temperature of the inverter, given by the new measurement key <device_id>-temperature-degc (45 degC without a fresh value); the power derating lowers the maximum power and the AC charge limit. Optimization parameters are always valid: the GENETIC and GENETIC0 parameter preparation resolve the inverter with resolve_current_operating_parameters_or_defaults, which never raises. An unusable profile gives the generic-hybrid profile, a missing nominal power the fallback of 10000 W, an inverter derated to zero power the parameters at 45 degC, and no usable profile at all the profile adjustment with constant efficiency; each is logged as error. The GENETIC inverter takes the AC→DC efficiency curve of the profile, solved exactly on each linear piece of the curve (about 2 % longer runs); GENETIC0 keeps constant efficiencies and no longer replaces the configured inverters with the demo inverter; a battery, electric vehicle or inverter that cannot be prepared is left out of the GENETIC0 run, never replaced by a demo device. Configurations migrate: max_power_w becomes profile_adjustment.nominal_power_w, max_ac_charge_power_w moves into the adjustment, an ac_to_dc_efficiency of 0 keeps AC charging disabled, and the efficiency fields are dropped with an error log, as for batteries, so the profile efficiencies apply. Home Assistant config paths follow. Additional changes - Move the curve algorithms of the battery profile into profilecurve, so battery and inverter profiles share them; the battery profile keeps its document format and classes. - Move ProfileBaseModel, the strict base of profile documents, into profilestore. - Serve inverter profiles through the profile REST API. Refuse to delete a profile that a configured device uses and that has no packaged profile to revert to (409). - Share the measurement access of the device settings in devicemeasurement. - Rename check_battery_profiles to check_device_profiles; the device profile check at configuration setup covers inverters, too. - Document inverter profiles, their configuration, defaults and sharing; regenerate the configuration and OpenAPI documentation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Assisted-by: Claude Code (claude-opus-5-5)
This commit is contained in:
Bobby Noelte
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
e255f987bf
commit
faf37abfe7
@@ -1,6 +1,6 @@
|
||||
# Akkudoktor-EOS
|
||||
|
||||
**Version**: `v0.3.0.dev2611111415621708`
|
||||
**Version**: `v0.3.0.dev2611111434732824`
|
||||
|
||||
<!-- 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.
|
||||
@@ -2165,7 +2165,8 @@ Delete Profile
|
||||
Delete a user profile.
|
||||
|
||||
Returns the profile that applies now (the packaged one of the same name),
|
||||
or null if there is none.
|
||||
or null if there is none. A profile that a configured device uses can only
|
||||
be deleted if a packaged profile of the same name applies afterwards.
|
||||
"""
|
||||
```
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
@@ -282,62 +282,68 @@ that is configured, even if more devices are configured.
|
||||
{
|
||||
"devices": {
|
||||
"max_inverters": 1,
|
||||
"inverters": [
|
||||
{
|
||||
"device_id": "inv1",
|
||||
"max_power_w": 10000,
|
||||
"battery_id": "bat1",
|
||||
"ac_to_dc_efficiency": 0.95,
|
||||
"dc_to_ac_efficiency": 0.95,
|
||||
"max_ac_charge_power_w": 5000
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The inverter supports separate AC↔DC conversion efficiencies:
|
||||
|
||||
- `ac_to_dc_efficiency`: Conversion loss when charging the battery from AC grid power (0-1).
|
||||
Set to `0` to disable AC charging. Default `1.0`.
|
||||
- `dc_to_ac_efficiency`: Conversion loss when discharging battery to AC load/grid (0-1).
|
||||
Must be > 0. Default `1.0`.
|
||||
- `max_ac_charge_power_w`: Maximum AC charging power in watts. `null` = no additional limit.
|
||||
Set to `0` to disable AC charging. Default `null`.
|
||||
- `dc_to_ac_efficiency_curve`: Optional load-dependent DC→AC efficiency as a list of
|
||||
`[load_fraction, efficiency]` points, with the load fraction relative to `max_power_w`.
|
||||
Real inverters are much less efficient at low load, e.g. when the battery serves a small
|
||||
night-time base load. The points must be strictly increasing in load fraction (0-1) with
|
||||
efficiencies in (0, 1]; values in between are interpolated linearly, values outside are
|
||||
clamped to the first/last point. When set, the curve replaces `dc_to_ac_efficiency` for
|
||||
battery discharge. The efficiency is always the one at the AC power that is delivered: if
|
||||
the battery limits a discharge (low state of charge or its power limit), the conversion is
|
||||
evaluated at that lower load, not at the requested one. Default `null` (constant
|
||||
`dc_to_ac_efficiency`, unchanged behaviour).
|
||||
- `dc_to_ac_efficiency_reference_load_fraction`: Load fraction at which the curve is evaluated
|
||||
where stored energy is valued without a specific discharge, e.g. the energy left in the
|
||||
battery at the end of the horizon and the AC charge break-even. Choose the typical load
|
||||
the battery serves. Only used with `dc_to_ac_efficiency_curve`. Default `0.06`.
|
||||
|
||||
**Example with an efficiency curve:**
|
||||
|
||||
```json
|
||||
{
|
||||
"devices": {
|
||||
"inverters": {
|
||||
"inv1": {
|
||||
"max_power_w": 10000,
|
||||
"battery_id": "bat1",
|
||||
"dc_to_ac_efficiency_curve": [
|
||||
[0.02, 0.80], [0.07, 0.93], [0.30, 0.96], [1.00, 0.95]
|
||||
],
|
||||
"dc_to_ac_efficiency_reference_load_fraction": 0.06
|
||||
"inverter_profile": "generic-hybrid",
|
||||
"profile_adjustment": {
|
||||
"nominal_power_w": 10000,
|
||||
"max_ac_charge_power_w": 5000
|
||||
},
|
||||
"battery_id": "bat1"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The technical data of the inverter comes from an **inverter profile** (see
|
||||
[](#inverter-profiles)): the efficiency curves for battery discharge (DC→AC) and for charging
|
||||
the battery from the grid (AC→DC), the AC charge power limit of the model and the power derating
|
||||
over the ambient temperature. The inverter settings select the profile and describe how the unit
|
||||
differs from it:
|
||||
|
||||
- `inverter_profile`: Name of the inverter profile. Default `generic-hybrid`.
|
||||
- `profile_adjustment.nominal_power_w`: Nominal AC power of the installed inverter [W]. Replaces
|
||||
the nominal power of the profile; required for a generic profile such as `generic-hybrid`.
|
||||
- `profile_adjustment.max_power_w`: AC power limit of the installation [W], e.g. a configured
|
||||
output limit. Can only lower the (derated) nominal power. Default `null`.
|
||||
- `profile_adjustment.max_ac_charge_power_w`: AC charge power limit of the installation [W]. Can
|
||||
only lower the limit of the profile. Set to `0` to disable AC charging. Default `null`.
|
||||
- `dc_to_ac_efficiency_reference_load_fraction`: Load fraction of the maximum power at which the
|
||||
DC→AC efficiency curve is evaluated where stored energy is valued without a specific discharge,
|
||||
e.g. the energy left in the battery at the end of the horizon and the AC charge break-even.
|
||||
Choose the typical load the battery serves. Default `0.06`.
|
||||
|
||||
The efficiency curves are over the load fraction, the AC power relative to the nominal power.
|
||||
Real inverters are much less efficient at low load, e.g. when the battery serves a small
|
||||
night-time base load. The efficiency is always the one at the AC power of the conversion: if the
|
||||
battery limits a discharge (low state of charge or its power limit), the conversion is evaluated
|
||||
at that lower load, not at the requested one; charging from the grid draws the AC energy at the
|
||||
efficiency of the AC load actually drawn.
|
||||
|
||||
**Power derating:** inverters reduce their power when they get hot. EOS reads the ambient
|
||||
temperature of the inverter from the measurement `<device_id>-temperature-degc` (e.g.
|
||||
`inv1-temperature-degc`) at the start of each optimization and limits the maximum power and the
|
||||
AC charge power by the derating of the profile at that temperature. Without a measurement in the
|
||||
last hour EOS assumes 45 °C, where the `generic-hybrid` profile is not derated yet.
|
||||
|
||||
The resolved values are shown as read-only fields of the inverter configuration
|
||||
(`effective_nominal_power_w`, `effective_max_power_w`, `effective_max_ac_charge_power_w`,
|
||||
`effective_dc_to_ac_efficiency`, `effective_ac_to_dc_efficiency`), evaluated at 45 °C. If the
|
||||
configured inverter profile does not exist or is invalid, the optimization uses `generic-hybrid`
|
||||
with the profile adjustment instead and logs an error naming the inverter.
|
||||
|
||||
:::{admonition} Note
|
||||
:class: note
|
||||
Configurations of earlier versions are migrated automatically. `max_power_w` becomes
|
||||
`profile_adjustment.nominal_power_w` and `max_ac_charge_power_w` moves into the profile
|
||||
adjustment; an `ac_to_dc_efficiency` of `0` keeps AC charging disabled. The former fields
|
||||
`ac_to_dc_efficiency`, `dc_to_ac_efficiency`, `dc_to_ac_efficiency_curve` and
|
||||
`ac_charge_limits_total_charge` come from the inverter profile now and are dropped (logged as
|
||||
error), so the efficiencies of the profile apply instead of the former default `1.0` (lossless).
|
||||
To keep other values, save an own inverter profile and select it.
|
||||
:::
|
||||
|
||||
#### Electric vehicle simulation configuration
|
||||
|
||||
**Example:**
|
||||
|
||||
@@ -221,20 +221,20 @@ Profiles can be managed with the REST API:
|
||||
|
||||
| **Endpoint** | **Description** |
|
||||
| -------------------------------------- | ---------------------------------------------------------------- |
|
||||
| **GET** `/v1/profile` | List the profile kinds (e.g. `battery`). |
|
||||
| **GET** `/v1/profile` | List the profile kinds (`battery`, `inverter`). |
|
||||
| **GET** `/v1/profile/{kind}` | List the user and packaged profiles of a kind. |
|
||||
| **GET** `/v1/profile/{kind}/schema` | JSON schema of the profile documents of a kind. |
|
||||
| **GET** `/v1/profile/{kind}/{name}` | Get a profile document. |
|
||||
| **PUT** `/v1/profile/{kind}/{name}` | Validate a profile document and save it as user profile. |
|
||||
| **DELETE** `/v1/profile/{kind}/{name}` | Delete a user profile. Returns the profile that applies instead. |
|
||||
|
||||
The **Profiles** page of EOSdash edits battery profiles as JSON and plots the limit maps and
|
||||
efficiency curves as EOS evaluates them. Edits can be previewed before they are saved.
|
||||
The **Profiles** page of EOSdash edits battery and inverter profiles as JSON and plots them as EOS
|
||||
evaluates them: for a battery the limit maps and efficiency curves, for an inverter the efficiency
|
||||
curves and the power derating. Edits can be previewed before they are saved.
|
||||
|
||||
To share a profile with other users, open it on the **Profiles** page and press **Share on
|
||||
GitHub**. It opens a new issue with the battery profile form in your browser, filled in with the
|
||||
profile; check it and submit it. EOS sends nothing itself. Reviewed profiles are packaged with
|
||||
EOS.
|
||||
To share a profile with other users, open it on the **Profiles** page and press **Share**. It
|
||||
opens a new issue with the battery or inverter profile form in your browser, filled in with the
|
||||
profile; check it and submit it. EOS sends nothing itself. Reviewed profiles are packaged with EOS.
|
||||
|
||||
### Battery Stati
|
||||
|
||||
@@ -324,6 +324,61 @@ The **operation mode factor** (0.0–1.0) specifies the normalized power rate re
|
||||
battery's nominal maximum charge power. A value of 1.0 corresponds to full-rate charging, while 0.0
|
||||
indicates no power transfer. Intermediate values scale the power proportionally.
|
||||
|
||||
## Inverter
|
||||
|
||||
The inverter connects the DC side (PV, battery) with the AC side (household, grid). Its
|
||||
configuration (`devices/inverters/<device_id>`) is described in the automatic optimization, see
|
||||
the inverter simulation configuration there.
|
||||
|
||||
(inverter-profiles)=
|
||||
|
||||
### Inverter Profiles
|
||||
|
||||
The technical data of an inverter comes from an **inverter profile**, a JSON document with:
|
||||
|
||||
- the DC→AC efficiency curve (battery discharge) and the AC→DC efficiency curve (charging the
|
||||
battery from the grid) over the load fraction, the AC power relative to the nominal power,
|
||||
- the nominal AC power, except for a generic profile,
|
||||
- optionally the AC charge power limit of the model (`max_ac_charge_power_w`) and whether this
|
||||
limit also limits PV charging of the battery (`ac_charge_limits_total_charge`, e.g. some hybrid
|
||||
inverters in time-of-use grid charging),
|
||||
- optionally the power derating over the ambient temperature (`power_derating`: the allowed
|
||||
fraction of the nominal power at each temperature).
|
||||
|
||||
The curves are read linearly between their breakpoints and held at their end values beyond them.
|
||||
Unknown keys are rejected.
|
||||
|
||||
```json
|
||||
{
|
||||
"inverter_model": "My hybrid inverter",
|
||||
"nominal_power_w": 10000,
|
||||
"dc_to_ac_efficiency": {
|
||||
"load_fraction": [0.05, 0.2, 0.5, 1.0],
|
||||
"efficiency": [0.88, 0.955, 0.97, 0.965]
|
||||
},
|
||||
"ac_to_dc_efficiency": {
|
||||
"load_fraction": [0.05, 0.2, 0.5, 1.0],
|
||||
"efficiency": [0.86, 0.95, 0.965, 0.96]
|
||||
},
|
||||
"power_derating": {
|
||||
"temperature_degC": [45.0, 60.0],
|
||||
"power_fraction": [1.0, 0.6]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
EOS ships the profile `generic-hybrid` with typical efficiencies of a hybrid inverter, no nominal
|
||||
power (set `profile_adjustment.nominal_power_w`) and full power up to 45 °C. EOS evaluates the
|
||||
derating at the ambient temperature measured as `<device_id>-temperature-degc`, or at 45 °C
|
||||
without a measurement. Inverter profiles are stored, looked up and managed like battery profiles
|
||||
(kind `inverter`, user directory `<general/data_folder_path>/profile/inverter/`), with the same
|
||||
REST API and the **Profiles** page of EOSdash.
|
||||
|
||||
The optimization always gets valid inverter parameters. If they cannot be resolved, EOS logs an
|
||||
error and uses defaults: the profile `generic-hybrid` for an unusable profile, a nominal power of
|
||||
10000 W if none is set, and the parameters at 45 °C if the inverter is derated to zero power at
|
||||
the measured temperature.
|
||||
|
||||
## Home Appliance
|
||||
|
||||
The optimization algorithm supports one start of the home appliance within the optimization
|
||||
|
||||
Reference in New Issue
Block a user