mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2025-10-29 05:46:20 +00:00
b397b5d43e
This fix implements the long term goal to have the EOS server run optimization (or
energy management) on regular intervals automatically. Thus clients can request
the current energy management plan at any time and it is updated on regular
intervals without interaction by the client.
This fix started out to "only" make automatic optimization (or energy management)
runs working. It turned out there are several endpoints that in some way
update predictions or run the optimization. To lock against such concurrent attempts
the code had to be refactored to allow control of execution. During refactoring it
became clear that some classes and files are named without a proper reference
to their usage. Thus not only refactoring but also renaming became necessary.
The names are still not the best, but I hope they are more intuitive.
The fix includes several bug fixes that are not directly related to the automatic optimization
but are necessary to keep EOS running properly to do the automatic optimization and
to test and document the changes.
This is a breaking change as the configuration structure changed once again and
the server API was also enhanced and streamlined. The server API that is used by
Andreas and Jörg in their videos has not changed.
* fix: automatic optimization
Allow optimization to automatically run on configured intervals gathering all
optimization parameters from configuration and predictions. The automatic run
can be configured to only run prediction updates skipping the optimization.
Extend documentaion to also cover automatic optimization. Lock automatic runs
against runs initiated by the /optimize or other endpoints. Provide new
endpoints to retrieve the energy management plan and the genetic solution
of the latest automatic optimization run. Offload energy management to thread
pool executor to keep the app more responsive during the CPU heavy optimization
run.
* fix: EOS servers recognize environment variables on startup
Force initialisation of EOS configuration on server startup to assure
all sources of EOS configuration are properly set up and read. Adapt
server tests and configuration tests to also test for environment
variable configuration.
* fix: Remove 0.0.0.0 to localhost translation under Windows
EOS imposed a 0.0.0.0 to localhost translation under Windows for
convenience. This caused some trouble in user configurations. Now, as the
default IP address configuration is 127.0.0.1, the user is responsible
for to set up the correct Windows compliant IP address.
* fix: allow names for hosts additional to IP addresses
* fix: access pydantic model fields by class
Access by instance is deprecated.
* fix: down sampling key_to_array
* fix: make cache clear endpoint clear all cache files
Make /v1/admin/cache/clear clear all cache files. Before it only cleared
expired cache files by default. Add new endpoint /v1/admin/clear-expired
to only clear expired cache files.
* fix: timezonefinder returns Europe/Paris instead of Europe/Berlin
timezonefinder 8.10 got more inaccurate for timezones in europe as there is
a common timezone. Use new package tzfpy instead which is still returning
Europe/Berlin if you are in Germany. tzfpy also claims to be faster than
timezonefinder.
* fix: provider settings configuration
Provider configuration used to be a union holding the settings for several
providers. Pydantic union handling does not always find the correct type
for a provider setting. This led to exceptions in specific configurations.
Now provider settings are explicit comfiguration items for each possible
provider. This is a breaking change as the configuration structure was
changed.
* fix: ClearOutside weather prediction irradiance calculation
Pvlib needs a pandas time index. Convert time index.
* fix: test config file priority
Do not use config_eos fixture as this fixture already creates a config file.
* fix: optimization sample request documentation
Provide all data in documentation of optimization sample request.
* fix: gitlint blocking pip dependency resolution
Replace gitlint by commitizen. Gitlint is not actively maintained anymore.
Gitlint dependencies blocked pip from dependency resolution.
* fix: sync pre-commit config to actual dependency requirements
.pre-commit-config.yaml was out of sync, also requirements-dev.txt.
* fix: missing babel in requirements.txt
Add babel to requirements.txt
* feat: setup default device configuration for automatic optimization
In case the parameters for automatic optimization are not fully defined a
default configuration is setup to allow the automatic energy management
run. The default configuration may help the user to correctly define
the device configuration.
* feat: allow configuration of genetic algorithm parameters
The genetic algorithm parameters for number of individuals, number of
generations, the seed and penalty function parameters are now avaliable
as configuration options.
* feat: allow configuration of home appliance time windows
The time windows a home appliance is allowed to run are now configurable
by the configuration (for /v1 API) and also by the home appliance parameters
(for the classic /optimize API). If there is no such configuration the
time window defaults to optimization hours, which was the standard before
the change. Documentation on how to configure time windows is added.
* feat: standardize mesaurement keys for battery/ ev SoC measurements
The standardized measurement keys to report battery SoC to the device
simulations can now be retrieved from the device configuration as a
read-only config option.
* feat: feed in tariff prediction
Add feed in tarif predictions needed for automatic optimization. The feed in
tariff can be retrieved as fixed feed in tarif or can be imported. Also add
tests for the different feed in tariff providers. Extend documentation to
cover the feed in tariff providers.
* feat: add energy management plan based on S2 standard instructions
EOS can generate an energy management plan as a list of simple instructions.
May be retrieved by the /v1/energy-management/plan endpoint. The instructions
loosely follow the S2 energy management standard.
* feat: make measurement keys configurable by EOS configuration.
The fixed measurement keys are replaced by configurable measurement keys.
* feat: make pendulum DateTime, Date, Duration types usable for pydantic models
Use pydantic_extra_types.pendulum_dt to get pydantic pendulum types. Types are
added to the datetimeutil utility. Remove custom made pendulum adaptations
from EOS pydantic module. Make EOS modules use the pydantic pendulum types
managed by the datetimeutil module instead of the core pendulum types.
* feat: Add Time, TimeWindow, TimeWindowSequence and to_time to datetimeutil.
The time windows are are added to support home appliance time window
configuration. All time classes are also pydantic models. Time is the base
class for time definition derived from pendulum.Time.
* feat: Extend DataRecord by configurable field like data.
Configurable field like data was added to support the configuration of
measurement records.
* feat: Add additional information to health information
Version information is added to the health endpoints of eos and eosDash.
The start time of the last optimization and the latest run time of the energy
management is added to the EOS health information.
* feat: add pydantic merge model tests
* feat: add plan tab to EOSdash
The plan tab displays the current energy management instructions.
* feat: add predictions tab to EOSdash
The predictions tab displays the current predictions.
* feat: add cache management to EOSdash admin tab
The admin tab is extended by a section for cache management. It allows to
clear the cache.
* feat: add about tab to EOSdash
The about tab resembles the former hello tab and provides extra information.
* feat: Adapt changelog and prepare for release management
Release management using commitizen is added. The changelog file is adapted and
teh changelog and a description for release management is added in the
documentation.
* feat(doc): Improve install and devlopment documentation
Provide a more concise installation description in Readme.md and add extra
installation page and development page to documentation.
* chore: Use memory cache for interpolation instead of dict in inverter
Decorate calculate_self_consumption() with @cachemethod_until_update to cache
results in memory during an energy management/ optimization run. Replacement
of dict type caching in inverter is now possible because all optimization
runs are properly locked and the memory cache CacheUntilUpdateStore is properly
cleared at the start of any energy management/ optimization operation.
* chore: refactor genetic
Refactor the genetic algorithm modules for enhanced module structure and better
readability. Removed unnecessary and overcomplex devices singleton. Also
split devices configuration from genetic algorithm parameters to allow further
development independently from genetic algorithm parameter format. Move
charge rates configuration for electric vehicles from optimization to devices
configuration to allow to have different charge rates for different cars in
the future.
* chore: Rename memory cache to CacheEnergyManagementStore
The name better resembles the task of the cache to chache function and method
results for an energy management run. Also the decorator functions are renamed
accordingly: cachemethod_energy_management, cache_energy_management
* chore: use class properties for config/ems/prediction mixin classes
* chore: skip debug logs from mathplotlib
Mathplotlib is very noisy in debug mode.
* chore: automatically sync bokeh js to bokeh python package
bokeh was updated to 3.8.0, make JS CDN automatically follow the package version.
* chore: rename hello.py to about.py
Make hello.py the adapted EOSdash about page.
* chore: remove demo page from EOSdash
As no the plan and prediction pages are working without configuration, the demo
page is no longer necessary
* chore: split test_server.py for system test
Split test_server.py to create explicit test_system.py for system tests.
* chore: move doc utils to generate_config_md.py
The doc utils are only used in scripts/generate_config_md.py. Move it there to
attribute for strong cohesion.
* chore: improve pydantic merge model documentation
* chore: remove pendulum warning from readme
* chore: remove GitHub discussions from contributing documentation
Github discussions is to be replaced by Akkudoktor.net.
* chore(release): bump version to 0.1.0+dev for development
* build(deps): bump fastapi[standard] from 0.115.14 to 0.117.1
bump fastapi and make coverage version (for pytest-cov) explicit to avoid pip break.
* build(deps): bump uvicorn from 0.36.0 to 0.37.0
BREAKING CHANGE: EOS configuration changed. V1 API changed.
- The available_charge_rates_percent configuration is removed from optimization.
Use the new charge_rate configuration for the electric vehicle
- Optimization configuration parameter hours renamed to horizon_hours
- Device configuration now has to provide the number of devices and device
properties per device.
- Specific prediction provider configuration to be provided by explicit
configuration item (no union for all providers).
- Measurement keys to be provided as a list.
- New feed in tariff providers have to be configured.
- /v1/measurement/loadxxx endpoints are removed. Use generic mesaurement endpoints.
- /v1/admin/cache/clear now clears all cache files. Use
/v1/admin/cache/clear-expired to only clear all expired cache files.
Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
67 KiB
67 KiB
Configuration Table
Settings for common configuration
General configuration to set directories of cache and output files and system location (latitude
and longitude).
Validators ensure each parameter is within a specified range. A computed property, timezone,
determines the time zone based on latitude and longitude.
Attributes: latitude (Optional[float]): Latitude in degrees, must be between -90 and 90. longitude (Optional[float]): Longitude in degrees, must be between -180 and 180.
Properties: timezone (Optional[str]): Computed time zone string based on the specified latitude and longitude.
:::{table} general :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| version | EOS_GENERAL__VERSION |
str |
rw |
0.1.0+dev |
Configuration file version. Used to check compatibility. |
| data_folder_path | EOS_GENERAL__DATA_FOLDER_PATH |
Optional[pathlib.Path] |
rw |
None |
Path to EOS data directory. |
| data_output_subpath | EOS_GENERAL__DATA_OUTPUT_SUBPATH |
Optional[pathlib.Path] |
rw |
output |
Sub-path for the EOS output data directory. |
| latitude | EOS_GENERAL__LATITUDE |
Optional[float] |
rw |
52.52 |
Latitude in decimal degrees, between -90 and 90, north is positive (ISO 19115) (°) |
| longitude | EOS_GENERAL__LONGITUDE |
Optional[float] |
rw |
13.405 |
Longitude in decimal degrees, within -180 to 180 (°) |
| timezone | Optional[str] |
ro |
N/A |
Compute timezone based on latitude and longitude. | |
| data_output_path | Optional[pathlib.Path] |
ro |
N/A |
Compute data_output_path based on data_folder_path. | |
| config_folder_path | Optional[pathlib.Path] |
ro |
N/A |
Path to EOS configuration directory. | |
| config_file_path | Optional[pathlib.Path] |
ro |
N/A |
Path to EOS configuration file. | |
| ::: |
Example Input
.. code-block:: json
{
"general": {
"version": "0.1.0+dev",
"data_folder_path": null,
"data_output_subpath": "output",
"latitude": 52.52,
"longitude": 13.405
}
}
Example Output
.. code-block:: json
{
"general": {
"version": "0.1.0+dev",
"data_folder_path": null,
"data_output_subpath": "output",
"latitude": 52.52,
"longitude": 13.405,
"timezone": "Europe/Berlin",
"data_output_path": null,
"config_folder_path": "/home/user/.config/net.akkudoktoreos.net",
"config_file_path": "/home/user/.config/net.akkudoktoreos.net/EOS.config.json"
}
}
Cache Configuration
:::{table} cache :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| subpath | EOS_CACHE__SUBPATH |
Optional[pathlib.Path] |
rw |
cache |
Sub-path for the EOS cache data directory. |
| cleanup_interval | EOS_CACHE__CLEANUP_INTERVAL |
float |
rw |
300 |
Intervall in seconds for EOS file cache cleanup. |
| ::: |
Example Input/Output
.. code-block:: json
{
"cache": {
"subpath": "cache",
"cleanup_interval": 300.0
}
}
Energy Management Configuration
:::{table} ems :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| startup_delay | EOS_EMS__STARTUP_DELAY |
float |
rw |
5 |
Startup delay in seconds for EOS energy management runs. |
| interval | EOS_EMS__INTERVAL |
Optional[float] |
rw |
None |
Intervall in seconds between EOS energy management runs. |
| mode | EOS_EMS__MODE |
Optional[akkudoktoreos.core.emsettings.EnergyManagementMode] |
rw |
None |
Energy management mode [OPTIMIZATION |
| ::: |
Example Input/Output
.. code-block:: json
{
"ems": {
"startup_delay": 5.0,
"interval": 300.0,
"mode": "OPTIMIZATION"
}
}
Logging Configuration
:::{table} logging :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| console_level | EOS_LOGGING__CONSOLE_LEVEL |
Optional[str] |
rw |
None |
Logging level when logging to console. |
| file_level | EOS_LOGGING__FILE_LEVEL |
Optional[str] |
rw |
None |
Logging level when logging to file. |
| file_path | Optional[pathlib.Path] |
ro |
N/A |
Computed log file path based on data output path. | |
| ::: |
Example Input
.. code-block:: json
{
"logging": {
"console_level": "TRACE",
"file_level": "TRACE"
}
}
Example Output
.. code-block:: json
{
"logging": {
"console_level": "TRACE",
"file_level": "TRACE",
"file_path": "/home/user/.local/share/net.akkudoktoreos.net/output/eos.log"
}
}
Base configuration for devices simulation settings
:::{table} devices :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| batteries | EOS_DEVICES__BATTERIES |
Optional[list[akkudoktoreos.devices.devices.BatteriesCommonSettings]] |
rw |
None |
List of battery devices |
| max_batteries | EOS_DEVICES__MAX_BATTERIES |
Optional[int] |
rw |
None |
Maximum number of batteries that can be set |
| electric_vehicles | EOS_DEVICES__ELECTRIC_VEHICLES |
Optional[list[akkudoktoreos.devices.devices.BatteriesCommonSettings]] |
rw |
None |
List of electric vehicle devices |
| max_electric_vehicles | EOS_DEVICES__MAX_ELECTRIC_VEHICLES |
Optional[int] |
rw |
None |
Maximum number of electric vehicles that can be set |
| inverters | EOS_DEVICES__INVERTERS |
Optional[list[akkudoktoreos.devices.devices.InverterCommonSettings]] |
rw |
None |
List of inverters |
| max_inverters | EOS_DEVICES__MAX_INVERTERS |
Optional[int] |
rw |
None |
Maximum number of inverters that can be set |
| home_appliances | EOS_DEVICES__HOME_APPLIANCES |
Optional[list[akkudoktoreos.devices.devices.HomeApplianceCommonSettings]] |
rw |
None |
List of home appliances |
| max_home_appliances | EOS_DEVICES__MAX_HOME_APPLIANCES |
Optional[int] |
rw |
None |
Maximum number of home_appliances that can be set |
| measurement_keys | Optional[list[str]] |
ro |
N/A |
Return the measurement keys for the resource/ device stati that are measurements. | |
| ::: |
Example Input
.. code-block:: json
{
"devices": {
"batteries": [
{
"device_id": "battery1",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.0,
"max_charge_power_w": 5000,
"min_charge_power_w": 50,
"charge_rates": null,
"min_soc_percentage": 0,
"max_soc_percentage": 100,
"measurement_key_soc_factor": "battery1-soc-factor",
"measurement_key_power_l1_w": "battery1-power-l1-w",
"measurement_key_power_l2_w": "battery1-power-l2-w",
"measurement_key_power_l3_w": "battery1-power-l3-w",
"measurement_key_power_3_phase_sym_w": "battery1-power-3-phase-sym-w",
"measurement_keys": [
"battery1-soc-factor",
"battery1-power-l1-w",
"battery1-power-l2-w",
"battery1-power-l3-w",
"battery1-power-3-phase-sym-w"
]
}
],
"max_batteries": 1,
"electric_vehicles": [
{
"device_id": "battery1",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.0,
"max_charge_power_w": 5000,
"min_charge_power_w": 50,
"charge_rates": null,
"min_soc_percentage": 0,
"max_soc_percentage": 100,
"measurement_key_soc_factor": "battery1-soc-factor",
"measurement_key_power_l1_w": "battery1-power-l1-w",
"measurement_key_power_l2_w": "battery1-power-l2-w",
"measurement_key_power_l3_w": "battery1-power-l3-w",
"measurement_key_power_3_phase_sym_w": "battery1-power-3-phase-sym-w",
"measurement_keys": [
"battery1-soc-factor",
"battery1-power-l1-w",
"battery1-power-l2-w",
"battery1-power-l3-w",
"battery1-power-3-phase-sym-w"
]
}
],
"max_electric_vehicles": 1,
"inverters": [],
"max_inverters": 1,
"home_appliances": [],
"max_home_appliances": 1
}
}
Example Output
.. code-block:: json
{
"devices": {
"batteries": [
{
"device_id": "battery1",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.0,
"max_charge_power_w": 5000,
"min_charge_power_w": 50,
"charge_rates": null,
"min_soc_percentage": 0,
"max_soc_percentage": 100,
"measurement_key_soc_factor": "battery1-soc-factor",
"measurement_key_power_l1_w": "battery1-power-l1-w",
"measurement_key_power_l2_w": "battery1-power-l2-w",
"measurement_key_power_l3_w": "battery1-power-l3-w",
"measurement_key_power_3_phase_sym_w": "battery1-power-3-phase-sym-w",
"measurement_keys": [
"battery1-soc-factor",
"battery1-power-l1-w",
"battery1-power-l2-w",
"battery1-power-l3-w",
"battery1-power-3-phase-sym-w"
]
}
],
"max_batteries": 1,
"electric_vehicles": [
{
"device_id": "battery1",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.0,
"max_charge_power_w": 5000,
"min_charge_power_w": 50,
"charge_rates": null,
"min_soc_percentage": 0,
"max_soc_percentage": 100,
"measurement_key_soc_factor": "battery1-soc-factor",
"measurement_key_power_l1_w": "battery1-power-l1-w",
"measurement_key_power_l2_w": "battery1-power-l2-w",
"measurement_key_power_l3_w": "battery1-power-l3-w",
"measurement_key_power_3_phase_sym_w": "battery1-power-3-phase-sym-w",
"measurement_keys": [
"battery1-soc-factor",
"battery1-power-l1-w",
"battery1-power-l2-w",
"battery1-power-l3-w",
"battery1-power-3-phase-sym-w"
]
}
],
"max_electric_vehicles": 1,
"inverters": [],
"max_inverters": 1,
"home_appliances": [],
"max_home_appliances": 1,
"measurement_keys": [
"battery1-soc-factor",
"battery1-power-l1-w",
"battery1-power-l2-w",
"battery1-power-l3-w",
"battery1-power-3-phase-sym-w",
"battery1-soc-factor",
"battery1-power-l1-w",
"battery1-power-l2-w",
"battery1-power-l3-w",
"battery1-power-3-phase-sym-w"
]
}
}
Home Appliance devices base settings
:::{table} devices::home_appliances::list :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| device_id | str |
rw |
<unknown> |
ID of device |
| consumption_wh | int |
rw |
required |
Energy consumption [Wh]. |
| duration_h | int |
rw |
required |
Usage duration in hours [0 ... 24]. |
| time_windows | Optional[akkudoktoreos.utils.datetimeutil.TimeWindowSequence] |
rw |
None |
Sequence of allowed time windows. Defaults to optimization general time window. |
| measurement_keys | Optional[list[str]] |
ro |
N/A |
Measurement keys for the home appliance stati that are measurements. |
| ::: |
Example Input
.. code-block:: json
{
"devices": {
"home_appliances": [
{
"device_id": "battery1",
"consumption_wh": 2000,
"duration_h": 1,
"time_windows": {
"windows": [
{
"start_time": "10:00:00.000000 Europe/Berlin",
"duration": "2 hours",
"day_of_week": null,
"date": null,
"locale": null
}
]
}
},
{
"device_id": "ev1",
"consumption_wh": 2000,
"duration_h": 1,
"time_windows": {
"windows": [
{
"start_time": "10:00:00.000000 Europe/Berlin",
"duration": "2 hours",
"day_of_week": null,
"date": null,
"locale": null
}
]
}
},
{
"device_id": "inverter1",
"consumption_wh": 2000,
"duration_h": 1,
"time_windows": {
"windows": [
{
"start_time": "10:00:00.000000 Europe/Berlin",
"duration": "2 hours",
"day_of_week": null,
"date": null,
"locale": null
}
]
}
},
{
"device_id": "dishwasher",
"consumption_wh": 2000,
"duration_h": 1,
"time_windows": {
"windows": [
{
"start_time": "10:00:00.000000 Europe/Berlin",
"duration": "2 hours",
"day_of_week": null,
"date": null,
"locale": null
}
]
}
}
]
}
}
Example Output
.. code-block:: json
{
"devices": {
"home_appliances": [
{
"device_id": "battery1",
"consumption_wh": 2000,
"duration_h": 1,
"time_windows": {
"windows": [
{
"start_time": "10:00:00.000000 Europe/Berlin",
"duration": "2 hours",
"day_of_week": null,
"date": null,
"locale": null
}
]
},
"measurement_keys": []
},
{
"device_id": "ev1",
"consumption_wh": 2000,
"duration_h": 1,
"time_windows": {
"windows": [
{
"start_time": "10:00:00.000000 Europe/Berlin",
"duration": "2 hours",
"day_of_week": null,
"date": null,
"locale": null
}
]
},
"measurement_keys": []
},
{
"device_id": "inverter1",
"consumption_wh": 2000,
"duration_h": 1,
"time_windows": {
"windows": [
{
"start_time": "10:00:00.000000 Europe/Berlin",
"duration": "2 hours",
"day_of_week": null,
"date": null,
"locale": null
}
]
},
"measurement_keys": []
},
{
"device_id": "dishwasher",
"consumption_wh": 2000,
"duration_h": 1,
"time_windows": {
"windows": [
{
"start_time": "10:00:00.000000 Europe/Berlin",
"duration": "2 hours",
"day_of_week": null,
"date": null,
"locale": null
}
]
},
"measurement_keys": []
}
]
}
}
Inverter devices base settings
:::{table} devices::inverters::list :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| device_id | str |
rw |
<unknown> |
ID of device |
| max_power_w | Optional[float] |
rw |
None |
Maximum power [W]. |
| battery_id | Optional[str] |
rw |
None |
ID of battery controlled by this inverter. |
| measurement_keys | Optional[list[str]] |
ro |
N/A |
Measurement keys for the inverter stati that are measurements. |
| ::: |
Example Input
.. code-block:: json
{
"devices": {
"inverters": [
{
"device_id": "battery1",
"max_power_w": 10000.0,
"battery_id": null
},
{
"device_id": "ev1",
"max_power_w": 10000.0,
"battery_id": "battery1"
},
{
"device_id": "inverter1",
"max_power_w": 10000.0,
"battery_id": "battery1"
},
{
"device_id": "dishwasher",
"max_power_w": 10000.0,
"battery_id": "battery1"
}
]
}
}
Example Output
.. code-block:: json
{
"devices": {
"inverters": [
{
"device_id": "battery1",
"max_power_w": 10000.0,
"battery_id": null,
"measurement_keys": []
},
{
"device_id": "ev1",
"max_power_w": 10000.0,
"battery_id": "battery1",
"measurement_keys": []
},
{
"device_id": "inverter1",
"max_power_w": 10000.0,
"battery_id": "battery1",
"measurement_keys": []
},
{
"device_id": "dishwasher",
"max_power_w": 10000.0,
"battery_id": "battery1",
"measurement_keys": []
}
]
}
}
Battery devices base settings
:::{table} devices::batteries::list :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| device_id | str |
rw |
<unknown> |
ID of device |
| capacity_wh | int |
rw |
8000 |
Capacity [Wh]. |
| charging_efficiency | float |
rw |
0.88 |
Charging efficiency [0.01 ... 1.00]. |
| discharging_efficiency | float |
rw |
0.88 |
Discharge efficiency [0.01 ... 1.00]. |
| levelized_cost_of_storage_kwh | float |
rw |
0.0 |
Levelized cost of storage (LCOS), the average lifetime cost of delivering one kWh [€/kWh]. |
| max_charge_power_w | Optional[float] |
rw |
5000 |
Maximum charging power [W]. |
| min_charge_power_w | Optional[float] |
rw |
50 |
Minimum charging power [W]. |
| charge_rates | Optional[list[float]] |
rw |
None |
Charge rates as factor of maximum charging power [0.00 ... 1.00]. None denotes all charge rates are available. |
| min_soc_percentage | int |
rw |
0 |
Minimum state of charge (SOC) as percentage of capacity [%]. |
| max_soc_percentage | int |
rw |
100 |
Maximum state of charge (SOC) as percentage of capacity [%]. |
| measurement_key_soc_factor | str |
ro |
N/A |
Measurement key for the battery state of charge (SoC) as factor of total capacity [0.0 ... 1.0]. |
| measurement_key_power_l1_w | str |
ro |
N/A |
Measurement key for the L1 power the battery is charged or discharged with [W]. |
| measurement_key_power_l2_w | str |
ro |
N/A |
Measurement key for the L2 power the battery is charged or discharged with [W]. |
| measurement_key_power_l3_w | str |
ro |
N/A |
Measurement key for the L3 power the battery is charged or discharged with [W]. |
| measurement_key_power_3_phase_sym_w | str |
ro |
N/A |
Measurement key for the symmetric 3 phase power the battery is charged or discharged with [W]. |
| measurement_keys | Optional[list[str]] |
ro |
N/A |
Measurement keys for the battery stati that are measurements. |
Battery SoC, power. | :::
Example Input
.. code-block:: json
{
"devices": {
"batteries": [
{
"device_id": "battery1",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.12,
"max_charge_power_w": 5000.0,
"min_charge_power_w": 50.0,
"charge_rates": [
0.0,
0.25,
0.5,
0.75,
1.0
],
"min_soc_percentage": 10,
"max_soc_percentage": 100
},
{
"device_id": "ev1",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.12,
"max_charge_power_w": 5000.0,
"min_charge_power_w": 50.0,
"charge_rates": null,
"min_soc_percentage": 10,
"max_soc_percentage": 100
},
{
"device_id": "inverter1",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.12,
"max_charge_power_w": 5000.0,
"min_charge_power_w": 50.0,
"charge_rates": null,
"min_soc_percentage": 10,
"max_soc_percentage": 100
},
{
"device_id": "dishwasher",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.12,
"max_charge_power_w": 5000.0,
"min_charge_power_w": 50.0,
"charge_rates": null,
"min_soc_percentage": 10,
"max_soc_percentage": 100
}
]
}
}
Example Output
.. code-block:: json
{
"devices": {
"batteries": [
{
"device_id": "battery1",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.12,
"max_charge_power_w": 5000.0,
"min_charge_power_w": 50.0,
"charge_rates": [
0.0,
0.25,
0.5,
0.75,
1.0
],
"min_soc_percentage": 10,
"max_soc_percentage": 100,
"measurement_key_soc_factor": "battery1-soc-factor",
"measurement_key_power_l1_w": "battery1-power-l1-w",
"measurement_key_power_l2_w": "battery1-power-l2-w",
"measurement_key_power_l3_w": "battery1-power-l3-w",
"measurement_key_power_3_phase_sym_w": "battery1-power-3-phase-sym-w",
"measurement_keys": [
"battery1-soc-factor",
"battery1-power-l1-w",
"battery1-power-l2-w",
"battery1-power-l3-w",
"battery1-power-3-phase-sym-w"
]
},
{
"device_id": "ev1",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.12,
"max_charge_power_w": 5000.0,
"min_charge_power_w": 50.0,
"charge_rates": null,
"min_soc_percentage": 10,
"max_soc_percentage": 100,
"measurement_key_soc_factor": "ev1-soc-factor",
"measurement_key_power_l1_w": "ev1-power-l1-w",
"measurement_key_power_l2_w": "ev1-power-l2-w",
"measurement_key_power_l3_w": "ev1-power-l3-w",
"measurement_key_power_3_phase_sym_w": "ev1-power-3-phase-sym-w",
"measurement_keys": [
"ev1-soc-factor",
"ev1-power-l1-w",
"ev1-power-l2-w",
"ev1-power-l3-w",
"ev1-power-3-phase-sym-w"
]
},
{
"device_id": "inverter1",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.12,
"max_charge_power_w": 5000.0,
"min_charge_power_w": 50.0,
"charge_rates": null,
"min_soc_percentage": 10,
"max_soc_percentage": 100,
"measurement_key_soc_factor": "inverter1-soc-factor",
"measurement_key_power_l1_w": "inverter1-power-l1-w",
"measurement_key_power_l2_w": "inverter1-power-l2-w",
"measurement_key_power_l3_w": "inverter1-power-l3-w",
"measurement_key_power_3_phase_sym_w": "inverter1-power-3-phase-sym-w",
"measurement_keys": [
"inverter1-soc-factor",
"inverter1-power-l1-w",
"inverter1-power-l2-w",
"inverter1-power-l3-w",
"inverter1-power-3-phase-sym-w"
]
},
{
"device_id": "dishwasher",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.12,
"max_charge_power_w": 5000.0,
"min_charge_power_w": 50.0,
"charge_rates": null,
"min_soc_percentage": 10,
"max_soc_percentage": 100,
"measurement_key_soc_factor": "dishwasher-soc-factor",
"measurement_key_power_l1_w": "dishwasher-power-l1-w",
"measurement_key_power_l2_w": "dishwasher-power-l2-w",
"measurement_key_power_l3_w": "dishwasher-power-l3-w",
"measurement_key_power_3_phase_sym_w": "dishwasher-power-3-phase-sym-w",
"measurement_keys": [
"dishwasher-soc-factor",
"dishwasher-power-l1-w",
"dishwasher-power-l2-w",
"dishwasher-power-l3-w",
"dishwasher-power-3-phase-sym-w"
]
}
]
}
}
Measurement Configuration
:::{table} measurement :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| load_emr_keys | EOS_MEASUREMENT__LOAD_EMR_KEYS |
Optional[list[str]] |
rw |
None |
The keys of the measurements that are energy meter readings of a load [kWh]. |
| grid_export_emr_keys | EOS_MEASUREMENT__GRID_EXPORT_EMR_KEYS |
Optional[list[str]] |
rw |
None |
The keys of the measurements that are energy meter readings of energy export to grid [kWh]. |
| grid_import_emr_keys | EOS_MEASUREMENT__GRID_IMPORT_EMR_KEYS |
Optional[list[str]] |
rw |
None |
The keys of the measurements that are energy meter readings of energy import from grid [kWh]. |
| pv_production_emr_keys | EOS_MEASUREMENT__PV_PRODUCTION_EMR_KEYS |
Optional[list[str]] |
rw |
None |
The keys of the measurements that are PV production energy meter readings [kWh]. |
| keys | list[str] |
ro |
N/A |
The keys of the measurements that can be stored. | |
| ::: |
Example Input
.. code-block:: json
{
"measurement": {
"load_emr_keys": [
"load0_emr"
],
"grid_export_emr_keys": [
"grid_export_emr"
],
"grid_import_emr_keys": [
"grid_import_emr"
],
"pv_production_emr_keys": [
"pv1_emr"
]
}
}
Example Output
.. code-block:: json
{
"measurement": {
"load_emr_keys": [
"load0_emr"
],
"grid_export_emr_keys": [
"grid_export_emr"
],
"grid_import_emr_keys": [
"grid_import_emr"
],
"pv_production_emr_keys": [
"pv1_emr"
],
"keys": [
"grid_export_emr",
"grid_import_emr",
"load0_emr",
"pv1_emr"
]
}
}
General Optimization Configuration
:::{table} optimization :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| horizon_hours | EOS_OPTIMIZATION__HORIZON_HOURS |
Optional[int] |
rw |
24 |
The general time window within which the energy optimization goal shall be achieved [h]. Defaults to 24 hours. |
| interval | EOS_OPTIMIZATION__INTERVAL |
Optional[int] |
rw |
3600 |
The optimization interval [sec]. |
| genetic | EOS_OPTIMIZATION__GENETIC |
Optional[akkudoktoreos.optimization.optimization.GeneticCommonSettings] |
rw |
None |
Genetic optimization algorithm configuration. |
| ::: |
Example Input/Output
.. code-block:: json
{
"optimization": {
"horizon_hours": 24,
"interval": 3600,
"genetic": {
"individuals": 400,
"generations": 400,
"seed": null,
"penalties": {
"ev_soc_miss": 10
}
}
}
}
General Genetic Optimization Algorithm Configuration
:::{table} optimization::genetic :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| individuals | Optional[int] |
rw |
300 |
Number of individuals (solutions) to generate for the (initial) generation [>= 10]. Defaults to 300. |
| generations | Optional[int] |
rw |
400 |
Number of generations to evaluate the optimal solution [>= 10]. Defaults to 400. |
| seed | Optional[int] |
rw |
None |
Fixed seed for genetic algorithm. Defaults to 'None' which means random seed. |
| penalties | Optional[dict[str, Union[float, int, str]]] |
rw |
None |
A dictionary of penalty function parameters consisting of a penalty function parameter name and the associated value. |
| ::: |
Example Input/Output
.. code-block:: json
{
"optimization": {
"genetic": {
"individuals": 300,
"generations": 400,
"seed": null,
"penalties": {
"ev_soc_miss": 10
}
}
}
}
General Prediction Configuration
This class provides configuration for prediction settings, allowing users to specify parameters such as the forecast duration (in hours). Validators ensure each parameter is within a specified range.
Attributes: hours (Optional[int]): Number of hours into the future for predictions. Must be non-negative. historic_hours (Optional[int]): Number of hours into the past for historical data. Must be non-negative.
Validators:
validate_hours (int): Ensures hours is a non-negative integer.
validate_historic_hours (int): Ensures historic_hours is a non-negative integer.
:::{table} prediction :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| hours | EOS_PREDICTION__HOURS |
Optional[int] |
rw |
48 |
Number of hours into the future for predictions |
| historic_hours | EOS_PREDICTION__HISTORIC_HOURS |
Optional[int] |
rw |
48 |
Number of hours into the past for historical predictions data |
| ::: |
Example Input/Output
.. code-block:: json
{
"prediction": {
"hours": 48,
"historic_hours": 48
}
}
Electricity Price Prediction Configuration
:::{table} elecprice :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| provider | EOS_ELECPRICE__PROVIDER |
Optional[str] |
rw |
None |
Electricity price provider id of provider to be used. |
| charges_kwh | EOS_ELECPRICE__CHARGES_KWH |
Optional[float] |
rw |
None |
Electricity price charges [€/kWh]. Will be added to variable market price. |
| vat_rate | EOS_ELECPRICE__VAT_RATE |
Optional[float] |
rw |
1.19 |
VAT rate factor applied to electricity price when charges are used. |
| provider_settings | EOS_ELECPRICE__PROVIDER_SETTINGS |
ElecPriceCommonProviderSettings |
rw |
required |
Provider settings |
| ::: |
Example Input/Output
.. code-block:: json
{
"elecprice": {
"provider": "ElecPriceAkkudoktor",
"charges_kwh": 0.21,
"vat_rate": 1.19,
"provider_settings": {
"ElecPriceImport": null
}
}
}
Common settings for elecprice data import from file or JSON String
:::{table} elecprice::provider_settings::ElecPriceImport :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| import_file_path | Union[str, pathlib.Path, NoneType] |
rw |
None |
Path to the file to import elecprice data from. |
| import_json | Optional[str] |
rw |
None |
JSON string, dictionary of electricity price forecast value lists. |
| ::: |
Example Input/Output
.. code-block:: json
{
"elecprice": {
"provider_settings": {
"ElecPriceImport": {
"import_file_path": null,
"import_json": "{\"elecprice_marketprice_wh\": [0.0003384, 0.0003318, 0.0003284]}"
}
}
}
}
Electricity Price Prediction Provider Configuration
:::{table} elecprice::provider_settings :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| ElecPriceImport | Optional[akkudoktoreos.prediction.elecpriceimport.ElecPriceImportCommonSettings] |
rw |
None |
ElecPriceImport settings |
| ::: |
Example Input/Output
.. code-block:: json
{
"elecprice": {
"provider_settings": {
"ElecPriceImport": null
}
}
}
Feed In Tariff Prediction Configuration
:::{table} feedintariff :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| provider | EOS_FEEDINTARIFF__PROVIDER |
Optional[str] |
rw |
None |
Feed in tariff provider id of provider to be used. |
| provider_settings | EOS_FEEDINTARIFF__PROVIDER_SETTINGS |
FeedInTariffCommonProviderSettings |
rw |
required |
Provider settings |
| ::: |
Example Input/Output
.. code-block:: json
{
"feedintariff": {
"provider": "FeedInTariffFixed",
"provider_settings": {
"FeedInTariffFixed": null,
"FeedInTariffImport": null
}
}
}
Common settings for feed in tariff data import from file or JSON string
:::{table} feedintariff::provider_settings::FeedInTariffImport :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| import_file_path | Union[str, pathlib.Path, NoneType] |
rw |
None |
Path to the file to import feed in tariff data from. |
| import_json | Optional[str] |
rw |
None |
JSON string, dictionary of feed in tariff forecast value lists. |
| ::: |
Example Input/Output
.. code-block:: json
{
"feedintariff": {
"provider_settings": {
"FeedInTariffImport": {
"import_file_path": null,
"import_json": "{\"fead_in_tariff_wh\": [0.000078, 0.000078, 0.000023]}"
}
}
}
}
Common settings for elecprice fixed price
:::{table} feedintariff::provider_settings::FeedInTariffFixed :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| feed_in_tariff_kwh | Optional[float] |
rw |
None |
Electricity price feed in tariff [€/kWH]. |
| ::: |
Example Input/Output
.. code-block:: json
{
"feedintariff": {
"provider_settings": {
"FeedInTariffFixed": {
"feed_in_tariff_kwh": 0.078
}
}
}
}
Feed In Tariff Prediction Provider Configuration
:::{table} feedintariff::provider_settings :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| FeedInTariffFixed | Optional[akkudoktoreos.prediction.feedintarifffixed.FeedInTariffFixedCommonSettings] |
rw |
None |
FeedInTariffFixed settings |
| FeedInTariffImport | Optional[akkudoktoreos.prediction.feedintariffimport.FeedInTariffImportCommonSettings] |
rw |
None |
FeedInTariffImport settings |
| ::: |
Example Input/Output
.. code-block:: json
{
"feedintariff": {
"provider_settings": {
"FeedInTariffFixed": null,
"FeedInTariffImport": null
}
}
}
Load Prediction Configuration
:::{table} load :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| provider | EOS_LOAD__PROVIDER |
Optional[str] |
rw |
None |
Load provider id of provider to be used. |
| provider_settings | EOS_LOAD__PROVIDER_SETTINGS |
LoadCommonProviderSettings |
rw |
required |
Provider settings |
| ::: |
Example Input/Output
.. code-block:: json
{
"load": {
"provider": "LoadAkkudoktor",
"provider_settings": {
"LoadAkkudoktor": null,
"LoadVrm": null,
"LoadImport": null
}
}
}
Common settings for load data import from file or JSON string
:::{table} load::provider_settings::LoadImport :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| import_file_path | Union[str, pathlib.Path, NoneType] |
rw |
None |
Path to the file to import load data from. |
| import_json | Optional[str] |
rw |
None |
JSON string, dictionary of load forecast value lists. |
| ::: |
Example Input/Output
.. code-block:: json
{
"load": {
"provider_settings": {
"LoadImport": {
"import_file_path": null,
"import_json": "{\"load0_mean\": [676.71, 876.19, 527.13]}"
}
}
}
}
Common settings for VRM API
:::{table} load::provider_settings::LoadVrm :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| load_vrm_token | str |
rw |
your-token |
Token for Connecting VRM API |
| load_vrm_idsite | int |
rw |
12345 |
VRM-Installation-ID |
| ::: |
Example Input/Output
.. code-block:: json
{
"load": {
"provider_settings": {
"LoadVrm": {
"load_vrm_token": "your-token",
"load_vrm_idsite": 12345
}
}
}
}
Common settings for load data import from file
:::{table} load::provider_settings::LoadAkkudoktor :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| loadakkudoktor_year_energy | Optional[float] |
rw |
None |
Yearly energy consumption (kWh). |
| ::: |
Example Input/Output
.. code-block:: json
{
"load": {
"provider_settings": {
"LoadAkkudoktor": {
"loadakkudoktor_year_energy": 40421.0
}
}
}
}
Load Prediction Provider Configuration
:::{table} load::provider_settings :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| LoadAkkudoktor | Optional[akkudoktoreos.prediction.loadakkudoktor.LoadAkkudoktorCommonSettings] |
rw |
None |
LoadAkkudoktor settings |
| LoadVrm | Optional[akkudoktoreos.prediction.loadvrm.LoadVrmCommonSettings] |
rw |
None |
LoadVrm settings |
| LoadImport | Optional[akkudoktoreos.prediction.loadimport.LoadImportCommonSettings] |
rw |
None |
LoadImport settings |
| ::: |
Example Input/Output
.. code-block:: json
{
"load": {
"provider_settings": {
"LoadAkkudoktor": null,
"LoadVrm": null,
"LoadImport": null
}
}
}
PV Forecast Configuration
:::{table} pvforecast :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| provider | EOS_PVFORECAST__PROVIDER |
Optional[str] |
rw |
None |
PVForecast provider id of provider to be used. |
| provider_settings | EOS_PVFORECAST__PROVIDER_SETTINGS |
PVForecastCommonProviderSettings |
rw |
required |
Provider settings |
| planes | EOS_PVFORECAST__PLANES |
Optional[list[akkudoktoreos.prediction.pvforecast.PVForecastPlaneSetting]] |
rw |
None |
Plane configuration. |
| max_planes | EOS_PVFORECAST__MAX_PLANES |
Optional[int] |
rw |
0 |
Maximum number of planes that can be set |
| planes_peakpower | List[float] |
ro |
N/A |
Compute a list of the peak power per active planes. | |
| planes_azimuth | List[float] |
ro |
N/A |
Compute a list of the azimuths per active planes. | |
| planes_tilt | List[float] |
ro |
N/A |
Compute a list of the tilts per active planes. | |
| planes_userhorizon | Any |
ro |
N/A |
Compute a list of the user horizon per active planes. | |
| planes_inverter_paco | Any |
ro |
N/A |
Compute a list of the maximum power rating of the inverter per active planes. | |
| ::: |
Example Input
.. code-block:: json
{
"pvforecast": {
"provider": "PVForecastAkkudoktor",
"provider_settings": {
"PVForecastImport": null,
"PVForecastVrm": null
},
"planes": [
{
"surface_tilt": 10.0,
"surface_azimuth": 180.0,
"userhorizon": [
10.0,
20.0,
30.0
],
"peakpower": 5.0,
"pvtechchoice": "crystSi",
"mountingplace": "free",
"loss": 14.0,
"trackingtype": 0,
"optimal_surface_tilt": false,
"optimalangles": false,
"albedo": null,
"module_model": null,
"inverter_model": null,
"inverter_paco": 6000,
"modules_per_string": 20,
"strings_per_inverter": 2
},
{
"surface_tilt": 20.0,
"surface_azimuth": 90.0,
"userhorizon": [
5.0,
15.0,
25.0
],
"peakpower": 3.5,
"pvtechchoice": "crystSi",
"mountingplace": "free",
"loss": 14.0,
"trackingtype": 1,
"optimal_surface_tilt": false,
"optimalangles": false,
"albedo": null,
"module_model": null,
"inverter_model": null,
"inverter_paco": 4000,
"modules_per_string": 20,
"strings_per_inverter": 2
}
],
"max_planes": 1
}
}
Example Output
.. code-block:: json
{
"pvforecast": {
"provider": "PVForecastAkkudoktor",
"provider_settings": {
"PVForecastImport": null,
"PVForecastVrm": null
},
"planes": [
{
"surface_tilt": 10.0,
"surface_azimuth": 180.0,
"userhorizon": [
10.0,
20.0,
30.0
],
"peakpower": 5.0,
"pvtechchoice": "crystSi",
"mountingplace": "free",
"loss": 14.0,
"trackingtype": 0,
"optimal_surface_tilt": false,
"optimalangles": false,
"albedo": null,
"module_model": null,
"inverter_model": null,
"inverter_paco": 6000,
"modules_per_string": 20,
"strings_per_inverter": 2
},
{
"surface_tilt": 20.0,
"surface_azimuth": 90.0,
"userhorizon": [
5.0,
15.0,
25.0
],
"peakpower": 3.5,
"pvtechchoice": "crystSi",
"mountingplace": "free",
"loss": 14.0,
"trackingtype": 1,
"optimal_surface_tilt": false,
"optimalangles": false,
"albedo": null,
"module_model": null,
"inverter_model": null,
"inverter_paco": 4000,
"modules_per_string": 20,
"strings_per_inverter": 2
}
],
"max_planes": 1,
"planes_peakpower": [
5.0,
3.5
],
"planes_azimuth": [
180.0,
90.0
],
"planes_tilt": [
10.0,
20.0
],
"planes_userhorizon": [
[
10.0,
20.0,
30.0
],
[
5.0,
15.0,
25.0
]
],
"planes_inverter_paco": [
6000.0,
4000.0
]
}
}
PV Forecast Plane Configuration
:::{table} pvforecast::planes::list :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| surface_tilt | Optional[float] |
rw |
30.0 |
Tilt angle from horizontal plane. Ignored for two-axis tracking. |
| surface_azimuth | Optional[float] |
rw |
180.0 |
Orientation (azimuth angle) of the (fixed) plane. Clockwise from north (north=0, east=90, south=180, west=270). |
| userhorizon | Optional[List[float]] |
rw |
None |
Elevation of horizon in degrees, at equally spaced azimuth clockwise from north. |
| peakpower | Optional[float] |
rw |
None |
Nominal power of PV system in kW. |
| pvtechchoice | Optional[str] |
rw |
crystSi |
PV technology. One of 'crystSi', 'CIS', 'CdTe', 'Unknown'. |
| mountingplace | Optional[str] |
rw |
free |
Type of mounting for PV system. Options are 'free' for free-standing and 'building' for building-integrated. |
| loss | Optional[float] |
rw |
14.0 |
Sum of PV system losses in percent |
| trackingtype | Optional[int] |
rw |
None |
Type of suntracking. 0=fixed, 1=single horizontal axis aligned north-south, 2=two-axis tracking, 3=vertical axis tracking, 4=single horizontal axis aligned east-west, 5=single inclined axis aligned north-south. |
| optimal_surface_tilt | Optional[bool] |
rw |
False |
Calculate the optimum tilt angle. Ignored for two-axis tracking. |
| optimalangles | Optional[bool] |
rw |
False |
Calculate the optimum tilt and azimuth angles. Ignored for two-axis tracking. |
| albedo | Optional[float] |
rw |
None |
Proportion of the light hitting the ground that it reflects back. |
| module_model | Optional[str] |
rw |
None |
Model of the PV modules of this plane. |
| inverter_model | Optional[str] |
rw |
None |
Model of the inverter of this plane. |
| inverter_paco | Optional[int] |
rw |
None |
AC power rating of the inverter [W]. |
| modules_per_string | Optional[int] |
rw |
None |
Number of the PV modules of the strings of this plane. |
| strings_per_inverter | Optional[int] |
rw |
None |
Number of the strings of the inverter of this plane. |
| ::: |
Example Input/Output
.. code-block:: json
{
"pvforecast": {
"planes": [
{
"surface_tilt": 10.0,
"surface_azimuth": 180.0,
"userhorizon": [
10.0,
20.0,
30.0
],
"peakpower": 5.0,
"pvtechchoice": "crystSi",
"mountingplace": "free",
"loss": 14.0,
"trackingtype": 0,
"optimal_surface_tilt": false,
"optimalangles": false,
"albedo": null,
"module_model": null,
"inverter_model": null,
"inverter_paco": 6000,
"modules_per_string": 20,
"strings_per_inverter": 2
},
{
"surface_tilt": 20.0,
"surface_azimuth": 90.0,
"userhorizon": [
5.0,
15.0,
25.0
],
"peakpower": 3.5,
"pvtechchoice": "crystSi",
"mountingplace": "free",
"loss": 14.0,
"trackingtype": 1,
"optimal_surface_tilt": false,
"optimalangles": false,
"albedo": null,
"module_model": null,
"inverter_model": null,
"inverter_paco": 4000,
"modules_per_string": 20,
"strings_per_inverter": 2
}
]
}
}
Common settings for VRM API
:::{table} pvforecast::provider_settings::PVForecastVrm :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| pvforecast_vrm_token | str |
rw |
your-token |
Token for Connecting VRM API |
| pvforecast_vrm_idsite | int |
rw |
12345 |
VRM-Installation-ID |
| ::: |
Example Input/Output
.. code-block:: json
{
"pvforecast": {
"provider_settings": {
"PVForecastVrm": {
"pvforecast_vrm_token": "your-token",
"pvforecast_vrm_idsite": 12345
}
}
}
}
Common settings for pvforecast data import from file or JSON string
:::{table} pvforecast::provider_settings::PVForecastImport :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| import_file_path | Union[str, pathlib.Path, NoneType] |
rw |
None |
Path to the file to import PV forecast data from. |
| import_json | Optional[str] |
rw |
None |
JSON string, dictionary of PV forecast value lists. |
| ::: |
Example Input/Output
.. code-block:: json
{
"pvforecast": {
"provider_settings": {
"PVForecastImport": {
"import_file_path": null,
"import_json": "{\"pvforecast_ac_power\": [0, 8.05, 352.91]}"
}
}
}
}
PV Forecast Provider Configuration
:::{table} pvforecast::provider_settings :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| PVForecastImport | Optional[akkudoktoreos.prediction.pvforecastimport.PVForecastImportCommonSettings] |
rw |
None |
PVForecastImport settings |
| PVForecastVrm | Optional[akkudoktoreos.prediction.pvforecastvrm.PVForecastVrmCommonSettings] |
rw |
None |
PVForecastVrm settings |
| ::: |
Example Input/Output
.. code-block:: json
{
"pvforecast": {
"provider_settings": {
"PVForecastImport": null,
"PVForecastVrm": null
}
}
}
Weather Forecast Configuration
:::{table} weather :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| provider | EOS_WEATHER__PROVIDER |
Optional[str] |
rw |
None |
Weather provider id of provider to be used. |
| provider_settings | EOS_WEATHER__PROVIDER_SETTINGS |
WeatherCommonProviderSettings |
rw |
required |
Provider settings |
| ::: |
Example Input/Output
.. code-block:: json
{
"weather": {
"provider": "WeatherImport",
"provider_settings": {
"WeatherImport": null
}
}
}
Common settings for weather data import from file or JSON string
:::{table} weather::provider_settings::WeatherImport :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| import_file_path | Union[str, pathlib.Path, NoneType] |
rw |
None |
Path to the file to import weather data from. |
| import_json | Optional[str] |
rw |
None |
JSON string, dictionary of weather forecast value lists. |
| ::: |
Example Input/Output
.. code-block:: json
{
"weather": {
"provider_settings": {
"WeatherImport": {
"import_file_path": null,
"import_json": "{\"weather_temp_air\": [18.3, 17.8, 16.9]}"
}
}
}
}
Weather Forecast Provider Configuration
:::{table} weather::provider_settings :widths: 10 10 5 5 30 :align: left
| Name | Type | Read-Only | Default | Description |
|---|---|---|---|---|
| WeatherImport | Optional[akkudoktoreos.prediction.weatherimport.WeatherImportCommonSettings] |
rw |
None |
WeatherImport settings |
| ::: |
Example Input/Output
.. code-block:: json
{
"weather": {
"provider_settings": {
"WeatherImport": null
}
}
}
Server Configuration
:::{table} server :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| host | EOS_SERVER__HOST |
Optional[str] |
rw |
127.0.0.1 |
EOS server IP address. Defaults to 127.0.0.1. |
| port | EOS_SERVER__PORT |
Optional[int] |
rw |
8503 |
EOS server IP port number. Defaults to 8503. |
| verbose | EOS_SERVER__VERBOSE |
Optional[bool] |
rw |
False |
Enable debug output |
| startup_eosdash | EOS_SERVER__STARTUP_EOSDASH |
Optional[bool] |
rw |
True |
EOS server to start EOSdash server. Defaults to True. |
| eosdash_host | EOS_SERVER__EOSDASH_HOST |
Optional[str] |
rw |
None |
EOSdash server IP address. Defaults to EOS server IP address. |
| eosdash_port | EOS_SERVER__EOSDASH_PORT |
Optional[int] |
rw |
None |
EOSdash server IP port number. Defaults to EOS server IP port number + 1. |
| ::: |
Example Input/Output
.. code-block:: json
{
"server": {
"host": "127.0.0.1",
"port": 8503,
"verbose": false,
"startup_eosdash": true,
"eosdash_host": "127.0.0.1",
"eosdash_port": 8504
}
}
Utils Configuration
:::{table} utils :widths: 10 20 10 5 5 30 :align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
|---|---|---|---|---|---|
| ::: |
Example Input/Output
.. code-block:: json
{
"utils": {}
}
Full example Config
.. code-block:: json
{
"general": {
"version": "0.1.0+dev",
"data_folder_path": null,
"data_output_subpath": "output",
"latitude": 52.52,
"longitude": 13.405
},
"cache": {
"subpath": "cache",
"cleanup_interval": 300.0
},
"ems": {
"startup_delay": 5.0,
"interval": 300.0,
"mode": "OPTIMIZATION"
},
"logging": {
"console_level": "TRACE",
"file_level": "TRACE"
},
"devices": {
"batteries": [
{
"device_id": "battery1",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.0,
"max_charge_power_w": 5000,
"min_charge_power_w": 50,
"charge_rates": null,
"min_soc_percentage": 0,
"max_soc_percentage": 100,
"measurement_key_soc_factor": "battery1-soc-factor",
"measurement_key_power_l1_w": "battery1-power-l1-w",
"measurement_key_power_l2_w": "battery1-power-l2-w",
"measurement_key_power_l3_w": "battery1-power-l3-w",
"measurement_key_power_3_phase_sym_w": "battery1-power-3-phase-sym-w",
"measurement_keys": [
"battery1-soc-factor",
"battery1-power-l1-w",
"battery1-power-l2-w",
"battery1-power-l3-w",
"battery1-power-3-phase-sym-w"
]
}
],
"max_batteries": 1,
"electric_vehicles": [
{
"device_id": "battery1",
"capacity_wh": 8000,
"charging_efficiency": 0.88,
"discharging_efficiency": 0.88,
"levelized_cost_of_storage_kwh": 0.0,
"max_charge_power_w": 5000,
"min_charge_power_w": 50,
"charge_rates": null,
"min_soc_percentage": 0,
"max_soc_percentage": 100,
"measurement_key_soc_factor": "battery1-soc-factor",
"measurement_key_power_l1_w": "battery1-power-l1-w",
"measurement_key_power_l2_w": "battery1-power-l2-w",
"measurement_key_power_l3_w": "battery1-power-l3-w",
"measurement_key_power_3_phase_sym_w": "battery1-power-3-phase-sym-w",
"measurement_keys": [
"battery1-soc-factor",
"battery1-power-l1-w",
"battery1-power-l2-w",
"battery1-power-l3-w",
"battery1-power-3-phase-sym-w"
]
}
],
"max_electric_vehicles": 1,
"inverters": [],
"max_inverters": 1,
"home_appliances": [],
"max_home_appliances": 1
},
"measurement": {
"load_emr_keys": [
"load0_emr"
],
"grid_export_emr_keys": [
"grid_export_emr"
],
"grid_import_emr_keys": [
"grid_import_emr"
],
"pv_production_emr_keys": [
"pv1_emr"
]
},
"optimization": {
"horizon_hours": 24,
"interval": 3600,
"genetic": {
"individuals": 400,
"generations": 400,
"seed": null,
"penalties": {
"ev_soc_miss": 10
}
}
},
"prediction": {
"hours": 48,
"historic_hours": 48
},
"elecprice": {
"provider": "ElecPriceAkkudoktor",
"charges_kwh": 0.21,
"vat_rate": 1.19,
"provider_settings": {
"ElecPriceImport": null
}
},
"feedintariff": {
"provider": "FeedInTariffFixed",
"provider_settings": {
"FeedInTariffFixed": null,
"FeedInTariffImport": null
}
},
"load": {
"provider": "LoadAkkudoktor",
"provider_settings": {
"LoadAkkudoktor": null,
"LoadVrm": null,
"LoadImport": null
}
},
"pvforecast": {
"provider": "PVForecastAkkudoktor",
"provider_settings": {
"PVForecastImport": null,
"PVForecastVrm": null
},
"planes": [
{
"surface_tilt": 10.0,
"surface_azimuth": 180.0,
"userhorizon": [
10.0,
20.0,
30.0
],
"peakpower": 5.0,
"pvtechchoice": "crystSi",
"mountingplace": "free",
"loss": 14.0,
"trackingtype": 0,
"optimal_surface_tilt": false,
"optimalangles": false,
"albedo": null,
"module_model": null,
"inverter_model": null,
"inverter_paco": 6000,
"modules_per_string": 20,
"strings_per_inverter": 2
},
{
"surface_tilt": 20.0,
"surface_azimuth": 90.0,
"userhorizon": [
5.0,
15.0,
25.0
],
"peakpower": 3.5,
"pvtechchoice": "crystSi",
"mountingplace": "free",
"loss": 14.0,
"trackingtype": 1,
"optimal_surface_tilt": false,
"optimalangles": false,
"albedo": null,
"module_model": null,
"inverter_model": null,
"inverter_paco": 4000,
"modules_per_string": 20,
"strings_per_inverter": 2
}
],
"max_planes": 1
},
"weather": {
"provider": "WeatherImport",
"provider_settings": {
"WeatherImport": null
}
},
"server": {
"host": "127.0.0.1",
"port": 8503,
"verbose": false,
"startup_eosdash": true,
"eosdash_host": "127.0.0.1",
"eosdash_port": 8504
},
"utils": {}
}