{"id":16263265,"url":"https://github.com/Akkudoktor-EOS/EOS","last_synced_at":"2025-10-25T06:30:33.849Z","repository":{"id":257307435,"uuid":"758458104","full_name":"Akkudoktor-EOS/EOS","owner":"Akkudoktor-EOS","description":"This repository features an Energy Optimization System (EOS) that optimizes energy distribution, usage for batteries, heat pumps\u0026 household devices. It includes predictive models for electricity prices (planned), load forecasting\u0026 dynamic optimization to maximize energy efficiency \u0026 minimize costs. Founder Dr. Andreas Schmitz (YouTube @akkudoktor)","archived":false,"fork":false,"pushed_at":"2025-02-08T15:55:50.000Z","size":29345,"stargazers_count":639,"open_issues_count":32,"forks_count":60,"subscribers_count":48,"default_branch":"main","last_synced_at":"2025-02-09T14:01:42.603Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://akkudoktor.net","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Akkudoktor-EOS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-16T11:13:56.000Z","updated_at":"2025-02-09T08:24:09.000Z","dependencies_parsed_at":"2024-10-24T10:47:39.346Z","dependency_job_id":"21206e65-3a3e-4804-b771-f91df54aabae","html_url":"https://github.com/Akkudoktor-EOS/EOS","commit_stats":{"total_commits":328,"total_committers":19,"mean_commits":"17.263157894736842","dds":0.5152439024390244,"last_synced_commit":"f8463d90c1949f9d29df4f8343bfce5e33200845"},"previous_names":["akkudoktor-eos/eos"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Akkudoktor-EOS%2FEOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Akkudoktor-EOS%2FEOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Akkudoktor-EOS%2FEOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Akkudoktor-EOS%2FEOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Akkudoktor-EOS","download_url":"https://codeload.github.com/Akkudoktor-EOS/EOS/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238089308,"owners_count":19414600,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T17:01:00.825Z","updated_at":"2025-10-25T06:30:33.843Z","avatar_url":"https://github.com/Akkudoktor-EOS.png","language":"Python","funding_links":[],"categories":["Repos","Energy Systems","🔧 Utilities \u0026 Miscellaneous","Table of Contents"],"sub_categories":["Energy System Modeling Frameworks","Other"],"readme":"# Energy System Simulation and Optimization\n\nThis 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\nDocumentation can be found at [Akkudoktor-EOS](https://akkudoktor-eos.readthedocs.io/en/latest/).\n\n## Getting Involved\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## System requirements\n\n- Python \u003e= 3.11, \u003c 3.13\n- Architecture: amd64, aarch64 (armv8)\n- OS: Linux, Windows, macOS\n\nNote: For Python 3.13 some dependencies (e.g. [Pendulum](https://github.com/python-pendulum/Pendulum)) are not yet available on https://pypi.org and have to be manually compiled (a recent [Rust](https://www.rust-lang.org/tools/install) installation is required).\n\nOther architectures (e.g. armv6, armv7) are unsupported for now, because a multitude of dependencies are not available on https://piwheels.org and have to be built manually (a recent Rust installation and [GCC](https://gcc.gnu.org/) are required, Python 3.11 is recommended).\n\n## Installation\n\nThe project requires Python 3.11 or newer. Docker images (amd64/aarch64) can be found at [akkudoktor/eos](https://hub.docker.com/r/akkudoktor/eos).\n\nFollowing sections describe how to locally start the EOS server on `http://localhost:8503`.\n\n### Run from source\n\nInstall dependencies in virtual environment:\n\nLinux:\n\n```bash\npython -m venv .venv\n.venv/bin/pip install -r requirements.txt\n.venv/bin/pip install -e .\n```\n\nWindows:\n\n```cmd\npython -m venv .venv\n.venv\\Scripts\\Activate\n.venv\\Scripts\\pip install -r requirements.txt\n.venv\\Scripts\\pip install -e .\n```\n\nFinally, start the EOS server to access it at `http://localhost:8503` (API docs at `http://localhost:8503/docs`):\n\nLinux:\n\n```bash\n.venv/bin/python src/akkudoktoreos/server/eos.py\n```\n\nWindows:\n\n```cmd\n.venv\\Scripts\\python src/akkudoktoreos/server/eos.py\n```\n\n### Docker\n\nStart EOS with following command to access it at `http://localhost:8503` (API docs at `http://localhost:8503/docs`):\n\n```bash\ndocker compose up\n```\n\nIf you are running the EOS container on a system hosting multiple services, such as a Synology NAS, and want to allow external network access to EOS, please ensure that the default exported ports (8503, 8504) are available on the host. On Synology systems, these ports might already be in use (refer to [this guide](https://kb.synology.com/en-me/DSM/tutorial/What_network_ports_are_used_by_Synology_services)). If the ports are occupied, you will need to reconfigure the exported ports accordingly.\n\n## Configuration\n\nThis project uses the `EOS.config.json` file to manage configuration settings.\n\n### Default Configuration\n\nA default configuration file `default.config.json` is provided. This file contains all the necessary configuration keys with their default values.\n\n### Custom Configuration\n\nUsers can specify a custom configuration directory by setting the environment variable `EOS_DIR`.\n\n- If the directory specified by `EOS_DIR` contains an existing `config.json` file, the application will use this configuration file.\n- 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`.\n\n### Configuration Updates\n\nIf 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.\n\n## Classes and Functionalities\n\nThis 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:\n\n- `Battery`: Simulates a battery storage system, including capacity, state of charge, and now charge and discharge losses.\n\n- `PVForecast`: Provides forecast data for photovoltaic generation, based on weather data and historical generation data.\n\n- `Load`: Models the load requirements of a household or business, enabling the prediction of future energy demand.\n\n- `Heatpump`: Simulates a heat pump, including its energy consumption and efficiency under various operating conditions.\n\n- `Strompreis`: Provides information on electricity prices, enabling optimization of energy consumption and generation based on tariff information.\n\n- `EMS`: The Energy Management System (EMS) coordinates the interaction between the various components, performs optimization, and simulates the operation of the entire energy system.\n\nThese 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.\n\n### Customization and Extension\n\nEach 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.\n\n## Server API\n\nSee the Swagger API documentation for detailed information: [EOS OpenAPI Spec](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json)\n\n## Further resources\n\n- [Installation guide (de)](https://meintechblog.de/2024/09/05/andreas-schmitz-joerg-installiert-mein-energieoptimierungssystem/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAkkudoktor-EOS%2FEOS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAkkudoktor-EOS%2FEOS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAkkudoktor-EOS%2FEOS/lists"}