edisgo.io.generators_import
===========================

.. py:module:: edisgo.io.generators_import


Functions
---------

.. autoapisummary::

   edisgo.io.generators_import.oedb_legacy
   edisgo.io.generators_import.oedb


Module Contents
---------------

.. py:function:: oedb_legacy(edisgo_object, generator_scenario, **kwargs)

   Gets generator park for specified scenario from oedb and integrates generators into
   the grid.

   The importer uses SQLAlchemy ORM objects. These are defined in
   `ego.io <https://github.com/openego/ego.io/tree/dev/egoio/db_tables/>`_.
   The data is imported from the tables
   `conventional power plants <https://openenergyplatform.org/database/    tables/ego_dp_conv_powerplant>`_ and
   `renewable power plants <https://openenergyplatform.org/database/    tables/ego_dp_res_powerplant>`_.

   When the generator data is retrieved, the following steps are conducted:

       * Step 1: Update capacity of existing generators if `update_existing` is True,
         which it is by default.
       * Step 2: Remove decommissioned generators if
         `remove_decommissioned` is True, which it is by default.
       * Step 3: Integrate new MV generators.
       * Step 4: Integrate new LV generators.

   For more information on how generators are integrated, see
   :attr:`~.network.topology.Topology.connect_to_mv` and
   :attr:`~.network.topology.Topology.connect_to_lv`.

   :param edisgo_object:
   :type edisgo_object: :class:`~.EDisGo`
   :param generator_scenario: Scenario for which to retrieve generator data. Possible options
                              are 'nep2035' and 'ego100'.
   :type generator_scenario: str

   :param remove_decommissioned: If True, removes generators from network that are not included in
                                 the imported dataset (=decommissioned). Default: True.
   :type remove_decommissioned: bool
   :param update_existing: If True, updates capacity of already existing generators to
                           capacity specified in the imported dataset. Default: True.
   :type update_existing: bool
   :param p_target: Per default, no target capacity is specified and generators are
                    expanded as specified in the respective scenario. However, you may
                    want to use one of the scenarios but have slightly more or less
                    generation capacity than given in the respective scenario. In that case
                    you can specify the desired target capacity per technology type using
                    this input parameter. The target capacity dictionary must have
                    technology types (e.g. 'wind' or 'solar') as keys and corresponding
                    target capacities in MW as values.
                    If a target capacity is given that is smaller than the total capacity
                    of all generators of that type in the future scenario, only some
                    generators in the future scenario generator park are installed,
                    until the target capacity is reached.
                    If the given target capacity is greater than that of all generators
                    of that type in the future scenario, then each generator capacity is
                    scaled up to reach the target capacity. Be careful to not have much
                    greater target capacities as this will lead to unplausible generation
                    capacities being connected to the different voltage levels.
                    Also be aware that only technologies specified in the dictionary are
                    expanded. Other technologies are kept the same.
                    Default: None.
   :type p_target: dict or None
   :param allowed_number_of_comp_per_lv_bus: Specifies, how many generators are at most allowed to be placed at
                                             the same LV bus. Default: 2.
   :type allowed_number_of_comp_per_lv_bus: int


.. py:function:: oedb(edisgo_object, scenario, engine, max_capacity=20)

   Gets generator park for specified scenario from oedb and integrates generators into
   the grid.

   The data is imported from the tables supply.egon_chp_plants,
   supply.egon_power_plants and supply.egon_power_plants_pv_roof_building.

   For the grid integration it is distinguished between PV rooftop plants and all
   other power plants.
   For PV rooftop the following steps are conducted:

   * Removes decommissioned PV rooftop plants (plants whose source ID cannot
     be matched to a source ID of an existing plant).
   * Updates existing PV rooftop plants. The following two cases are distinguished:

     * Nominal power increases: It is checked, if plant needs to be connected to a
       higher voltage level and if that is the case, the existing plant is removed from
       the grid and the new one integrated based on the geolocation.
     * Nominal power decreases: Nominal power of existing plant is overwritten.
   * Integrates new PV rooftop plants at corresponding building ID. If the plant needs
     to be connected to a higher voltage level than the building, it is integrated
     based on the geolocation.

   For all other power plants the following steps are conducted:

   * Removes decommissioned power and CHP plants (all plants that do not have a source
     ID or whose source ID can not be matched to a new plant and are not of subtype
     pv_rooftop, as these are handled in a separate function)
   * Updates existing power plants (plants whose source ID
     can be matched; solar, wind and CHP plants never have a source ID in
     the future scenarios and are therefore never updated). The following two cases
     are distinguished:

     * Nominal power increases: It is checked, if plant needs to be connected to a
       higher voltage level and if that is the case, the existing plant is removed from
       the grid and the new one integrated based on the geolocation.
     * Nominal power decreases: Nominal power of existing plant is overwritten.
   * Integrates new power and CHP plants based on the geolocation.

   :param edisgo_object:
   :type edisgo_object: :class:`~.EDisGo`
   :param scenario: Scenario for which to retrieve generator data. Possible options
                    are "eGon2035" and "eGon100RE".
   :type scenario: str
   :param engine: Database engine.
   :type engine: :sqlalchemy:`sqlalchemy.Engine<sqlalchemy.engine.Engine>`
   :param max_capacity: Maximum capacity in MW of power plants to retrieve from database. In general,
                        the generators that are retrieved from the database are selected based on the
                        voltage level they are in. In some cases, the voltage level is not correct as
                        it was wrongly set in the MaStR dataset. To avoid having unrealistically large
                        generators in the grids, an upper limit is also set. Per default this is 20 MW.
   :type max_capacity: float

   .. rubric:: Notes

   Note, that PV rooftop plants are queried using the building IDs not the MV grid ID
   as in egon_data buildings are mapped to a grid based on the
   zensus cell they are in whereas in ding0 buildings are mapped to a grid based on
   the geolocation. As it can happen that buildings lie outside an MV grid but within
   a zensus cell that is assigned to that MV grid, they are mapped differently in
   egon_data and ding0, and it is therefore better to query using the building IDs.