API Reference

emhass.command_line module

emhass.command_line.dayahead_forecast_optim(input_data_dict, logger)

Perform a call to the day-ahead optimization routine.

Parameters
  • input_data_dict (dict) – A dictionnary with multiple data used by the action functions

  • logger (logging object) – The passed logger object

Returns

The output data of the optimization

Return type

pd.DataFrame

emhass.command_line.main()

Define the main command line entry function.

emhass.command_line.perfect_forecast_optim(input_data_dict, logger)

Perform a call to the perfect forecast optimization routine.

Parameters
  • input_data_dict (dict) – A dictionnary with multiple data used by the action functions

  • logger (logging object) – The passed logger object

Returns

The output data of the optimization

Return type

pd.DataFrame

emhass.command_line.publish_data(input_data_dict, logger)

Publish the data obtained from the optimization results.

Parameters
  • input_data_dict (dict) – A dictionnary with multiple data used by the action functions

  • logger (logging object) – The passed logger object

Returns

The output data of the optimization readed from a CSV file in the data folder

Return type

pd.DataFrame

emhass.command_line.setUp(config_path, costfun, logger)

Set up some of the data needed for the different actions.

Parameters
  • config_path (str) – The absolute path where the config.yaml file is located

  • costfun (str) – The type of cost function to use for optimization problem

  • logger (logging object) – The passed logger object

Returns

A dictionnary with multiple data used by the action functions

Return type

dict

emhass.forecast module

class emhass.forecast.forecast(retrieve_hass_conf: dict, optim_conf: dict, plant_conf: dict, config_path: str, logger: logging.Logger, opt_time_delta: Optional[int] = 24)

Bases: object

Generate weather and load forecasts needed as inputs to the optimization.

The weather forecast is obtained from two methods. In the first method the tools proposed in the PVLib package are use to retrieve data from the GFS global model. However this API proposed by PVLib is highly experimental and prone to changes. A second method uses a scrapper to the ClearOutside webpage which proposes detailed forecasts based on Lat/Lon locations. This methods seems quite stable but as any scrape method it will fail if any changes are made to the webpage API.

The ‘get_power_from_weather’ method is proposed here to convert from irradiance data to electrical power. Again PVLib is used to model the PV plant. For the load forecast two methods are available.

The first method allows the user to use a CSV file with their own forecast. With this method a more powerful external package for time series forecast may be used to create your own detailed load forecast.

The CSV should contain no header and the timestamped data should have the following format:

2021-04-29 00:00:00+00:00,287.07

2021-04-29 00:30:00+00:00,274.27

2021-04-29 01:00:00+00:00,243.38

The second method is a naive method, also called persistance. 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 parameter ‘delta_forecast’.

get_load_forecast(days_min_load_forecast: Optional[int] = 3, method: Optional[str] = 'naive', csv_path: Optional[str] = '/data/data_load_forecast.csv')pandas.core.series.Series

Get and generate the load forecast data.

Parameters
  • days_min_load_forecast (int, optional) – The number of last days to retrieve that will be used to generate a naive forecast, defaults to 3

  • method (str, optional) – The method to be used to generate load forecast, the options are ‘csv’ to load a CSV file or ‘naive’ for a persistance model, defaults to ‘naive’

  • csv_path (str, optional) – The path to the CSV file used when method = ‘csv’, defaults to “/data/data_load_forecast.csv”

Returns

The DataFrame containing the electrical load power in Watts

Return type

pd.DataFrame

get_power_from_weather(df_weather: pandas.core.frame.DataFrame)pandas.core.series.Series

Convert wheater forecast data into electrical power.

Parameters

df_weather (pd.DataFrame) – The DataFrame containing the weather forecasted data. This DF should be generated by the ‘get_weather_forecast’ method or at least contain the same columns names filled with proper data.

Returns

The DataFrame containing the electrical power in Watts

Return type

pd.DataFrame

get_weather_forecast(method: Optional[str] = 'scrapper')pandas.core.frame.DataFrame

Get and generate weather forecast data.

Parameters

method (str, optional) – The desired method, options are ‘scrapper’ and ‘pvlib’, defaults to ‘scrapper’

Returns

The DataFrame containing the forecasted data

Return type

pd.DataFrame

emhass.optimization module

class emhass.optimization.optimization(retrieve_hass_conf: dict, optim_conf: dict, plant_conf: dict, days_list: pandas.core.indexes.datetimes.date_range, costfun: str, config_path: str, logger: logging.Logger, opt_time_delta: Optional[int] = 24)

Bases: object

Optimize the deferrable load and battery energy dispatch problem using the linear programming optimization technique. All equipement equations, including the battery equations are hence transformed in a linear form.

This class methods are:

  • get_load_unit_cost

  • perform_optimization

  • perform_perfect_forecast_optim

  • perform_dayahead_forecast_optim

get_load_unit_cost(df_final: pandas.core.frame.DataFrame)pandas.core.frame.DataFrame

Get the unit cost for the load consumption based on multiple tariff periods. This is the cost of the energy from the utility in a vector sampled at the fixed freq value.

Parameters

df_input_data (pd.DataFrame) – The DataFrame containing all the input data retrieved from hass

Returns

The input DataFrame with one additionnal column appended containing the load cost by unit of time

Return type

pd.DataFrame

perform_dayahead_forecast_optim(df_input_data: pandas.core.frame.DataFrame, P_PV: pandas.core.series.Series, P_load: pandas.core.series.Series)pandas.core.frame.DataFrame

Perform a day-ahead optimization task using real forecast data.

Parameters
  • df_input_data (pandas.DataFrame) – A DataFrame containing all the input data used for the optimization, notably the unit load cost for power consumption.

  • P_PV (pandas.DataFrame) – The forecasted PV power production.

  • P_load (pandas.DataFrame) – The forecasted Load power consumption. This power should not include the power from the deferrable load that we want to find.

Returns

opt_res: A DataFrame containing the optimization results

Return type

pandas.DataFrame

perform_optimization(data_opt: pandas.core.frame.DataFrame, P_PV: numpy.array, P_load: numpy.array, unit_load_cost: numpy.array)pandas.core.frame.DataFrame

Perform the actual optimization using linear programming (LP).

Parameters
  • data_tp (pd.DataFrame) – A DataFrame containing the input data. The results of the optimization will be appended (decision variables, cost function values, etc)

  • P_PV (numpy.array) – The photovoltaic power values. This can be real historical values or forecasted values.

  • P_load (np.array) – The load power consumption values

  • unit_load_cost (np.array) – The cost of power consumption for each unit of time. This is the cost of the energy from the utility in a vector sampled at the fixed freq value

Returns

The input DataFrame with all the different results from the optimization appended

Return type

pd.DataFrame

perform_perfect_forecast_optim(df_input_data: pandas.core.frame.DataFrame)pandas.core.frame.DataFrame

Perform an optimization on historical data (perfectly known PV production).

Parameters

df_input_data (pandas.DataFrame) – A DataFrame containing all the input data used for the optimization, notably photovoltaics and load consumption powers.

Returns

opt_res: A DataFrame containing the optimization results

Return type

pandas.DataFrame

emhass.retrieve_hass module

class emhass.retrieve_hass.retrieve_hass(hass_url: str, long_lived_token: str, freq: pandas._libs.tslibs.timedeltas.Timedelta, time_zone: datetime.timezone, config_path: str, logger: logging.Logger)

Bases: object

Retrieve data from Home Assistant using the restful API.

This class allows the user to retrieve data from a Home Assistant instance using the provided restful API (https://developers.home-assistant.io/docs/api/rest/)

This class methods are:

  • get_data: to retrieve the actual data from hass

  • prepare_data: to apply some data treatment in preparation for the optimization task

  • post_data: Post passed data to hass

get_data(days_list: pandas.core.indexes.datetimes.date_range, var_list: list, minimal_response: Optional[bool] = False, significant_changes_only: Optional[bool] = False)None

Retrieve the actual data from hass.

Parameters
  • days_list (pandas.date_range) – A list of days to retrieve. The ISO format should be used and the timezone is UTC. The frequency of the data_range should be freq=’D’

  • var_list (list) – The list of variables to retrive from hass. These should be the exact name of the sensor in Home Assistant. For example: [‘sensor.home_load’, ‘sensor.home_pv’]

  • minimal_response (bool, optional) – Retrieve a minimal response using the hass restful API, defaults to False

  • significant_changes_only (bool, optional) – Retrieve significant changes only using the hass restful API, defaults to False

Returns

The DataFrame populated with the retrieved data from hass

Return type

pandas.DataFrame

Warning

The minimal_response and significant_changes_only options are experimental

post_data(data_df: pandas.core.frame.DataFrame, idx: int, entity_id: str, unit_of_measurement: str, friendly_name: str)None

Post passed data to hass.

Parameters
  • data_df (pd.DataFrame) – The DataFrame containing the data that will be posted to hass. This should be a one columns DF or a series.

  • idx (int) – The int index of the location of the data within the passed DataFrame. We will post just one value at a time.

  • entity_id (str) – The unique entity_id of the sensor in hass.

  • unit_of_measurement (str) – The units of the sensor.

  • friendly_name (str) – The friendly name that will be used in the hass frontend.

prepare_data(var_load: str, load_negative: Optional[bool] = False, set_zero_min: Optional[bool] = True, var_replace_zero: Optional[list] = None, var_interp: Optional[list] = None)None

Apply some data treatment in preparation for the optimization task.

Parameters
  • var_load (str) – The name of the variable for the household load consumption.

  • load_negative (bool, optional) – Set to True if the retrived load variable is negative by convention, defaults to False

  • set_zero_min (bool, optional) – A special treatment for a minimum value saturation to zero. Values below zero are replaced by nans, defaults to True

  • var_replace_zero (list, optional) – A list of retrived variables that we would want to replace nans with zeros, defaults to None

  • var_interp (list, optional) – A list of retrived variables that we would want to interpolate nan values using linear interpolation, defaults to None

Returns

The DataFrame populated with the retrieved data from hass and after the data treatment

Return type

pandas.DataFrame

emhass.utils module

emhass.utils.get_days_list(days_to_retrieve: int)pandas.core.indexes.datetimes.date_range

Get list of past days from today to days_to_retrieve.

Parameters

days_to_retrieve (int) – Total number of days to retrieve from the past

Returns

The list of days

Return type

pd.date_range

emhass.utils.get_logger(fun_name: str, config_path: str, file: Optional[bool] = True)Tuple[logging.Logger, logging.StreamHandler]

Create a simple logger object.

Parameters
  • fun_name (str) – The Python function object name where the logger will be used

  • config_path (str) – The path to the yaml configuration file

  • file (bool, optional) – Write log to a file, defaults to True

Returns

The logger object and the handler

Return type

object

emhass.utils.get_root()str

Get the root absolute path of the working directory.

Returns

The root path

Return type

str

emhass.utils.get_root_2pardir()str

Get the root absolute path of the working directory using two pardir commands.

Returns

The root path

Return type

str

emhass.utils.get_yaml_parse(config_path: str)Tuple[dict, dict, dict]

Perform parsing of the config.yaml file.

Parameters

config_path (str) – The path to the yaml configuration file

Returns

A tuple with the dictionaries containing the parsed data

Return type

tuple(dict)