Conceptual documentation (#463)

Added new instruction.md, changed index.md accordingly and deleted the no longer needed about.md of new documentation structure.
Refinement of differences to other solutions and features of EOS.

Co-authored-by: Eric Hirsch <git@familie-hirsch.net>

docs/akkudoktoreos/about.md

@@ -1,9 +0,0 @@
-% SPDX-License-Identifier: Apache-2.0
-
-# 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
-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.

docs/akkudoktoreos/integration.md

@@ -1,4 +1,5 @@
 % SPDX-License-Identifier: Apache-2.0
+(integration-page)=
 
 # Integration
 
@@ -27,6 +28,8 @@ Andreas Schmitz uses [Node-RED](https://nodered.org/) as part of his home automa
 [Home Assistant](https://www.home-assistant.io/) is an open-source home automation platform that
 emphasizes local control and user privacy.
 
+(duetting-solution)=
+
 ### Home Assistant Resources
 
 - Duetting's [EOS Home Assistant Addon](https://github.com/Duetting/ha_eos_addon) — Additional

docs/akkudoktoreos/introduction.md

@@ -0,0 +1,180 @@
+% SPDX-License-Identifier: Apache-2.0
+
+# Introduction
+
+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 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.
+
+After successfully installing a PV system with or without battery storage, most owners
+first priority is often to charge the electric car with surplus energy in order to use
+the electricity generated by the PV system cost-effectively for electromobility.
+
+After initial experiences, the desire to include battery storage and dynamic electricity
+prices in the solution soon arises. The market already offers various commercial and
+non-commercial solutions for this, such as the popular open source hardware and software
+solutions evcc or openWB.
+
+Some solutions take into account the current values ​​of the system such as PV power
+output, battery storage charge level or the current electricity price to decide whether
+to charge the electric car with PV surplus or from the grid (e.g. openWB), some use
+historical consumption values ​​and PV forecast data for their calculations, but leave out
+the current electricity prices and charging the battery storage from the power grid
+(Predbat). Others are specialiced on working in combination with a specific smart home
+solution (e.g. emhass). Still others focus on certain consumers, such as the electric car,
+or are currently working on integrating the forecast values ​​(evcc). And some are commercial
+devices that require an electrician to install them and expect a certain ecosystem
+(e.g. Sunny Home Manager).
+
+The Akkudoktor EOS
+
+- takes into account historical, current and forecast data such as consumption values, PV
+  forecast data, electricity price forecast, battery storage and electric car charge levels
+- the simulation also takes into account the possibility of charging the battery storage
+  from the grid at low electricity prices
+- is not limited to certain consumers, but includes electric cars, heat pumps or more
+  powerful consumers such as tumble dryers
+- is independent of a specific smart home solution and can also be integrated into
+  self-developed solutions if desired
+- is a free and independent open source software solution
+
+![Introdution](../_static/introduction/introduction.png)
+
+The challenge is to charge (electric car) or start the consumers (washing machine, dryer)
+at the right time and to do so as cost-efficiently as possible. If PV yield forecast,
+battery storage and dynamic electricity price forecasts are included in the calculation,
+the possibilities increase, but unfortunately so does the complexity.
+
+The Akkudoktor EOS addresses this challenge by simulating energy flows in the household
+based on target values, forecast data and current operating data over a 48-hour
+observation period, running through a large number of different scenarios and finally
+providing a cost-optimized plan for the current day controlling the relevant consumers.
+
+## Prerequisites
+
+- Technical requirements
+- Input data
+
+### Technical requirements
+
+- reasonably fast computer on which EOS is installed
+- controllable energy system consisting of photovoltaic system, solar battery storage,
+  energy intensive consumers that must provide the appropriate interfaces
+- integration solution for integrating the energy system and EOS
+
+### Input Data
+
+![Overview](../_static/introduction/overview.png)
+
+The EOS requires various types of data for the simulation:
+
+Forecast data
+
+- PV yield forecast
+- Expected household consumption
+- Electricity price forecast
+- Forecast temperature trend (if heatpump is used)
+
+Basic data and current operating data
+
+- Current charge level of the battery storage
+- Value of electricity in the battery storage
+- Current charge level of the electric car
+- Energy consumption and running time of dishwasher, washing machine and tumble dryer
+
+Target values
+
+- Charge level the electric car should reach in the next few hours
+- Consumers to run in the next few hours
+
+There are various service providers available for PV forecasting that calculate forecast
+data for a PV system based on the various influencing factors, such as system size,
+orientation, location, time of year and weather conditions. EOS also offers a
+[PV forecasting service](#prediction-page) which can be used. This service uses
+public data in the background.
+
+For the forecast of household consumption EOS provides a standard load curve for an
+average day based on annual household consumption that you can fetch via API. This data
+was compiled based on data from several households and provides an initial usable basis.
+Alternatively your own collected historical data could be used to reflect your personal
+consumption behaviour.
+
+## Simulation Results
+
+Based on the input data, the EOS uses a genetic algorithm to create a cost-optimized
+schedule for the coming hours from numerous simulations of the overall system.
+
+The plan created contains for each of the coming hours
+
+- Control information
+  - whether and with what power the battery storage should be charged from the grid
+  - when the battery storage should be charged via the PV system
+  - whether discharging the battery storage is permitted or not
+  - when and with what power the electric car should be charged
+  - when a household appliance should be activated
+- Energy history information
+  - Total load of the house
+  - Grid consumption
+  - Feed-in
+  - Load of the planned household appliances
+  - Charge level of the battery storage
+  - Charge level of the electric car
+  - Active losses
+- Cost information
+  - Revenue per hour (when fed into the grid)
+  - Total costs per hour (when drawn from the grid)
+  - Overall balance (revenue-costs)
+  - Cost development
+
+If required, the simulation result can also be created and downloaded in graphical
+form as a PDF from EOS.
+
+## Integration
+
+The Akkudoktor EOS can be integrated into a wide variety of systems with a variety
+of components.
+
+![Integration](../_static/introduction/integration.png)
+
+However, the components are not integrated by the EOS itself, but must be intergrated by
+the user using an integration solution and currently requires some effort and technical
+know-how.
+
+Any [integration](#integration-page) solution that can act as an intermediary between the
+components and the REST API of EOS can be used. One possible solution that enables the
+integration of components and EOS is Node-RED. Another solution could be Home Assistant
+usings its built in features.
+
+Access to the data and functions of the components can be done in a variety of ways.
+Node-RED offers a large number of types of nodes that allow access via the protocols
+commonly used in this area, such as Modbus or MQTT. Access to any existing databases,
+such as InfluxDB or PostgreSQL, is also possible via nodes provided by Node-RED.
+
+It becomes easier if a smart home solution like Homa Assistant, openHAB or ioBroker or
+solutions such as evcc or openWB are already in use. In this case, these smart home
+solutions already take over the technical integration and communication with the components
+at a technical level and Node-RED offers nodes for accessing these solutions, so that the
+corresponding sources can be easily integrated into a flow.
+
+In Home Assistant you could use an automation to prepare the input payload for EOS and
+then use the RESTful integration to call EOS. Based on this concept there is already a
+home assistand add-on created by [Duetting](#duetting-solution).
+
+The plan created by EOS must also be executed via the chosen integration solution,
+with the respective devices receiving their instructions according to the plan.
+
+## Limitations
+
+The plan calculated by EOS is cost-optimized due to the genetic algorithm used, but not
+necessarily cost-optimal, since genetic algorithms do not always find the global optimum,
+but usually find good local optima very quickly in a large solution space.
+
+## Links
+
+- [German Video explaining the basic concept and installation process for the early version of EOS (YouTube)](https://www.youtube.com/live/ftQULW4-1ts?si=oDdBBifCpUmiCXaY)
+- [German Forum of Akkudoktor EOS](https://akkudoktor.net/c/der-akkudoktor/eos)
+- [Akkudoktor-EOS GitHub Repository](https://github.com/Akkudoktor-EOS/EOS)
+- [Latest EOS Documentation](https://akkudoktor-eos.readthedocs.io/en/latest/)

docs/akkudoktoreos/prediction.md

@@ -1,4 +1,5 @@
 % SPDX-License-Identifier: Apache-2.0
+(prediction-page)=
 
 # Predictions
 
@@ -199,19 +200,19 @@ Configuration options:
 - `longitude`: Longitude in decimal degrees, within -180 to 180 (°)
 - `pvforecast<0..5>_surface_tilt`: Tilt angle from horizontal plane. Ignored for two-axis tracking.
 - `pvforecast<0..5>_surface_azimuth`: Orientation (azimuth angle) of the (fixed) plane.
-                                      Clockwise from north (north=0, east=90, south=180, west=270).
+  Clockwise from north (north=0, east=90, south=180, west=270).
 - `pvforecast<0..5>_userhorizon`: Elevation of horizon in degrees, at equally spaced azimuth clockwise from north.
 - `pvforecast<0..5>_peakpower`: Nominal power of PV system in kW.
 - `pvforecast<0..5>_pvtechchoice`: PV technology. One of 'crystSi', 'CIS', 'CdTe', 'Unknown'.
 - `pvforecast<0..5>_mountingplace`: Type of mounting for PV system. Options are 'free' for free-standing
-                                    and 'building' for building-integrated.
+  and 'building' for building-integrated.
 - `pvforecast<0..5>_loss`: Sum of PV system losses in percent
 - `pvforecast<0..5>_trackingtype`: Type of suntracking. 0=fixed,
-                                   1=single horizontal axis aligned north-south,
+  1=single horizontal axis aligned north-south,
-                                   2=two-axis tracking,
+  2=two-axis tracking,
-                                   3=vertical axis tracking,
+  3=vertical axis tracking,
-                                   4=single horizontal axis aligned east-west,
+  4=single horizontal axis aligned east-west,
-                                   5=single inclined axis aligned north-south.
+  5=single inclined axis aligned north-south.
 - `pvforecast<0..5>_optimal_surface_tilt`: Calculate the optimum tilt angle. Ignored for two-axis tracking.
 - `pvforecast<0..5>_optimalangles`: Calculate the optimum tilt and azimuth angles. Ignored for two-axis tracking.
 - `pvforecast<0..5>_albedo`: Proportion of the light hitting the ground that it reflects back.
@@ -223,7 +224,7 @@ Configuration options:
 - `pvforecastimport_file_path`: Path to the file to import PV forecast data from.
 - `pvforecastimport_json`: JSON string, dictionary of PV forecast value lists.
 
-------
+---
 
 Some of the configuration options directly follow the
 [PVGIS](https://joint-research-centre.ec.europa.eu/photovoltaic-geographical-information-system-pvgis/getting-started-pvgis/pvgis-user-manual_en)
@@ -257,13 +258,13 @@ conditions (STC), which are a constant 1000W of solar irradiation per square met
 the array, at an array temperature of 25°C. The peak power should be entered in kilowatt-peak (kWp).
 If you do not know the declared peak power of your modules but instead know the area of the modules
 and the declared conversion efficiency (in percent), you can calculate the peak power as
-power = area * efficiency / 100.
+power = area \* efficiency / 100.
 
 Bifacial modules: PVGIS doesn't make specific calculations for bifacial modules at present. Users
 who wish to explore the possible benefits of this technology can input the power value for Bifacial
 Nameplate Irradiance. This can also be can also be estimated from the front side peak power P_STC
 value and the bifaciality factor, φ (if reported in the module data sheet) as:
-P_BNPI  = P_STC \* (1 + φ \* 0.135). NB this bifacial approach  is not appropriate for BAPV or BIPV
+P_BNPI = P_STC \* (1 + φ \* 0.135). NB this bifacial approach is not appropriate for BAPV or BIPV
 installations or for modules mounting on a N-S axis i.e. facing E-W.
 
 - `pvforecast<0..5>_loss`
@@ -304,7 +305,7 @@ represent equal angular distance around the horizon. For instance, if you have 3
 point is due north, the next is 10 degrees east of north, and so on, until the last point, 10
 degrees west of north.
 
-------
+---
 
 Most of the configuration options are in line with the
 [PVLib](https://pvlib-python.readthedocs.io/en/stable/_modules/pvlib/iotools/pvgis.html) definition for PVGIS data.
@@ -320,7 +321,7 @@ Tilt angle from horizontal plane.
 Orientation (azimuth angle) of the (fixed) plane. Clockwise from north (north=0, east=90, south=180,
 west=270). This is offset 180 degrees from the convention used by PVGIS.
 
-------
+---
 
 ### PVForecastAkkudoktor Provider
 
@@ -336,7 +337,7 @@ For each plane `<0..5>` of the PV system the following configuration options mus
 
 - `pvforecast<0..5>_surface_tilt`: Tilt angle from horizontal plane. Ignored for two-axis tracking.
 - `pvforecast<0..5>_surface_azimuth`: Orientation (azimuth angle) of the (fixed) plane.
-                                      Clockwise from north (north=0, east=90, south=180, west=270).
+  Clockwise from north (north=0, east=90, south=180, west=270).
 - `pvforecast<0..5>_userhorizon`: Elevation of horizon in degrees, at equally spaced azimuth clockwise from north.
 - `pvforecast<0..5>_inverter_paco`: AC power rating of the inverter. [W]
 - `pvforecast<0..5>_peakpower`: Nominal power of PV system in kW.

docs/index.md

@@ -8,12 +8,32 @@
 
 ```{toctree}
 :maxdepth: 2
-:caption: 'Contents:'
+:caption: Overview
+
+akkudoktoreos/introduction.md
+
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Tutorials
 
-welcome.md
-akkudoktoreos/about.md
 develop/getting_started.md
+
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: How-To Guides
+
 develop/CONTRIBUTING.md
+
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Reference
+
 akkudoktoreos/architecture.md
 akkudoktoreos/configuration.md
 akkudoktoreos/optimization.md
@@ -22,6 +42,7 @@ akkudoktoreos/measurement.md
 akkudoktoreos/integration.md
 akkudoktoreos/serverapi.md
 akkudoktoreos/api.rst
+
 ```
 
 ## Indices and tables