mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2026-10-14 10:01:59 +00:00
Andreas
a2f4ef6f54
The optimizer treated the end of `optimization.horizon_hours` as the end of the world: energy left in the battery there was worth a single configured price per kWh, so it either dumped the battery into the last hours or hoarded it, depending on that one number. The horizon is now two spans. `horizon_hours` still receives every control command. The new `optimization.tail_horizon_hours` (default 48 h) is a pure lookahead that never produces a command. In AUTO terminal-value mode a deterministic dynamic program solves that tail backwards on a 101-point SoC grid using the production battery and inverter models - SoC bounds, power caps, conversion losses, configured charge and export rates, direct-marketing permission and LCOS on delivered DC energy - and the existing AUTO proxy supplies the continuation value at the tail end. Genetic fitness reads the resulting curve. `tail_horizon_hours: 0` restores the plain proxy at the control end, FIXED is unchanged. The forecast budget is reported, never enforced by refusal: a tail that does not fit is shortened to what the forecast covers and reported as `effective_tail_hours`, and a control horizon that does not fit is warned about at configuration time and rejected by the optimizer at run time, which knows which series ran out. `prediction.hours` defaults to 72 so the new defaults fit out of the box; existing shorter configurations keep starting. Control arrays and warm-start genomes now begin at the run timestamp rather than midnight, flagged by `controls_start_at_now` so the adapters still read older solutions. `forecast_interval_seconds` declares the resolution of shortened native quarter-hour inputs. Required forecasts are no longer silently replaced by demo providers. A missing PV, price, load, feed-in or weather forecast used to rewrite the configured provider and retry, so a run could quietly optimize against invented data. Missing values now stay missing, and provider values are held only within their own source interval instead of being extended indefinitely. Also fixes a config update that could leave EOS half-updated: the merged candidate is validated before the singleton is reinitialized. Four provider tests that hard-coded the old 48 h prediction default are rewritten to derive their expectations from the configured horizon.
113 lines
4.2 KiB
Markdown
113 lines
4.2 KiB
Markdown
% SPDX-License-Identifier: Apache-2.0
|
|
(configuration-page)=
|
|
|
|
# Configuration Guide
|
|
|
|
The configuration controls all aspects of EOS: optimization, prediction, measurement, and energy
|
|
management.
|
|
|
|
## Storing Configuration
|
|
|
|
EOS stores configuration data in a `nested structure`.
|
|
|
|
Some `configuration keys` are read-only and cannot be altered. These keys are either set up by other
|
|
means, such as environment variables, or determined from other information.
|
|
|
|
Several endpoints of the EOS REST server allow for the management and retrieval of configuration
|
|
data.
|
|
|
|
:::{admonition} Note
|
|
:class: note
|
|
Configuration changes inside EOS are updated in memory, meaning all changes will be lost upon
|
|
restarting the EOS REST server unless the configuration is saved to the `EOS configuration file`.
|
|
This can be done manually or is done automatically by default.
|
|
:::
|
|
|
|
### Save Configuration File
|
|
|
|
Configure EOS for `AUTOMATIC` (vs. `MANUAL`) configuration file update in case of configuration
|
|
changes.
|
|
|
|
Use endpoint `PUT /v1/config/file` to save the current configuration to the
|
|
`EOS configuration file`.
|
|
|
|
### Load Configuration File
|
|
|
|
Use endpoint `POST /v1/config/reset` to reset the configuration to the values in the
|
|
`EOS configuration file`.
|
|
|
|
## Configuration Sources and Priorities
|
|
|
|
The configuration sources and their priorities are as follows:
|
|
|
|
1. `Settings`: Provided during runtime by the REST interface
|
|
2. `Environment Variables`: Defined at startup of the REST server and during runtime
|
|
3. `EOS Configuration File`: Read at startup of the REST server and on request
|
|
4. `Default Values`
|
|
|
|
### Runtime Config Updates
|
|
|
|
The EOS configuration can be updated at runtime.
|
|
|
|
Use the following endpoints to change the current runtime configuration:
|
|
|
|
- `PUT /v1/config`: Update the entire or parts of the configuration.
|
|
|
|
:::{admonition} Note
|
|
:class: note
|
|
Those updates are not persistent automatically. However it is possible to save the configuration to
|
|
the `EOS configuration file`. See [Save Configuration File](#save-configuration-file) above.
|
|
:::
|
|
|
|
### Environment Variables
|
|
|
|
All `configuration keys` can be set by environment variables prefixed with `EOS_` and separated by
|
|
`__` for nested structures. Environment variables are case insensitive.
|
|
|
|
EOS recognizes the following special environment variables (case sensitive):
|
|
|
|
- `EOS_CONFIG_DIR`: The directory to search for an EOS configuration file.
|
|
- `EOS_DIR`: The directory used by EOS for data, which will also be searched for an EOS
|
|
configuration file.
|
|
|
|
### EOS Configuration File
|
|
|
|
The EOS configuration file provides persistent storage for configuration data. It can be modified
|
|
directly or through the REST interface.
|
|
|
|
If you do not have a configuration file, it will be automatically created on the first startup of
|
|
the REST server in a system-dependent location.
|
|
|
|
To determine the location of the configuration file used by EOS, ask the REST server. The endpoint
|
|
`GET /v1/config` provides the `general.config_file_path` configuration key.
|
|
|
|
EOS searches for the configuration file in the following order:
|
|
|
|
1. The directory specified by the `EOS_CONFIG_DIR` environment variable
|
|
2. The directory specified by the `EOS_DIR` environment variable
|
|
3. A platform-specific default directory for EOS
|
|
4. The current working directory
|
|
|
|
The first configuration file available in these directories is loaded. If no configuration file is
|
|
found, a default configuration file is created, and the default settings are written to it. The
|
|
location of the created configuration file follows the same order in which EOS searches for
|
|
configuration files, and it depends on whether the relevant environment variables are set.
|
|
|
|
Use the following endpoints to interact with the configuration file:
|
|
|
|
- `PUT /v1/config/file`: Save the current configuration to the configuration file.
|
|
- `PUT /v1/config/reset`: Reload the configuration file, all unsaved runtime configuration is reset.
|
|
|
|
### Default Values
|
|
|
|
Some of the `configuration keys` have default values by definition. For most of the
|
|
`configuration keys` the default value is just `None`, which means no default value.
|
|
|
|
```{include} /_generated/config.md
|
|
:heading-offset: 1
|
|
:relative-docs: ..
|
|
:relative-images:
|
|
```
|
|
|
|
See [Control horizon and battery lookahead](optimization_horizons.md) for horizon validation, forecast availability and control-array indexing.
|