How akkudoktor-eos/eos works
Main Components
• Energy System Simulator/Optimizer (EMS): At the core, this application models and optimizes an energy system. Components include Battery, PVForecast, Load, Heatpump, and more. These elements can be represented as distinct modules.
• Forecasting & Prediction Modules: Include subcomponents such as PVForecast, Load Prediction, Electricity Price forecasting (Strompreis), and weather integrations.
• Devices/Subsystems: Clearly call out modules representing physical devices (battery, heat pump, inverter, etc.).
• Configuration Management: Highlight the configuration system that manages settings via JSON configuration files (EOS.config.json and default.config.json) and environment variables.
• API Server: Indicated by the presence of src/akkudoktoreos/server (e.g., eos.py, eosdash.py), which provides endpoints for external interaction and documentation via Swagger.
• Data Handling: Represent the modules handling measurement data, configuration loadings, and data caching (also depicted under “data” and “utils” modules).
• Optimization Engine: The optimization folder contains genetic algorithms and optimization classes that drive smart decision-making.
• External Interfaces & Deployment: Note the Dockerfile, docker-compose.yaml, and CI/CD configurations indicating deployment containers along with GitHub workflows.
Relationships and Interactions
• The API server (src/akkudoktoreos/server) handles incoming requests from clients (with interactive documentation at http://localhost:8503/docs) and passes these to the core EMS component.
• The EMS orchestrates simulation and optimization by invoking the various device modules (battery, heat pump, inverter) and forecasting modules (PVForecast, weather, load).
• Configuration components read and possibly update settings from the JSON config files; these settings are then used by the EMS and other modules to run simulations/optimizations.
• Data flows can be visualized from input data (loaded from files or API) to prediction modules to the optimization engine, then finally to generation of simulation results (which may be visualized or returned via API).
Architectural Patterns and Design Principles
• The project appears to follow a modular and layered architecture. Modules are separated by functionality (config, core, prediction, optimization, server) which is helpful to decouple concerns.
• Abstraction is utilized with “abc” (abstract base classes) in multiple components (configabc, coreabc, devicesabc, etc.) to enforce interfaces and enable customization or future extension.
• Dependency injection and configuration management are emphasized via the config files, enabling both default and custom operation flows.
• Testing is treated as first-class (see tests directory), ensuring that individual modules can be verified independently.
• The OpenAPI / Swagger integration demonstrates an API-first design for external connectivity.
Instructing the Principal Software Engineer
• Elements are clearly labeled. For instance, the “Battery” module should clearly mention its associated methods related to state of charge and losses.
• API calls enter through the Server component.
• The EMS distributes tasks to Forecast and Optimization modules.
• Data flows back from modules to the API layer for output generation.
• External integrations (Swagger API docs, Docker container orchestration) to underline deployment and connectivity aspects.
Detailed Component List
• API Server:
• Components: eos.py, eosdash.py, server.py.
• Role: Exposing API endpoints, integrating Swagger documentation.
• Energy Management System (EMS):
• Modules: core/ems, optimization (genetic algorithms, optimization logic), and coordination between device components.
• Forecast and Prediction Modules:
• Components: pvforecast, elecprice, load, weather.
• Role: Predicting generation, demand, and pricing.
• Device Modules:
• Components: battery, inverter, heatpump, generic device interfaces.
• Configuration & Data Management:
• Components: config directory, default.config.json, dynamic updating of EOS.config.json.
• Utility Services:
• Components: cache, datetime utilities, logging.
• Infrastructure & Deployment:
• Dockerfile, docker-compose.yaml, CI/CD workflow indicators from .github and Makefile.