Welcome to oemof’s feedinlib documentation!

Contents:

Getting started

The feedinlib is designed to calculate feed-in time series of photovoltaic and wind power plants. It is part of the oemof group but works as a standalone application.

The feedinlib is ready to use but it definitely has a lot of space for further development, new and improved models and nice features.

Introduction

So far the feedinlib provides interfaces to download open_FRED and ERA5 weather data. open_FRED is a local reanalysis weather data set that provides weather data for Germany (and bounding box). ERA5 is a global reanalysis weather data set that provides weather data for the whole world. The weather data can be used to calculate the electrical output of PV and wind power plants. At the moment the feedinlib provides interfaces to the pvlib and the windpowerlib. Furthermore, technical parameters for many PV modules and inverters, as well as wind turbines, are made available and can be easily used for calculations.

Installation

If you have a working Python 3 environment, use pip to install the latest feedinlib version:

pip install feedinlib

The feedinlib is designed for Python 3 and tested on Python >= 3.5.

We highly recommend to use virtual environments. Please see the installation page of the oemof documentation for complete instructions on how to install python and a virtual environment on your operating system.

Examples and basic usage

The basic usage of the feedinlib is shown in the Examples section. The examples are provided as jupyter notebooks that you can download here:

• ERA5 weather data example
• open_FRED weather data example
• pvlib model example
• windpowerlib model example

Furthermore, you have to install the feedinlib with additional packages needed to run the notebooks, e.g. jupyter.

pip install feedinlib[examples]

To launch jupyter notebook type jupyter notebook in the terminal. This will open a browser window. Navigate to the directory containing the notebook(s) to open it. See the jupyter notebook quick start guide for more information on how to run jupyter notebooks.

Contributing

We are warmly welcoming all who want to contribute to the feedinlib. If you are interested do not hesitate to contact us via github.

As the feedinlib started with contributors from the oemof developer group we use the same developer rules.

How to create a pull request:

• Fork the feedinlib repository to your own github account.
• Create a local clone of your fork and install the cloned repository using pip with -e option:

pip install -e /path/to/the/repository

• Change, add or remove code.
• Commit your changes.
• Create a pull request and describe what you will do and why.
• Wait for approval.

Generally the following steps are required when changing, adding or removing code:

• Add new tests if you have written new functions/classes.
• Add/change the documentation (new feature, API changes …).
• Add a whatsnew entry and your name to Contributors.
• Check if all tests still work by simply executing pytest in your feedinlib directory:

pytest

Citing the feedinlib

We use the zenodo project to get a DOI for each version. Search zenodo for the right citation of your feedinlib version.

License

MIT License

Copyright (C) 2017 oemof developer group

Examples

Example for open_FRED weather data download

This example shows you how to download open_FRED weather data from the OpenEnergy DataBase and store it locally. Furthermore, it shows how to convert the weather data to the format needed by the pvlib and windpowerlib.

# imports
from shapely.geometry import Point, Polygon

from feedinlib.db import Weather
from feedinlib.db import defaultdb

Download data for single coordinate

location = Point(13.5, 52.4)

Besides a location you have to specify a time period for which you would like to download the data as well as the weather variables you need. The feedinlib provides predefined sets of variables that are needed to use the pvlib and windpowerlib. These can be applied by setting the variables parameter to “pvlib” or “windpowerlib”, as shown below.

# download data for January 2015 (end date will not be included in the
# time period for which data is downloaded)
start_date, end_date = '2015-01-01', '2015-02-01'
variables = "windpowerlib"

As the open_FRED weather dataset provides some variables at different heights, such as wind speed and air pressure, it is possible to define which heights you want to retrieve the data for.

heights = [80, 100]

Now we can retrieve the data:

open_FRED_weather_windpowerlib = Weather(
    start=start_date, stop=end_date, locations=[location],
    heights=heights,
    variables=variables,
    **defaultdb())

Download data for a region

lat_point_list = [51.936377, 51.936377, 51.744302, 51.744302, 51.936377]
lon_point_list = [12.621739, 13.005414, 13.005414, 12.621739, 12.621739]
region = Polygon(zip(lon_point_list, lat_point_list))

In this example we will retrieve weather data needed for pvlib calculations. We can do this by setting variables to “pvlib”. In this case specifying the heights for which to retrieve the data is not necessary as irradiance data is only available at the surface and 10m wind speed is used per default.

The following code may take a while to execute!

open_FRED_weather_pvlib = Weather(
    start='2015-06-01', stop='2015-06-05',
    locations=[], regions=[region],
    variables="pvlib",
    **defaultdb())

Convert data into pvlib and windpowerlib format

In order to use the weather data for your feed-in calculations using the pvlib and windpowerlib it has to be converted into the required format. This can easily be done as follows.

# convert to windpowerlib dataframe
windpowerlib_df = open_FRED_weather_windpowerlib.df(location=location, lib="windpowerlib")

# save dataframe as csv
windpowerlib_df.to_csv('windpowerlib_df.csv')

# select point inside region
point = Point(12.7, 51.9)
# convert to pvlib dataframe
pvlib_df = open_FRED_weather_pvlib.df(location=point, lib="pvlib")

Example for ERA5 weather data download

This example shows you how to download ERA5 weather data from the Climate Data Store (CDS) and store it locally. Furthermore, it shows how to convert the weather data to the format needed by the pvlib and windpowerlib.

In order to download ERA5 weather data you need an account at the CDS. Furthermore, you need to install the cdsapi package. See here for installation details.

When downloading the data using the API your request gets queued and may take a while to be completed. All actual calls of the data download are therefore commented to avoid unintended download.

• Download data for single coordinate
• Download data for a region
• Convert data into pvlib and windpowerlib format

from feedinlib import era5

Download data for single coordinate

To download data for a single location you have to specify latitude and longitude of the desired location. Data will be retrieved for the nearest weather data point to that location.

latitude = 52.4
longitude = 13.5

Besides a location you have to specify a time period for which you would like to download the data as well as the weather variables you need. The feedinlib provides predefined sets of variables that are needed to use the pvlib and windpowerlib. These can be applied by setting the variable parameter to “pvlib” or “windpowerlib”, as shown below. If you want to download data for both library you can set variable to ‘feedinlib’.

# set start and end date (end date will be included
# in the time period for which data is downloaded)
start_date, end_date = '2015-01-01', '2015-02-01'
# set variable set to download
variable = "windpowerlib"

If you want to store the downloaded data you may provide a filename (including path) to save data to.

target_file = 'ERA5_weather_data.nc'

Now we can retrieve the data:

# get windpowerlib data for specified location
ds = era5.get_era5_data_from_datespan_and_position(
    variable=variable,
    start_date=start_date, end_date=end_date,
    latitude=latitude, longitude=longitude,
    target_file=target_file)

Download data for a region

When wanting to download weather data for a region instead of providing a single value for each latitude and longitude you have to provide latitude and longitude as lists in the following form:

latitude = [51.0, 53.0]  # [latitude south, latitude north]
longitude = [13.5, 13.8]  # [longitude west, longitude east]

variable = "pvlib"

# get pvlib data for specified area
ds = era5.get_era5_data_from_datespan_and_position(
    variable=variable,
    start_date=start_date, end_date=end_date,
    latitude=latitude, longitude=longitude,
    target_file=target_file)

If you want weather data for the whole world, you may leave latitude and longitude unspecified.

# get feedinlib data (includes pvlib and windpowerlib data)
# for the whole world
ds = era5.get_era5_data_from_datespan_and_position(
    variable="feedinlib",
    start_date=start_date, end_date=end_date,
    target_file=target_file)

Convert data into pvlib and windpowerlib format

In order to use the weather data for your feed-in calculations using the pvlib and windpowerlib it has to be converted into the required format. This can easily be done as follows.

# filename (including path) downloaded ERA5 data was saved to
era5_netcdf_filename = 'ERA5_weather_data.nc'

# get weather data in windpowerlib format for all locations in
# netcdf file
windpowerlib_df = era5.weather_df_from_era5(
    era5_netcdf_filename=filename,
    lib='windpowerlib')

If the netcdf contains more than one location the windpowerlib_df will contain all of those locations and the index of the dataframe will be a multiindex with levels (time, latitude, longitude). To use it for windpowerlib calculations you need to select a single location first. To directly obtain data for a single location you need to specify it using the area parameter:

# get weather data in windpowerlib format for single location
# (weather data for nearest weather data point to specified
# location is returned)
area = [13.5, 52.4]
windpowerlib_df = era5.weather_df_from_era5(
    era5_netcdf_filename=filename,
    lib='windpowerlib', area=area)

You may also specify an area for which to retrieve weather data. Again, keep in mind that in that case the index of the returned dataframe will be a multiindex with levels (time, latitude, longitude) and cannot be directly used for windpowerlib or pvlib calculations.

# specify rectangular area
area = [(13.5, 13.8), (51.0, 53.0)]

# specify area giving a Polygon
from shapely.geometry import Polygon
lat_point_list = [51.936377, 51.936377, 51.744302, 51.744302, 51.936377]
lon_point_list = [12.621739, 13.005414, 13.005414, 12.621739, 12.621739]
area = Polygon(zip(lon_point_list, lat_point_list))

Furthermore, it is possible to specify a start and end date to retrieve data for. They must be provided as something that can be converted to a timestamp, i.e. ‘2013-07-02’.

# get weather data in pvlib format starting January 15th
start = '2015-01-15'
windpowerlib_df = era5.weather_df_from_era5(
    era5_netcdf_filename=filename,
    lib='pvlib', area=area, start=start)

Example for using the Pvlib model

The Pvlib model can be used to determine the feed-in of a photovoltaic module using the pvlib. The pvlib is a python library for simulating the performance of photovoltaic energy systems. For more information check out the documentation of the pvlib.

The following example shows you how to use the Pvlib model.

• Set up Photovoltaic object
• Get weather data
• Calculate feed-in

Set up Photovoltaic object

To calculate the feed-in using the Pvlib model you have to set up a Photovoltaic object. You can import it as follows:

from feedinlib import Photovoltaic

To set up a Photovoltaic system you have to provide all PV system parameters required by the PVlib model. The required parameters can be looked up in the model’s documentation. For the Pvlib model these are the azimuth and tilt of the module as well as the albedo or surface type. Furthermore, the name of the module and inverter are needed to obtain technical parameters from the provided module and inverter databases. For an overview of the provided modules and inverters you can use the function get_power_plant_data().

from feedinlib import get_power_plant_data

# get modules
module_df = get_power_plant_data(dataset='sandiamod')
# print the first four modules
module_df.iloc[:, 1:5]

	Advent_Solar_Ventura_210___2008_	Advent_Solar_Ventura_215___2009_	Aleo_S03_160__2007__E__	Aleo_S03_165__2007__E__
Vintage	2008	2009	2007 (E)	2007 (E)
Area	1.646	1.646	1.28	1.28
Material	mc-Si	mc-Si	c-Si	c-Si
Cells_in_Series	60	60	72	72
Parallel_Strings	1	1	1	1
Isco	8.34	8.49	5.1	5.2
Voco	35.31	35.92	43.5	43.6
Impo	7.49	7.74	4.55	4.65
Vmpo	27.61	27.92	35.6	35.8
Aisc	0.00077	0.00082	0.0003	0.0003
Aimp	-0.00015	-0.00013	-0.00025	-0.00025
C0	0.937	1.015	0.99	0.99
C1	0.063	-0.015	0.01	0.01
Bvoco	-0.133	-0.135	-0.152	-0.152
Mbvoc	0	0	0	0
Bvmpo	-0.135	-0.136	-0.158	-0.158
Mbvmp	0	0	0	0
N	1.495	1.373	1.25	1.25
C2	0.0182	0.0036	-0.15	-0.15
C3	-10.758	-7.2509	-8.96	-8.96
A0	0.9067	0.9323	0.938	0.938
A1	0.09573	0.06526	0.05422	0.05422
A2	-0.0266	-0.01567	-0.009903	-0.009903
A3	0.00343	0.00193	0.0007297	0.0007297
A4	-0.0001794	-9.81e-05	-1.907e-05	-1.907e-05
B0	1	1	1	1
B1	-0.002438	-0.002438	-0.002438	-0.002438
B2	0.00031	0.00031	0.0003103	0.0003103
B3	-1.246e-05	-1.246e-05	-1.246e-05	-1.246e-05
B4	2.11e-07	2.11e-07	2.11e-07	2.11e-07
B5	-1.36e-09	-1.36e-09	-1.36e-09	-1.36e-09
DTC	3	3	3	3
FD	1	1	1	1
A	-3.45	-3.47	-3.56	-3.56
B	-0.077	-0.087	-0.075	-0.075
C4	0.972	0.989	0.995	0.995
C5	0.028	0.012	0.005	0.005
IXO	8.25	8.49	5.04	5.14
IXXO	5.2	5.45	3.16	3.25
C6	1.067	1.137	1.15	1.15
C7	-0.067	-0.137	-0.15	-0.15
Notes	Source: Sandia National Laboratories Updated 9...	Source: Sandia National Laboratories Updated 9...	Source: Sandia National Laboratories Updated 9...	Source: Sandia National Laboratories Updated 9...

# get inverter data
inverter_df = get_power_plant_data(dataset='cecinverter')
# print the first four inverters
inverter_df.iloc[:, 1:5]

	ABB__MICRO_0_25_I_OUTD_US_208__208V__208V__CEC_2018_	ABB__MICRO_0_25_I_OUTD_US_240_240V__CEC_2014_	ABB__MICRO_0_25_I_OUTD_US_240__240V__240V__CEC_2018_	ABB__MICRO_0_3_I_OUTD_US_208_208V__CEC_2014_
Vac	208.000000	240.000000	240.000000	208.000000
Paco	250.000000	250.000000	250.000000	300.000000
Pdco	259.589000	259.552697	259.492000	311.714554
Vdco	40.000000	39.982246	40.000000	40.227111
Pso	2.089610	1.931194	2.240410	1.971053
C0	-0.000041	-0.000027	-0.000039	-0.000036
C1	-0.000091	-0.000158	-0.000132	-0.000256
C2	0.000494	0.001480	0.002418	-0.000833
C3	-0.013171	-0.034600	-0.014926	-0.039100
Pnt	0.020000	0.050000	0.050000	0.020000
Vdcmax	50.000000	65.000000	50.000000	65.000000
Idcmax	6.489710	10.000000	6.487300	10.000000
Mppt_low	30.000000	20.000000	30.000000	30.000000
Mppt_high	50.000000	50.000000	50.000000	50.000000

Now you can set up a PV system to calculate feed-in for, using for example the first module and converter in the databases:

system_data = {
    'module_name': 'Advent_Solar_Ventura_210___2008_',  # module name as in database
    'inverter_name': 'ABB__MICRO_0_25_I_OUTD_US_208__208V__208V__CEC_2018_',  # inverter name as in database
    'azimuth': 180,
    'tilt': 30,
    'albedo': 0.2}
pv_system = Photovoltaic(**system_data)

Optional power plant parameters

Besides the required PV system parameters you can provide optional parameters such as the number of modules per string, etc. Optional PV system parameters are specific to the used model and how to find out about the possible optional parameters is documented in the model’s feedin method under power_plant_parameters. In case of the Pvlib model see here.

system_data['modules_per_string'] = 2
pv_system_with_optional_parameters = Photovoltaic(**system_data)

Get weather data

Besides setting up your PV system you have to provide weather data the feed-in is calculated with. This example uses open_FRED weather data. For more information on the data and download see the load_open_fred_weather_data Notebook.

from feedinlib.db import Weather
from feedinlib.db import defaultdb
from shapely.geometry import Point

# specify latitude and longitude of PV system location
lat = 52.4
lon = 13.5
location = Point(lon, lat)

# download weather data for June 2017
open_FRED_weather_data = Weather(
    start='2017-06-01', stop='2017-07-01',
    locations=[location],
    variables="pvlib",
    **defaultdb())

# get weather data in pvlib format
weather_df = open_FRED_weather_data.df(location=location, lib="pvlib")

/home/birgit/virtualenvs/feedinlib/lib/python3.6/site-packages/pandas/core/sorting.py:257: FutureWarning: Converting timezone-aware DatetimeArray to timezone-naive ndarray with 'datetime64[ns]' dtype. In the future, this will return an ndarray with 'object' dtype where each element is a 'pandas.Timestamp' with the correct 'tz'.
        To accept the future behavior, pass 'dtype=object'.
        To keep the old behavior, pass 'dtype="datetime64[ns]"'.
  items = np.asanyarray(items)

# plot irradiance
import matplotlib.pyplot as plt
%matplotlib inline
weather_df.loc[:, ['dhi', 'ghi']].plot(title='Irradiance')
plt.xlabel('Time')
plt.ylabel('Irradiance in $W/m^2$');

Calculate feed-in

The feed-in can be calculated by calling the Photovoltaic’s feedin method with the weather data. For the Pvlib model you also have to provide the location of the PV system.

feedin = pv_system.feedin(
    weather=weather_df,
    location=(lat, lon))

# plot calculated feed-in
import matplotlib.pyplot as plt
%matplotlib inline
feedin.plot(title='PV feed-in')
plt.xlabel('Time')
plt.ylabel('Power in W');

Scaled feed-in

The PV feed-in can also be automatically scaled by the PV system’s area or peak power. The following example shows how to scale feed-in by area.

feedin_scaled = pv_system.feedin(
    weather=weather_df,
    location=(lat, lon),
    scaling='area')

To scale by the peak power use scaling=peak_power.

The PV system area and peak power can be retrieved as follows:

pv_system.area

1.646

pv_system.peak_power

206.7989

# plot calculated feed-in
import matplotlib.pyplot as plt
%matplotlib inline
feedin_scaled.plot(title='Scaled PV feed-in')
plt.xlabel('Time')
plt.ylabel('Power in W');

Feed-in for PV system with optional parameters

In the following example the feed-in is calculated for the PV system with optional system parameters (with 2 modules per string, instead of 1, which is the default). It was chosen to demonstrate the importantance of choosing a suitable converter.

feedin_ac = pv_system_with_optional_parameters.feedin(
    weather=weather_df,
    location=(lat, lon))

# plot calculated feed-in
import matplotlib.pyplot as plt
%matplotlib inline
feedin_ac.plot(title='PV feed-in')
plt.xlabel('Time')
plt.ylabel('Power in W');

As the above plot shows the feed-in is cut off at 250 W. That is because it is limited by the inverter. So while the area is as expected two times greater as for the PV system without optional parameters, the peak power is only around 1.2 times higher.

pv_system_with_optional_parameters.peak_power / pv_system.peak_power

1.208903915833208

pv_system_with_optional_parameters.area / pv_system.area

2.0

If you are only interested in the modules power output without the inverter losses you can have the Pvlib model return the DC feed-in. This is done as follows:

feedin_dc = pv_system_with_optional_parameters.feedin(
    weather=weather_df,
    location=(lat, lon),
    mode='dc')

# plot calculated feed-in
import matplotlib.pyplot as plt
%matplotlib inline
feedin_dc.plot(label='DC', title='AC and DC PV feed-in', legend=True)
feedin_ac.plot(label='AC', legend=True)
plt.xlabel('Time')
plt.ylabel('Power in W');

Feed-in with optional model parameters

In order to change the default calculation configurations of the Pvlib model to e.g. choose a different model to calculate losses or the solar position you can pass further parameters to the feedin method. An overview of which further parameters may be provided is documented under the feedin method’s kwargs.

feedin_no_loss = pv_system.feedin(
    weather=weather_df,
    location=(lat, lon),
    aoi_model='no_loss')

# plot calculated feed-in
import matplotlib.pyplot as plt
%matplotlib inline
feedin_no_loss.iloc[0:96].plot(label='aoi_model = no_loss', legend=True)
feedin.iloc[0:96].plot(label='aoi_model = sapm_aoi_loss', legend=True)
plt.xlabel('Time')
plt.ylabel('Power in W');

What’s New

These are new features and improvements of note in each release

v0.0.11 (November 22, 2016)

New features

• Using model of windpowerlib instead of internal model. This will be the future of the feedinlib.

Bug fixes

• removed ‘vernetzen’-server because it is down

Contributors

• Uwe Krien

v0.0.10 (November 18, 2016)

Other changes

Move wind power calculations to windpowerlib Allow installation of windpowerlib for python versions >3.4 Import requests package instead of urllib5

Contributors

• Uwe Krien
• Stephen Bosch
• Birgit Schachler

v0.0.9 (August 23, 2016)

Bug fixes

• Adapt API due to changes in the pvlib
• Avoid pandas future warning running the pv model

Contributors

• Uwe Krien

v0.0.8 (Mai 2, 2016)

New features

• add a geometry attribute for shapely.geometry objects to the weather class
• add lookup table for the sandia pv modules

Documentation

• add link to the developer rules of oemof

Bug fixes

• Adapt url to sandia’s module library

Contributors

• Uwe Krien

v0.0.7 (October 20, 2015)

New features

• add a weather class to define the structure of the weather data input
• add example file to pass your own model class to the feedinlib

Documentation

• correct some typos
• some distribtions are clearer now
• describe the used units

Testing

• add more doctests
• removed obsolete tests

Bug fixes

• does not overwrite class attributes (issue 7)

Other changes

• rename classes to more describing names
• initialisation of a power plant changed (see README for details)

Contributors

• Uwe Krien
• Stephan Günther
• Cord Kaldemeyer

API

Power plant classes

Power plant classes for specific weather dependent renewable energy resources.

feedinlib.powerplants.Photovoltaic([model])	Class to define a standard set of PV system attributes.
feedinlib.powerplants.WindPowerPlant([model])	Class to define a standard set of wind power plant attributes.

Feed-in models

Feed-in models take in power plant and weather data to calculate power plant feed-in. So far models using the python libraries pvlib and windpowerlib to calculate photovoltaic and wind power feed-in, respectively, have been implemented.

feedinlib.models.Pvlib(**kwargs)	Model to determine the feed-in of a photovoltaic module using the pvlib.
feedinlib.models.WindpowerlibTurbine(**kwargs)	Model to determine the feed-in of a wind turbine using the windpowerlib.
feedinlib.models.WindpowerlibTurbineCluster(…)	Model to determine the feed-in of a wind turbine cluster using the windpowerlib.

Weather data

The feedinlib enables download of open_FRED weather data (local reanalysis data for Germany) and ERA5 weather data (global reanalysis data for the whole world).

feedinlib.db.Weather
feedinlib.era5.weather_df_from_era5
feedinlib.era5.get_era5_data_from_datespan_and_position

Tools

feedinlib.models.get_power_plant_data(…)

Function to retrieve power plant data sets provided by feed-in models.

Abstract classes

The feedinlib uses abstract classes for power plant and feed-in models that serve as blueprints for classes that implement those models. This ensures that new models provide required implementations that make it possible to easily exchange the model used in your calculation. They are important for people who want to implement new power plant and model classes rather than for users.

feedinlib.powerplants.Base(**attributes)	The base class of feedinlib power plants.
feedinlib.models.Base(**kwargs)	The base class of feedinlib models.
feedinlib.models.PhotovoltaicModelBase(**kwargs)	Expands model base class Base by PV specific attributes.
feedinlib.models.WindpowerModelBase(**kwargs)	Expands model base class Base by wind power specific attributes.

Indices and tables

• Index
• Module Index
• Search Page