Merge pull request #409 from davidusb-geek/davidusb-geek/docs/update_…

…easier_setup

Updated documentation and new release

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.12.0 - 2024-12-29
+### BREAKING CHANGE
+- The solar PV system is now optional. If you have a PV system then use the switch on the webui or set the `set_use_pv` parameter to `True`.
+### Improvement
+- A new load power forecast method based on statistic and typical household load power consumption. This and the optional PV, will make it easier for new users to on-board EMHASS because this new default behavior does not require any data retrieval from Home Assistant or any other external source.
+- Updated documentation.
+
 ## 0.11.4 - 2024-12-24
 ### Fix
 - Fix bug when treating runtime params, fix optimization_time_step timedelta 

README.md

@@ -90,9 +90,14 @@ You must follow these steps to make EMHASS work properly:
 1) Install and run EMHASS.
     - There are multiple methods of installing and Running EMHASS. See [Installation Method](#Installation-Methods) below to pick a method that best suits your use case.
 
-2) Define all the parameters in the configuration file *(`config.json`)* or configuration page *(`YOURIP:5000/configuration`)*. 
+2) Define all the parameters in the configuration file *(`config.json`)* or configuration page *(`YOURIP:5000/configuration`)*.
+```{note} 
+
+New in EMHASS v0.12.0: the default configuration does not need to retrieve any data from Home Assistant! After installing and running the add-on, EMHASS should start and it will be ready to launch an optimization.
+```
     - See the description for each parameter in the [configuration](https://emhass.readthedocs.io/en/latest/config.html) docs. 
-        - You will most notably need to define the main data entering EMHASS. This will be the Home Assistant sensor/variable `sensor.power_photovoltaics` for the name of your Home Assistant variable containing the PV produced power, and the sensor/variable `sensor.power_load_no_var_loads`, for the load power of your household excluding the power of the deferrable loads that you want to optimize.
+    - EMHASS has a default configuration with 2 deferrable loads, no solar PV, no batteries and a basic load power forecasting method.
+      - If you want to consider solar PV and more advanced load power forecast methods, you will need to define the main data entering EMHASS. This will be the Home Assistant sensor/variable `sensor.power_load_no_var_loads`, for the load power of your household excluding the power of the deferrable loads that you want to optimize, and the sensor/variable `sensor.power_photovoltaics` for the name of your Home Assistant variable containing the PV produced power (if solar PV is activated).
       - If you have a PV installation then this dedicated web app can be useful for finding your inverter and solar panel models: [https://emhass-pvlib-database.streamlit.app/](https://emhass-pvlib-database.streamlit.app/)
 
 4) Launch the optimization and check the results. 

docs/conf.py

@@ -22,7 +22,7 @@
 author = 'David HERNANDEZ'
 
 # The full version, including alpha/beta/rc tags
-release = '0.11.4'
+release = '0.12.0'
 
 # -- General configuration ---------------------------------------------------
 

docs/config.md

@@ -40,6 +40,7 @@ The parameters in the `secrets_emhass.yaml` file are:
 
 These are the parameters needed to properly define the optimization problem.
 
+- `set_use_pv`: Set to True if we should consider an solar PV system. Defaults to False.
 - `set_use_battery`: Set to True if we should consider an energy storage device such as a Li-Ion battery. Defaults to False.
 - `delta_forecast_daily`: The number of days for forecasted data. Defaults to 1.
 - `number_of_deferrable_loads`: Define the number of deferrable loads to consider. Defaults to 2.

docs/differences.md

@@ -31,6 +31,7 @@ See below for a list of associations between the parameters from `config_emhass.
 | params_secrets |  lat |  Latitude | |
 | params_secrets |  lon |  Longitude | |
 | params_secrets |  alt |  Altitude | |
+| optim_conf |  set_use_pv |  set_use_pv | |
 | optim_conf |  set_use_battery |  set_use_battery | |
 | optim_conf |  num_def_loads |  number_of_deferrable_loads | |
 | optim_conf |  P_deferrable_nom |  list_nominal_power_of_deferrable_loads |  nominal_power_of_deferrable_loads | 

docs/forecasts.md

@@ -8,16 +8,18 @@ EMHASS will need 4 forecasts to work properly:
 
 - Load cost forecast: the price of the energy from the grid in the next 24 hours. This is given in EUR/kWh.
 
-- PV production selling price forecast: the price at which you will sell your excess PV production in the next 24 hours. This is given in EUR/kWh.
+- PV production selling price forecast: the price at which you will sell your excess PV production in the next 24 hours. This is given in currency/kWh.
 
 Some methods are generalized to the 4 forecasts needed. For all the forecasts it is possible to pass the data either as a passed list of values or by reading from a CSV file. With these methods, it is then possible to use data from external forecast providers.
 
-Then there are the methods that are specific to each type of forecast and that proposed forecast is treated and generated internally by this EMHASS forecast class. For the weather forecast, the first method (`scrapper`) uses scrapping to the ClearOutside webpage which proposes detailed forecasts based on Lat/Lon locations. Another method (`solcast`) is using the Solcast PV production forecast service. A final method (`solar.forecast`) is using another external service: Solar.Forecast, for which just the nominal PV peak installed power should be provided. Search the forecast section on the documentation for examples of how to implement these different methods.
+Then there are the methods that are specific to each type of forecast and that proposed forecast is treated and generated internally by this EMHASS forecast class. 
+
+For the **weather forecast**, the first method (`scrapper`) uses scrapping to the ClearOutside webpage which proposes detailed forecasts based on Lat/Lon locations. Another method (`solcast`) is using the Solcast PV production forecast service. A final method (`solar.forecast`) is using another external service: Solar.Forecast, for which just the nominal PV peak installed power should be provided. Search the forecast section on the documentation for examples of how to implement these different methods.
 
 The `get_power_from_weather` method is proposed here to convert irradiance data to electrical power. The PVLib module is used to model the PV plant. A dedicated web app will help you search for your correct PV module and inverter: [https://emhass-pvlib-database.streamlit.app/](https://emhass-pvlib-database.streamlit.app/)
 
-The specific methods for the load forecast is a first method (`naive`) that uses a naive approach, also called persistence. It simply assumes that the forecast for 
-a future period will be equal to the observed values in a past period. The past period is controlled using the parameter `delta_forecast_daily`. A second method (`mlforecaster`)
+The specific methods for the **load forecast** is a first method (`typical`) that uses historic values of a typical household power consumption. This method uses simple statistic methods and load power grouped by the same day-of-the-week of the current month. The load power is scaled using the parameter `maximum_power_from_grid`. A second method (`naive`) that uses a naive approach, also called persistence. It simply assumes that the forecast for 
+a future period will be equal to the observed values in a past period. The past period is controlled using the parameter `delta_forecast_daily`. A third method (`mlforecaster`)
 uses an internal custom forecasting model using machine learning. There is a section in the documentation explaining how to use this method.
 
 ```{note} 
@@ -93,16 +95,18 @@ If you use the Solar.Forecast or Solcast methods, or explicitly pass the PV powe
 
 ## Load power forecast
 
-The default method for load forecast is a naive method, also called persistence. This is obtained using `method=naive`. This method simply assumes that the forecast for a future period will be equal to the observed values in a past period. The past period is controlled using the parameter `delta_forecast_daily` and the default value for this is 24h.
+```{note} 
 
-This is presented graphically here:
+New in EMHASS v0.12.0: the default method for load power forecast is the `typical` statistics-based method!
+```
 
-![](./images/naive_forecast.png)
+The default method for load forecast is the `typical` method, which uses basic statistics and a year long load power data grouped by the current day-of-the-week of the current month. This provides a typical daily load power characteristic with a 30 minute resolution. The load power is scaled using the parameter `maximum_power_from_grid`. This method uses the default data with 1-year of load power consumption in file `data/data_train_load_clustering.pkl`. You can customize this data to your own household consumption by running erasing the previous file and running the script `scripts/load_clustering.py` (this will try to fetch 365 days of data from your load power sensor). However, if you have a working configuration without any problems with data retrieve from Home Assistant, then it is adviced to use the more advanced method `mlforecaster`.
 
-```{note} 
+A second method is a naive method, also called persistence. This is obtained using `method=naive`. This method simply assumes that the forecast for a future period will be equal to the observed values in a past period. The past period is controlled using the parameter `delta_forecast_daily` and the default value for this is 24h.
 
-New in EMHASS v0.4.0: machine learning forecast models!
-```
+This is presented graphically here:
+
+![](./images/naive_forecast.png)
 
 Starting with v0.4.0, a new forecast framework is proposed within EMHASS. It provides a more efficient way to forecast the power load consumption. It is based on the `skforecast` module that uses `scikit-learn` regression models considering auto-regression lags as features. The hyperparameter optimization is proposed using Bayesian optimization from the `optuna` module. To use this change to `method=mlforecaster` in the configuration.
 

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "emhass"
-version = "0.11.4"
+version = "0.12.0"
 description = "An Energy Management System for Home Assistant"
 readme = "README.md"
 requires-python = ">=3.10, <3.12"