mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2025-08-26 15:31:14 +00:00
Add API documentation generation and use Markdown (#160)
* Add package API documentation generation Add generation of the API documentation for akkudoktoreos and akkudoktoreosserver packages. The API documentation is generated by the Sphinx autosummary extension. Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com> * Enable Google style source commenting and documentation generation. Enable automatic documentation generation from Google style docstrings in the source. Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com> * Check Google style source commenting. Check Google style commenting by the appropriate ruff rules. Commenting is _NOT_ enforced. Missing docstrings are ignored. Minor commenting quirks of the code base are adapted. Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com> * Improve Markdown handling and switch to Markdown documentation. Switch to Markdown for the documentation files to improve the user and developer experience (see issue #181). Keep files with special directives for automatic API documentation in RST format. The directives expect RST. Also add dummy handling for openai/ swagger server documentation. The openai interface definition is for now taken from the fastapi PR as EOS will switch to fastAPI. Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com> --------- Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com> Co-authored-by: Normann <github@koldrack.com>
This commit is contained in:
Bobby Noelte
GitHub
33
docs/_templates/autosummary/class.rst
vendored
Normal file
33
docs/_templates/autosummary/class.rst
vendored
Normal file
@@ -0,0 +1,33 @@
|
||||
{{ fullname | escape | underline}}
|
||||
|
||||
.. currentmodule:: {{ module }}
|
||||
|
||||
.. autoclass:: {{ objname }}
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
:inherited-members:
|
||||
|
||||
{% block methods %}
|
||||
.. automethod:: __init__
|
||||
|
||||
{% if methods %}
|
||||
.. rubric:: {{ _('Methods') }}
|
||||
|
||||
.. autosummary::
|
||||
{% for item in methods %}
|
||||
~{{ name }}.{{ item }}
|
||||
{%- endfor %}
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
|
||||
{% block attributes %}
|
||||
{% if attributes %}
|
||||
.. rubric:: {{ _('Attributes') }}
|
||||
|
||||
.. autosummary::
|
||||
{% for item in attributes %}
|
||||
~{{ name }}.{{ item }}
|
||||
{%- endfor %}
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
66
docs/_templates/autosummary/module.rst
vendored
Normal file
66
docs/_templates/autosummary/module.rst
vendored
Normal file
@@ -0,0 +1,66 @@
|
||||
{{ fullname | escape | underline}}
|
||||
|
||||
.. automodule:: {{ fullname }}
|
||||
|
||||
{% block attributes %}
|
||||
{% if attributes %}
|
||||
.. rubric:: Module Attributes
|
||||
|
||||
.. autosummary::
|
||||
:toctree:
|
||||
{% for item in attributes %}
|
||||
{{ item }}
|
||||
{%- endfor %}
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
|
||||
{% block functions %}
|
||||
{% if functions %}
|
||||
.. rubric:: {{ _('Functions') }}
|
||||
|
||||
.. autosummary::
|
||||
:toctree:
|
||||
{% for item in functions %}
|
||||
{{ item }}
|
||||
{%- endfor %}
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
|
||||
{% block classes %}
|
||||
{% if classes %}
|
||||
.. rubric:: {{ _('Classes') }}
|
||||
|
||||
.. autosummary::
|
||||
:toctree:
|
||||
:template: autosummary/class.rst
|
||||
{% for item in classes %}
|
||||
{{ item }}
|
||||
{%- endfor %}
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
|
||||
{% block exceptions %}
|
||||
{% if exceptions %}
|
||||
.. rubric:: {{ _('Exceptions') }}
|
||||
|
||||
.. autosummary::
|
||||
:toctree:
|
||||
{% for item in exceptions %}
|
||||
{{ item }}
|
||||
{%- endfor %}
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
|
||||
{% block modules %}
|
||||
{% if modules %}
|
||||
.. rubric:: Modules
|
||||
|
||||
.. autosummary::
|
||||
:toctree:
|
||||
:template: autosummary/module.rst
|
||||
:recursive:
|
||||
{% for item in modules %}
|
||||
{{ item }}
|
||||
{%- endfor %}
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
@@ -1,11 +1,6 @@
|
||||
..
|
||||
Copyright (c) 2024 Bobby Noelte
|
||||
SPDX-License-Identifier: Apache-2.0
|
||||
% SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
.. _akkudoktoreos_about:
|
||||
|
||||
About Akkudoktor EOS
|
||||
####################
|
||||
# About Akkudoktor EOS
|
||||
|
||||
The Energy System Simulation and Optimization System (EOS) provides a comprehensive solution for
|
||||
simulating and optimizing an energy system based on renewable energy sources. With a focus on
|
||||
16
docs/akkudoktoreos/api.rst
Normal file
16
docs/akkudoktoreos/api.rst
Normal file
@@ -0,0 +1,16 @@
|
||||
..
|
||||
SPDX-License-Identifier: Apache-2.0
|
||||
File has to be of RST format to make autosummary directive work correctly
|
||||
|
||||
.. _akkudoktoreos_api:
|
||||
|
||||
EOS API
|
||||
=======
|
||||
|
||||
.. autosummary::
|
||||
:toctree: _autosummary
|
||||
:template: autosummary/module.rst
|
||||
:recursive:
|
||||
|
||||
akkudoktoreos
|
||||
akkudoktoreosserver
|
||||
921
docs/akkudoktoreosserver/openapi.json
Normal file
921
docs/akkudoktoreosserver/openapi.json
Normal file
@@ -0,0 +1,921 @@
|
||||
{
|
||||
"openapi": "3.1.0",
|
||||
"info": {
|
||||
"title": "Akkudoktor-EOS",
|
||||
"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.",
|
||||
"version": "0.0.1"
|
||||
},
|
||||
"paths": {
|
||||
"/strompreis": {
|
||||
"get": {
|
||||
"summary": "Fastapi Strompreis",
|
||||
"operationId": "fastapi_strompreis_strompreis_get",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"items": {
|
||||
"type": "number"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Response Fastapi Strompreis Strompreis Get"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/gesamtlast": {
|
||||
"post": {
|
||||
"summary": "Fastapi Gesamtlast",
|
||||
"description": "Endpoint to handle total load calculation based on the latest measured data",
|
||||
"operationId": "fastapi_gesamtlast_gesamtlast_post",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "year_energy",
|
||||
"in": "query",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "number",
|
||||
"title": "Year Energy"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "hours",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"default": 48,
|
||||
"title": "Hours"
|
||||
}
|
||||
}
|
||||
],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object"
|
||||
},
|
||||
"title": "Measured Data"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "number"
|
||||
},
|
||||
"title": "Response Fastapi Gesamtlast Gesamtlast Post"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"422": {
|
||||
"description": "Validation Error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/HTTPValidationError"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/gesamtlast_simple": {
|
||||
"get": {
|
||||
"summary": "Fastapi Gesamtlast Simple",
|
||||
"operationId": "fastapi_gesamtlast_simple_gesamtlast_simple_get",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "year_energy",
|
||||
"in": "query",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "number",
|
||||
"title": "Year Energy"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "number"
|
||||
},
|
||||
"title": "Response Fastapi Gesamtlast Simple Gesamtlast Simple Get"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"422": {
|
||||
"description": "Validation Error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/HTTPValidationError"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/pvforecast": {
|
||||
"get": {
|
||||
"summary": "Fastapi Pvprognose",
|
||||
"operationId": "fastapi_pvprognose_pvforecast_get",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "url",
|
||||
"in": "query",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"title": "Url"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "ac_power_measurement",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "number"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"title": "Ac Power Measurement"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ForecastResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"422": {
|
||||
"description": "Validation Error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/HTTPValidationError"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/optimize": {
|
||||
"post": {
|
||||
"summary": "Fastapi Optimize",
|
||||
"operationId": "fastapi_optimize_optimize_post",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "start_hour",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "integer"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "Defaults to current hour of the day.",
|
||||
"title": "Start Hour"
|
||||
},
|
||||
"description": "Defaults to current hour of the day."
|
||||
}
|
||||
],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/OptimizationParameters"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/OptimizeResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"422": {
|
||||
"description": "Validation Error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/HTTPValidationError"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/visualization_results.pdf": {
|
||||
"get": {
|
||||
"summary": "Get Pdf",
|
||||
"operationId": "get_pdf_visualization_results_pdf_get",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"schemas": {
|
||||
"EAutoParameters": {
|
||||
"properties": {
|
||||
"kapazitaet_wh": {
|
||||
"type": "integer",
|
||||
"exclusiveMinimum": 0.0,
|
||||
"title": "Kapazitaet Wh",
|
||||
"description": "An integer representing the capacity of the battery in watt-hours."
|
||||
},
|
||||
"lade_effizienz": {
|
||||
"type": "number",
|
||||
"maximum": 1.0,
|
||||
"exclusiveMinimum": 0.0,
|
||||
"title": "Lade Effizienz",
|
||||
"description": "A float representing the charging efficiency of the battery.",
|
||||
"default": 0.88
|
||||
},
|
||||
"entlade_effizienz": {
|
||||
"type": "number",
|
||||
"title": "Entlade Effizienz",
|
||||
"default": 1.0
|
||||
},
|
||||
"max_ladeleistung_w": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "number",
|
||||
"exclusiveMinimum": 0.0
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"title": "Max Ladeleistung W",
|
||||
"description": "An integer representing the charging power of the battery in watts."
|
||||
},
|
||||
"start_soc_prozent": {
|
||||
"type": "integer",
|
||||
"maximum": 100.0,
|
||||
"minimum": 0.0,
|
||||
"title": "Start Soc Prozent",
|
||||
"description": "An integer representing the current state of charge (SOC) of the battery in percentage.",
|
||||
"default": 0
|
||||
},
|
||||
"min_soc_prozent": {
|
||||
"type": "integer",
|
||||
"maximum": 100.0,
|
||||
"minimum": 0.0,
|
||||
"title": "Min Soc Prozent",
|
||||
"description": "An integer representing the minimum state of charge (SOC) of the battery in percentage.",
|
||||
"default": 0
|
||||
},
|
||||
"max_soc_prozent": {
|
||||
"type": "integer",
|
||||
"maximum": 100.0,
|
||||
"minimum": 0.0,
|
||||
"title": "Max Soc Prozent",
|
||||
"default": 100
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"kapazitaet_wh"
|
||||
],
|
||||
"title": "EAutoParameters"
|
||||
},
|
||||
"EAutoResult": {
|
||||
"properties": {
|
||||
"charge_array": {
|
||||
"items": {
|
||||
"type": "number"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Charge Array",
|
||||
"description": "Indicates for each hour whether the EV is charging (`0` for no charging, `1` for charging)."
|
||||
},
|
||||
"discharge_array": {
|
||||
"items": {
|
||||
"type": "integer"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Discharge Array",
|
||||
"description": "Indicates for each hour whether the EV is discharging (`0` for no discharging, `1` for discharging)."
|
||||
},
|
||||
"entlade_effizienz": {
|
||||
"type": "number",
|
||||
"title": "Entlade Effizienz",
|
||||
"description": "The discharge efficiency as a float."
|
||||
},
|
||||
"hours": {
|
||||
"type": "integer",
|
||||
"title": "Hours",
|
||||
"default": "Amount of hours the simulation is done for."
|
||||
},
|
||||
"kapazitaet_wh": {
|
||||
"type": "integer",
|
||||
"title": "Kapazitaet Wh",
|
||||
"default": "The capacity of the EV\u2019s battery in watt-hours."
|
||||
},
|
||||
"lade_effizienz": {
|
||||
"type": "number",
|
||||
"title": "Lade Effizienz",
|
||||
"default": "The charging efficiency as a float."
|
||||
},
|
||||
"max_ladeleistung_w": {
|
||||
"type": "integer",
|
||||
"title": "Max Ladeleistung W",
|
||||
"description": "The maximum charging power of the EV in watts."
|
||||
},
|
||||
"soc_wh": {
|
||||
"type": "number",
|
||||
"title": "Soc Wh",
|
||||
"description": "The state of charge of the battery in watt-hours at the start of the simulation."
|
||||
},
|
||||
"start_soc_prozent": {
|
||||
"type": "integer",
|
||||
"title": "Start Soc Prozent",
|
||||
"description": "The state of charge of the battery in percentage at the start of the simulation."
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"charge_array",
|
||||
"discharge_array",
|
||||
"entlade_effizienz",
|
||||
"max_ladeleistung_w",
|
||||
"soc_wh",
|
||||
"start_soc_prozent"
|
||||
],
|
||||
"title": "EAutoResult",
|
||||
"description": "\"This object contains information related to the electric vehicle and its charging and discharging behavior"
|
||||
},
|
||||
"EnergieManagementSystemParameters": {
|
||||
"properties": {
|
||||
"pv_prognose_wh": {
|
||||
"items": {
|
||||
"type": "number"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Pv Prognose Wh",
|
||||
"description": "An array of floats representing the forecasted photovoltaic output in watts for different time intervals."
|
||||
},
|
||||
"strompreis_euro_pro_wh": {
|
||||
"items": {
|
||||
"type": "number"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Strompreis Euro Pro Wh",
|
||||
"description": "An array of floats representing the electricity price in euros per watt-hour for different time intervals."
|
||||
},
|
||||
"einspeiseverguetung_euro_pro_wh": {
|
||||
"type": "number",
|
||||
"title": "Einspeiseverguetung Euro Pro Wh",
|
||||
"description": "A float representing the feed-in compensation in euros per watt-hour."
|
||||
},
|
||||
"preis_euro_pro_wh_akku": {
|
||||
"type": "number",
|
||||
"title": "Preis Euro Pro Wh Akku"
|
||||
},
|
||||
"gesamtlast": {
|
||||
"items": {
|
||||
"type": "number"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Gesamtlast",
|
||||
"description": "An array of floats representing the total load (consumption) in watts for different time intervals."
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"pv_prognose_wh",
|
||||
"strompreis_euro_pro_wh",
|
||||
"einspeiseverguetung_euro_pro_wh",
|
||||
"preis_euro_pro_wh_akku",
|
||||
"gesamtlast"
|
||||
],
|
||||
"title": "EnergieManagementSystemParameters"
|
||||
},
|
||||
"ForecastResponse": {
|
||||
"properties": {
|
||||
"temperature": {
|
||||
"items": {
|
||||
"type": "number"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Temperature"
|
||||
},
|
||||
"pvpower": {
|
||||
"items": {
|
||||
"type": "number"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Pvpower"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"temperature",
|
||||
"pvpower"
|
||||
],
|
||||
"title": "ForecastResponse"
|
||||
},
|
||||
"HTTPValidationError": {
|
||||
"properties": {
|
||||
"detail": {
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/ValidationError"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Detail"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"title": "HTTPValidationError"
|
||||
},
|
||||
"HaushaltsgeraetParameters": {
|
||||
"properties": {
|
||||
"verbrauch_wh": {
|
||||
"type": "integer",
|
||||
"exclusiveMinimum": 0.0,
|
||||
"title": "Verbrauch Wh",
|
||||
"description": "An integer representing the energy consumption of a household device in watt-hours."
|
||||
},
|
||||
"dauer_h": {
|
||||
"type": "integer",
|
||||
"exclusiveMinimum": 0.0,
|
||||
"title": "Dauer H",
|
||||
"description": "An integer representing the usage duration of a household device in hours."
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"verbrauch_wh",
|
||||
"dauer_h"
|
||||
],
|
||||
"title": "HaushaltsgeraetParameters"
|
||||
},
|
||||
"OptimizationParameters": {
|
||||
"properties": {
|
||||
"ems": {
|
||||
"$ref": "#/components/schemas/EnergieManagementSystemParameters"
|
||||
},
|
||||
"pv_akku": {
|
||||
"$ref": "#/components/schemas/PVAkkuParameters"
|
||||
},
|
||||
"wechselrichter": {
|
||||
"$ref": "#/components/schemas/WechselrichterParameters",
|
||||
"default": {
|
||||
"max_leistung_wh": 10000.0
|
||||
}
|
||||
},
|
||||
"eauto": {
|
||||
"$ref": "#/components/schemas/EAutoParameters"
|
||||
},
|
||||
"spuelmaschine": {
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/components/schemas/HaushaltsgeraetParameters"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
},
|
||||
"temperature_forecast": {
|
||||
"items": {
|
||||
"type": "number"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Temperature Forecast",
|
||||
"default": "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_akku",
|
||||
"eauto"
|
||||
],
|
||||
"title": "OptimizationParameters"
|
||||
},
|
||||
"OptimizeResponse": {
|
||||
"properties": {
|
||||
"discharge_hours_bin": {
|
||||
"items": {
|
||||
"type": "integer"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Discharge Hours Bin",
|
||||
"description": "An array that indicates for each hour of the forecast period whether energy is discharged from the battery or not. The values are either `0` (no discharge) or `1` (discharge)."
|
||||
},
|
||||
"eautocharge_hours_float": {
|
||||
"items": {
|
||||
"type": "number"
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Eautocharge Hours Float",
|
||||
"description": "An array of binary values (0 or 1) that indicates whether the EV will be charged in a certain hour."
|
||||
},
|
||||
"result": {
|
||||
"$ref": "#/components/schemas/SimulationResult"
|
||||
},
|
||||
"eauto_obj": {
|
||||
"$ref": "#/components/schemas/EAutoResult"
|
||||
},
|
||||
"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."
|
||||
},
|
||||
"spuelstart": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "integer"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"title": "Spuelstart",
|
||||
"description": "Can be `null` or contain an object representing the start of washing (if applicable)."
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"discharge_hours_bin",
|
||||
"eautocharge_hours_float",
|
||||
"result",
|
||||
"eauto_obj"
|
||||
],
|
||||
"title": "OptimizeResponse",
|
||||
"description": "**Note**: The first value of \"Last_Wh_pro_Stunde\", \"Netzeinspeisung_Wh_pro_Stunde\" and \"Netzbezug_Wh_pro_Stunde\", 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."
|
||||
},
|
||||
"PVAkkuParameters": {
|
||||
"properties": {
|
||||
"kapazitaet_wh": {
|
||||
"type": "integer",
|
||||
"exclusiveMinimum": 0.0,
|
||||
"title": "Kapazitaet Wh",
|
||||
"description": "An integer representing the capacity of the battery in watt-hours."
|
||||
},
|
||||
"lade_effizienz": {
|
||||
"type": "number",
|
||||
"maximum": 1.0,
|
||||
"exclusiveMinimum": 0.0,
|
||||
"title": "Lade Effizienz",
|
||||
"description": "A float representing the charging efficiency of the battery.",
|
||||
"default": 0.88
|
||||
},
|
||||
"entlade_effizienz": {
|
||||
"type": "number",
|
||||
"maximum": 1.0,
|
||||
"exclusiveMinimum": 0.0,
|
||||
"title": "Entlade Effizienz",
|
||||
"default": 0.88
|
||||
},
|
||||
"max_ladeleistung_w": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "number",
|
||||
"exclusiveMinimum": 0.0
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"title": "Max Ladeleistung W",
|
||||
"description": "An integer representing the charging power of the battery in watts.",
|
||||
"default": 5000
|
||||
},
|
||||
"start_soc_prozent": {
|
||||
"type": "integer",
|
||||
"maximum": 100.0,
|
||||
"minimum": 0.0,
|
||||
"title": "Start Soc Prozent",
|
||||
"description": "An integer representing the state of charge of the battery at the **start** of the current hour (not the current state).",
|
||||
"default": 0
|
||||
},
|
||||
"min_soc_prozent": {
|
||||
"type": "integer",
|
||||
"maximum": 100.0,
|
||||
"minimum": 0.0,
|
||||
"title": "Min Soc Prozent",
|
||||
"description": "An integer representing the minimum state of charge (SOC) of the battery in percentage.",
|
||||
"default": 0
|
||||
},
|
||||
"max_soc_prozent": {
|
||||
"type": "integer",
|
||||
"maximum": 100.0,
|
||||
"minimum": 0.0,
|
||||
"title": "Max Soc Prozent",
|
||||
"default": 100
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"kapazitaet_wh"
|
||||
],
|
||||
"title": "PVAkkuParameters"
|
||||
},
|
||||
"SimulationResult": {
|
||||
"properties": {
|
||||
"Last_Wh_pro_Stunde": {
|
||||
"items": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "number"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Last Wh Pro Stunde",
|
||||
"description": "TBD"
|
||||
},
|
||||
"EAuto_SoC_pro_Stunde": {
|
||||
"items": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "number"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Eauto Soc Pro Stunde",
|
||||
"description": "The state of charge of the EV for each hour."
|
||||
},
|
||||
"Einnahmen_Euro_pro_Stunde": {
|
||||
"items": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "number"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Einnahmen Euro Pro Stunde",
|
||||
"description": "The revenue from grid feed-in or other sources in euros per hour."
|
||||
},
|
||||
"Gesamt_Verluste": {
|
||||
"type": "number",
|
||||
"title": "Gesamt Verluste",
|
||||
"description": "The total losses in watt-hours over the entire period."
|
||||
},
|
||||
"Gesamtbilanz_Euro": {
|
||||
"type": "number",
|
||||
"title": "Gesamtbilanz Euro",
|
||||
"description": "The total balance of revenues minus costs in euros."
|
||||
},
|
||||
"Gesamteinnahmen_Euro": {
|
||||
"type": "number",
|
||||
"title": "Gesamteinnahmen Euro",
|
||||
"description": "The total revenues in euros."
|
||||
},
|
||||
"Gesamtkosten_Euro": {
|
||||
"type": "number",
|
||||
"title": "Gesamtkosten Euro",
|
||||
"description": "The total costs in euros."
|
||||
},
|
||||
"Haushaltsgeraet_wh_pro_stunde": {
|
||||
"items": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "number"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Haushaltsgeraet Wh Pro Stunde",
|
||||
"description": "The energy consumption of a household appliance in watt-hours per hour."
|
||||
},
|
||||
"Kosten_Euro_pro_Stunde": {
|
||||
"items": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "number"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Kosten Euro Pro Stunde",
|
||||
"description": "The costs in euros per hour."
|
||||
},
|
||||
"Netzbezug_Wh_pro_Stunde": {
|
||||
"items": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "number"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Netzbezug Wh Pro Stunde",
|
||||
"description": "The grid energy drawn in watt-hours per hour."
|
||||
},
|
||||
"Netzeinspeisung_Wh_pro_Stunde": {
|
||||
"items": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "number"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Netzeinspeisung Wh Pro Stunde",
|
||||
"description": "The energy fed into the grid in watt-hours per hour."
|
||||
},
|
||||
"Verluste_Pro_Stunde": {
|
||||
"items": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "number"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Verluste Pro Stunde",
|
||||
"description": "The losses in watt-hours per hour."
|
||||
},
|
||||
"akku_soc_pro_stunde": {
|
||||
"items": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "number"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Akku Soc Pro Stunde",
|
||||
"description": "The state of charge of the battery (not the EV) in percentage per hour."
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"Last_Wh_pro_Stunde",
|
||||
"EAuto_SoC_pro_Stunde",
|
||||
"Einnahmen_Euro_pro_Stunde",
|
||||
"Gesamt_Verluste",
|
||||
"Gesamtbilanz_Euro",
|
||||
"Gesamteinnahmen_Euro",
|
||||
"Gesamtkosten_Euro",
|
||||
"Haushaltsgeraet_wh_pro_stunde",
|
||||
"Kosten_Euro_pro_Stunde",
|
||||
"Netzbezug_Wh_pro_Stunde",
|
||||
"Netzeinspeisung_Wh_pro_Stunde",
|
||||
"Verluste_Pro_Stunde",
|
||||
"akku_soc_pro_stunde"
|
||||
],
|
||||
"title": "SimulationResult",
|
||||
"description": "This object contains the results of the simulation and provides insights into various parameters over the entire forecast period"
|
||||
},
|
||||
"ValidationError": {
|
||||
"properties": {
|
||||
"loc": {
|
||||
"items": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "integer"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type": "array",
|
||||
"title": "Location"
|
||||
},
|
||||
"msg": {
|
||||
"type": "string",
|
||||
"title": "Message"
|
||||
},
|
||||
"type": {
|
||||
"type": "string",
|
||||
"title": "Error Type"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": [
|
||||
"loc",
|
||||
"msg",
|
||||
"type"
|
||||
],
|
||||
"title": "ValidationError"
|
||||
},
|
||||
"WechselrichterParameters": {
|
||||
"properties": {
|
||||
"max_leistung_wh": {
|
||||
"type": "number",
|
||||
"exclusiveMinimum": 0.0,
|
||||
"title": "Max Leistung Wh",
|
||||
"default": 10000
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"title": "WechselrichterParameters"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
17
docs/akkudoktoreosserver/serverapi.rst
Normal file
17
docs/akkudoktoreosserver/serverapi.rst
Normal file
@@ -0,0 +1,17 @@
|
||||
..
|
||||
SPDX-License-Identifier: Apache-2.0
|
||||
File has to be of RST format to make openapi directive work correctly
|
||||
|
||||
.. _akkudoktoreos_server_api:
|
||||
|
||||
Server API
|
||||
##########
|
||||
|
||||
For a more detailed documentation see the Swagger interface: `EOS OpenAPI Spec <https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json>`_
|
||||
|
||||
.. openapi:: openapi.json
|
||||
:examples:
|
||||
|
||||
..
|
||||
Due to bugs in sphinxcontrib-openapi referenced request/response objects fail to render and anyOf is broken too.
|
||||
:request:
|
||||
103
docs/conf.py
103
docs/conf.py
@@ -1,14 +1,12 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# For the full list of built-in configuration values, see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
"""Configuration file for the Sphinx documentation builder.
|
||||
|
||||
For the full list of built-in configuration values, see the documentation:
|
||||
https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
"""
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
# Make source file directories available to sphinx
|
||||
sys.path.insert(0, str(Path("..", "src").resolve()))
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||||
|
||||
@@ -23,7 +21,9 @@ release = "0.0.1"
|
||||
extensions = [
|
||||
"sphinx.ext.autodoc",
|
||||
"sphinx.ext.autosummary",
|
||||
"sphinx.ext.napoleon",
|
||||
"sphinx_rtd_theme",
|
||||
"sphinxcontrib.openapi",
|
||||
"myst_parser",
|
||||
]
|
||||
|
||||
@@ -36,6 +36,59 @@ source_suffix = {
|
||||
".md": "markdown",
|
||||
}
|
||||
|
||||
# -- Options for Myst Markdown -----------------------------------------------
|
||||
# see https://github.com/executablebooks/MyST-Parser/blob/master/docs/conf.py
|
||||
|
||||
myst_enable_extensions = [
|
||||
"dollarmath",
|
||||
"amsmath",
|
||||
"deflist",
|
||||
"fieldlist",
|
||||
"html_admonition",
|
||||
"html_image",
|
||||
"colon_fence",
|
||||
"smartquotes",
|
||||
"replacements",
|
||||
"linkify",
|
||||
"strikethrough",
|
||||
"substitution",
|
||||
"tasklist",
|
||||
"attrs_inline",
|
||||
"attrs_block",
|
||||
]
|
||||
myst_url_schemes = {
|
||||
"http": None,
|
||||
"https": None,
|
||||
"mailto": None,
|
||||
"ftp": None,
|
||||
"wiki": "https://en.wikipedia.org/wiki/{{path}}#{{fragment}}",
|
||||
"doi": "https://doi.org/{{path}}",
|
||||
"gh-pr": {
|
||||
"url": "https://github.com/Akkudoktor-EOS/EOS/pull/{{path}}#{{fragment}}",
|
||||
"title": "PR #{{path}}",
|
||||
"classes": ["github"],
|
||||
},
|
||||
"gh-issue": {
|
||||
"url": "https://github.com/Akkudoktor-EOS/EOS/issue/{{path}}#{{fragment}}",
|
||||
"title": "Issue #{{path}}",
|
||||
"classes": ["github"],
|
||||
},
|
||||
"gh-user": {
|
||||
"url": "https://github.com/{{path}}",
|
||||
"title": "@{{path}}",
|
||||
"classes": ["github"],
|
||||
},
|
||||
}
|
||||
myst_number_code_blocks = ["typescript"]
|
||||
myst_heading_anchors = 2
|
||||
myst_footnote_transition = True
|
||||
myst_dmath_double_inline = True
|
||||
myst_enable_checkboxes = True
|
||||
myst_substitutions = {
|
||||
"role": "[role](#syntax/roles)",
|
||||
"directive": "[directive](#syntax/directives)",
|
||||
}
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||||
|
||||
@@ -46,3 +99,39 @@ html_theme_options = {
|
||||
"logo_only": False,
|
||||
"titles_only": True,
|
||||
}
|
||||
|
||||
# -- Options for autodoc -------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
|
||||
|
||||
# Make source file directories available to sphinx
|
||||
sys.path.insert(0, str(Path("..", "src").resolve()))
|
||||
|
||||
autodoc_default_options = {
|
||||
"members": "var1, var2",
|
||||
"member-order": "bysource",
|
||||
"special-members": "__init__",
|
||||
"undoc-members": True,
|
||||
"exclude-members": "__weakref__",
|
||||
}
|
||||
|
||||
# -- Options for autosummary -------------------------------------------------
|
||||
autosummary_generate = True
|
||||
|
||||
# -- Options for openapi -----------------------------------------------------
|
||||
openapi_default_renderer = "httpdomain:old"
|
||||
|
||||
# -- Options for napoleon -------------------------------------------------
|
||||
napoleon_google_docstring = True
|
||||
napoleon_numpy_docstring = False
|
||||
napoleon_include_init_with_doc = False
|
||||
napoleon_include_private_with_doc = False
|
||||
napoleon_include_special_with_doc = True
|
||||
napoleon_use_admonition_for_examples = False
|
||||
napoleon_use_admonition_for_notes = False
|
||||
napoleon_use_admonition_for_references = False
|
||||
napoleon_use_ivar = False
|
||||
napoleon_use_param = True
|
||||
napoleon_use_rtype = True
|
||||
napoleon_preprocess_types = False
|
||||
napoleon_type_aliases = None
|
||||
napoleon_attr_annotations = True
|
||||
|
||||
@@ -1,20 +1,15 @@
|
||||
..
|
||||
SPDX-License-Identifier: Apache-2.0
|
||||
% SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
.. _akkudoktoreos_getting_started:
|
||||
# Getting Started
|
||||
|
||||
Getting Started
|
||||
###############
|
||||
## Installation
|
||||
|
||||
Installation
|
||||
************
|
||||
|
||||
`Good installation guide <https://meintechblog.de/2024/09/05/andreas-schmitz-joerg-installiert-mein-energieoptimierungssystem/>`_
|
||||
Good installation guide:
|
||||
https://meintechblog.de/2024/09/05/andreas-schmitz-joerg-installiert-mein-energieoptimierungssystem/
|
||||
|
||||
The project requires Python 3.10 or newer.
|
||||
|
||||
Quick Start Guide
|
||||
-----------------
|
||||
### Quick Start Guide
|
||||
|
||||
On Linux (Ubuntu/Debian):
|
||||
|
||||
@@ -22,7 +17,7 @@ On Linux (Ubuntu/Debian):
|
||||
sudo apt install make
|
||||
```
|
||||
|
||||
On MacOS (requires `Homebrew <https://brew.sh>`_):
|
||||
On MacOS (requires [Homebrew](https://brew.sh)):
|
||||
|
||||
```zsh
|
||||
brew install make
|
||||
@@ -31,8 +26,7 @@ brew install make
|
||||
Next, adjust `config.py`.
|
||||
The server can then be started with `make run`. A full overview of the main shortcuts is given by `make help`.
|
||||
|
||||
Detailed Instructions
|
||||
---------------------
|
||||
### Detailed Instructions
|
||||
|
||||
All necessary dependencies can be installed via `pip`. Clone the repository and install the required packages with:
|
||||
|
||||
@@ -63,22 +57,12 @@ source .venv/bin/activate
|
||||
```zsh
|
||||
. .venv/bin/activate
|
||||
```
|
||||
(if using zsh, primarily for MacOS users).
|
||||
|
||||
If `pip install` fails to install the mariadb dependency, the following commands may help:
|
||||
|
||||
* Debian/Ubuntu: `sudo apt-get install -y libmariadb-dev`
|
||||
* MacOS/Homebrew: `brew install mariadb-connector-c`
|
||||
|
||||
Followed by a renewed `pip install -r requirements.txt`.
|
||||
|
||||
Usage
|
||||
*****
|
||||
## Usage
|
||||
|
||||
Adjust `config.py`.
|
||||
|
||||
To start the server:
|
||||
To use the system, run `flask_server.py`, which starts the server:
|
||||
|
||||
```bash
|
||||
make run
|
||||
./flask_server.py
|
||||
```
|
||||
25
docs/index.md
Normal file
25
docs/index.md
Normal file
@@ -0,0 +1,25 @@
|
||||
% SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
```{image} _static/logo.png
|
||||
|
||||
```
|
||||
|
||||
# Akkudoktor EOS documentation
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 2
|
||||
:caption: 'Contents:'
|
||||
|
||||
welcome.md
|
||||
akkudoktoreos/about.md
|
||||
develop/getting_started.md
|
||||
develop/CONTRIBUTING.md
|
||||
akkudoktoreosserver/serverapi.rst
|
||||
akkudoktoreos/api.rst
|
||||
```
|
||||
|
||||
# Indices and tables
|
||||
|
||||
- {ref}`genindex`
|
||||
- {ref}`modindex`
|
||||
- {ref}`search`
|
||||
@@ -1,17 +0,0 @@
|
||||
..
|
||||
Copyright (c) 2024 Bobby Noelte
|
||||
SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
.. _akkudoktoreos:
|
||||
|
||||
Akkudoktor EOS documentation
|
||||
============================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
welcome
|
||||
akkudoktoreos/about
|
||||
develop/getting_started
|
||||
develop/CONTRIBUTING
|
||||
14
docs/welcome.md
Normal file
14
docs/welcome.md
Normal file
@@ -0,0 +1,14 @@
|
||||
% SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
# Welcome to the EOS documentation!
|
||||
|
||||
This documentation is continuously written. It is edited via text files in the
|
||||
[Markdown/ Markedly Structured Text](https://myst-parser.readthedocs.io/en/latest/index.html)
|
||||
markup language and then compiled into a static website/ offline document using the open source tool
|
||||
[Sphinx](https://www.sphinx-doc.org) and will someday land on
|
||||
[Read the Docs](https://akkudoktoreos.readthedocs.io/en/latest/index.html).
|
||||
|
||||
You can contribute to EOS's documentation by opening
|
||||
[GitHub issues](https://github.com/Akkudoktor-EOS/EOS/issues)
|
||||
or sending patches via pull requests on its
|
||||
[GitHub repository](https://github.com/Akkudoktor-EOS/EOS).
|
||||
@@ -1,19 +0,0 @@
|
||||
..
|
||||
Copyright (c) 2024 Bobby Noelte
|
||||
SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
.. _akkudoktoreos_welcome:
|
||||
|
||||
Welcome to the EOS documentation!
|
||||
#################################
|
||||
|
||||
This documentation is continuously written. It is edited via text files in the
|
||||
`reStructuredText(reST) <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
|
||||
markup language and then compiled into a static website/offline document using the open source tool
|
||||
`Sphinx <https://www.sphinx-doc.org>`_ and will hopefully someday land on
|
||||
`Read the Docs <https://akkudoktoreos.readthedocs.io/en/latest/index.html>`_.
|
||||
|
||||
You can contribute to EOS's documentation by opening
|
||||
`GitHub issues <https://github.com/Akkudoktor-EOS/EOS/issues>`_
|
||||
or sending patches via pull requests on its
|
||||
`GitHub repository <https://github.com/Akkudoktor-EOS/EOS>`_.
|
||||
Reference in New Issue
Block a user