"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.\n\n## Currency Information\n\nAll monetary values in this API are expressed in the locally configured currency of the EOS installation. The system is designed to work with any currency (e.g., EUR, SEK, CHF, USD, GBP, etc.). Each installation uses a single, consistent currency throughout all endpoints and responses.\n\nValues are given in whole currency units, not in hundredth subunits: a value of `0.0003` in an installation configured for Euro means 0.0003 EUR/Wh (i.e. 0.30 EUR/kWh), never cents. The same applies to all totals (e.g. `total_costs` of `1.5` = 1.50 EUR).\n\nField names containing cost, price, revenue, tariff, or similar monetary terms (e.g., `total_costs`, `electricity_price_per_wh`, `revenue_per_hour`) represent amounts in the configured currency, without explicit currency designation in the field name to maintain currency-neutrality.\n\n## Deprecated Field Names\n\nThe genetic optimization API fields were renamed from German to English. For backward compatibility the old German field names (e.g. `gesamtlast`, `pv_prognose_wh`, `Gesamtbilanz_Euro`) are still accepted on input and are emitted in responses alongside the English names, marked as deprecated in the schema. They will be removed in a future release \u2014 new clients should use the English field names only.\n",
"description":"Estimate capacity from independent SoC anchors and configured DC power.\n\nstore_estimate writes the separate capacity_estimate config field in memory.\nPersistence follows the regular EOS configuration save mechanism.\nThe active capacity_wh and raw measurements are never changed here.",
"description":"Health check endpoint to verify that the EOS server is alive.",
"operationId":"fastapi_health_get_v1_health_get",
"responses":{
"200":{
"description":"Successful Response",
"content":{
"application/json":{
"schema":{}
}
}
}
}
}
},
"/v1/config/reset":{
"post":{
"tags":[
"config"
],
"summary":"Fastapi Config Reset Post",
"description":"Reset the configuration to the EOS configuration file.\n\nReturns:\n configuration (ConfigEOS): The current configuration after update.",
"description":"Get the EOS configuration backup identifiers and backup metadata.\n\nReturns:\n dict[str, dict[str, Any]]: Mapping of backup identifiers to metadata.",
"title":"Response Fastapi Config Backup Get V1 Config Backup Get"
}
}
}
}
}
}
},
"/v1/config/revert":{
"put":{
"tags":[
"config"
],
"summary":"Fastapi Config Revert Put",
"description":"Revert the configuration to a EOS configuration backup.\n\nReturns:\n configuration (ConfigEOS): The current configuration after revert.",
"description":"Save the current configuration to the EOS configuration file.\n\nReturns:\n configuration (ConfigEOS): The current configuration that was saved.",
"description":"Get the current configuration.\n\nReturns:\n configuration (ConfigEOS): The current configuration.",
"operationId":"fastapi_config_get_v1_config_get",
"responses":{
"200":{
"description":"Successful Response",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ConfigEOS"
}
}
}
}
}
},
"put":{
"tags":[
"config"
],
"summary":"Fastapi Config Put",
"description":"Update the current config with the provided settings.\n\nNote that for any setting value that is None or unset, the configuration will fall back to\nvalues from other sources such as environment variables, the EOS configuration file, or default\nvalues.\n\nArgs:\n settings (SettingsEOS): The settings to write into the current settings.\n\nReturns:\n configuration (ConfigEOS): The current configuration after the write.",
"operationId":"fastapi_config_put_v1_config_put",
"requestBody":{
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/SettingsEOS"
}
}
},
"required":true
},
"responses":{
"200":{
"description":"Successful Response",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ConfigEOS"
}
}
}
},
"422":{
"description":"Validation Error",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/config/{path}":{
"put":{
"tags":[
"config"
],
"summary":"Fastapi Config Put Key",
"description":"Update a nested key or index in the config model.\n\nArgs:\n path (str): The nested path to the key (e.g., \"general/latitude\" or \"optimize/nested_list/0\").\n value (Any): The new value to assign to the key or index at path.\n\nReturns:\n configuration (ConfigEOS): The current configuration after the update.",
"description":"The nested path to the configuration key (e.g., general/latitude).",
"title":"Path"
},
"description":"The nested path to the configuration key (e.g., general/latitude)."
}
],
"requestBody":{
"content":{
"application/json":{
"schema":{
"anyOf":[
{},
{
"type":"null"
}
],
"description":"The value to assign to the specified configuration path (can be None).",
"title":"Value"
}
}
}
},
"responses":{
"200":{
"description":"Successful Response",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ConfigEOS"
}
}
}
},
"422":{
"description":"Validation Error",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"get":{
"tags":[
"config"
],
"summary":"Fastapi Config Get Key",
"description":"Get the value of a nested key or index in the config model.\n\nArgs:\n path (str): The nested path to the key (e.g., \"general/latitude\" or \"optimize/nested_list/0\").\n\nReturns:\n value (Any): The value of the selected nested key.",
"description":"The nested path to the configuration key (e.g., general/latitude).",
"title":"Path"
},
"description":"The nested path to the configuration key (e.g., general/latitude)."
}
],
"responses":{
"200":{
"description":"Successful Response",
"content":{
"application/json":{
"schema":{}
}
}
},
"422":{
"description":"Validation Error",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/logging/log":{
"get":{
"tags":[
"logging"
],
"summary":"Fastapi Logging Get Log",
"description":"Get structured log entries from the EOS log file.\n\nFilters and returns log entries based on the specified query parameters. The log\nfile is expected to contain newline-delimited JSON entries.\n\nArgs:\n limit (int): Maximum number of entries to return.\n level (Optional[str]): Filter logs by severity level (e.g., DEBUG, INFO).\n contains (Optional[str]): Return only logs that include this string in the message.\n regex (Optional[str]): Return logs that match this regular expression in the message.\n from_time (Optional[str]): ISO 8601 timestamp to filter logs not older than this.\n to_time (Optional[str]): ISO 8601 timestamp to filter logs not newer than this.\n tail (bool): If True, fetch the most recent log entries (like `tail`).\n\nReturns:\n JSONResponse: A JSON list of log entries.",
"description":"Get measurements for given key within given date range as series.\n\nArgs:\n key (str): Measurement key\n start_datetime (Optional[str]): Starting datetime (inclusive).\n Defaults to datetime of first measurement.\n end_datetime (Optional[str]: Ending datetime (exclusive).\n Defaults to datetime after latest measurement.\n interval (Optional[str]): Time duration for each interval.\n Defaults to 1 hour.\n fill_method (str): Method to handle missing values during resampling.\n\n - 'linear': Linearly interpolate missing values (for numeric data only).\n - 'time': Interpolate missing values (for numeric data only).\n - 'ffill': Forward fill missing values.\n - 'bfill': Backward fill missing values.\n - Defaults to 'linear' for numeric values, otherwise 'ffill'.\n\n resample_method (str):\n Method used to aggregate values within a resampling interval.\n\n - \"first\": Use the first value in each interval.\n - \"mean\": Compute the arithmetic mean of all samples in each interval.\n - \"interval_mean\": Compute the time-weighted mean assuming each\n value remains valid until the next timestamp (piecewise-constant\n signal).\n\n dropna: (bool): Whether to drop NAN/ None values before processing.\n Defaults to True.\n boundary (Literal[\"strict\", \"context\"]): resampling boundary\n \"strict\" \u2192 only values inside [start, end)\n \"context\" \u2192 include one value before and after for proper resampling\n align_to_interval (bool): When True, snap the resample origin to the nearest\n UTC epoch-aligned boundary of ``interval`` before resampling. This ensures\n that bucket timestamps always fall on wall-clock-round times regardless of\n when ``start_datetime`` falls:\n\n - 15-minute interval \u2192 buckets on :00, :15, :30, :45\n - 1-hour interval \u2192 buckets on the hour\n\n When False (default), the origin is ``query_start`` (or ``\"start_day\"`` when\n no start is given), preserving the existing behaviour where buckets are\n aligned to the query window rather than the clock.\n\n Set to True when storing compacted records back to the database so that the\n resulting timestamps are predictable and human-readable. Leave False for\n forecast or reporting queries where alignment to the exact query window is\n more important than clock-round boundaries.\n processing (SeriesProcessing):\n Processing mode for the returned series.\n\n - ``SeriesProcessing.RESAMPLED``: Return a processed series.\n Measurements are first filtered by ``start_datetime``,\n ``end_datetime``, and ``dropna``, then resampled according to\n ``interval`` and ``resample_method``, and finally missing values\n are filled using ``fill_method``.\n - ``SeriesProcessing.RAW``: Return the original measurement series.\n Measurements are filtered by ``start_datetime``,\n ``end_datetime``, and ``dropna`` only. No resampling or filling is\n performed, and ``interval``, ``fill_method``,\n ``resample_method``, ``boundary``, and\n ``align_to_interval`` are ignored.\n\n Defaults to ``SeriesProcessing.RAW``.\n\nReturns:\n Series",
"description":"Get a list of available prediction providers.\n\nArgs:\n enabled (bool): Return enabled/disabled providers. If unset, return all providers.",
"description":"Get prediction for given key within given date range as series.\n\nArgs:\n key (str): Prediction key\n start_datetime (Optional[str]): Starting datetime (inclusive).\n Defaults to start datetime of latest prediction.\n end_datetime (Optional[str]: Ending datetime (exclusive).\n Defaults to end datetime of latest prediction.\n interval (Optional[str]): Time duration for each interval.\n Defaults to 1 hour.\n fill_method (str): Method to handle missing values during resampling.\n\n - 'linear': Linearly interpolate missing values (for numeric data only).\n - 'time': Interpolate missing values (for numeric data only).\n - 'ffill': Forward fill missing values.\n - 'bfill': Backward fill missing values.\n - Defaults to 'linear' for numeric values, otherwise 'ffill'.\n\n resample_method (str):\n Method used to aggregate values within a resampling interval.\n\n - \"first\": Use the first value in each interval.\n - \"mean\": Compute the arithmetic mean of all samples in each interval.\n - \"interval_mean\": Compute the time-weighted mean assuming each\n value remains valid until the next timestamp (piecewise-constant\n signal).\n\n dropna: (bool): Whether to drop NAN/ None values before processing.\n Defaults to True.\n boundary (Literal[\"strict\", \"context\"]): resampling boundary\n \"strict\" \u2192 only values inside [start, end)\n \"context\" \u2192 include one value before and after for proper resampling\n align_to_interval (bool): When True, snap the resample origin to the nearest\n UTC epoch-aligned boundary of ``interval`` before resampling. This ensures\n that bucket timestamps always fall on wall-clock-round times regardless of\n when ``start_datetime`` falls:\n\n - 15-minute interval \u2192 buckets on :00, :15, :30, :45\n - 1-hour interval \u2192 buckets on the hour\n\n When False (default), the origin is ``query_start`` (or ``\"start_day\"`` when\n no start is given), preserving the existing behaviour where buckets are\n aligned to the query window rather than the clock.\n\n Set to True when storing compacted records back to the database so that the\n resulting timestamps are predictable and human-readable. Leave False for\n forecast or reporting queries where alignment to the exact query window is\n more important than clock-round boundaries.\n processing (SeriesProcessing):\n Processing mode for the returned series.\n\n - ``SeriesProcessing.RESAMPLED``: Return a processed series.\n Measurements are first filtered by ``start_datetime``,\n ``end_datetime``, and ``dropna``, then resampled according to\n ``interval`` and ``resample_method``, and finally missing values\n are filled using ``fill_method``.\n - ``SeriesProcessing.RAW``: Return the original measurement series.\n Measurements are filtered by ``start_datetime``,\n ``end_datetime``, and ``dropna`` only. No resampling or filling is\n performed, and ``interval``, ``fill_method``,\n ``resample_method``, ``boundary``, and\n ``align_to_interval`` are ignored.\n\n Defaults to ``SeriesProcessing.RAW``.\n\nReturns:\n Array",
"description":"Get prediction for given keys within given date range as dataframe.\n\nArgs:\n key (list[str]): Prediction keys\n start_datetime (Optional[str]): Starting datetime (inclusive).\n Defaults to start datetime of latest prediction.\n end_datetime (Optional[str]: Ending datetime (exclusive).\n Defaults to end datetime of latest prediction.\n interval (Optional[str]): Time duration for each interval.\n Defaults to 1 hour.\n fill_method (str): Method to handle missing values during resampling.\n\n - 'linear': Linearly interpolate missing values (for numeric data only).\n - 'time': Interpolate missing values (for numeric data only).\n - 'ffill': Forward fill missing values.\n - 'bfill': Backward fill missing values.\n - Defaults to 'linear' for numeric values, otherwise 'ffill'.\n\n resample_method (str):\n Method used to aggregate values within a resampling interval.\n\n - \"first\": Use the first value in each interval.\n - \"mean\": Compute the arithmetic mean of all samples in each interval.\n - \"interval_mean\": Compute the time-weighted mean assuming each\n value remains valid until the next timestamp (piecewise-constant\n signal).\n\n dropna: (bool): Whether to drop NAN/ None values before processing.\n Defaults to True.\n boundary (Literal[\"strict\", \"context\"]): resampling boundary\n \"strict\" \u2192 only values inside [start, end)\n \"context\" \u2192 include one value before and after for proper resampling\n align_to_interval (bool): When True, snap the resample origin to the nearest\n UTC epoch-aligned boundary of ``interval`` before resampling. This ensures\n that bucket timestamps always fall on wall-clock-round times regardless of\n when ``start_datetime`` falls:\n\n - 15-minute interval \u2192 buckets on :00, :15, :30, :45\n - 1-hour interval \u2192 buckets on the hour\n\n When False (default), the origin is ``query_start`` (or ``\"start_day\"`` when\n no start is given), preserving the existing behaviour where buckets are\n aligned to the query window rather than the clock.\n\n Set to True when storing compacted records back to the database so that the\n resulting timestamps are predictable and human-readable. Leave False for\n forecast or reporting queries where alignment to the exact query window is\n more important than clock-round boundaries.",
"description":"Get prediction for given key within given date range as value list.\n\nArgs:\n key (str): Prediction key\n start_datetime (Optional[str]): Starting datetime (inclusive).\n Defaults to start datetime of latest prediction.\n end_datetime (Optional[str]: Ending datetime (exclusive).\n Defaults to end datetime of latest prediction.\n interval (Optional[str]): Time duration for each interval.\n Defaults to 1 hour.\n fill_method (str): Method to handle missing values during resampling.\n\n - 'linear': Linearly interpolate missing values (for numeric data only).\n - 'time': Interpolate missing values (for numeric data only).\n - 'ffill': Forward fill missing values.\n - 'bfill': Backward fill missing values.\n - Defaults to 'linear' for numeric values, otherwise 'ffill'.\n\n resample_method (str):\n Method used to aggregate values within a resampling interval.\n\n - \"first\": Use the first value in each interval.\n - \"mean\": Compute the arithmetic mean of all samples in each interval.\n - \"interval_mean\": Compute the time-weighted mean assuming each\n value remains valid until the next timestamp (piecewise-constant\n signal).\n\n dropna: (bool): Whether to drop NAN/ None values before processing.\n Defaults to True.\n boundary (Literal[\"strict\", \"context\"]): resampling boundary\n \"strict\" \u2192 only values inside [start, end)\n \"context\" \u2192 include one value before and after for proper resampling\n align_to_interval (bool): When True, snap the resample origin to the nearest\n UTC epoch-aligned boundary of ``interval`` before resampling. This ensures\n that bucket timestamps always fall on wall-clock-round times regardless of\n when ``start_datetime`` falls:\n\n - 15-minute interval \u2192 buckets on :00, :15, :30, :45\n - 1-hour interval \u2192 buckets on the hour\n\n When False (default), the origin is ``query_start`` (or ``\"start_day\"`` when\n no start is given), preserving the existing behaviour where buckets are\n aligned to the query window rather than the clock.\n\n Set to True when storing compacted records back to the database so that the\n resulting timestamps are predictable and human-readable. Leave False for\n forecast or reporting queries where alignment to the exact query window is\n more important than clock-round boundaries.",
"title":"Response Fastapi Prediction List Get V1 Prediction List Get"
}
}
}
},
"422":{
"description":"Validation Error",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/prediction/import/{provider_id}":{
"put":{
"tags":[
"prediction"
],
"summary":"Fastapi Prediction Import Provider",
"description":"Import prediction for given provider ID.\n\nArgs:\n provider_id: ID of provider to update.\n data: Prediction data.\n force_enable: Update data even if provider is disabled.\n Defaults to False.",
"description":"Update predictions for all providers.\n\nArgs:\n force_update: Update data even if it is already cached.\n Defaults to False.\n force_enable: Update data even if provider is disabled.\n Defaults to False.",
"description":"Update predictions for given provider ID.\n\nArgs:\n provider_id: ID of provider to update.\n force_update: Update data even if it is already cached.\n Defaults to False.\n force_enable: Update data even if provider is disabled.\n Defaults to False.",
"summary":"Fastapi Energy Management Optimization Solution Genetic Pdf Get",
"description":"Render the retained GENETIC result without rerunning optimization.\n\nRendering runs outside the event loop. Copy the result before offloading;\nits recorded timestamp, interval and inputs own the report's time grid.\nThe legacy /visualization_results.pdf route continues to serve GENETIC0.",
"description":"Deprecated: Electricity Market Price Prediction per Wh [amount/Wh].\n\nElectricity prices start at 00.00.00 today and are provided for 48 hours\nin 1-hour intervals. If no prices are available the missing ones at the\nstart of the series are filled with the first available price.\n\nNote:\n Electricity price charges are added.\n\nNote:\n Set ElecPriceAkkudoktor as provider, then update data with\n '/v1/prediction/update'\n and then request data with\n '/v1/prediction/list?key=elecprice_marketprice_wh' or\n '/v1/prediction/list?key=elecprice_marketprice_kwh' instead.",
"description":"Deprecated: Total Load Prediction with adjustment.\n\nEndpoint to handle total load prediction adjusted by latest measured data.\n\nTotal load prediction starts at 00.00.00 today and is provided for 48 hours\nin 1-hour intervals. If no prediction values are available the missing ones\nat the start of the series are filled with the first available prediction value.\n\nNote:\n Use '/v1/prediction/list?key=loadforecast_power_w' instead.\n Load energy meter readings to be added to EOS measurement by:\n '/v1/measurement/value' or\n '/v1/measurement/series' or\n '/v1/measurement/dataframe' or\n '/v1/measurement/data'",
"description":"Deprecated: Total Load Prediction.\n\nEndpoint to handle total load prediction.\n\nTotal load prediction starts at 00.00.00 today and is provided for 48 hours\nin 1-hour intervals. If no prediction values are available the missing ones\nat the start of the series are filled with the first available prediction value.\n\nArgs:\n year_energy (float): Yearly energy consumption in Wh.\n\nNote:\n Set LoadAkkudoktor as provider, then update data with\n '/v1/prediction/update'\n and then request data with\n '/v1/prediction/list?key=loadforecast_power_w' instead.",
"description":"Deprecated: PV Forecast Prediction.\n\nEndpoint to handle PV forecast prediction.\n\nPVForecast starts at 00.00.00 today and is provided for 48 hours\nin 1-hour intervals. If no forecast values are available the missing ones\nat the start of the series are filled with the first available forecast value.\n\nNote:\n Set PVForecastAkkudoktor as provider, then update data with\n '/v1/prediction/update'\n and then request data with\n '/v1/prediction/list?key=pvforecast_ac_power' and\n '/v1/prediction/list?key=pvforecastakkudoktor_temp_air' instead.",
"description":"Optimize GENETIC using configured devices and optional fresh runtime inputs.\n\nStatic settings belong in configuration; query overrides are rejected.\nForecast arrays start at local\nmidnight and contain Wh per configured GENETIC slot; prices are currency/Wh.\nAn empty body uses configured providers and fresh measured states of charge.\nThe deprecated /optimize endpoint continues to run hourly GENETIC0.",
"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.",
"description":"Absolute moment by which 'min_soc_percentage' has to be reached (departure time). A date time without timezone is read as local time. None means end of the optimization horizon.",
"examples":[
null,
"2026-07-16T07:00:00+02:00"
],
"x-scope":[
"GENETIC"
]
},
"min_soc_max_duration_h":{
"anyOf":[
{
"type":"number",
"exclusiveMinimum":0.0
},
{
"type":"null"
}
],
"title":"Min Soc Max Duration H",
"description":"Maximum time from the start of the optimization until 'min_soc_percentage' has to be reached [h]. Combined with 'min_soc_deadline_datetime' the earlier of the two applies.",
"description":"Battery and electric vehicle device settings.\n\nUsed for both stationary batteries and EV battery packs.\n\nNote: Used for the GENETIC and GENETIC0 algorithm."
"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.",
"description":"Absolute moment by which 'min_soc_percentage' has to be reached (departure time). A date time without timezone is read as local time. None means end of the optimization horizon.",
"examples":[
null,
"2026-07-16T07:00:00+02:00"
],
"x-scope":[
"GENETIC"
]
},
"min_soc_max_duration_h":{
"anyOf":[
{
"type":"number",
"exclusiveMinimum":0.0
},
{
"type":"null"
}
],
"title":"Min Soc Max Duration H",
"description":"Maximum time from the start of the optimization until 'min_soc_percentage' has to be reached [h]. Combined with 'min_soc_deadline_datetime' the earlier of the two applies.",
"description":"Battery and electric vehicle device settings.\n\nUsed for both stationary batteries and EV battery packs.\n\nNote: Used for the GENETIC and GENETIC0 algorithm."
"description":"Only a battery-terminal DC power channel is supported, not inverter AC."
},
"BatteryCapacityRequest":{
"properties":{
"start":{
"type":"string",
"format":"date-time",
"title":"Start"
},
"end":{
"type":"string",
"format":"date-time",
"title":"End"
},
"start_soc_percentage":{
"type":"number",
"maximum":100.0,
"minimum":0.0,
"title":"Start Soc Percentage"
},
"end_soc_percentage":{
"type":"number",
"maximum":100.0,
"minimum":0.0,
"title":"End Soc Percentage",
"default":100
},
"soc_reference":{
"type":"string",
"enum":[
"bms",
"external_calibration",
"voltage_current_anchor"
],
"title":"Soc Reference"
},
"store_estimate":{
"type":"boolean",
"title":"Store Estimate",
"default":false
}
},
"additionalProperties":false,
"type":"object",
"required":[
"start",
"end",
"start_soc_percentage",
"soc_reference"
],
"title":"BatteryCapacityRequest",
"description":"Caller attests both anchors are independent of the capacity being fitted.\n\nEnd is the first confirmed full point when using the default end SoC.\nVoltage/current anchors must be independently established for the chemistry."
"description":"Singleton configuration handler for the EOS application.\n\nConfigEOS extends `SettingsEOS` with support for default configuration paths and automatic\ninitialization.\n\n`ConfigEOS` ensures that only one instance of the class is created throughout the application,\nallowing consistent access to EOS configuration settings. This singleton instance loads\nconfiguration data from a predefined set of directories or creates a default configuration if\nnone is found.\n\nInitialization Process:\n - Upon instantiation, the singleton instance attempts to load a configuration file in this order:\n 1. The directory specified by the `EOS_CONFIG_DIR` environment variable\n 2. The directory specified by the `EOS_DIR` environment variable.\n 3. A platform specific default directory for EOS.\n 4. The current working directory.\n - The first available configuration file found in these directories is loaded.\n - If no configuration file is found, a default configuration file is created in the platform\n specific default directory, and default settings are loaded into it.\n\nAttributes from the loaded configuration are accessible directly as instance attributes of\n`ConfigEOS`, providing a centralized, shared configuration object for EOS.\n\nSingleton Behavior:\n - This class uses the `SingletonMixin` to ensure that all requests for `ConfigEOS` return\n the same instance, which contains the most up-to-date configuration. Modifying the configuration\n in one part of the application reflects across all references to this class.\n\nRaises:\n FileNotFoundError: If no configuration file is found, and creating a default configuration fails.\n\nExample:\n To initialize and access configuration attributes (only one instance is created):\n .. code-block:: python\n\n config_eos = ConfigEOS() # Always returns the same instance\n print(config_eos.prediction.hours) # Access a setting from the loaded configuration"
"description":"Behaviour when a flexible consumer's deadline cannot be met.\n\nA deadline (``deadline_datetime``) demands that a complete run has *finished*\nbefore that moment. Depending on \"now\", the run duration, the optimization\nhorizon and the allowed time windows, no such start may exist.\n\nPolicies\n--------\n- BEST_EFFORT:\n Run as early as the remaining constraints allow, i.e. minimize the\n delay instead of the cost (\"it should have been done by 03:00, so\n start now\"). A warning is logged. This keeps an optimization request\n answerable instead of failing it - the usual choice for home\n automation.\n\n- STRICT:\n Keep the deadline. A ONCE consumer without a feasible start makes the\n optimization fail; a DAILY consumer is simply not scheduled on days\n without a feasible start."
},
"ConsumerScheduleMode":{
"type":"string",
"enum":[
"ONCE",
"DAILY"
],
"title":"ConsumerScheduleMode",
"description":"Schedule mode of a flexible consumer (home appliance).\n\nDetermines how often a consumer's load profile is scheduled within the\noptimization horizon.\n\nModes\n-----\n- ONCE:\n The consumer runs exactly once somewhere within the optimization\n horizon (\"fire and forget\"). The optimizer picks the start.\n\n- DAILY:\n The consumer runs once per local calendar day, but only on days for\n which at least one complete, allowed run still fits into the remaining\n horizon. The optimizer picks one start per eligible day."
"description":"Ordered list of value time windows. Each window defines a time interval and an associated value."
}
},
"type":"object",
"title":"CycleTimeWindowSequence",
"description":"Sequence of time windows associated to cycles.\n\nThis model specializes ``ValueTimeWindowSequence`` so that the ``value``\nfield of each ``ValueTimeWindow`` encodes the **cycle index** (0-based\ninteger) the window belongs to.\n\nTypical use: an appliance that must run ``n`` times per day, each run\nconstrained to a distinct time window. Assign ``value=0`` to windows\nfor the first cycle, ``value=1`` for the second, and so on. Multiple\nwindows may share the same cycle index (their allowed regions are unioned).\nWindows with ``value=None`` are silently ignored by all cycle-aware methods."
"description":"Ordered list of value time windows. Each window defines a time interval and an associated value."
}
},
"type":"object",
"title":"CycleTimeWindowSequence",
"description":"Sequence of time windows associated to cycles.\n\nThis model specializes ``ValueTimeWindowSequence`` so that the ``value``\nfield of each ``ValueTimeWindow`` encodes the **cycle index** (0-based\ninteger) the window belongs to.\n\nTypical use: an appliance that must run ``n`` times per day, each run\nconstrained to a distinct time window. Assign ``value=0`` to windows\nfor the first cycle, ``value=1`` for the second, and so on. Multiple\nwindows may share the same cycle index (their allowed regions are unioned).\nWindows with ``value=None`` are silently ignored by all cycle-aware methods."
"description":"Currently active operation mode ID."
},
"operation_mode_factor":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Operation Mode Factor",
"description":"Factor with which the operation mode is configured (0 to 1)."
},
"previous_operation_mode_id":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Previous Operation Mode Id",
"description":"Previously active operation mode ID. Required unless this is the first mode."
},
"transition_timestamp":{
"anyOf":[
{
"type":"string",
"format":"date-time"
},
{
"type":"null"
}
],
"title":"Transition Timestamp",
"description":"Timestamp of transition to the active operation mode."
}
},
"type":"object",
"required":[
"active_operation_mode_id",
"operation_mode_factor"
],
"title":"DDBCActuatorStatus",
"description":"Current status of a DDBC Actuator.\n\nProvides information about the currently active operation mode and transition history.\nUsed to track the current state of the actuator."
},
"DDBCInstruction":{
"properties":{
"id":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Id",
"description":"Unique identifier of the instruction in the ResourceManager scope. If not provided and a `resource_id` is passed at instantiation, this will be auto-generated as `{resource_id}@{UUID}`."
},
"execution_time":{
"type":"string",
"format":"date-time",
"title":"Execution Time",
"description":"Start time of the instruction execution."
},
"abnormal_condition":{
"type":"boolean",
"title":"Abnormal Condition",
"description":"Indicates if this is an instruction for abnormal conditions. Defaults to False.",
"default":false
},
"type":{
"type":"string",
"const":"DDBCInstruction",
"title":"Type",
"default":"DDBCInstruction"
},
"actuator_id":{
"type":"string",
"title":"Actuator Id",
"description":"ID of the actuator this instruction belongs to."
},
"operation_mode_id":{
"type":"string",
"title":"Operation Mode Id",
"description":"ID of the DDBC.OperationMode to apply."
},
"operation_mode_factor":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Operation Mode Factor",
"description":"Factor with which the operation mode should be applied (0 to 1)."
},
"resource_id":{
"type":"string",
"title":"Resource Id",
"description":"Get the resource identifier component from the instruction's `id`.\n\nAssumes the `id` follows the format `{resource_id}@{UUID}`. Extracts the resource_id part\nof the id by splitting at the last @.\n\nReturns:\n str: The resource identifier prefix of `id`, or an empty string if `id` is None.",
"readOnly":true
}
},
"type":"object",
"required":[
"execution_time",
"actuator_id",
"operation_mode_id",
"operation_mode_factor",
"resource_id"
],
"title":"DDBCInstruction",
"description":"Instruction for Demand Driven Based Control (DDBC).\n\nContains information about when and how to activate a specific operation mode\nfor an actuator. Used to command resources to change their operation at a specified time."
"description":"Database provider id of provider to be used.",
"examples":[
"LMDB"
]
},
"compression_level":{
"type":"integer",
"maximum":9.0,
"minimum":0.0,
"title":"Compression Level",
"description":"Compression level for database record data.",
"default":9,
"examples":[
0,
9
]
},
"initial_load_window_h":{
"anyOf":[
{
"type":"integer",
"minimum":0.0
},
{
"type":"null"
}
],
"title":"Initial Load Window H",
"description":"Specifies the default duration of the initial load window when loading records from the database, in hours. If set to None, the full available range is loaded. The window is centered around the current time by default, unless a different center time is specified. Different database namespaces may define their own default windows.",
"examples":[
"48",
"None"
]
},
"keep_duration_h":{
"anyOf":[
{
"type":"integer",
"minimum":0.0
},
{
"type":"null"
}
],
"title":"Keep Duration H",
"description":"Default maximum duration records shall be kept in database [hours, none].\nNone indicates forever. Database namespaces may have diverging definitions.",
"examples":[
48,
"none"
]
},
"autosave_interval_sec":{
"anyOf":[
{
"type":"integer",
"minimum":5.0
},
{
"type":"null"
}
],
"title":"Autosave Interval Sec",
"description":"Automatic saving interval [seconds].\nSet to None to disable automatic saving.",
"default":10,
"examples":[
5
]
},
"compaction_interval_sec":{
"anyOf":[
{
"type":"integer",
"minimum":0.0
},
{
"type":"null"
}
],
"title":"Compaction Interval Sec",
"description":"Interval in between automatic tiered compaction runs [seconds].\nCompaction downsamples old records to reduce storage while retaining coverage. Set to None to disable automatic compaction.",
"description":"Number of records to process in batch operations.",
"default":100,
"examples":[
100
]
}
},
"type":"object",
"title":"DatabaseCommonSettings",
"description":"Configuration model for database settings.\n\nAttributes:\n provider: Optional provider identifier (e.g. \"LMDB\").\n max_records_in_memory: Maximum records kept in memory before auto-save.\n auto_save: Whether to auto-save when threshold exceeded.\n batch_size: Batch size for batch operations."
},
"DatabaseCommonSettings-Output":{
"properties":{
"provider":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Provider",
"description":"Database provider id of provider to be used.",
"examples":[
"LMDB"
]
},
"compression_level":{
"type":"integer",
"maximum":9.0,
"minimum":0.0,
"title":"Compression Level",
"description":"Compression level for database record data.",
"default":9,
"examples":[
0,
9
]
},
"initial_load_window_h":{
"anyOf":[
{
"type":"integer",
"minimum":0.0
},
{
"type":"null"
}
],
"title":"Initial Load Window H",
"description":"Specifies the default duration of the initial load window when loading records from the database, in hours. If set to None, the full available range is loaded. The window is centered around the current time by default, unless a different center time is specified. Different database namespaces may define their own default windows.",
"examples":[
"48",
"None"
]
},
"keep_duration_h":{
"anyOf":[
{
"type":"integer",
"minimum":0.0
},
{
"type":"null"
}
],
"title":"Keep Duration H",
"description":"Default maximum duration records shall be kept in database [hours, none].\nNone indicates forever. Database namespaces may have diverging definitions.",
"examples":[
48,
"none"
]
},
"autosave_interval_sec":{
"anyOf":[
{
"type":"integer",
"minimum":5.0
},
{
"type":"null"
}
],
"title":"Autosave Interval Sec",
"description":"Automatic saving interval [seconds].\nSet to None to disable automatic saving.",
"default":10,
"examples":[
5
]
},
"compaction_interval_sec":{
"anyOf":[
{
"type":"integer",
"minimum":0.0
},
{
"type":"null"
}
],
"title":"Compaction Interval Sec",
"description":"Interval in between automatic tiered compaction runs [seconds].\nCompaction downsamples old records to reduce storage while retaining coverage. Set to None to disable automatic compaction.",
"description":"Number of records to process in batch operations.",
"default":100,
"examples":[
100
]
},
"providers":{
"items":{
"type":"string"
},
"type":"array",
"title":"Providers",
"description":"Return available database provider ids.",
"readOnly":true
}
},
"type":"object",
"required":[
"providers"
],
"title":"DatabaseCommonSettings",
"description":"Configuration model for database settings.\n\nAttributes:\n provider: Optional provider identifier (e.g. \"LMDB\").\n max_records_in_memory: Maximum records kept in memory before auto-save.\n auto_save: Whether to auto-save when threshold exceeded.\n batch_size: Batch size for batch operations."
"description":"Configuration for all controllable devices in the simulation.\n\nEvery device collection is a ``dict[str, <Settings>]`` keyed by\n``device_id``. This makes config paths stable regardless of\ndeclaration order and lets each device settings class build its own\nconfig path from ``self.device_id`` without needing an external index."
"description":"Configuration for all controllable devices in the simulation.\n\nEvery device collection is a ``dict[str, <Settings>]`` keyed by\n``device_id``. This makes config paths stable regardless of\ndeclaration order and lets each device settings class build its own\nconfig path from ``self.device_id`` without needing an external index."
"description":"Sequence of time windows defining the total fixed per-kWh electricty fee charged for consumed energy, accumulating all applicable fixed per-kWh charges (e.g. network charge, metering fee, concession fee) into a single amount [amount/kWh]. If not provided, no fixed per-kWh consumption fee is applied.",
"description":"Sequence of time windows defining the total fixed electricity surcharge applied as a percentage of the monetary amount already charged for consumed energy, accumulating all applicable percentage-based surcharges (e.g. VAT, electricity tax) into a single percentage [%]. This is a percentage of the fee amount, not a per-kWh rate. If not provided, no percentage-based consumption surcharge is applied.",
"description":"Sequence of time windows defining the total deduction from feed-in energy per Wh [amount/Wh]. This is the accumulation of all fixed per-Wh charges deducted from feed-in energy - such as metering fees or grid-operator handling charges - into a single amount. Applied after the percentage-based deduction, i.e. it reduces the price by a flat amount per Wh rather than by a share of the raw price. If not provided, no fixed per-kWh feed-in fee is applied.",
"description":"Sequence of time windows defining the total percentage deducted from the raw feed-in price (spot price) [%]. This is the accumulation of all percentage-based deductions payable on the feed-in tariff - such as a marketing or balancing fee retained by the aggregator - into a single percentage. It is applied as `raw_price * (100 - percent) / 100`, i.e. it scales down the raw price rather than adding a surcharge to it. If not provided, no percentage-based feed-in deduction is applied.",
"examples":[
{
"windows":[
{
"duration":"24 hours",
"start_time":"00:00",
"value":19.0
}
]
}
]
}
},
"type":"object",
"title":"ElecFeeFixedCommonSettings",
"description":"Common settings for fixed electricity fees.\n\nThis model defines a fixed electricity fee schedule using a sequence\nof time windows. Each window specifies a time interval and the electricity\nfee applicable during that interval."
"description":"Sequence of time windows defining the total fixed per-kWh electricty fee charged for consumed energy, accumulating all applicable fixed per-kWh charges (e.g. network charge, metering fee, concession fee) into a single amount [amount/kWh]. If not provided, no fixed per-kWh consumption fee is applied.",
"description":"Sequence of time windows defining the total fixed electricity surcharge applied as a percentage of the monetary amount already charged for consumed energy, accumulating all applicable percentage-based surcharges (e.g. VAT, electricity tax) into a single percentage [%]. This is a percentage of the fee amount, not a per-kWh rate. If not provided, no percentage-based consumption surcharge is applied.",
"description":"Sequence of time windows defining the total deduction from feed-in energy per Wh [amount/Wh]. This is the accumulation of all fixed per-Wh charges deducted from feed-in energy - such as metering fees or grid-operator handling charges - into a single amount. Applied after the percentage-based deduction, i.e. it reduces the price by a flat amount per Wh rather than by a share of the raw price. If not provided, no fixed per-kWh feed-in fee is applied.",
"description":"Sequence of time windows defining the total percentage deducted from the raw feed-in price (spot price) [%]. This is the accumulation of all percentage-based deductions payable on the feed-in tariff - such as a marketing or balancing fee retained by the aggregator - into a single percentage. It is applied as `raw_price * (100 - percent) / 100`, i.e. it scales down the raw price rather than adding a surcharge to it. If not provided, no percentage-based feed-in deduction is applied.",
"examples":[
{
"windows":[
{
"duration":"24 hours",
"start_time":"00:00",
"value":19.0
}
]
}
]
}
},
"type":"object",
"title":"ElecFeeFixedCommonSettings",
"description":"Common settings for fixed electricity fees.\n\nThis model defines a fixed electricity fee schedule using a sequence\nof time windows. Each window specifies a time interval and the electricity\nfee applicable during that interval."
},
"ElecFeeImportCommonSettings":{
"properties":{
"import_file_path":{
"anyOf":[
{
"type":"string"
},
{
"type":"string",
"format":"path"
},
{
"type":"null"
}
],
"title":"Import File Path",
"description":"Path to the file to import elecfee data from.",
"examples":[
null,
"/path/to/prices.json"
]
},
"import_json":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Import Json",
"description":"JSON string, dictionary of electricity fee forecast value lists.",
"description":"Sequence of time windows defining the fixed price schedule. If not provided, no fixed pricing is applied.",
"examples":[
{
"windows":[
{
"duration":"8 hours",
"start_time":"00:00",
"value":0.288
},
{
"duration":"16 hours",
"start_time":"08:00",
"value":0.34
}
]
}
]
}
},
"type":"object",
"title":"ElecPriceFixedCommonSettings",
"description":"Common configuration settings for fixed electricity pricing.\n\nThis model defines a fixed electricity price schedule using a sequence\nof time windows. Each window specifies a time interval and the electricity\nprice applicable during that interval."
"description":"Sequence of time windows defining the fixed price schedule. If not provided, no fixed pricing is applied.",
"examples":[
{
"windows":[
{
"duration":"8 hours",
"start_time":"00:00",
"value":0.288
},
{
"duration":"16 hours",
"start_time":"08:00",
"value":0.34
}
]
}
]
}
},
"type":"object",
"title":"ElecPriceFixedCommonSettings",
"description":"Common configuration settings for fixed electricity pricing.\n\nThis model defines a fixed electricity price schedule using a sequence\nof time windows. Each window specifies a time interval and the electricity\nprice applicable during that interval."
"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.",
"description":"Absolute moment by which 'min_soc_percentage' has to be reached (departure time). A date time without timezone is read as local time. None means end of the optimization horizon.",
"examples":[
null,
"2026-07-16T07:00:00+02:00"
]
},
"min_soc_max_duration_h":{
"anyOf":[
{
"type":"number",
"exclusiveMinimum":0.0
},
{
"type":"null"
}
],
"title":"Min Soc Max Duration H",
"description":"Maximum time from the start of the optimization until 'min_soc_percentage' has to be reached [h]. Combined with 'min_soc_deadline_datetime' the earlier of the two applies.",
"description":"A coordinated energy management plan composed of device control instructions.\n\nAttributes:\n plan_id (ID): Unique identifier for this energy management plan.\n generated_at (DateTime): Timestamp when the plan was generated.\n valid_from (Optional[DateTime]): Earliest start time of any instruction.\n valid_until (Optional[DateTime]): Latest end time across all instructions\n with finite duration; None if all instructions have infinite duration.\n instructions (list[BaseInstruction]): List of control instructions for the plan.\n comment (Optional[str]): Optional comment or annotation for the plan."
"description":"Timestamp when energy values were measured."
},
"last_reset":{
"anyOf":[
{
"type":"string",
"format":"date-time"
},
{
"type":"null"
}
],
"title":"Last Reset",
"description":"Timestamp when the energy meter's cumulative counter was last reset."
},
"values":{
"items":{
"$ref":"#/components/schemas/PowerValue"
},
"type":"array",
"title":"Values",
"description":"Array of measured energy values. Shall contain at least one item and at most one item per 'commodity_quantity' (defined inside the PowerValue)."
}
},
"type":"object",
"required":[
"measurement_timestamp",
"values"
],
"title":"EnergyMeasurement",
"description":"Captures a set of energy meter readouts taken at a specific point in time.\n\nEnergy is defined as the cummulative power per hour as provided by an energy meter.\n\nThis model records multiple energy values (for different commodity quantities)\nalong with the timestamp when the meter readouts were taken, enabling time-series\nanalysis and monitoring of energy consumption or production.\n\nNote: This is an extension to the S2 standard."
},
"FRBCActuatorStatus":{
"properties":{
"type":{
"type":"string",
"const":"FRBCActuatorStatus",
"title":"Type",
"default":"FRBCActuatorStatus"
},
"active_operation_mode_id":{
"type":"string",
"title":"Active Operation Mode Id",
"description":"Currently active operation mode ID."
},
"operation_mode_factor":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Operation Mode Factor",
"description":"Factor with which the mode is configured (0 to 1)."
},
"previous_operation_mode_id":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Previous Operation Mode Id",
"description":"Previously active operation mode ID."
},
"transition_timestamp":{
"anyOf":[
{
"type":"string",
"format":"date-time"
},
{
"type":"null"
}
],
"title":"Transition Timestamp",
"description":"Timestamp of the last transition between modes."
}
},
"type":"object",
"required":[
"active_operation_mode_id",
"operation_mode_factor"
],
"title":"FRBCActuatorStatus",
"description":"Current status of an FRBC Actuator.\n\nProvides information about the currently active operation mode and transition history.\nUsed to track the current state of the actuator."
"description":"Total cumulative exported energy from the energy meter start."
}
},
"type":"object",
"title":"FRBCEnergyStatus",
"description":"Energy status of an FRBC storage.\n\nNote: This is an extension to the S2 standard."
},
"FRBCInstruction":{
"properties":{
"id":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Id",
"description":"Unique identifier of the instruction in the ResourceManager scope. If not provided and a `resource_id` is passed at instantiation, this will be auto-generated as `{resource_id}@{UUID}`."
},
"execution_time":{
"type":"string",
"format":"date-time",
"title":"Execution Time",
"description":"Start time of the instruction execution."
},
"abnormal_condition":{
"type":"boolean",
"title":"Abnormal Condition",
"description":"Indicates if this is an instruction for abnormal conditions. Defaults to False.",
"default":false
},
"type":{
"type":"string",
"const":"FRBCInstruction",
"title":"Type",
"default":"FRBCInstruction"
},
"actuator_id":{
"type":"string",
"title":"Actuator Id",
"description":"ID of the actuator this instruction belongs to."
},
"operation_mode_id":{
"type":"string",
"title":"Operation Mode Id",
"description":"ID of the operation mode to activate."
},
"operation_mode_factor":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Operation Mode Factor",
"description":"Factor for the operation mode configuration (0 to 1)."
},
"resource_id":{
"type":"string",
"title":"Resource Id",
"description":"Get the resource identifier component from the instruction's `id`.\n\nAssumes the `id` follows the format `{resource_id}@{UUID}`. Extracts the resource_id part\nof the id by splitting at the last @.\n\nReturns:\n str: The resource identifier prefix of `id`, or an empty string if `id` is None.",
"readOnly":true
}
},
"type":"object",
"required":[
"execution_time",
"actuator_id",
"operation_mode_id",
"operation_mode_factor",
"resource_id"
],
"title":"FRBCInstruction",
"description":"Instruction for Fill Rate Based Control (FRBC).\n\nContains information about when and how to activate a specific operation mode\nfor an actuator. Used to command resources to change their operation at a specified time."
},
"FRBCStorageStatus":{
"properties":{
"type":{
"type":"string",
"const":"FRBCStorageStatus",
"title":"Type",
"default":"FRBCStorageStatus"
},
"present_fill_level":{
"type":"number",
"title":"Present Fill Level",
"description":"Current fill level of the storage."
}
},
"type":"object",
"required":[
"present_fill_level"
],
"title":"FRBCStorageStatus",
"description":"Current status of an FRBC Storage.\n\nIndicates the current fill level of the storage, which is essential\nfor determining applicable operation modes and control decisions."
},
"FRBCTimerStatus":{
"properties":{
"type":{
"type":"string",
"const":"FRBCTimerStatus",
"title":"Type",
"default":"FRBCTimerStatus"
},
"actuator_id":{
"type":"string",
"title":"Actuator Id",
"description":"ID of the actuator the timer belongs to."
},
"timer_id":{
"type":"string",
"title":"Timer Id",
"description":"ID of the timer this status refers to."
},
"finished_at":{
"type":"string",
"format":"date-time",
"title":"Finished At",
"description":"Indicates when the Timer will be finished. If the DateTime is in the future, the timer is not yet finished. If the DateTime is in the past, the timer is finished. If the timer was never started, the value can be an arbitrary DateTimeStamp in the past."
}
},
"type":"object",
"required":[
"actuator_id",
"timer_id",
"finished_at"
],
"title":"FRBCTimerStatus",
"description":"Current status of an FRBC Timer.\n\nIndicates when the Timer will be finished."
"description":"Enable export-aware GENETIC optimization. Sale revenues remain those of the configured feed-in provider or explicit forecast; purchase prices never replace them.",
"description":"Enable export-aware GENETIC optimization. Sale revenues remain those of the configured feed-in provider or explicit forecast; purchase prices never replace them.",
"description":"Number of prediction hours. Defaults to global config prediction hours.",
"examples":[
null
]
},
"max_power_wh":{
"type":"number",
"exclusiveMinimum":0.0,
"title":"Max Power Wh",
"examples":[
10000
]
},
"battery_id":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Battery Id",
"description":"ID of battery",
"examples":[
null,
"battery1"
]
},
"ac_to_dc_efficiency":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Ac To Dc Efficiency",
"description":"Efficiency of AC to DC conversion (for AC/grid charging of battery). Set to 0 to disable AC charging via inverter. Default 1.0 for backward compatibility (no additional inverter loss).",
"default":1.0,
"examples":[
0.95,
1.0,
0.0
]
},
"dc_to_ac_efficiency":{
"type":"number",
"maximum":1.0,
"exclusiveMinimum":0.0,
"title":"Dc To Ac Efficiency",
"description":"Efficiency of DC to AC conversion (for battery discharging to AC load/grid). Default 1.0 for backward compatibility (no additional inverter loss).",
"default":1.0,
"examples":[
0.95,
1.0
]
},
"max_ac_charge_power_w":{
"anyOf":[
{
"type":"number",
"minimum":0.0
},
{
"type":"null"
}
],
"title":"Max Ac Charge Power W",
"description":"Maximum AC charging power in watts. None means no additional limit (battery's own max_charge_power_w applies). Set to 0 to disable AC charging.",
"description":"An array of floats representing the temperature forecast in degrees Celsius for different time intervals."
},
"start_solution":{
"anyOf":[
{
"items":{
"type":"number"
},
"type":"array"
},
{
"type":"null"
}
],
"title":"Start Solution",
"description":"Can be `null` or contain a previous solution (if available)."
}
},
"type":"object",
"required":[
"ems",
"pv_battery",
"inverter",
"ev"
],
"title":"Genetic0OptimizationParameters",
"description":"Main parameter class for running the genetic energy optimization.\n\nCollects all model and configuration parameters necessary to run the\noptimization process, such as forecasts, pricing, battery and appliance models."
"description":"Main parameter class for running the genetic energy optimization.\n\nCollects all model and configuration parameters necessary to run the\noptimization process, such as forecasts, pricing, battery and appliance models."
"description":"Electric vehicle state after optimization."
},
"start_hour":{
"type":"integer",
"title":"Start Hour",
"description":"Start hour.",
"default":0
},
"start_solution":{
"anyOf":[
{
"items":{
"type":"number"
},
"type":"array"
},
{
"type":"null"
}
],
"title":"Start Solution",
"description":"An array of binary values (0 or 1) representing a possible starting solution for the simulation."
},
"washingstart":{
"anyOf":[
{
"type":"integer"
},
{
"type":"null"
}
],
"title":"Washingstart",
"description":"Can be `null` or contain an object representing the start of washing (if applicable)."
},
"extra_data":{
"anyOf":[
{
"additionalProperties":{
"anyOf":[
{
"items":{
"type":"integer"
},
"type":"array"
},
{
"items":{
"type":"number"
},
"type":"array"
}
]
},
"type":"object"
},
{
"type":"null"
}
],
"title":"Extra Data",
"description":"Dictionary of balance: TBD, losses: TBD, constraints: TBD."
},
"fitness_history":{
"anyOf":[
{
"additionalProperties":{
"anyOf":[
{
"items":{
"type":"integer"
},
"type":"array"
},
{
"items":{
"type":"number"
},
"type":"array"
}
]
},
"type":"object"
},
{
"type":"null"
}
],
"title":"Fitness History",
"description":"Dictionary of gen: Generation numbers (X-axis), avg: Average fitness for each generation (Y-axis), max: Maximum fitness for each generation (Y-axis), min: Minimum fitness for each generation (Y-axis)."
},
"fixed_seed":{
"anyOf":[
{
"type":"integer"
},
{
"type":"null"
}
],
"title":"Fixed Seed",
"description":"Fixed seed."
},
"eautocharge_hours_float":{
"anyOf":[
{
"items":{
"type":"number"
},
"type":"array"
},
{
"type":"null"
}
],
"title":"Eautocharge Hours Float",
"description":"Deprecated: Use ev_charge_hours_float instead.",
"description":"**Note**: The first value of \"load_wh_per_hour\", \"grid_feed_in_wh_per_hour\", and \"grid_consumption_wh_per_hour\", will be set to null in the JSON output and represented as NaN or None in the corresponding classes' data returns. This approach is adopted to ensure that the current hour's processing remains unchanged."
"description":"Maximum age of SoC measurements for configuration-based optimization [s].",
"default":300
},
"tail_horizon_hours":{
"type":"integer",
"minimum":0.0,
"title":"Tail Horizon Hours",
"description":"Forecast lookahead after the control horizon [h]. No tail commands are issued. Set 0 to disable.",
"default":48
},
"terminal_value_mode":{
"$ref":"#/components/schemas/TerminalValueMode",
"description":"How to value the energy left in the battery at the end of the control horizon. AUTO solves the forecast tail with an AUTO continuation proxy at its end (or only the proxy if tail is zero); FIXED uses 'terminal_value_euro_per_kwh'. Defaults to AUTO.",
"default":"AUTO",
"examples":[
"AUTO",
"FIXED"
]
},
"terminal_value_euro_per_kwh":{
"type":"number",
"title":"Terminal Value Euro Per Kwh",
"description":"Value assigned to usable battery energy remaining at the end of the optimization horizon [EUR/kWh]. This terminal value is independent of the battery LCOS. Only used with terminal_value_mode = FIXED. Defaults to 0 EUR/kWh.",
"default":0.0,
"examples":[
0.0,
0.2
]
},
"terminal_value_window_hours":{
"type":"integer",
"minimum":1.0,
"title":"Terminal Value Window Hours",
"description":"Length of the trailing window at the effective tail end the AUTO continuation curve is derived from [h]. One day covers a full load and PV cycle. Defaults to 24 hours.",
"description":"Maximum age of SoC measurements for configuration-based optimization [s].",
"default":300
},
"tail_horizon_hours":{
"type":"integer",
"minimum":0.0,
"title":"Tail Horizon Hours",
"description":"Forecast lookahead after the control horizon [h]. No tail commands are issued. Set 0 to disable.",
"default":48
},
"terminal_value_mode":{
"$ref":"#/components/schemas/TerminalValueMode",
"description":"How to value the energy left in the battery at the end of the control horizon. AUTO solves the forecast tail with an AUTO continuation proxy at its end (or only the proxy if tail is zero); FIXED uses 'terminal_value_euro_per_kwh'. Defaults to AUTO.",
"default":"AUTO",
"examples":[
"AUTO",
"FIXED"
]
},
"terminal_value_euro_per_kwh":{
"type":"number",
"title":"Terminal Value Euro Per Kwh",
"description":"Value assigned to usable battery energy remaining at the end of the optimization horizon [EUR/kWh]. This terminal value is independent of the battery LCOS. Only used with terminal_value_mode = FIXED. Defaults to 0 EUR/kWh.",
"default":0.0,
"examples":[
0.0,
0.2
]
},
"terminal_value_window_hours":{
"type":"integer",
"minimum":1.0,
"title":"Terminal Value Window Hours",
"description":"Length of the trailing window at the effective tail end the AUTO continuation curve is derived from [h]. One day covers a full load and PV cycle. Defaults to 24 hours.",
"description":"List of flexible consumers (home appliances) to schedule."
},
"start_solution_datetime":{
"anyOf":[
{
"type":"string",
"format":"date-time"
},
{
"type":"null"
}
],
"title":"Start Solution Datetime",
"description":"Start of the slot that gene 0 of 'start_solution' controls, as returned with the previous solution. The warm start is shifted by the slots that have elapsed until this run. Without it, a 'start_solution' identical to the last solution of this server uses that solution's start; any other one is used unshifted.",
"description":"Main parameter class for running the genetic energy optimization.\n\nCollects all model and configuration parameters necessary to run the\noptimization process, such as forecasts, pricing, battery and appliance models."
"description":"Dictionary of gen: Generation numbers (X-axis), avg: Average fitness for each generation (Y-axis), max: Maximum fitness for each generation (Y-axis), min: Minimum fitness for each generation (Y-axis)."
"description":"Control arrays start at the run timestamp instead of midnight.",
"default":false
},
"battery_grid_export_allowed":{
"items":{
"type":"integer"
},
"type":"array",
"title":"Battery Grid Export Allowed",
"description":"Array with battery-to-grid export values (1 for export discharge, 0 otherwise)."
},
"terminal_value":{
"anyOf":[
{
"$ref":"#/components/schemas/TerminalValueResult"
},
{
"type":"null"
}
],
"description":"The terminal value applied to the energy left in the battery at the end of the horizon, including the curve it was read from. None when no battery is part of the optimization."
},
"battery_grid_export_factor":{
"items":{
"type":"number"
},
"type":"array",
"title":"Battery Grid Export Factor",
"description":"Array with the battery-to-grid export level per slot as factor of the rated discharge power (0.0 for no export). Empty when direct marketing is disabled; a solution without this array exports at full power wherever 'battery_grid_export_allowed' is 1."
},
"start_solution_datetime":{
"anyOf":[
{
"type":"string",
"format":"date-time"
},
{
"type":"null"
}
],
"title":"Start Solution Datetime",
"description":"Start of the slot that gene 0 of 'start_solution' controls. Send it back together with 'start_solution' so the next run can shift the warm start by the slots that have elapsed since.",
"examples":[
null,
"2026-09-14T07:45:00+02:00"
]
},
"appliance_starts":{
"additionalProperties":{
"items":{
"type":"string",
"format":"date-time"
},
"type":"array"
},
"type":"object",
"title":"Appliance Starts",
"description":"Scheduled run start times per appliance device_id as absolute local datetimes."
},
"appliance_deadline_missed":{
"additionalProperties":{
"type":"boolean"
},
"type":"object",
"title":"Appliance Deadline Missed",
"description":"Per appliance device_id with a 'deadline_datetime': whether the scheduled run misses that deadline (or was not scheduled at all). Appliances without a deadline are not listed."
},
"interval_seconds":{
"type":"integer",
"title":"Interval Seconds",
"description":"Duration of one result/control slot in seconds.",
"description":"**Note**: The first value of \"load_wh_per_hour\", \"grid_feed_in_wh_per_hour\", and \"grid_consumption_wh_per_hour\", will be set to null in the JSON output and represented as NaN or None in the corresponding classes' data returns. This approach is adopted to ensure that the current hour's processing remains unchanged."
"description":"Number of times the appliance must run within the horizon. Required when cycle_time_windows is null (unconstrained). Ignored when cycle_time_windows is provided -- the number of distinct cycle indices in the windows defines num_cycles. Defaults to 1.",
"description":"Per-cycle allowed scheduling time windows. Each window's value field specifies the cycle index (0-based). When null, the appliance may start at any step and num_cycles must be set explicitly.",
"description":"Minimum idle time between the end of one cycle and the start of the next [h]. Applies uniformly between all consecutive cycles. 0 means back-to-back runs are permitted.",
"default":0,
"examples":[
0,
1,
4
],
"x-scope":[
"GENETIC"
]
},
"cycles_completed_measurement_key":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Cycles Completed Measurement Key",
"description":"Measurement store key holding the number of cycles already completed in the current planning day. Read by HomeApplianceDevice.setup_run via context.resolve_measurement. Defaults to '{device_id}.cycles_completed' when null.",
"description":"Explicit load profile describing a single complete run as a sequence of non-negative power values in watts. Each value covers 'load_profile_interval_seconds'. Mutually exclusive with consumption_wh/duration_h.",
"examples":[
[
200.0,
2000.0,
1800.0,
100.0
]
],
"x-scope":[
"GENETIC"
]
},
"load_profile_interval_seconds":{
"anyOf":[
{
"type":"integer",
"exclusiveMinimum":0.0
},
{
"type":"null"
}
],
"title":"Load Profile Interval Seconds",
"description":"Duration of one 'load_profile_power_w' step in seconds. Defaults to the configured optimization interval when a profile is given.",
"description":"List of allowed time windows. Defaults to optimization general time window.",
"examples":[
[
{
"duration":"3 hours",
"start_time":"10:00"
}
]
],
"x-scope":[
"GENETIC"
]
},
"earliest_start_datetime":{
"anyOf":[
{
"type":"string",
"format":"date-time"
},
{
"type":"null"
}
],
"title":"Earliest Start Datetime",
"description":"Absolute earliest moment the run may start. Starts before it are dropped, in addition to 'time_windows' and the horizon. A date time without timezone is read as local time. This bound is never relaxed.",
"examples":[
null,
"2026-07-15T20:00:00+02:00"
],
"x-scope":[
"GENETIC"
]
},
"deadline_datetime":{
"anyOf":[
{
"type":"string",
"format":"date-time"
},
{
"type":"null"
}
],
"title":"Deadline Datetime",
"description":"Absolute deadline: the complete run must have *finished* at or before this moment (e.g. end of the day, or 03:00 tonight). A date time without timezone is read as local time. See 'deadline_policy' for what happens when no start can meet it.",
"description":"What to do when 'deadline_datetime' cannot be met: BEST_EFFORT runs as early as possible instead (warning logged), STRICT keeps the deadline (a ONCE consumer then fails the optimization).",
"description":"Controllable home appliance device settings.\n\nRepresents a shiftable load whose start time \u2014 and optionally the\nstart times for multiple sequential runs \u2014 can be deferred by the\noptimiser within per-cycle allowed time windows.\n\nThe number of remaining cycles to plan is determined at runtime by\nreading ``cycles_completed_measurement_key`` from the measurement\nstore inside ``HomeApplianceDevice.setup_run``.\n\n``num_cycles`` is required when ``cycle_time_windows`` is ``None``\n(unconstrained); when windows are provided it is derived from\n``cycle_time_windows.num_cycles()``.\n\nSingle-cycle, unconstrained (start any time)\n---------------------------------------------\n\n::\n\n device_id: dishwasher\n consumption_wh: 1500\n duration_h: 2\n num_cycles: 1\n ports:\n - port_id: p_ac\n bus_id: bus_ac\n direction: sink\n\nSingle-cycle, constrained to one window\n----------------------------------------\n\nEach window's ``value`` field carries the **cycle index** (0-based).\nWindows without a ``value`` are ignored by the optimizer::\n\n device_id: dishwasher\n consumption_wh: 1500\n duration_h: 2\n ports:\n - port_id: p_ac\n bus_id: bus_ac\n direction: sink\n cycle_time_windows:\n windows:\n - start_time: \"10:00\"\n duration: \"12 hours\"\n value: 0\n\nMulti-cycle, per-cycle windows\n--------------------------------\n\nTwo cycles, each with its own window. Cycle 0 runs in the morning,\ncycle 1 in the evening::\n\n device_id: washing_machine\n consumption_wh: 2000\n duration_h: 2\n min_cycle_gap_h: 1\n ports:\n - port_id: p_ac\n bus_id: bus_ac\n direction: sink\n cycle_time_windows:\n windows:\n - start_time: \"07:00\"\n duration: \"5 hours\"\n value: 0\n - start_time: \"17:00\"\n duration: \"5 hours\"\n value: 1\n\nMulti-cycle, shared window (both cycles may run any time 10:00-20:00)\n-----------------------------------------------------------------------\n\nAssign the same-shaped windows to distinct cycle indices so the\noptimizer can place them independently::\n\n cycle_time_windows:\n windows:\n - start_time: \"10:00\"\n duration: \"10 hours\"\n value: 0\n - start_time: \"10:00\"\n duration: \"10 hours\"\n value: 1"
"description":"Number of times the appliance must run within the horizon. Required when cycle_time_windows is null (unconstrained). Ignored when cycle_time_windows is provided -- the number of distinct cycle indices in the windows defines num_cycles. Defaults to 1.",
"description":"Per-cycle allowed scheduling time windows. Each window's value field specifies the cycle index (0-based). When null, the appliance may start at any step and num_cycles must be set explicitly.",
"description":"Minimum idle time between the end of one cycle and the start of the next [h]. Applies uniformly between all consecutive cycles. 0 means back-to-back runs are permitted.",
"default":0,
"examples":[
0,
1,
4
],
"x-scope":[
"GENETIC"
]
},
"cycles_completed_measurement_key":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Cycles Completed Measurement Key",
"description":"Measurement store key holding the number of cycles already completed in the current planning day. Read by HomeApplianceDevice.setup_run via context.resolve_measurement. Defaults to '{device_id}.cycles_completed' when null.",
"description":"Explicit load profile describing a single complete run as a sequence of non-negative power values in watts. Each value covers 'load_profile_interval_seconds'. Mutually exclusive with consumption_wh/duration_h.",
"examples":[
[
200.0,
2000.0,
1800.0,
100.0
]
],
"x-scope":[
"GENETIC"
]
},
"load_profile_interval_seconds":{
"anyOf":[
{
"type":"integer",
"exclusiveMinimum":0.0
},
{
"type":"null"
}
],
"title":"Load Profile Interval Seconds",
"description":"Duration of one 'load_profile_power_w' step in seconds. Defaults to the configured optimization interval when a profile is given.",
"description":"List of allowed time windows. Defaults to optimization general time window.",
"examples":[
[
{
"duration":"3 hours",
"start_time":"10:00"
}
]
],
"x-scope":[
"GENETIC"
]
},
"earliest_start_datetime":{
"anyOf":[
{
"type":"string",
"format":"date-time"
},
{
"type":"null"
}
],
"title":"Earliest Start Datetime",
"description":"Absolute earliest moment the run may start. Starts before it are dropped, in addition to 'time_windows' and the horizon. A date time without timezone is read as local time. This bound is never relaxed.",
"examples":[
null,
"2026-07-15T20:00:00+02:00"
],
"x-scope":[
"GENETIC"
]
},
"deadline_datetime":{
"anyOf":[
{
"type":"string",
"format":"date-time"
},
{
"type":"null"
}
],
"title":"Deadline Datetime",
"description":"Absolute deadline: the complete run must have *finished* at or before this moment (e.g. end of the day, or 03:00 tonight). A date time without timezone is read as local time. See 'deadline_policy' for what happens when no start can meet it.",
"description":"What to do when 'deadline_datetime' cannot be met: BEST_EFFORT runs as early as possible instead (warning logged), STRICT keeps the deadline (a ONCE consumer then fails the optimization).",
"description":"Number of cycles as seen by the optimizer.\n\nDerived from cycle_time_windows.num_cycles() when windows are\nprovided; falls back to the explicit num_cycles field otherwise.",
"description":"Controllable home appliance device settings.\n\nRepresents a shiftable load whose start time \u2014 and optionally the\nstart times for multiple sequential runs \u2014 can be deferred by the\noptimiser within per-cycle allowed time windows.\n\nThe number of remaining cycles to plan is determined at runtime by\nreading ``cycles_completed_measurement_key`` from the measurement\nstore inside ``HomeApplianceDevice.setup_run``.\n\n``num_cycles`` is required when ``cycle_time_windows`` is ``None``\n(unconstrained); when windows are provided it is derived from\n``cycle_time_windows.num_cycles()``.\n\nSingle-cycle, unconstrained (start any time)\n---------------------------------------------\n\n::\n\n device_id: dishwasher\n consumption_wh: 1500\n duration_h: 2\n num_cycles: 1\n ports:\n - port_id: p_ac\n bus_id: bus_ac\n direction: sink\n\nSingle-cycle, constrained to one window\n----------------------------------------\n\nEach window's ``value`` field carries the **cycle index** (0-based).\nWindows without a ``value`` are ignored by the optimizer::\n\n device_id: dishwasher\n consumption_wh: 1500\n duration_h: 2\n ports:\n - port_id: p_ac\n bus_id: bus_ac\n direction: sink\n cycle_time_windows:\n windows:\n - start_time: \"10:00\"\n duration: \"12 hours\"\n value: 0\n\nMulti-cycle, per-cycle windows\n--------------------------------\n\nTwo cycles, each with its own window. Cycle 0 runs in the morning,\ncycle 1 in the evening::\n\n device_id: washing_machine\n consumption_wh: 2000\n duration_h: 2\n min_cycle_gap_h: 1\n ports:\n - port_id: p_ac\n bus_id: bus_ac\n direction: sink\n cycle_time_windows:\n windows:\n - start_time: \"07:00\"\n duration: \"5 hours\"\n value: 0\n - start_time: \"17:00\"\n duration: \"5 hours\"\n value: 1\n\nMulti-cycle, shared window (both cycles may run any time 10:00-20:00)\n-----------------------------------------------------------------------\n\nAssign the same-shaped windows to distinct cycle indices so the\noptimizer can place them independently::\n\n cycle_time_windows:\n windows:\n - start_time: \"10:00\"\n duration: \"10 hours\"\n value: 0\n - start_time: \"10:00\"\n duration: \"10 hours\"\n value: 1"
"description":"Allowed per-cycle time windows. Each window's `value` encodes the 0-based cycle index it applies to; multiple windows may share a cycle index. When omitted, every cycle is unconstrained across the full prediction horizon.",
"description":"Allowed recurring windows shared by every cycle; intersected with per-cycle windows."
},
"load_profile_power_w":{
"anyOf":[
{
"items":{
"type":"number"
},
"type":"array"
},
{
"type":"null"
}
],
"title":"Load Profile Power W",
"description":"Explicit load profile describing a single complete run as a sequence of non-negative power values in watts. Each value covers 'load_profile_interval_seconds'. Mutually exclusive with consumption_wh/duration_h.",
"examples":[
[
200.0,
2000.0,
1800.0,
100.0
]
]
},
"load_profile_interval_seconds":{
"anyOf":[
{
"type":"integer",
"exclusiveMinimum":0.0
},
{
"type":"null"
}
],
"title":"Load Profile Interval Seconds",
"description":"Duration of one 'load_profile_power_w' step in seconds. Defaults to the configured optimization interval when a profile is given.",
"description":"Scheduling mode: ONCE (a single run within the horizon) or DAILY (one run per local calendar day with a feasible full run).",
"default":"ONCE",
"examples":[
"ONCE",
"DAILY"
]
},
"earliest_start_datetime":{
"anyOf":[
{
"type":"string",
"format":"date-time"
},
{
"type":"null"
}
],
"title":"Earliest Start Datetime",
"description":"Absolute earliest moment the run may start. Starts before it are dropped, in addition to 'time_windows' and the horizon. A date time without timezone is read as local time. This bound is never relaxed.",
"examples":[
null,
"2026-07-15T20:00:00+02:00"
]
},
"deadline_datetime":{
"anyOf":[
{
"type":"string",
"format":"date-time"
},
{
"type":"null"
}
],
"title":"Deadline Datetime",
"description":"Absolute deadline: the complete run must have *finished* at or before this moment (e.g. end of the day, or 03:00 tonight). A date time without timezone is read as local time. See 'deadline_policy' for what happens when no start can meet it.",
"description":"What to do when 'deadline_datetime' cannot be met: BEST_EFFORT runs as early as possible instead (warning logged), STRICT keeps the deadline (a ONCE consumer then fails the optimization).",
"description":"Mapping of EOS config keys to Home Assistant entity IDs.\nThe config key has to be given by a \u2018/\u2019-separated path\ne.g. devices/batteries/0/capacity_wh",
"description":"Entity IDs for device (resource) instructions to be updated by EOS.\nThe device ids (resource ids) have to be prepended by 'sensor.eos_' to build the entity_id.\nE.g. The instruction for device id 'battery1' becomes the entity_id 'sensor.eos_battery1'.",
"examples":[
[
"sensor.eos_battery1"
]
]
},
"solution_entity_ids":{
"anyOf":[
{
"items":{
"type":"string"
},
"type":"array"
},
{
"type":"null"
}
],
"title":"Solution Entity Ids",
"description":"Entity IDs for optimization solution keys to be updated by EOS.\nThe solution keys have to be prepended by 'sensor.eos_' to build the entity_id.\nE.g. solution key 'battery1_idle_op_mode' becomes the entity_id 'sensor.eos_battery1_idle_op_mode'.",
"examples":[
[
"sensor.eos_battery1_idle_mode_mode"
]
]
}
},
"type":"object",
"title":"HomeAssistantAdapterCommonSettings",
"description":"Common settings for the home assistant adapter."
},
"HomeAssistantAdapterCommonSettings-Output":{
"properties":{
"config_entity_ids":{
"anyOf":[
{
"additionalProperties":{
"type":"string"
},
"type":"object"
},
{
"type":"null"
}
],
"title":"Config Entity Ids",
"description":"Mapping of EOS config keys to Home Assistant entity IDs.\nThe config key has to be given by a \u2018/\u2019-separated path\ne.g. devices/batteries/0/capacity_wh",
"description":"Entity IDs for device (resource) instructions to be updated by EOS.\nThe device ids (resource ids) have to be prepended by 'sensor.eos_' to build the entity_id.\nE.g. The instruction for device id 'battery1' becomes the entity_id 'sensor.eos_battery1'.",
"examples":[
[
"sensor.eos_battery1"
]
]
},
"solution_entity_ids":{
"anyOf":[
{
"items":{
"type":"string"
},
"type":"array"
},
{
"type":"null"
}
],
"title":"Solution Entity Ids",
"description":"Entity IDs for optimization solution keys to be updated by EOS.\nThe solution keys have to be prepended by 'sensor.eos_' to build the entity_id.\nE.g. solution key 'battery1_idle_op_mode' becomes the entity_id 'sensor.eos_battery1_idle_op_mode'.",
"examples":[
[
"sensor.eos_battery1_idle_mode_mode"
]
]
},
"homeassistant_entity_ids":{
"items":{
"type":"string"
},
"type":"array",
"title":"Homeassistant Entity Ids",
"description":"Entity IDs available at Home Assistant.",
"readOnly":true
},
"eos_solution_entity_ids":{
"items":{
"type":"string"
},
"type":"array",
"title":"Eos Solution Entity Ids",
"description":"Entity IDs for optimization solution available at EOS.",
"readOnly":true
},
"eos_device_instruction_entity_ids":{
"items":{
"type":"string"
},
"type":"array",
"title":"Eos Device Instruction Entity Ids",
"description":"Entity IDs for energy management instructions available at EOS.",
"readOnly":true
}
},
"type":"object",
"required":[
"homeassistant_entity_ids",
"eos_solution_entity_ids",
"eos_device_instruction_entity_ids"
],
"title":"HomeAssistantAdapterCommonSettings",
"description":"Common settings for the home assistant adapter."
"description":"A non-overlapping AC branch; polarity normalizes the sensor's sign."
},
"HouseholdSettings":{
"properties":{
"topology":{
"type":"string",
"enum":[
"direct",
"separate_ac",
"hybrid_ac"
],
"title":"Topology"
},
"inputs":{
"items":{
"$ref":"#/components/schemas/HouseholdInput"
},
"type":"array",
"minItems":1,
"title":"Inputs"
}
},
"additionalProperties":false,
"type":"object",
"required":[
"topology",
"inputs"
],
"title":"HouseholdSettings",
"description":"Fixed topology, never user-supplied executable balance expressions.\n\nGrid import, PV production and battery/inverter discharge are positive.\nEV/device inputs are positive consumption, subtracted only from derived loads."
"description":"True if the AC charge setpoint caps the battery's total charge power, PV included. Some hybrid inverters (e.g. Deye in time-of-use grid charging) limit the whole charge current to the grid charge current; PV surplus above it is exported, not stored. False keeps the default model: PV surplus charges first and the grid adds ac_charge x max_charge_power_w on top.",
"description":"Standby power consumed when the inverter is fully idle (battery=0 and PV=0) [W]. Default 0.0.",
"default":0.0,
"examples":[
5.0,
0.0
],
"x-scope":[
"UNUSED"
]
},
"on_state_power_consumption_w":{
"type":"number",
"minimum":0.0,
"title":"On State Power Consumption W",
"description":"Auxiliary power consumed whenever the inverter is active (non-zero AC power) [W]. Default 0.0.",
"default":0.0,
"examples":[
10.0,
0.0
],
"x-scope":[
"UNUSED"
]
},
"pv_to_ac_efficiency":{
"type":"number",
"maximum":1.0,
"exclusiveMinimum":0.0,
"title":"Pv To Ac Efficiency",
"description":"Efficiency of PV DC\u2192AC conversion (0\u20131). Required when pv_power_w_key is set (SOLAR or HYBRID). Default 1.0.",
"default":1.0,
"examples":[
0.97,
1.0
],
"x-scope":[
"UNUSED"
]
},
"pv_to_battery_efficiency":{
"type":"number",
"maximum":1.0,
"exclusiveMinimum":0.0,
"title":"Pv To Battery Efficiency",
"description":"Efficiency of PV DC\u2192battery charging path (0\u20131). Used for HYBRID inverters only. Default 1.0.",
"default":1.0,
"examples":[
0.98,
1.0
],
"x-scope":[
"UNUSED"
]
},
"pv_max_power_w":{
"anyOf":[
{
"type":"number",
"exclusiveMinimum":0.0
},
{
"type":"null"
}
],
"title":"Pv Max Power W",
"description":"Maximum DC PV power fed into the inverter [W]. Required when pv_power_w_key is set (SOLAR or HYBRID). Values from pv_power_w_key are clipped to this limit.",
"examples":[
8000.0
],
"x-scope":[
"UNUSED"
]
},
"pv_min_power_w":{
"type":"number",
"minimum":0.0,
"title":"Pv Min Power W",
"description":"Minimum DC PV power threshold [W]. Steps with available PV below this value are treated as zero. Default 0.0.",
"default":0.0,
"examples":[
50.0,
0.0
],
"x-scope":[
"UNUSED"
]
},
"pv_power_w_key":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Pv Power W Key",
"description":"SimulationContext prediction key resolving to a per-step PV power forecast array [W] of shape (horizon,). Set for SOLAR and HYBRID inverter types; leave None for BATTERY.",
"examples":[
"pv_forecast_w",
null
],
"x-scope":[
"UNUSED"
]
},
"battery_capacity_wh":{
"anyOf":[
{
"type":"number",
"exclusiveMinimum":0.0
},
{
"type":"null"
}
],
"title":"Battery Capacity Wh",
"description":"Usable battery capacity [Wh]. Required for BATTERY and HYBRID inverter types.",
"examples":[
10000.0
],
"x-scope":[
"UNUSED"
]
},
"battery_charge_rates":{
"anyOf":[
{
"items":{
"type":"number"
},
"type":"array"
},
{
"type":"null"
}
],
"title":"Battery Charge Rates",
"description":"Optional list of discrete charge rate fractions (each in (0, 1]). When set, the battery is constrained to these specific fractions of battery_max_charge_rate. null means continuous charging. All values must be in (0, 1].",
"examples":[
null,
[
0.25,
0.5,
1.0
]
],
"x-scope":[
"UNUSED"
]
},
"battery_min_charge_rate":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Battery Min Charge Rate",
"description":"Minimum non-zero charge rate as a fraction of the 1C rate (1C = battery_capacity_wh W). Charge commands below this threshold are rounded to zero. Default 0.0.",
"default":0.0,
"examples":[
0.1,
0.0
],
"x-scope":[
"UNUSED"
]
},
"battery_max_charge_rate":{
"type":"number",
"maximum":1.0,
"exclusiveMinimum":0.0,
"title":"Battery Max Charge Rate",
"description":"Maximum charge rate as a fraction of the 1C rate (1C = battery_capacity_wh W). bat_factor=+1 maps to this rate. Default 1.0.",
"default":1.0,
"examples":[
0.5,
1.0
],
"x-scope":[
"UNUSED"
]
},
"battery_min_discharge_rate":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Battery Min Discharge Rate",
"description":"Minimum discharge rate as a fraction of the 1C rate (1C = battery_capacity_wh W). Discharge commands below this threshold are rounded to zero. Default 0.0.",
"default":0.0,
"examples":[
0.1,
0.0
],
"x-scope":[
"UNUSED"
]
},
"battery_max_discharge_rate":{
"type":"number",
"maximum":1.0,
"exclusiveMinimum":0.0,
"title":"Battery Max Discharge Rate",
"description":"Maximum discharge rate as a fraction of the 1C rate. (1C = battery_capacity_wh W). bat_factor=\u22121 maps to this rate. Default 1.0.",
"default":1.0,
"examples":[
0.5,
1.0
],
"x-scope":[
"UNUSED"
]
},
"battery_min_soc_factor":{
"type":"number",
"exclusiveMaximum":1.0,
"minimum":0.0,
"title":"Battery Min Soc Factor",
"description":"Minimum allowed state of charge as a fraction of battery_capacity_wh. Must be < battery_max_soc_factor. Default 0.0.",
"default":0.0,
"examples":[
0.1,
0.0
],
"x-scope":[
"UNUSED"
]
},
"battery_max_soc_factor":{
"type":"number",
"maximum":1.0,
"exclusiveMinimum":0.0,
"title":"Battery Max Soc Factor",
"description":"Maximum allowed state of charge as a fraction of battery_capacity_wh. Must be > battery_min_soc_factor. Default 1.0.",
"default":1.0,
"examples":[
0.9,
1.0
],
"x-scope":[
"UNUSED"
]
},
"battery_initial_soc_factor_key":{
"type":"string",
"title":"Battery Initial Soc Factor Key",
"description":"SimulationContext measurement key resolving to the initial battery SoC as a fraction of battery_capacity_wh, in [min_soc_factor, max_soc_factor]. An empty string means the device uses battery_min_soc_factor as the initial SoC (fully depleted to the minimum).",
"default":"",
"examples":[
"battery1_soc_factor",
""
],
"x-scope":[
"UNUSED"
]
},
"battery_lcos_amt_kwh":{
"type":"number",
"minimum":0.0,
"title":"Battery Lcos Amt Kwh",
"description":"Levelized cost of battery storage [Amt./kWh cycled]. Penalises unnecessary charging/discharging so the GA avoids grid-charge\u2192discharge cycles with no price-spread benefit. Typical residential Li-ion value: 0.05 Amt./kWh. Set to 0.0 to encourage the optimizer to use the battery. Defaults to 0.0.",
"default":0.0,
"examples":[
0.05,
0.0
],
"x-scope":[
"UNUSED"
]
},
"battery_discharge_reward_amt_kwh":{
"type":"number",
"minimum":0.0,
"title":"Battery Discharge Reward Amt Kwh",
"description":"Shadow price rewarding battery discharge [Amt./kWh discharged AC]. Adds a direct fitness benefit per kWh the battery delivers, on top of the grid import cost reduction already captured by GridConnectionDevice. Helps the GA discover discharge when the load-matching rate is small relative to mutation noise. Suggested value: import_price - export_price - lcos (e.g. 0.30 - 0.08 - 0.05 = 0.17). Set to 0.0 to disable.",
"description":"Inverter device settings.\n\nAn inverter bridges a DC bus (PV / battery) and an AC bus (grid /\nhousehold). It must therefore have at least one DC port and one AC\nport."
"description":"True if the AC charge setpoint caps the battery's total charge power, PV included. Some hybrid inverters (e.g. Deye in time-of-use grid charging) limit the whole charge current to the grid charge current; PV surplus above it is exported, not stored. False keeps the default model: PV surplus charges first and the grid adds ac_charge x max_charge_power_w on top.",
"description":"Standby power consumed when the inverter is fully idle (battery=0 and PV=0) [W]. Default 0.0.",
"default":0.0,
"examples":[
5.0,
0.0
],
"x-scope":[
"UNUSED"
]
},
"on_state_power_consumption_w":{
"type":"number",
"minimum":0.0,
"title":"On State Power Consumption W",
"description":"Auxiliary power consumed whenever the inverter is active (non-zero AC power) [W]. Default 0.0.",
"default":0.0,
"examples":[
10.0,
0.0
],
"x-scope":[
"UNUSED"
]
},
"pv_to_ac_efficiency":{
"type":"number",
"maximum":1.0,
"exclusiveMinimum":0.0,
"title":"Pv To Ac Efficiency",
"description":"Efficiency of PV DC\u2192AC conversion (0\u20131). Required when pv_power_w_key is set (SOLAR or HYBRID). Default 1.0.",
"default":1.0,
"examples":[
0.97,
1.0
],
"x-scope":[
"UNUSED"
]
},
"pv_to_battery_efficiency":{
"type":"number",
"maximum":1.0,
"exclusiveMinimum":0.0,
"title":"Pv To Battery Efficiency",
"description":"Efficiency of PV DC\u2192battery charging path (0\u20131). Used for HYBRID inverters only. Default 1.0.",
"default":1.0,
"examples":[
0.98,
1.0
],
"x-scope":[
"UNUSED"
]
},
"pv_max_power_w":{
"anyOf":[
{
"type":"number",
"exclusiveMinimum":0.0
},
{
"type":"null"
}
],
"title":"Pv Max Power W",
"description":"Maximum DC PV power fed into the inverter [W]. Required when pv_power_w_key is set (SOLAR or HYBRID). Values from pv_power_w_key are clipped to this limit.",
"examples":[
8000.0
],
"x-scope":[
"UNUSED"
]
},
"pv_min_power_w":{
"type":"number",
"minimum":0.0,
"title":"Pv Min Power W",
"description":"Minimum DC PV power threshold [W]. Steps with available PV below this value are treated as zero. Default 0.0.",
"default":0.0,
"examples":[
50.0,
0.0
],
"x-scope":[
"UNUSED"
]
},
"pv_power_w_key":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Pv Power W Key",
"description":"SimulationContext prediction key resolving to a per-step PV power forecast array [W] of shape (horizon,). Set for SOLAR and HYBRID inverter types; leave None for BATTERY.",
"examples":[
"pv_forecast_w",
null
],
"x-scope":[
"UNUSED"
]
},
"battery_capacity_wh":{
"anyOf":[
{
"type":"number",
"exclusiveMinimum":0.0
},
{
"type":"null"
}
],
"title":"Battery Capacity Wh",
"description":"Usable battery capacity [Wh]. Required for BATTERY and HYBRID inverter types.",
"description":"Optional list of discrete charge rate fractions (each in (0, 1]). When set, the battery is constrained to these specific fractions of battery_max_charge_rate. null means continuous charging. All values must be in (0, 1].",
"examples":[
null,
[
0.25,
0.5,
1.0
]
],
"x-scope":[
"UNUSED"
]
},
"battery_min_charge_rate":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Battery Min Charge Rate",
"description":"Minimum non-zero charge rate as a fraction of the 1C rate (1C = battery_capacity_wh W). Charge commands below this threshold are rounded to zero. Default 0.0.",
"default":0.0,
"examples":[
0.1,
0.0
],
"x-scope":[
"UNUSED"
]
},
"battery_max_charge_rate":{
"type":"number",
"maximum":1.0,
"exclusiveMinimum":0.0,
"title":"Battery Max Charge Rate",
"description":"Maximum charge rate as a fraction of the 1C rate (1C = battery_capacity_wh W). bat_factor=+1 maps to this rate. Default 1.0.",
"default":1.0,
"examples":[
0.5,
1.0
],
"x-scope":[
"UNUSED"
]
},
"battery_min_discharge_rate":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Battery Min Discharge Rate",
"description":"Minimum discharge rate as a fraction of the 1C rate (1C = battery_capacity_wh W). Discharge commands below this threshold are rounded to zero. Default 0.0.",
"default":0.0,
"examples":[
0.1,
0.0
],
"x-scope":[
"UNUSED"
]
},
"battery_max_discharge_rate":{
"type":"number",
"maximum":1.0,
"exclusiveMinimum":0.0,
"title":"Battery Max Discharge Rate",
"description":"Maximum discharge rate as a fraction of the 1C rate. (1C = battery_capacity_wh W). bat_factor=\u22121 maps to this rate. Default 1.0.",
"default":1.0,
"examples":[
0.5,
1.0
],
"x-scope":[
"UNUSED"
]
},
"battery_min_soc_factor":{
"type":"number",
"exclusiveMaximum":1.0,
"minimum":0.0,
"title":"Battery Min Soc Factor",
"description":"Minimum allowed state of charge as a fraction of battery_capacity_wh. Must be < battery_max_soc_factor. Default 0.0.",
"default":0.0,
"examples":[
0.1,
0.0
],
"x-scope":[
"UNUSED"
]
},
"battery_max_soc_factor":{
"type":"number",
"maximum":1.0,
"exclusiveMinimum":0.0,
"title":"Battery Max Soc Factor",
"description":"Maximum allowed state of charge as a fraction of battery_capacity_wh. Must be > battery_min_soc_factor. Default 1.0.",
"default":1.0,
"examples":[
0.9,
1.0
],
"x-scope":[
"UNUSED"
]
},
"battery_initial_soc_factor_key":{
"type":"string",
"title":"Battery Initial Soc Factor Key",
"description":"SimulationContext measurement key resolving to the initial battery SoC as a fraction of battery_capacity_wh, in [min_soc_factor, max_soc_factor]. An empty string means the device uses battery_min_soc_factor as the initial SoC (fully depleted to the minimum).",
"default":"",
"examples":[
"battery1_soc_factor",
""
],
"x-scope":[
"UNUSED"
]
},
"battery_lcos_amt_kwh":{
"type":"number",
"minimum":0.0,
"title":"Battery Lcos Amt Kwh",
"description":"Levelized cost of battery storage [Amt./kWh cycled]. Penalises unnecessary charging/discharging so the GA avoids grid-charge\u2192discharge cycles with no price-spread benefit. Typical residential Li-ion value: 0.05 Amt./kWh. Set to 0.0 to encourage the optimizer to use the battery. Defaults to 0.0.",
"default":0.0,
"examples":[
0.05,
0.0
],
"x-scope":[
"UNUSED"
]
},
"battery_discharge_reward_amt_kwh":{
"type":"number",
"minimum":0.0,
"title":"Battery Discharge Reward Amt Kwh",
"description":"Shadow price rewarding battery discharge [Amt./kWh discharged AC]. Adds a direct fitness benefit per kWh the battery delivers, on top of the grid import cost reduction already captured by GridConnectionDevice. Helps the GA discover discharge when the load-matching rate is small relative to mutation noise. Suggested value: import_price - export_price - lcos (e.g. 0.30 - 0.08 - 0.05 = 0.17). Set to 0.0 to disable.",
"description":"Measurement keys for this inverter.\n\nReturns the ``battery_initial_soc_factor_key`` if non-empty, so\nthe EMS measurement store knows to watch for this key.",
"description":"Inverter device settings.\n\nAn inverter bridges a DC bus (PV / battery) and an AC bus (grid /\nhousehold). It must therefore have at least one DC port and one AC\nport."
"description":"Number of prediction hours. Defaults to global config prediction hours.",
"examples":[
null
]
},
"max_power_wh":{
"type":"number",
"exclusiveMinimum":0.0,
"title":"Max Power Wh",
"examples":[
10000
]
},
"battery_id":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Battery Id",
"description":"ID of battery",
"examples":[
null,
"battery1"
]
},
"ac_to_dc_efficiency":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Ac To Dc Efficiency",
"description":"Efficiency of AC to DC conversion (for AC/grid charging of battery). Set to 0 to disable AC charging via inverter. Default 1.0 for backward compatibility (no additional inverter loss).",
"default":1.0,
"examples":[
0.95,
1.0,
0.0
]
},
"dc_to_ac_efficiency":{
"type":"number",
"maximum":1.0,
"exclusiveMinimum":0.0,
"title":"Dc To Ac Efficiency",
"description":"Efficiency of DC to AC conversion (for battery discharging to AC load/grid). Default 1.0 for backward compatibility (no additional inverter loss).",
"default":1.0,
"examples":[
0.95,
1.0
]
},
"max_ac_charge_power_w":{
"anyOf":[
{
"type":"number",
"minimum":0.0
},
{
"type":"null"
}
],
"title":"Max Ac Charge Power W",
"description":"Maximum AC charging power in watts. None means no additional limit (battery's own max_charge_power_w applies). Set to 0 to disable AC charging.",
"description":"True if the AC charge setpoint caps the battery's total charge power, PV included. PV surplus above it is exported, not stored. False keeps the default model: PV surplus charges first and the grid adds ac_charge x max_charge_power_w on top.",
"description":"Common settings for the NodeRED adapter.\n\nThe Node-RED adapter sends to HTTP IN nodes.\n\nThis is the example flow:\n\n`[HTTP In <URL>] -> [Function (parse payload)] -> [Debug] -> [HTTP Response]`\n\nThere are two URLs that are used:\n\n- GET /eos/data_aquisition\n The GET is issued before the optimization.\n- POST /eos/control_dispatch\n The POST is issued after the optimization."
"description":"Unique identifier of the instruction in the ResourceManager scope. If not provided and a `resource_id` is passed at instantiation, this will be auto-generated as `{resource_id}@{UUID}`."
},
"execution_time":{
"type":"string",
"format":"date-time",
"title":"Execution Time",
"description":"Start time of the instruction execution."
},
"abnormal_condition":{
"type":"boolean",
"title":"Abnormal Condition",
"description":"Indicates if this is an instruction for abnormal conditions. Defaults to False.",
"default":false
},
"type":{
"type":"string",
"const":"OMBCInstruction",
"title":"Type",
"default":"OMBCInstruction"
},
"operation_mode_id":{
"type":"string",
"title":"Operation Mode Id",
"description":"ID of the OMBC.OperationMode to activate."
},
"operation_mode_factor":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Operation Mode Factor",
"description":"Factor with which the operation mode is configured (0 to 1)."
},
"resource_id":{
"type":"string",
"title":"Resource Id",
"description":"Get the resource identifier component from the instruction's `id`.\n\nAssumes the `id` follows the format `{resource_id}@{UUID}`. Extracts the resource_id part\nof the id by splitting at the last @.\n\nReturns:\n str: The resource identifier prefix of `id`, or an empty string if `id` is None.",
"readOnly":true
}
},
"type":"object",
"required":[
"execution_time",
"operation_mode_id",
"operation_mode_factor",
"resource_id"
],
"title":"OMBCInstruction",
"description":"Instruction for Operation Mode Based Control (OMBC).\n\nContains information about when and how to activate a specific operation mode.\nUsed to command resources to change their operation at a specified time."
},
"OMBCStatus":{
"properties":{
"type":{
"type":"string",
"const":"OMBCStatus",
"title":"Type",
"default":"OMBCStatus"
},
"active_operation_mode_id":{
"type":"string",
"title":"Active Operation Mode Id",
"description":"ID of the currently active operation mode."
},
"operation_mode_factor":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Operation Mode Factor",
"description":"Factor with which the operation mode is configured (between 0 and 1)."
},
"previous_operation_mode_id":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Previous Operation Mode Id",
"description":"ID of the previously active operation mode, if known."
},
"transition_timestamp":{
"anyOf":[
{
"type":"string",
"format":"date-time"
},
{
"type":"null"
}
],
"title":"Transition Timestamp",
"description":"Timestamp of transition to the active operation mode, if applicable."
}
},
"type":"object",
"required":[
"active_operation_mode_id",
"operation_mode_factor"
],
"title":"OMBCStatus",
"description":"Reports the current operational status of an Operation Mode Based Control system.\n\nThis model provides real-time status information about an OMBC-controlled device,\nincluding which operation mode is currently active, how it is configured,\nand information about recent mode transitions. It enables monitoring of the\ndevice's operational state and tracking mode transition history."
"description":"Datetime data frame with time series prediction data per optimization interval:- pv_energy_wh: PV energy prediction (positive) in wh- elec_price_amt_kwh: Electricity price prediction in money per kwh- feed_in_tariff_amt_kwh: Feed in tariff prediction in money per kwh- weather_temp_air_celcius: Temperature in \u00b0C- loadforecast_energy_wh: Load mean energy prediction in wh- loadakkudoktor_std_energy_wh: Load energy standard deviation prediction in wh- loadakkudoktor_mean_energy_wh: Load mean energy prediction in wh"
"description":"Datetime data frame with time series solution data per optimization interval:- load_energy_wh: Load of all energy consumers in wh- grid_energy_wh: Grid energy feed in (negative) or consumption (positive) in wh- costs_amt: Costs in money amount- revenue_amt: Revenue in money amount- losses_energy_wh: Energy losses in wh- <device-id>_operation_mode_id: Operation mode id of the device.- <device-id>_operation_mode_factor: Operation mode factor of the device.- <device-id>_soc_factor: State of charge of a battery/ electric vehicle device as factor of total capacity.- <device-id>_energy_wh: Energy consumption (positive) of a device in wh."
"description":"Unique identifier of the instruction in the ResourceManager scope. If not provided and a `resource_id` is passed at instantiation, this will be auto-generated as `{resource_id}@{UUID}`."
},
"execution_time":{
"type":"string",
"format":"date-time",
"title":"Execution Time",
"description":"Start time of the instruction execution."
},
"abnormal_condition":{
"type":"boolean",
"title":"Abnormal Condition",
"description":"Indicates if this is an instruction for abnormal conditions. Defaults to False.",
"default":false
},
"type":{
"type":"string",
"const":"PEBCInstruction",
"title":"Type",
"default":"PEBCInstruction"
},
"power_constraints_id":{
"type":"string",
"title":"Power Constraints Id",
"description":"ID of the associated PEBC.PowerConstraints."
},
"power_envelopes":{
"items":{
"$ref":"#/components/schemas/PEBCPowerEnvelope"
},
"type":"array",
"minItems":1,
"title":"Power Envelopes",
"description":"List of PowerEnvelopes to follow. One per CommodityQuantity, max one per type."
},
"resource_id":{
"type":"string",
"title":"Resource Id",
"description":"Get the resource identifier component from the instruction's `id`.\n\nAssumes the `id` follows the format `{resource_id}@{UUID}`. Extracts the resource_id part\nof the id by splitting at the last @.\n\nReturns:\n str: The resource identifier prefix of `id`, or an empty string if `id` is None.",
"readOnly":true
}
},
"type":"object",
"required":[
"execution_time",
"power_constraints_id",
"power_envelopes",
"resource_id"
],
"title":"PEBCInstruction",
"description":"Represents a control instruction for Power Envelope Based Control.\n\nThis model defines a complete instruction for controlling a device using power\nenvelopes. It specifies when the instruction should be executed, which power\nconstraints apply, and the specific power envelopes to follow. It supports\nmultiple power envelopes for different commodity quantities."
},
"PEBCPowerEnvelope":{
"properties":{
"id":{
"type":"string",
"title":"Id",
"description":"Unique identifier of this PEBC.PowerEnvelope, scoped to the ResourceManager."
},
"commodity_quantity":{
"$ref":"#/components/schemas/CommodityQuantity",
"description":"Type of power quantity the envelope applies to."
"description":"Chronologically ordered list of PowerEnvelopeElements. Defines how power should be constrained over time."
}
},
"type":"object",
"required":[
"id",
"commodity_quantity",
"power_envelope_elements"
],
"title":"PEBCPowerEnvelope",
"description":"Defines a complete power envelope constraint for a specific commodity quantity.\n\nThis model specifies a time-series of power limits (upper and lower bounds) that\na device must operate within. The power envelope consists of sequential elements,\neach defining constraints for a specific duration, creating a complete time-varying\noperational boundary for the device."
},
"PEBCPowerEnvelopeElement":{
"properties":{
"duration":{
"type":"string",
"format":"duration",
"title":"Duration",
"description":"Duration of this power envelope element."
},
"upper_limit":{
"type":"number",
"title":"Upper Limit",
"description":"Upper power limit for the given commodity_quantity. Shall match PEBC.AllowedLimitRange with limit_type UPPER_LIMIT."
},
"lower_limit":{
"type":"number",
"title":"Lower Limit",
"description":"Lower power limit for the given commodity_quantity. Shall match PEBC.AllowedLimitRange with limit_type LOWER_LIMIT."
}
},
"type":"object",
"required":[
"duration",
"upper_limit",
"lower_limit"
],
"title":"PEBCPowerEnvelopeElement",
"description":"Defines a segment of a power envelope for a specific duration.\n\nThis model specifies the upper and lower power limits for a specific time duration,\nforming part of a complete power envelope. A sequence of these elements creates\na time-varying power envelope that constrains device power consumption or production."
},
"PPBCEndInterruptionInstruction":{
"properties":{
"id":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Id",
"description":"Unique identifier of the instruction in the ResourceManager scope. If not provided and a `resource_id` is passed at instantiation, this will be auto-generated as `{resource_id}@{UUID}`."
},
"execution_time":{
"type":"string",
"format":"date-time",
"title":"Execution Time",
"description":"Start time of the instruction execution."
},
"abnormal_condition":{
"type":"boolean",
"title":"Abnormal Condition",
"description":"Indicates if this is an instruction for abnormal conditions. Defaults to False.",
"default":false
},
"type":{
"type":"string",
"const":"PPBCEndInterruptionInstruction",
"title":"Type",
"default":"PPBCEndInterruptionInstruction"
},
"power_profile_id":{
"type":"string",
"title":"Power Profile Id",
"description":"ID of the PowerProfileDefinition related to the ended interruption."
},
"sequence_container_id":{
"type":"string",
"title":"Sequence Container Id",
"description":"ID of the container containing the sequence."
},
"power_sequence_id":{
"type":"string",
"title":"Power Sequence Id",
"description":"ID of the PowerSequence for which the interruption ends."
},
"resource_id":{
"type":"string",
"title":"Resource Id",
"description":"Get the resource identifier component from the instruction's `id`.\n\nAssumes the `id` follows the format `{resource_id}@{UUID}`. Extracts the resource_id part\nof the id by splitting at the last @.\n\nReturns:\n str: The resource identifier prefix of `id`, or an empty string if `id` is None.",
"readOnly":true
}
},
"type":"object",
"required":[
"execution_time",
"power_profile_id",
"sequence_container_id",
"power_sequence_id",
"resource_id"
],
"title":"PPBCEndInterruptionInstruction",
"description":"Represents an instruction to resume execution of a previously interrupted power sequence.\n\nThis model defines a control instruction that ends an interruption and resumes\nexecution of a previously interrupted power sequence. It complements the start\ninterruption instruction, enabling the complete interruption-resumption cycle\nfor flexible sequence execution control."
"description":"Status list for all sequence containers in the PowerProfileDefinition."
}
},
"type":"object",
"required":[
"sequence_container_status"
],
"title":"PPBCPowerProfileStatus",
"description":"Reports the current status of a power profile execution.\n\nThis model provides comprehensive status information for all sequence containers\nin a power profile definition, enabling monitoring of profile execution progress.\nIt tracks which sequences have been selected and their current execution status."
},
"PPBCPowerSequenceContainerStatus":{
"properties":{
"power_profile_id":{
"type":"string",
"title":"Power Profile Id",
"description":"ID of the related PowerProfileDefinition."
},
"sequence_container_id":{
"type":"string",
"title":"Sequence Container Id",
"description":"ID of the PowerSequenceContainer being reported on."
},
"selected_sequence_id":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Selected Sequence Id",
"description":"ID of the selected PowerSequence, if any."
},
"progress":{
"anyOf":[
{
"type":"string",
"format":"duration"
},
{
"type":"null"
}
],
"title":"Progress",
"description":"Elapsed time since the selected sequence started, if applicable."
"description":"Status of the selected PowerSequence."
}
},
"type":"object",
"required":[
"power_profile_id",
"sequence_container_id",
"status"
],
"title":"PPBCPowerSequenceContainerStatus",
"description":"Reports the status of a specific power sequence container execution.\n\nThis model provides detailed status information for a single sequence container,\nincluding which sequence was selected, the current execution progress, and the\noperational status. It enables fine-grained monitoring of sequence execution\nwithin the broader power profile."
},
"PPBCPowerSequenceStatus":{
"type":"string",
"enum":[
"NOT_SCHEDULED",
"SCHEDULED",
"EXECUTING",
"INTERRUPTED",
"FINISHED",
"ABORTED"
],
"title":"PPBCPowerSequenceStatus",
"description":"Enumeration of status values for Power Profile Based Control sequences."
},
"PPBCScheduleInstruction":{
"properties":{
"id":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Id",
"description":"Unique identifier of the instruction in the ResourceManager scope. If not provided and a `resource_id` is passed at instantiation, this will be auto-generated as `{resource_id}@{UUID}`."
},
"execution_time":{
"type":"string",
"format":"date-time",
"title":"Execution Time",
"description":"Start time of the instruction execution."
},
"abnormal_condition":{
"type":"boolean",
"title":"Abnormal Condition",
"description":"Indicates if this is an instruction for abnormal conditions. Defaults to False.",
"default":false
},
"type":{
"type":"string",
"const":"PPBCScheduleInstruction",
"title":"Type",
"default":"PPBCScheduleInstruction"
},
"power_profile_id":{
"type":"string",
"title":"Power Profile Id",
"description":"ID of the PowerProfileDefinition being scheduled."
},
"sequence_container_id":{
"type":"string",
"title":"Sequence Container Id",
"description":"ID of the container with the selected sequence."
},
"power_sequence_id":{
"type":"string",
"title":"Power Sequence Id",
"description":"ID of the selected PowerSequence."
},
"resource_id":{
"type":"string",
"title":"Resource Id",
"description":"Get the resource identifier component from the instruction's `id`.\n\nAssumes the `id` follows the format `{resource_id}@{UUID}`. Extracts the resource_id part\nof the id by splitting at the last @.\n\nReturns:\n str: The resource identifier prefix of `id`, or an empty string if `id` is None.",
"readOnly":true
}
},
"type":"object",
"required":[
"execution_time",
"power_profile_id",
"sequence_container_id",
"power_sequence_id",
"resource_id"
],
"title":"PPBCScheduleInstruction",
"description":"Represents an instruction to schedule execution of a specific power sequence.\n\nThis model defines a control instruction that schedules the execution of a\nselected power sequence from a power profile. It specifies which sequence\nhas been selected and when it should begin execution, enabling precise control\nof device power behavior according to the predefined sequence."
},
"PPBCStartInterruptionInstruction":{
"properties":{
"id":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Id",
"description":"Unique identifier of the instruction in the ResourceManager scope. If not provided and a `resource_id` is passed at instantiation, this will be auto-generated as `{resource_id}@{UUID}`."
},
"execution_time":{
"type":"string",
"format":"date-time",
"title":"Execution Time",
"description":"Start time of the instruction execution."
},
"abnormal_condition":{
"type":"boolean",
"title":"Abnormal Condition",
"description":"Indicates if this is an instruction for abnormal conditions. Defaults to False.",
"default":false
},
"type":{
"type":"string",
"const":"PPBCStartInterruptionInstruction",
"title":"Type",
"default":"PPBCStartInterruptionInstruction"
},
"power_profile_id":{
"type":"string",
"title":"Power Profile Id",
"description":"ID of the PowerProfileDefinition whose sequence is being interrupted."
},
"sequence_container_id":{
"type":"string",
"title":"Sequence Container Id",
"description":"ID of the container containing the sequence."
},
"power_sequence_id":{
"type":"string",
"title":"Power Sequence Id",
"description":"ID of the PowerSequence to be interrupted."
},
"resource_id":{
"type":"string",
"title":"Resource Id",
"description":"Get the resource identifier component from the instruction's `id`.\n\nAssumes the `id` follows the format `{resource_id}@{UUID}`. Extracts the resource_id part\nof the id by splitting at the last @.\n\nReturns:\n str: The resource identifier prefix of `id`, or an empty string if `id` is None.",
"readOnly":true
}
},
"type":"object",
"required":[
"execution_time",
"power_profile_id",
"sequence_container_id",
"power_sequence_id",
"resource_id"
],
"title":"PPBCStartInterruptionInstruction",
"description":"Represents an instruction to interrupt execution of a running power sequence.\n\nThis model defines a control instruction that interrupts the execution of an\nactive power sequence. It enables dynamic control over sequence execution,\nallowing temporary suspension of a sequence in response to changing system conditions\nor requirements, particularly for sequences marked as interruptible."
"description":"Akkudoktor forecast backend: remote API or local Open-Meteo/pvlib model.",
"default":"remote",
"examples":[
"remote",
"local"
]
},
"resolution_minutes":{
"type":"integer",
"title":"Resolution Minutes",
"description":"Forecast resolution in minutes. 15 requests Open-Meteo's `minutely_15` block (natively resolved over Central Europe and North America, interpolated from hourly elsewhere); 60 requests the `hourly` block.",
"default":15,
"examples":[
15,
60
]
},
"forecast_days":{
"anyOf":[
{
"type":"integer",
"maximum":16.0,
"minimum":1.0
},
{
"type":"null"
}
],
"title":"Forecast Days",
"description":"Forecast horizon in days (1-16). Leave empty to derive it from `prediction.hours`, which is what keeps the optimizer's tail horizon fed.",
"examples":[
null,
7
]
},
"past_days":{
"anyOf":[
{
"type":"integer",
"maximum":92.0,
"minimum":0.0
},
{
"type":"null"
}
],
"title":"Past Days",
"description":"Days of past data to request (0-92). Leave empty to derive it from `prediction.historic_hours`.",
"examples":[
null,
3
]
},
"weather_models":{
"items":{
"type":"string"
},
"type":"array",
"minItems":1,
"title":"Weather Models",
"description":"Open-Meteo weather models to request. Listing more than one turns the input into a poor-man's ensemble: the members are averaged per variable, which is the cheapest reliable way to cut irradiance forecast error. Costs no extra API calls.",
"default":[
"best_match"
],
"examples":[
[
"best_match"
],
[
"icon_seamless",
"ecmwf_ifs025",
"gfs_seamless"
]
]
},
"transposition_model":{
"type":"string",
"title":"Transposition Model",
"description":"pvlib sky-diffuse transposition model: isotropic, klucher, haydavies, reindl, king or perez.",
"default":"perez",
"examples":[
"perez",
"haydavies"
]
},
"albedo":{
"type":"number",
"maximum":1.0,
"minimum":0.0,
"title":"Albedo",
"description":"Ground albedo used for planes that do not set their own.",
"description":"Module power temperature coefficient in %/degC (negative). Matches the `cellCoEff` the akkudoktor.net forecast uses.",
"default":-0.36,
"examples":[
-0.36,
-0.29
]
},
"apply_iam":{
"type":"boolean",
"title":"Apply Iam",
"description":"Apply the ASHRAE incidence-angle modifier to the beam component.",
"default":true,
"examples":[
true
]
},
"shift_to_interval_start":{
"type":"boolean",
"title":"Shift To Interval Start",
"description":"Open-Meteo stamps an interval mean with the interval END. EOS labels an interval by its START, so records are shifted back by one interval. Disable only to compare like-for-like against a provider that does not.",
"default":true,
"examples":[
true
]
},
"calibration_enabled":{
"type":"boolean",
"title":"Calibration Enabled",
"description":"Correct systematic model error against measured PV production. Requires `measurement.pv_production_emr_keys` to be configured and fed. Fits a global scale factor plus per-solar-azimuth factors, which is what catches near-field shading the horizon profile misses.",
"default":false,
"examples":[
true
]
},
"calibration_days":{
"type":"integer",
"maximum":92.0,
"minimum":1.0,
"title":"Calibration Days",
"description":"Length of the measurement window used to fit the correction.",
"default":30,
"examples":[
30,
14
]
},
"calibration_reference_days":{
"type":"integer",
"maximum":92.0,
"minimum":3.0,
"title":"Calibration Reference Days",
"description":"Lookback used to distinguish healthy production from outages or curtailment. If the calibration window contains too few healthy days, the most recent healthy days from this reference window are used.",
"default":30,
"examples":[
30,
14
]
},
"calibration_outage_filter_enabled":{
"type":"boolean",
"title":"Calibration Outage Filter Enabled",
"description":"Exclude days whose measured production is far below the recent healthy plant level. This prevents inverter, battery and curtailment events from being learned as permanent PV model losses.",
"default":true,
"examples":[
true
]
},
"calibration_outage_threshold":{
"type":"number",
"exclusiveMaximum":1.0,
"exclusiveMinimum":0.0,
"title":"Calibration Outage Threshold",
"description":"A day is treated as unavailable when its measured/modelled energy ratio is below this fraction of the robust healthy reference ratio.",
"default":0.55,
"examples":[
0.55,
0.5
]
},
"calibration_min_healthy_days":{
"type":"integer",
"maximum":31.0,
"minimum":1.0,
"title":"Calibration Min Healthy Days",
"description":"Minimum number of healthy days used for a fit. Older healthy days from the reference window are added when the recent window contains fewer.",
"default":3,
"examples":[
3
]
},
"calibration_azimuth_bin_degrees":{
"type":"integer",
"maximum":180.0,
"minimum":0.0,
"title":"Calibration Azimuth Bin Degrees",
"description":"Width of the solar-azimuth bins for the correction. 0 fits a single global factor only.",
"default":45,
"examples":[
45,
30,
15,
0
]
},
"calibration_prior_kwh":{
"type":"number",
"minimum":0.0,
"title":"Calibration Prior Kwh",
"description":"Shrinkage strength: a bin needs this much modelled energy before its own factor outweighs the global one. Higher is more conservative.",
"default":5.0,
"examples":[
5.0,
20.0
]
},
"calibration_min_factor":{
"type":"number",
"exclusiveMinimum":0.0,
"title":"Calibration Min Factor",
"description":"Lower clamp on any fitted correction factor.",
"default":0.5,
"examples":[
0.5
]
},
"calibration_max_factor":{
"type":"number",
"exclusiveMinimum":0.0,
"title":"Calibration Max Factor",
"description":"Upper clamp on any fitted correction factor.",
"description":"Home Assistant entity providing the PV forecast.",
"default":"sensor.pv_forecast",
"examples":[
"sensor.pv1_power_now"
]
},
"attribute":{
"type":"string",
"title":"Attribute",
"description":"Entity attribute holding the forecast list.",
"default":"forecast",
"examples":[
"forecast"
]
},
"datetime_key":{
"type":"string",
"title":"Datetime Key",
"description":"Key for the timestamp in each forecast entry.",
"default":"datetime",
"examples":[
"datetime"
]
},
"value_key":{
"type":"string",
"title":"Value Key",
"description":"Key for the AC power value in each forecast entry.",
"default":"watts",
"examples":[
"watts"
]
},
"value_unit":{
"type":"string",
"enum":[
"W",
"kW"
],
"title":"Value Unit",
"description":"Unit of the forecast value. Converted to W internally.",
"default":"W",
"examples":[
"W",
"kW"
]
},
"base_url":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Base Url",
"description":"Base URL of the Home Assistant instance. Only required when EOS is not running as a Home Assistant add-on (no SUPERVISOR_TOKEN available).",
"examples":[
"http://homeassistant.local:8123"
]
},
"token":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Token",
"description":"Long-lived access token for the Home Assistant instance. Only required when EOS is not running as a Home Assistant add-on.",
"examples":[
null
]
}
},
"type":"object",
"title":"PVForecastHomeAssistantCommonSettings",
"description":"Common settings for pvforecast data from a Home Assistant entity."
"description":"pvnode.com API key (Bearer auth). Required.",
"default":"",
"examples":[
"pvn_live_xxxxxxxxxxxxxxxx"
]
},
"site_id":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Site Id",
"description":"pvnode.com site id of the saved plant ('Anlagen-ID'). When set, the saved (possibly calibrated) site is used. Leave empty to send the configured pvforecast.planes inline instead.",
"examples":[
"abcd-1234"
]
},
"forecast_days":{
"type":"integer",
"maximum":7.0,
"minimum":1.0,
"title":"Forecast Days",
"description":"Forecast horizon in days (1-7, capped by the pvnode plan).",
"default":2,
"examples":[
2
]
}
},
"type":"object",
"title":"PVForecastPVNodeCommonSettings",
"description":"Common settings for the pvnode.com PV forecast provider."
"description":"Timestamp when PowerValues were measured."
},
"values":{
"items":{
"$ref":"#/components/schemas/PowerValue"
},
"type":"array",
"title":"Values",
"description":"Array of measured PowerValues. Shall contain at least one item and at most one item per 'commodity_quantity' (defined inside the PowerValue)."
}
},
"type":"object",
"required":[
"measurement_timestamp",
"values"
],
"title":"PowerMeasurement",
"description":"Captures a set of power measurements taken at a specific point in time.\n\nThis model records multiple power values (for different commodity quantities)\nalong with the timestamp when the measurements were taken, enabling time-series\nanalysis and monitoring of power consumption or production."
},
"PowerValue":{
"properties":{
"commodity_quantity":{
"$ref":"#/components/schemas/CommodityQuantity",
"description":"The power quantity the value refers to."
},
"value":{
"type":"number",
"title":"Value",
"description":"Power value expressed in the unit associated with the CommodityQuantity."
}
},
"type":"object",
"required":[
"commodity_quantity",
"value"
],
"title":"PowerValue",
"description":"Represents a specific power value measurement with its associated commodity quantity.\n\nThis class links a numerical power value to a specific type of power quantity (such as\nactive power, reactive power, etc.) and its unit of measurement."
"description":"Pydantic model for time series data with consistent value lengths.\n\nThis model validates a dictionary where:\n- Keys are strings representing data series names\n- Values are lists of numeric or string values\n- Special keys 'start_datetime' and 'interval' can contain string values\nfor time series indexing\n- All value lists must have the same length\n\nExample:\n .. code-block:: python\n\n {\n \"start_datetime\": \"2024-01-01 00:00:00\", # optional\n \"interval\": \"1 hour\", # optional\n \"loadforecast_power_w\": [20.5, 21.0, 22.1],\n \"load_min\": [18.5, 19.0, 20.1]\n }"
"description":"Pydantic model for validating pandas DataFrame data with datetime index."
},
"PydanticDateTimeSeries":{
"properties":{
"data":{
"additionalProperties":true,
"type":"object",
"title":"Data"
},
"dtype":{
"type":"string",
"title":"Dtype",
"default":"float64"
},
"tz":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Tz"
}
},
"type":"object",
"required":[
"data"
],
"title":"PydanticDateTimeSeries",
"description":"Pydantic model for validating pandas Series with datetime index in JSON format.\n\nThis model handles Series data serialized with orient='index', where the keys are\ndatetime strings and values are the series values. Provides validation and\nconversion between JSON and pandas Series with datetime index.\n\nAttributes:\n data (Dict[str, Any]): Dictionary mapping datetime strings to values.\n dtype (str): The data type of the series values.\n tz (str | None): Timezone name if the datetime index is timezone-aware."
"description":"External series from local midnight, in slot Wh and currency per Wh.\n\nThe interval is configured in optimization.genetic.interval_sec. Omitted\nseries are read from the configured providers, preserving their raw coverage."
"description":"Public EOSdash base URL for redirects and error-page links, including an optional proxy path prefix. Set this for reverse proxies or mapped ports; it does not change the bind address. Without it, direct access uses the request host and EOSdash port. Raw forwarded headers are not used.",
"description":"The name of the target user to switch to. If ``None`` (default), the current effective user is used and no privilege change is attempted.",
"examples":[
null,
"user"
]
},
"reload":{
"anyOf":[
{
"type":"boolean"
},
{
"type":"null"
}
],
"title":"Reload",
"description":"Enable server auto-reload for debugging or development. Default is False. Monitors the package directory for changes and reloads the server.",
"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].",
"description":"Forecast summary used by the deterministic tail optimization."
},
"TailPlanSlot":{
"properties":{
"slot":{
"type":"integer",
"title":"Slot"
},
"hour_from_start":{
"type":"number",
"title":"Hour From Start"
},
"action":{
"type":"string",
"title":"Action"
},
"alternative_action":{
"type":"string",
"title":"Alternative Action",
"default":""
},
"decision_margin_euro":{
"type":"number",
"title":"Decision Margin Euro",
"default":0.0
},
"soc_start_percentage":{
"type":"number",
"title":"Soc Start Percentage"
},
"soc_end_percentage":{
"type":"number",
"title":"Soc End Percentage"
},
"pv_wh":{
"type":"number",
"title":"Pv Wh"
},
"load_wh":{
"type":"number",
"title":"Load Wh"
},
"grid_import_wh":{
"type":"number",
"title":"Grid Import Wh"
},
"grid_export_wh":{
"type":"number",
"title":"Grid Export Wh"
},
"battery_charge_wh":{
"type":"number",
"title":"Battery Charge Wh"
},
"battery_discharge_wh":{
"type":"number",
"title":"Battery Discharge Wh"
},
"import_price_euro_per_kwh":{
"type":"number",
"title":"Import Price Euro Per Kwh"
},
"feed_in_tariff_euro_per_kwh":{
"type":"number",
"title":"Feed In Tariff Euro Per Kwh"
},
"slot_value_euro":{
"type":"number",
"title":"Slot Value Euro"
},
"remaining_value_euro":{
"type":"number",
"title":"Remaining Value Euro"
},
"ac_charge_factor":{
"type":"number",
"title":"Ac Charge Factor"
},
"dc_charge_allowed":{
"type":"integer",
"title":"Dc Charge Allowed"
},
"discharge_allowed":{
"type":"integer",
"title":"Discharge Allowed"
},
"battery_grid_export_factor":{
"type":"number",
"title":"Battery Grid Export Factor"
}
},
"type":"object",
"required":[
"slot",
"hour_from_start",
"action",
"soc_start_percentage",
"soc_end_percentage",
"pv_wh",
"load_wh",
"grid_import_wh",
"grid_export_wh",
"battery_charge_wh",
"battery_discharge_wh",
"import_price_euro_per_kwh",
"feed_in_tariff_euro_per_kwh",
"slot_value_euro",
"remaining_value_euro",
"ac_charge_factor",
"dc_charge_allowed",
"discharge_allowed",
"battery_grid_export_factor"
],
"title":"TailPlanSlot",
"description":"One diagnostic slot of the optimal tail path.\n\nThese values explain the lookahead used for fitness. They are diagnostics\nonly and are never copied into the executable control arrays."
},
"TerminalValueCurve":{
"properties":{
"energy_wh":{
"items":{
"type":"number"
},
"type":"array",
"title":"Energy Wh",
"description":"Breakpoints of usable AC energy left in the battery [Wh]."
},
"value_euro":{
"items":{
"type":"number"
},
"type":"array",
"title":"Value Euro",
"description":"Cumulative credit at each breakpoint [EUR]."
},
"operating_value_euro":{
"items":{
"type":"number"
},
"type":"array",
"title":"Operating Value Euro",
"description":"Tail operating component at each breakpoint [EUR]; empty for a proxy curve."
},
"continuation_value_euro":{
"items":{
"type":"number"
},
"type":"array",
"title":"Continuation Value Euro",
"description":"Continuation component at each breakpoint [EUR]; empty for a proxy curve."
},
"marginal_euro_per_kwh":{
"items":{
"type":"number"
},
"type":"array",
"title":"Marginal Euro Per Kwh",
"description":"Marginal value of the segment that starts at each breakpoint [EUR/kWh]. May be negative or non-monotone in TAIL mode."
},
"residual_energy_wh":{
"type":"number",
"title":"Residual Energy Wh",
"description":"Energy up to which the curve is backed by residual load - the knee. Everything beyond it is only worth an export.",
"default":0.0
},
"window_slots":{
"type":"integer",
"title":"Window Slots",
"description":"Number of trailing horizon slots the curve was derived from. Fewer slots than a full day mean a shorter proxy period.",
"default":0
}
},
"type":"object",
"title":"TerminalValueCurve",
"description":"Piecewise linear, concave value of battery energy left at the horizon.\n\n``energy_wh`` and ``value_euro`` are the breakpoints of the cumulative\nvalue, ``marginal_euro_per_kwh`` the slope of each segment. Both arrays\nstart at the origin; the curve is flat beyond its last breakpoint."
},
"TerminalValueMode":{
"type":"string",
"enum":[
"AUTO",
"FIXED"
],
"title":"TerminalValueMode",
"description":"How the energy left in the battery at the end of the horizon is valued.\n\nModes\n-----\n- AUTO:\n Solve the deterministic forecast tail and apply a conservative\n continuation proxy at its end. Tail values may decrease with SOC when\n empty capacity is valuable. With a zero tail, use the proxy directly.\n\n- FIXED:\n Credit every stored kWh with the configured\n ``terminal_value_euro_per_kwh`` (or ``preis_euro_pro_wh_akku`` of the\n request). The historical behaviour; a value of 0 makes the optimizer\n empty the battery towards the end of the horizon."
},
"TerminalValueResult":{
"properties":{
"control_horizon_hours":{
"type":"number",
"title":"Control Horizon Hours",
"default":0
},
"requested_tail_hours":{
"type":"number",
"title":"Requested Tail Hours",
"default":0
},
"effective_tail_hours":{
"type":"number",
"title":"Effective Tail Hours",
"default":0
},
"tail_end_hour":{
"type":"number",
"title":"Tail End Hour",
"default":0
},
"continuation_mode":{
"type":"string",
"title":"Continuation Mode",
"default":"FIXED"
},
"mode":{
"type":"string",
"title":"Mode",
"description":"Terminal value mode the run used: TAIL, AUTO or FIXED.",
"examples":[
"TAIL",
"AUTO",
"FIXED"
]
},
"battery_energy_wh":{
"type":"number",
"title":"Battery Energy Wh",
"description":"Usable AC energy left in the battery at the end of the horizon [Wh].",
"default":0.0
},
"credited_euro":{
"type":"number",
"title":"Credited Euro",
"description":"Credit applied to the total balance [EUR].",
"default":0.0
},
"tail_operating_euro":{
"type":"number",
"title":"Tail Operating Euro",
"description":"Optimal net cash flow within the effective tail for the selected control-end battery state [EUR].",
"default":0.0
},
"continuation_value_euro":{
"type":"number",
"title":"Continuation Value Euro",
"description":"Continuation credit remaining at the end of the optimal tail path [EUR].",
"default":0.0
},
"curve":{
"anyOf":[
{
"$ref":"#/components/schemas/TerminalValueCurve"
},
{
"type":"null"
}
],
"description":"Combined tail value curve (tail operation plus continuation) read by fitness; None in FIXED mode."
},
"continuation_curve":{
"anyOf":[
{
"$ref":"#/components/schemas/TerminalValueCurve"
},
{
"type":"null"
}
],
"description":"Conservative AUTO proxy constructed at the effective tail end."
},
"tail_diagnostics":{
"anyOf":[
{
"$ref":"#/components/schemas/TailDiagnostics"
},
{
"type":"null"
}
]
},
"tail_plan":{
"items":{
"$ref":"#/components/schemas/TailPlanSlot"
},
"type":"array",
"title":"Tail Plan",
"description":"Diagnostic optimal battery path inside the tail. It explains the lookahead but is never an executable control plan."
},
"reason":{
"type":"string",
"title":"Reason",
"description":"Why this mode applied. Empty in AUTO mode; in FIXED mode it says whether FIXED was configured or whether AUTO fell back because no curve could be derived.",
"default":"",
"examples":[
"",
"terminal_value_mode is FIXED"
]
}
},
"type":"object",
"required":[
"mode"
],
"title":"TerminalValueResult",
"description":"What the optimizer credited for the energy left in the battery."
"description":"Naive start time of the time window (time of day, no timezone). Interpreted in the timezone of the datetime passed to contains() or earliest_start_time().",
"description":"Optional day of the week restriction. Can be specified as integer (0=Monday to 6=Sunday) or localized weekday name. If None, applies every day unless `date` is set.",
"description":"Optional specific calendar date for the time window. Naive \u2014 matched against the local date of the datetime passed to contains(). Overrides `day_of_week` if set.",
"description":"Locale used to parse weekday names in `day_of_week` when given as string. If not set, Pendulum's default locale is used. Examples: 'en', 'de', 'fr', etc.",
"description":"Model defining a daily or date time window with optional localization support.\n\nRepresents a time interval starting at `start_time` and lasting for `duration`.\nCan restrict applicability to a specific day of the week or a specific calendar date.\nSupports day names in multiple languages via locale-aware parsing.\n\nTimezone contract:\n\n``start_time`` is always **naive** (no ``tzinfo``). It is interpreted as a\nlocal wall-clock time in whatever timezone the caller's ``date_time`` or\n``reference_date`` carries. When those arguments are timezone-aware the\nwindow boundaries are evaluated in that timezone; when they are naive,\narithmetic is performed as-is (no timezone conversion occurs).\n\n``date``, being a calendar ``Date`` object, is inherently timezone-free.\n\nThis design avoids the ambiguity that arises when a stored ``start_time``\ncarries its own timezone that differs from the caller's timezone, and keeps\nthe model serialisable without timezone state."
"description":"Naive start time of the time window (time of day, no timezone). Interpreted in the timezone of the datetime passed to contains() or earliest_start_time().",
"description":"Optional day of the week restriction. Can be specified as integer (0=Monday to 6=Sunday) or localized weekday name. If None, applies every day unless `date` is set.",
"description":"Optional specific calendar date for the time window. Naive \u2014 matched against the local date of the datetime passed to contains(). Overrides `day_of_week` if set.",
"description":"Locale used to parse weekday names in `day_of_week` when given as string. If not set, Pendulum's default locale is used. Examples: 'en', 'de', 'fr', etc.",
"description":"Model defining a daily or date time window with optional localization support.\n\nRepresents a time interval starting at `start_time` and lasting for `duration`.\nCan restrict applicability to a specific day of the week or a specific calendar date.\nSupports day names in multiple languages via locale-aware parsing.\n\nTimezone contract:\n\n``start_time`` is always **naive** (no ``tzinfo``). It is interpreted as a\nlocal wall-clock time in whatever timezone the caller's ``date_time`` or\n``reference_date`` carries. When those arguments are timezone-aware the\nwindow boundaries are evaluated in that timezone; when they are naive,\narithmetic is performed as-is (no timezone conversion occurs).\n\n``date``, being a calendar ``Date`` object, is inherently timezone-free.\n\nThis design avoids the ambiguity that arises when a stored ``start_time``\ncarries its own timezone that differs from the caller's timezone, and keeps\nthe model serialisable without timezone state."
"description":"List of TimeWindow objects that make up this sequence."
}
},
"type":"object",
"title":"TimeWindowSequence",
"description":"Model representing a sequence of time windows with collective operations.\n\nManages multiple TimeWindow objects and provides methods to work with them\nas a cohesive unit for scheduling and availability checking."
"description":"List of TimeWindow objects that make up this sequence."
}
},
"type":"object",
"title":"TimeWindowSequence",
"description":"Model representing a sequence of time windows with collective operations.\n\nManages multiple TimeWindow objects and provides methods to work with them\nas a cohesive unit for scheduling and availability checking."
"description":"Naive start time of the time window (time of day, no timezone). Interpreted in the timezone of the datetime passed to contains() or earliest_start_time().",
"examples":[
"00:00:00"
]
},
"duration":{
"type":"string",
"format":"duration",
"title":"Duration",
"description":"Duration of the time window starting from `start_time`.",
"examples":[
"2 hours"
]
},
"day_of_week":{
"anyOf":[
{
"type":"integer"
},
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Day Of Week",
"description":"Optional day of the week restriction. Can be specified as integer (0=Monday to 6=Sunday) or localized weekday name. If None, applies every day unless `date` is set.",
"examples":[
null
]
},
"date":{
"anyOf":[
{
"type":"string",
"format":"date"
},
{
"type":"null"
}
],
"title":"Date",
"description":"Optional specific calendar date for the time window. Naive \u2014 matched against the local date of the datetime passed to contains(). Overrides `day_of_week` if set.",
"examples":[
null
]
},
"locale":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Locale",
"description":"Locale used to parse weekday names in `day_of_week` when given as string. If not set, Pendulum's default locale is used. Examples: 'en', 'de', 'fr', etc.",
"examples":[
null
]
},
"value":{
"anyOf":[
{
"type":"number",
"minimum":0.0
},
{
"type":"null"
}
],
"title":"Value",
"description":"Value applicable during this time window.",
"examples":[
0.288
]
}
},
"type":"object",
"required":[
"start_time",
"duration"
],
"title":"ValueTimeWindow",
"description":"Value applicable during a specific time window.\n\nThis model extends `TimeWindow` by associating a value with the defined time interval."
},
"ValueTimeWindow-Output":{
"properties":{
"start_time":{
"type":"string",
"title":"Start Time",
"description":"Naive start time of the time window (time of day, no timezone). Interpreted in the timezone of the datetime passed to contains() or earliest_start_time().",
"examples":[
"00:00:00"
]
},
"duration":{
"type":"string",
"title":"Duration",
"description":"Duration of the time window starting from `start_time`.",
"examples":[
"2 hours"
]
},
"day_of_week":{
"anyOf":[
{
"type":"integer"
},
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Day Of Week",
"description":"Optional day of the week restriction. Can be specified as integer (0=Monday to 6=Sunday) or localized weekday name. If None, applies every day unless `date` is set.",
"examples":[
null
]
},
"date":{
"anyOf":[
{
"type":"string",
"format":"date"
},
{
"type":"null"
}
],
"title":"Date",
"description":"Optional specific calendar date for the time window. Naive \u2014 matched against the local date of the datetime passed to contains(). Overrides `day_of_week` if set.",
"examples":[
null
]
},
"locale":{
"anyOf":[
{
"type":"string"
},
{
"type":"null"
}
],
"title":"Locale",
"description":"Locale used to parse weekday names in `day_of_week` when given as string. If not set, Pendulum's default locale is used. Examples: 'en', 'de', 'fr', etc.",
"examples":[
null
]
},
"value":{
"anyOf":[
{
"type":"number",
"minimum":0.0
},
{
"type":"null"
}
],
"title":"Value",
"description":"Value applicable during this time window.",
"examples":[
0.288
]
}
},
"type":"object",
"required":[
"start_time",
"duration"
],
"title":"ValueTimeWindow",
"description":"Value applicable during a specific time window.\n\nThis model extends `TimeWindow` by associating a value with the defined time interval."
"description":"Ordered list of value time windows. Each window defines a time interval and an associated value."
}
},
"type":"object",
"title":"ValueTimeWindowSequence",
"description":"Sequence of value time windows.\n\nThis model specializes `TimeWindowSequence` to ensure that all\ncontained windows are instances of `ValueTimeWindow`.\nIt provides the full set of sequence operations (containment checks,\navailability, start time calculations) for value windows."
"description":"Ordered list of value time windows. Each window defines a time interval and an associated value."
}
},
"type":"object",
"title":"ValueTimeWindowSequence",
"description":"Sequence of value time windows.\n\nThis model specializes `TimeWindowSequence` to ensure that all\ncontained windows are instances of `ValueTimeWindow`.\nIt provides the full set of sequence operations (containment checks,\navailability, start time calculations) for value windows."
