Mirrors/EOS
1
0
Fork 0
mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2025-10-30 06:16:21 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

fix: automatic optimization (#596)

Browse Source 
This fix implements the long term goal to have the EOS server run optimization (or
energy management) on regular intervals automatically. Thus clients can request
the current energy management plan at any time and it is updated on regular
intervals without interaction by the client.

This fix started out to "only" make automatic optimization (or energy management)
runs working. It turned out there are several endpoints that in some way
update predictions or run the optimization. To lock against such concurrent attempts
the code had to be refactored to allow control of execution. During refactoring it
became clear that some classes and files are named without a proper reference
to their usage. Thus not only refactoring but also renaming became necessary.
The names are still not the best, but I hope they are more intuitive.

The fix includes several bug fixes that are not directly related to the automatic optimization
but are necessary to keep EOS running properly to do the automatic optimization and
to test and document the changes.

This is a breaking change as the configuration structure changed once again and
the server API was also enhanced and streamlined. The server API that is used by
Andreas and Jörg in their videos has not changed.

* fix: automatic optimization

  Allow optimization to automatically run on configured intervals gathering all
  optimization parameters from configuration and predictions. The automatic run
  can be configured to only run prediction updates skipping the optimization.
  Extend documentaion to also cover automatic optimization. Lock automatic runs
  against runs initiated by the /optimize or other endpoints. Provide new
  endpoints to retrieve the energy management plan and the genetic solution
  of the latest automatic optimization run. Offload energy management to thread
  pool executor to keep the app more responsive during the CPU heavy optimization
  run.

* fix: EOS servers recognize environment variables on startup

  Force initialisation of EOS configuration on server startup to assure
  all sources of EOS configuration are properly set up and read. Adapt
  server tests and configuration tests to also test for environment
  variable configuration.

* fix: Remove 0.0.0.0 to localhost translation under Windows

  EOS imposed a 0.0.0.0 to localhost translation under Windows for
  convenience. This caused some trouble in user configurations. Now, as the
  default IP address configuration is 127.0.0.1, the user is responsible
  for to set up the correct Windows compliant IP address.

* fix: allow names for hosts additional to IP addresses

* fix: access pydantic model fields by class

  Access by instance is deprecated.

* fix: down sampling key_to_array

* fix: make cache clear endpoint clear all cache files

  Make /v1/admin/cache/clear clear all cache files. Before it only cleared
  expired cache files by default. Add new endpoint /v1/admin/clear-expired
  to only clear expired cache files.

* fix: timezonefinder returns Europe/Paris instead of Europe/Berlin

  timezonefinder 8.10 got more inaccurate for timezones in europe as there is
  a common timezone. Use new package tzfpy instead which is still returning
  Europe/Berlin if you are in Germany. tzfpy also claims to be faster than
  timezonefinder.

* fix: provider settings configuration

  Provider configuration used to be a union holding the settings for several
  providers. Pydantic union handling does not always find the correct type
  for a provider setting. This led to exceptions in specific configurations.
  Now provider settings are explicit comfiguration items for each possible
  provider. This is a breaking change as the configuration structure was
  changed.

* fix: ClearOutside weather prediction irradiance calculation

  Pvlib needs a pandas time index. Convert time index.

* fix: test config file priority

  Do not use config_eos fixture as this fixture already creates a config file.

* fix: optimization sample request documentation

  Provide all data in documentation of optimization sample request.

* fix: gitlint blocking pip dependency resolution

  Replace gitlint by commitizen. Gitlint is not actively maintained anymore.
  Gitlint dependencies blocked pip from dependency resolution.

* fix: sync pre-commit config to actual dependency requirements

  .pre-commit-config.yaml was out of sync, also requirements-dev.txt.

* fix: missing babel in requirements.txt

  Add babel to requirements.txt

* feat: setup default device configuration for automatic optimization

  In case the parameters for automatic optimization are not fully defined a
  default configuration is setup to allow the automatic energy management
  run. The default configuration may help the user to correctly define
  the device configuration.

* feat: allow configuration of genetic algorithm parameters

  The genetic algorithm parameters for number of individuals, number of
  generations, the seed and penalty function parameters are now avaliable
  as configuration options.

* feat: allow configuration of home appliance time windows

  The time windows a home appliance is allowed to run are now configurable
  by the configuration (for /v1 API) and also by the home appliance parameters
  (for the classic /optimize API). If there is no such configuration the
  time window defaults to optimization hours, which was the standard before
  the change. Documentation on how to configure time windows is added.

* feat: standardize mesaurement keys for battery/ ev SoC measurements

  The standardized measurement keys to report battery SoC to the device
  simulations can now be retrieved from the device configuration as a
  read-only config option.

* feat: feed in tariff prediction

  Add feed in tarif predictions needed for automatic optimization. The feed in
  tariff can be retrieved as fixed feed in tarif or can be imported. Also add
  tests for the different feed in tariff providers. Extend documentation to
  cover the feed in tariff providers.

* feat: add energy management plan based on S2 standard instructions

  EOS can generate an energy management plan as a list of simple instructions.
  May be retrieved by the /v1/energy-management/plan endpoint. The instructions
  loosely follow the S2 energy management standard.

* feat: make measurement keys configurable by EOS configuration.

  The fixed measurement keys are replaced by configurable measurement keys.

* feat: make pendulum DateTime, Date, Duration types usable for pydantic models

  Use pydantic_extra_types.pendulum_dt to get pydantic pendulum types. Types are
  added to the datetimeutil utility. Remove custom made pendulum adaptations
  from EOS pydantic module. Make EOS modules use the pydantic pendulum types
  managed by the datetimeutil module instead of the core pendulum types.

* feat: Add Time, TimeWindow, TimeWindowSequence and to_time to datetimeutil.

  The time windows are are added to support home appliance time window
  configuration. All time classes are also pydantic models. Time is the base
  class for time definition derived from pendulum.Time.

* feat: Extend DataRecord by configurable field like data.

  Configurable field like data was added to support the configuration of
  measurement records.

* feat: Add additional information to health information

  Version information is added to the health endpoints of eos and eosDash.
  The start time of the last optimization and the latest run time of the energy
  management is added to the EOS health information.

* feat: add pydantic merge model tests

* feat: add plan tab to EOSdash

  The plan tab displays the current energy management instructions.

* feat: add predictions tab to EOSdash

  The predictions tab displays the current predictions.

* feat: add cache management to EOSdash admin tab

  The admin tab is extended by a section for cache management. It allows to
  clear the cache.

* feat: add about tab to EOSdash

  The about tab resembles the former hello tab and provides extra information.

* feat: Adapt changelog and prepare for release management

  Release management using commitizen is added. The changelog file is adapted and
  teh changelog and a description for release management is added in the
  documentation.

* feat(doc): Improve install and devlopment documentation

  Provide a more concise installation description in Readme.md and add extra
  installation page and development page to documentation.

* chore: Use memory cache for interpolation instead of dict in inverter

  Decorate calculate_self_consumption() with @cachemethod_until_update to cache
  results in memory during an energy management/ optimization run. Replacement
  of dict type caching in inverter is now possible because all optimization
  runs are properly locked and the memory cache CacheUntilUpdateStore is properly
  cleared at the start of any energy management/ optimization operation.

* chore: refactor genetic

  Refactor the genetic algorithm modules for enhanced module structure and better
  readability. Removed unnecessary and overcomplex devices singleton. Also
  split devices configuration from genetic algorithm parameters to allow further
  development independently from genetic algorithm parameter format. Move
  charge rates configuration for electric vehicles from optimization to devices
  configuration to allow to have different charge rates for different cars in
  the future.

* chore: Rename memory cache to CacheEnergyManagementStore

  The name better resembles the task of the cache to chache function and method
  results for an energy management run. Also the decorator functions are renamed
  accordingly: cachemethod_energy_management, cache_energy_management

* chore: use class properties for config/ems/prediction mixin classes

* chore: skip debug logs from mathplotlib

  Mathplotlib is very noisy in debug mode.

* chore: automatically sync bokeh js to bokeh python package

  bokeh was updated to 3.8.0, make JS CDN automatically follow the package version.

* chore: rename hello.py to about.py

  Make hello.py the adapted EOSdash about page.

* chore: remove demo page from EOSdash

  As no the plan and prediction pages are working without configuration, the demo
  page is no longer necessary

* chore: split test_server.py for system test

  Split test_server.py to create explicit test_system.py for system tests.

* chore: move doc utils to generate_config_md.py

  The doc utils are only used in scripts/generate_config_md.py. Move it there to
  attribute for strong cohesion.

* chore: improve pydantic merge model documentation

* chore: remove pendulum warning from readme

* chore: remove GitHub discussions from contributing documentation

  Github discussions is to be replaced by Akkudoktor.net.

* chore(release): bump version to 0.1.0+dev for development

* build(deps): bump fastapi[standard] from 0.115.14 to 0.117.1

  bump fastapi and make coverage version (for pytest-cov) explicit to avoid pip break.

* build(deps): bump uvicorn from 0.36.0 to 0.37.0

BREAKING CHANGE: EOS configuration changed. V1 API changed.

  - The available_charge_rates_percent configuration is removed from optimization.
    Use the new charge_rate configuration for the electric vehicle
  - Optimization configuration parameter hours renamed to horizon_hours
  - Device configuration now has to provide the number of devices and device
    properties per device.
  - Specific prediction provider configuration to be provided by explicit
    configuration item (no union for all providers).
  - Measurement keys to be provided as a list.
  - New feed in tariff providers have to be configured.
  - /v1/measurement/loadxxx endpoints are removed. Use generic mesaurement endpoints.
  - /v1/admin/cache/clear now clears all cache files. Use
    /v1/admin/cache/clear-expired to only clear all expired cache files.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
This commit is contained in:
Bobby Noelte
2025-10-28 02:50:31 +01:00
committed by GitHub
parent 20a9eb78d8
commit b397b5d43e
146 changed files with 22024 additions and 5339 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/develop/CHANGELOG.md Normal file
View File

@@ -0,0 +1,4 @@
```{include} ../../CHANGELOG.md
:relative-docs: ../
:relative-images:
```

572
docs/develop/develop.md Normal file
View File

@@ -0,0 +1,572 @@
% SPDX-License-Identifier: Apache-2.0
(develop-page)=
# Development Guide
## Development Prerequisites
Have or
[create](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github)
a [GitHub](https://github.com/) account.
Make shure all the source installation prequistes are installed. See the
[installation guideline](#install-page) for a detailed list of tools.
Under Linux the [make](https://www.gnu.org/software/make/manual/make.html) tool should be installed
as we have a lot of pre-fabricated commands for it.
Install your favorite editor or integrated development environment (IDE):
- Full-Featured IDEs
- [Eclipse + PyDev](https://www.pydev.org/)
- [KDevelop](https://www.kdevelop.org/)
- [PyCharm](https://www.jetbrains.com/pycharm/)
- ...
- Code Editors with Python Support
- [Visual Studio Code (VS Code)](https://code.visualstudio.com/)
- [Sublime Text](https://www.sublimetext.com/)
- [Atom / Pulsar](https://pulsar-edit.dev/)
- ...
- Python-Focused or Beginner-Friendly IDEs
- [Spyder](https://www.spyder-ide.org/)
- [Thonny](https://thonny.org/)
- [IDLE](https://www.python.org/downloads/)
- ...
## Step 1 – Fork the Repository
[Fork the EOS repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
to your GitHub account.
Clone your fork locally and add the EOS upstream remote to track updates.
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
git clone https://github.com/<YOURUSERNAME>/EOS.git
cd EOS
git remote add eos https://github.com/Akkudoktor-EOS/EOS.git
.. tab:: Linux
.. code-block:: bash
git clone https://github.com/<YOURUSERNAME>/EOS.git
cd EOS
git remote add eos https://github.com/Akkudoktor-EOS/EOS.git
```
Replace `<YOURUSERNAME>` with your GitHub username.
## Step 2 – Development Setup
This is recommended for developers who want to modify the source code and test changes locally.
### Step 2.1 – Create a Virtual Environment
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
python -m venv .venv
.venv\Scripts\pip install --upgrade pip
.venv\Scripts\pip install -r requirements-dev.txt
.venv\Scripts\pip install build
.venv\Scripts\pip install -e .
.. tab:: Linux
.. code-block:: bash
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements-dev.txt
.venv/bin/pip install build
.venv/bin/pip install -e .
.. tab:: Linux Make
.. code-block:: bash
make install
```
### Step 2.2 – Activate the Virtual Environment
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
.venv\Scripts\activate.bat
.. tab:: Linux
.. code-block:: bash
source .venv/bin/activate
```
### Step 2.3 - Install pre-commit
Our code style and commit message checks use [`pre-commit`](https://pre-commit.com).
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
pre-commit install
pre-commit install --hook-type commit-msg --hook-type pre-push
.. tab:: Linux
.. code-block:: bash
pre-commit install
pre-commit install --hook-type commit-msg --hook-type pre-push
```
## Step 3 - Run EOS
Make EOS accessible at [http://localhost:8503/docs](http://localhost:8503/docs) and EOSdash at
[http://localhost:8504](http://localhost:8504).
### Option 1 – Using Python Virtual Environment
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
python -m akkudoktoreos.server.eos
.. tab:: Linux
.. code-block:: bash
python -m akkudoktoreos.server.eos
.. tab:: Linux Make
.. code-block:: bash
make run
```
To have full control of the servers during development you may start the servers independently -
e.g. in different terminal windows. Don't forget to activate the virtual environment in your
terminal window.
:::{admonition} Note
:class: note
If you killed or stopped the servers shortly before, the ports may still be occupied by the last
processes. It may take more than 60 seconds until the ports are released.
:::
You may add the `--reload true` parameter to have the servers automatically restarted on source code
changes. It is best to also add `--startup_eosdash false` to EOS to prevent the automatic restart
interfere with the EOS server trying to start EOSdash.
<!-- pyml disable line-length -->
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
python -m akkudoktoreos.server.eosdash --host localhost --port 8504 --log_level DEBUG --reload true
.. tab:: Linux
.. code-block:: bash
python -m akkudoktoreos.server.eosdash --host localhost --port 8504 --log_level DEBUG --reload true
.. tab:: Linux Make
.. code-block:: bash
make run-dash-dev
```
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
python -m akkudoktoreos.server.eos --host localhost --port 8503 --log_level DEBUG --startup_eosdash false --reload true
.. tab:: Linux
.. code-block:: bash
python -m akkudoktoreos.server.eos --host localhost --port 8503 --log_level DEBUG --startup_eosdash false --reload true
.. tab:: Linux Make
.. code-block:: bash
make run-dev
```
<!-- pyml enable line-length -->
### Option 2 – Using Docker
#### Step 3.1 – Build the Docker Image
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
docker build -t akkudoktoreos .
.. tab:: Linux
.. code-block:: bash
docker build -t akkudoktoreos .
```
#### Step 3.2 – Run the Container
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
docker run -d `
--name akkudoktoreos `
-p 8503:8503 `
-p 8504:8504 `
-e OPENBLAS_NUM_THREADS=1 `
-e OMP_NUM_THREADS=1 `
-e MKL_NUM_THREADS=1 `
-e EOS_SERVER__HOST=0.0.0.0 `
-e EOS_SERVER__PORT=8503 `
-e EOS_SERVER__EOSDASH_HOST=0.0.0.0 `
-e EOS_SERVER__EOSDASH_PORT=8504 `
--ulimit nproc=65535:65535 `
--ulimit nofile=65535:65535 `
--security-opt seccomp=unconfined `
akkudoktor-eos:latest
.. tab:: Linux
.. code-block:: bash
docker run -d \
--name akkudoktoreos \
-p 8503:8503 \
-p 8504:8504 \
-e OPENBLAS_NUM_THREADS=1 \
-e OMP_NUM_THREADS=1 \
-e MKL_NUM_THREADS=1 \
-e EOS_SERVER__HOST=0.0.0.0 \
-e EOS_SERVER__PORT=8503 \
-e EOS_SERVER__EOSDASH_HOST=0.0.0.0 \
-e EOS_SERVER__EOSDASH_PORT=8504 \
--ulimit nproc=65535:65535 \
--ulimit nofile=65535:65535 \
--security-opt seccomp=unconfined \
akkudoktor-eos:latest
```
#### Step 3.3 – Manage the Container
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
docker logs -f akkudoktoreos
docker stop akkudoktoreos
docker start akkudoktoreos
docker rm -f akkudoktoreos
.. tab:: Linux
.. code-block:: bash
docker logs -f akkudoktoreos
docker stop akkudoktoreos
docker start akkudoktoreos
docker rm -f akkudoktoreos
```
For detailed Docker instructions, refer to
**[Method 3 & 4: Installation with Docker](install.md#method-3-installation-with-docker-dockerhub)**
and
**[Method 4: Docker Compose](install.md#method-4-installation-with-docker-docker-compose)**.
### Step 4 - Create the changes
#### Step 4.1 - Create a development branch
```bash
git checkout -b <MY_DEVELOPMENT_BRANCH>
```
Replace `<MY_DEVELOPMENT_BRANCH>` with the development branch name. The branch name shall be of the
format (feat|fix|chore|docs|refactor|test)/[a-z0-9._-]+, e.g:
- feat/my_cool_new_feature
- fix/this_annoying_bug
- ...
#### Step 4.2 – Edit the sources
Use your fovourite editor or IDE to edit the sources.
#### Step 4.3 - Check the source code for correct format
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
pre-commit run --all-files
.. tab:: Linux
.. code-block:: bash
pre-commit run --all-files
.. tab:: Linux Make
.. code-block:: bash
make format
```
#### Step 4.4 - Test the changes
At a minimum, you should run the module tests:
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
pytest -vs --cov src --cov-report term-missing
.. tab:: Linux
.. code-block:: bash
pytest -vs --cov src --cov-report term-missing
.. tab:: Linux Make
.. code-block:: bash
make test
```
You should also run the system tests. These include additional tests that interact with real
resources:
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
pytest --system-test -vs --cov src --cov-report term-missing
.. tab:: Linux
.. code-block:: bash
pytest --system-test -vs --cov src --cov-report term-missing
.. tab:: Linux Make
.. code-block:: bash
make test-system
```
#### Step 4.5 - Commit the changes
Add the changed and new files to the commit.
Create a commit.
### Step 5 - Pull request
Before creating a pull request assure the changes are based on the latest EOS upstream.
Update your local main branch:
```bash
git checkout main
git pull eos main
```
Switch back to your local development branch and rebase to main.
```bash
git checkout <MY_DEVELOPMENT_BRANCH>
git rebase -i main
```
During rebase you can also squash your changes into one (preferred) or a set of commits that have
proper commit messages and can easily be reviewed.
After rebase run the tests once again.
If everything is ok push the commit(s) to your fork on Github.
```bash
git push -f origin
```
If your push by intention does not comply to the rules you can skip the verification by:
```bash
git push -f --no-verify origin
```
<!-- pyml disable line-length -->
Once ready, [submit a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)
with your fork to the [Akkudoktor-EOS/EOS@master](https://github.com/Akkudoktor-EOS/EOS) repository.
<!-- pyml enable line-length -->
## Developer Tips
### Keep Your Fork Updated
Regularly pull changes from the eos repository to avoid merge conflicts:
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
git checkout main
git pull eos main
git push origin
.. tab:: Linux
.. code-block:: bash
git checkout main
git pull eos main
git push origin
```
Rebase your development branch to the latest eos main branch.
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
git checkout <MY_DEVELOPMENT_BRANCH>
git rebase -i main
.. tab:: Linux
.. code-block:: bash
git checkout <MY_DEVELOPMENT_BRANCH>
git rebase -i main
```
### Create Feature Branches
Work in separate branches for each feature or bug fix:
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
git checkout -b feat/my-feature
.. tab:: Linux
.. code-block:: bash
git checkout -b feat/my-feature
```
### Run Tests Frequently
Ensure your changes do not break existing functionality:
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
pytest -vs --cov src --cov-report term-missing
.. tab:: Linux
.. code-block:: bash
pytest -vs --cov src --cov-report term-missing
.. tab:: Linux Make
.. code-block:: bash
make test
```
### Follow Coding Standards
Keep your code consistent with existing style and conventions.
### Use Issues for Discussion
Before making major changes, open an issue or discuss with maintainers.
### Document Changes
Update docstrings, comments, and any relevant documentation.

157
docs/develop/getting_started.md
View File

@@ -1,127 +1,86 @@
% SPDX-License-Identifier: Apache-2.0
(getting-started-page)=
# Getting Started
## Installation
## Installation and Running
The project requires Python 3.10 or newer. Currently there are no official packages or images published.
AkkudoktorEOS can be installed and run using several different methods:
Following sections describe how to locally start the EOS server on `http://localhost:8503`.
- **Release package** (for stable versions)
- **Docker image** (for easy deployment)
- **From source** (for developers)
### Run from source
See the [installation guideline](#install-page) for detailed instructions on each method.
Install the dependencies in a virtual environment:
### Where to Find AkkudoktorEOS
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\pip install -e .
.. tab:: Linux
.. code-block:: bash
python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e .
```
Start the EOS fastapi server:
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
.venv\Scripts\python src/akkudoktoreos/server/eos.py
.. tab:: Linux
.. code-block:: bash
.venv/bin/python src/akkudoktoreos/server/eos.py
```
### Docker
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
docker compose up --build
.. tab:: Linux
.. code-block:: bash
docker compose up --build
```
- **Release Packages**: [GitHub Releases](https://github.com/Akkudoktor-EOS/EOS/releases)
- **Docker Images**: [Docker Hub](https://hub.docker.com/r/akkudoktor/eos)
- **Source Code**: [GitHub Repository](https://github.com/Akkudoktor-EOS/EOS)
## Configuration
This project uses the `EOS.config.json` file to manage configuration settings.
AkkudoktorEOS uses the `EOS.config.json` file to manage all configuration settings.
### Default Configuration
A default configuration file `default.config.json` is provided. This file contains all the necessary
configuration keys with their default values.
If essential configuration settings are missing, the application automatically uses a default
configuration to get you started quickly.
### Custom Configuration
### Custom Configuration Directory
Users can specify a custom configuration directory by setting the environment variable `EOS_DIR`.
You can specify a custom location for your configuration by setting the `EOS_DIR` environment
variable:
- If the directory specified by `EOS_DIR` contains an existing `EOS.config.json` file, the
application will use this configuration file.
- If the `EOS.config.json` file does not exist in the specified directory, the `default.config.json`
file will be copied to the directory as `EOS.config.json`.
```bash
export EOS_DIR=/path/to/your/config
```
### Configuration Updates
**How it works:**
If the configuration keys in the `EOS.config.json` file are missing or different from those in
`default.config.json`, they will be automatically updated to match the default settings, ensuring
that all required keys are present.
- **If `EOS.config.json` exists** in the `EOS_DIR` directory → the application uses this
configuration
- **If `EOS.config.json` doesn't exist** → the application copies `default.config.json` to `EOS_DIR`
as `EOS.config.json`
## Classes and Functionalities
### Creating Your Configuration
This project uses various classes to simulate and optimize the components of an energy system. Each
class represents a specific aspect of the system, as described below:
There are three ways to configure AkkudoktorEOS:
- `Battery`: Simulates a battery storage system, including capacity, state of charge, and now
charge and discharge losses.
1. **EOSdash (Recommended)** - The easiest method is to use the web-based dashboard at
[http://localhost:8504](http://localhost:8504)
- `PVForecast`: Provides forecast data for photovoltaic generation, based on weather data and
historical generation data.
2. **Manual editing** - Create or edit the `EOS.config.json` file directly in your preferred text
editor
- `Load`: Models the load requirements of a household or business, enabling the prediction of future
energy demand.
3. **Server API** - Programmatically change configuration through the [server API](#server-api-page)
- `Heatpump`: Simulates a heat pump, including its energy consumption and efficiency under various
operating conditions.
For a complete reference of all available configuration options, see the [configuration guideline](#configuration-page).
- `Strompreis`: Provides information on electricity prices, enabling optimization of energy
consumption and generation based on tariff information.
## Quick Start Example
- `EMS`: The Energy Management System (EMS) coordinates the interaction between the various
components, performs optimization, and simulates the operation of the entire energy system.
```bash
# Pull the latest docker image
docker pull akkudoktor/eos:latest
These classes work together to enable a detailed simulation and optimization of the energy system.
For each class, specific parameters and settings can be adjusted to test different scenarios and
strategies.
# Run the application
docker run -d \
--name akkudoktoreos \
-p 8503:8503 \
-p 8504:8504 \
-e OPENBLAS_NUM_THREADS=1 \
-e OMP_NUM_THREADS=1 \
-e MKL_NUM_THREADS=1 \
-e EOS_SERVER__HOST=0.0.0.0 \
-e EOS_SERVER__PORT=8503 \
-e EOS_SERVER__EOSDASH_HOST=0.0.0.0 \
-e EOS_SERVER__EOSDASH_PORT=8504 \
--ulimit nproc=65535:65535 \
--ulimit nofile=65535:65535 \
--security-opt seccomp=unconfined \
akkudoktor/eos:latest
### Customization and Extension
Each class is designed to be easily customized and extended to integrate additional functions or
improvements. For example, new methods can be added for more accurate modeling of PV system or
battery behavior. Developers are invited to modify and extend the system according to their needs.
# Access the dashboard
open http://localhost:8504
```

288
docs/develop/install.md Normal file
View File

@@ -0,0 +1,288 @@
% SPDX-License-Identifier: Apache-2.0
(install-page)=
# Installation Guide
This guide provides four different methods to install AkkudoktorEOS. Choose the method that best
suits your needs.
## Installation Prerequisites
Before installing, ensure you have the following:
- **For Source/Release Installation:**
- Python 3.10 or higher
- pip (Python package manager)
- Git (for source installation)
- Tar/Zip (for release package installation)
- **For Docker Installation:**
- Docker Engine 20.10 or higher
- Docker Compose (optional, but recommended)
## Method 1: Installation from Source (GitHub)
This method is recommended for developers or users who want the latest features.
### M1-Step 1: Clone the Repository
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
git clone https://github.com/Akkudoktor-EOS/EOS.git
cd EOS
.. tab:: Linux
.. code-block:: bash
git clone https://github.com/Akkudoktor-EOS/EOS.git
cd EOS
```
### M1-Step 2: Create a Virtual Environment and install dependencies
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\pip install -e .
.. tab:: Linux
.. code-block:: bash
python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e .
```
### M1-Step 3: Run EOS
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
.venv\Scripts\python -m akkudoktoreos.server.eos
.. tab:: Linux
.. code-block:: bash
.venv/bin/python -m akkudoktoreos.server.eos
```
EOS should now be accessible at [http://localhost:8503/docs](http://localhost:8503/docs) and EOSdash
should be available at [http://localhost:8504](http://localhost:8504).
If you want to make EOS and EOSdash accessible from outside of your machine or container at this
stage of the installation provide appropriate IP addresses on startup.
<!-- pyml disable line-length -->
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
.venv\Scripts\python -m akkudoktoreos.server.eos --host 0.0.0.0 --eosdash-host 0.0.0.0
.. tab:: Linux
.. code-block:: bash
.venv/bin/python -m akkudoktoreos.server.eos --host 0.0.0.0 --eosdash-host 0.0.0.0
```
<!-- pyml enable line-length -->
### M1-Step 4: Configure EOS
Use [EOSdash](http://localhost:8504) to configure EOS.
### Updating from Source
To update to the latest version:
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
git pull origin main
.venv\Scripts\pip install -r requirements.txt --upgrade
.. tab:: Linux
.. code-block:: bash
git pull origin main
.venv/bin/pip install -r requirements.txt --upgrade
```
## Method 2: Installation from Release Package (GitHub)
This method is recommended for users who want a stable, tested version.
### M2-Step 1: Download the Latest Release
Visit the [Releases page](https://github.com/Akkudoktor-EOS/EOS/releases) and download the latest
release package (e.g., `akkudoktoreos-v0.1.0.tar.gz` or `akkudoktoreos-v0.1.0.zip`).
### M2-Step 2: Extract the Package
```bash
tar -xzf akkudoktoreos-v0.1.0.tar.gz # For .tar.gz
# or
unzip akkudoktoreos-v0.1.0.zip # For .zip
cd akkudoktoreos-v0.1.0
```
### Follow Step 2, 3 and 4 of Method 1: Installation from source
Installation from release package now needs the exact same steps 2, 3, 4 of method 1.
## Method 3: Installation with Docker (DockerHub)
This method is recommended for easy deployment and containerized environments.
### M3-Step 1: Pull the Docker Image
```bash
docker pull akkudoktor/eos:latest
```
For a specific version:
```bash
docker pull akkudoktor/eos:v0.1.0
```
### M3-Step 2: Run the Container
**Basic run:**
```bash
docker run -d \
--name akkudoktoreos \
-p 8503:8503 \
-p 8504:8504 \
-e OPENBLAS_NUM_THREADS=1 \
-e OMP_NUM_THREADS=1 \
-e MKL_NUM_THREADS=1 \
-e EOS_SERVER__HOST=0.0.0.0 \
-e EOS_SERVER__PORT=8503 \
-e EOS_SERVER__EOSDASH_HOST=0.0.0.0 \
-e EOS_SERVER__EOSDASH_PORT=8504 \
--ulimit nproc=65535:65535 \
--ulimit nofile=65535:65535 \
--security-opt seccomp=unconfined \
akkudoktor/eos:latest
```
### M3-Step 3: Verify the Container is Running
```bash
docker ps
docker logs akkudoktoreos
```
EOS should now be accessible at [http://localhost:8503/docs](http://localhost:8503/docs) and EOSdash
should be available at [http://localhost:8504](http://localhost:8504).
### M3-Step 4: Configure EOS
Use [EOSdash](http://localhost:8504) to configure EOS.
### Docker Management Commands
**View logs:**
```bash
docker logs -f akkudoktoreos
```
**Stop the container:**
```bash
docker stop akkudoktoreos
```
**Start the container:**
```bash
docker start akkudoktoreos
```
**Remove the container:**
```bash
docker rm -f akkudoktoreos
```
**Update to latest version:**
```bash
docker pull Akkudoktor-EOS/EOS:latest
docker stop akkudoktoreos
docker rm akkudoktoreos
# Then run the container again with the run command
```
## Method 4: Installation with Docker (docker-compose)
### M4-Step 1: Get the akkudoktoreos source code
You may use either method 1 or method 2 to get the source code.
### M4-Step 2: Build and run the container
```{eval-rst}
.. tabs::
.. tab:: Windows
.. code-block:: powershell
docker compose up --build
.. tab:: Linux
.. code-block:: bash
docker compose up --build
```
### M4-Step 3: Verify the Container is Running
```bash
docker ps
docker logs akkudoktoreos
```
EOS should now be accessible at [http://localhost:8503/docs](http://localhost:8503/docs) and EOSdash
should be available at [http://localhost:8504](http://localhost:8504).
### M4-Step 4: Configure EOS
Use [EOSdash](http://localhost:8504) to configure EOS.

187
docs/develop/release.md Normal file
View File

@@ -0,0 +1,187 @@
% SPDX-License-Identifier: Apache-2.0
(release-page)=
# Release Process
This document describes how to prepare and publish a new release **via a Pull Request from a fork**,
using **Commitizen** to manage versioning and changelogs — and how to set a **development version** after the release.
## ✅ Overview of the Process
| Step | Actor | Action |
|------|-------------|--------|
| 1 | Contributor | Prepare a release branch **in your fork** using Commitizen |
| 2 | Contributor | Open a **Pull Request to upstream** (`Akkudoktor-EOS/EOS`) |
| 3 | Maintainer | Review and **merge the release PR** |
| 4 | Maintainer | Create the **GitHub Release and tag** |
| 5 | Maintainer | Set the **development version marker** via a follow-up PR |
## 🔄 Detailed Workflow
### 1️⃣ Contributor: Prepare the Release in Your Fork
**Clone and sync your fork:**
```bash
git clone https://github.com/<your-username>/EOS
cd EOS
git remote add eos https://github.com/Akkudoktor-EOS/EOS
git fetch eos
git checkout main
git pull eos main
````
**Create the release branch:**
```bash
git checkout -b release/vX.Y.Z
```
**Run Commitizen to bump version and update changelog:**
```bash
make bump
```
> ✅ This updates version files and `CHANGELOG.md` in a single commit.
> 🚫 **Do not push tags** — tags are created by the maintainer via GitHub Releases.
**Push the branch to your fork:**
```bash
git push origin release/vX.Y.Z
```
### 2️⃣ Contributor: Open the Release Pull Request
| From | To |
| ------------------------------------ | ------------------------- |
| `<your-username>/EOS:release/vX.Y.Z` | `Akkudoktor-EOS/EOS:main` |
**PR Title:**
```text
Release vX.Y.Z
```
**PR Description Template:**
```markdown
## Release vX.Y.Z
This pull request prepares release **vX.Y.Z**.
### Changes
- Version bump via Commitizen
- Changelog update
### Changelog Summary
<!-- Copy key highlights from CHANGELOG.md here -->
See `CHANGELOG.md` for full details.
```
### 3️⃣ Maintainer: Review and Merge the Release PR
**Review Checklist:**
* ✅ Only version files and `CHANGELOG.md` are modified
* ✅ Version numbers are consistent
* ✅ Changelog is complete and properly formatted
* ✅ No unrelated changes are included
**Merge Strategy:**
* Prefer **Merge Commit** (or **Squash Merge**, per project preference)
* Use commit message: `Release vX.Y.Z`
### 4️⃣ Maintainer: Publish the GitHub Release
1. Go to **GitHub → Releases → Draft a new release**
2. **Choose tag** → enter `vX.Y.Z` (GitHub creates the tag on publish)
3. **Release title:** `vX.Y.Z`
4. **Paste changelog entry** from `CHANGELOG.md`
5. Optionally enable **Set as latest release**
6. Click **Publish release** 🎉
### 5️⃣ Maintainer: Prepare the Development Version Marker
**Sync local copy:**
```bash
git fetch eos
git checkout main
git pull eos main
```
**Create a development version branch:**
```bash
git checkout -b release/vX.Y.Z_dev
```
**Set development marker manually:**
The following files have to be updated:
* pyproject.toml
* src/akkudoktoreos/core/version.py
* src/data/default.config.json
Example for pyproject.toml
```bash
sed -i 's/version = "\(.*\)"/version = "\1+dev"/' pyproject.toml
git add pyproject.toml
git commit -m "chore: set development version marker"
git push origin release/vX.Y.Z_dev
```
### 6️⃣ Maintainer (or Contributor): Open the Development Version PR
| From | To |
| ---------------------------------------- | ------------------------- |
| `<your-username>/EOS:release/vX.Y.Z_dev` | `Akkudoktor-EOS/EOS:main` |
**PR Title:**
```text
Release vX.Y.Z+dev
```
**PR Description Template:**
```markdown
## Release vX.Y.Z_dev
This pull request marks the repository as back in active development.
### Changes
- Set version to `vX.Y.Z+dev`
No changelog entry is needed.
```
### 7️⃣ Maintainer: Review and Merge the Development Version PR
**Checklist:**
* ✅ Only version files updated to `+dev`
* ✅ No unintended changes
**Merge Strategy:**
* Merge with commit message: `Release vX.Y.Z_dev`
## ✅ Quick Reference
| Step | Actor | Action |
| ---- | ----- | ------ |
| **1. Prepare release branch** | Contributor | Bump version & changelog via Commitizen |
| **2. Open release PR** | Contributor | Submit release for review |
| **3. Review & merge release PR** | Maintainer | Finalize changes into `main` |
| **4. Publish GitHub Release** | Maintainer | Create tag & notify users |
| **5. Prepare development version branch** | Maintainer | Set development marker |
| **6. Open development PR** | Maintainer (or Contributor) | Propose returning to development state |
| **7. Review & merge development PR** | Maintainer | Mark repository as back in development |