Update notebook

Author: Birgit Schachler

example/basic_example.ipynb

@@ -4,9 +4,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This example shows you the basic usage of the windpowerlib. There are mainly three steps.\n",
-    "First you need to define your wind turbine, then get your weather data and in the last step call the windpowerlib ModelChain to generate your feedin timeseries.\n",
-    "Be careful with the units!"
+    "This example shows you the basic usage of the windpowerlib. \n",
+    "There are mainly three steps. First you have to import your weather data, then you need to specify your wind turbine, and in the last step call the windpowerlib functions to calculate the feedin timeseries."
    ]
   },
   {
@@ -59,7 +58,8 @@
    "source": [
     "### Import weather data\n",
     "\n",
-    "The function below imports the example weather data from the weather.csv file provided along with the windpowerlib. The data include wind speed at two different heights in m/s, air temperature in two different heights in K, surface roughness length in m and air pressure in Pa.\n",
+    "In order to use the windpowerlib you need to at least provide wind speed data for the time frame you want to analyse.\n",
+    "The function below imports example weather data from the weather.csv file provided along with the windpowerlib. The data include wind speed at two different heights in m/s, air temperature in two different heights in K, surface roughness length in m and air pressure in Pa.\n",
     "\n",
     "To find out which weather data in which units need to be provided in order to use the ModelChain or other functions of the windpowerlib see the individual function documentation."
    ]
@@ -72,7 +72,7 @@
    },
    "outputs": [],
    "source": [
-    "def read_weather_data(filename, datetime_column='Unnamed: 0',\n",
+    "def read_weather_data(filename, datetime_column='time_index',\n",
     "                      **kwargs):\n",
     "    r\"\"\"\n",
     "    Fetches weather data from a file.\n",
@@ -109,7 +109,7 @@
     "\n",
     "\n",
     "# Read weather data from csv\n",
-    "weather = read_weather_data('weather.csv')"
+    "weather = read_weather_data(filename='weather.csv', datapath='')"
    ]
   },
   {
@@ -127,6 +127,7 @@
    },
    "outputs": [],
    "source": [
+    "# height in meters\n",
     "data_height = {\n",
     "    'pressure': 0,\n",
     "    'temp_air': 2,\n",
@@ -146,19 +147,26 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "There are two ways to initialize a WindTurbine object. You can either specify your own turbine, as done below or use"
+    "To initialise your specific turbine you need a dictionary that contains your basic parameters. A turbine is defined by its nominal power, hub height, rotor diameter, and power or power coefficient curve.\n",
+    "\n",
+    "There are two ways to initialise a WindTurbine object in the windpowerlib. You can either specify your own turbine, as done below for 'myTurbine' or fetch power and/or power coefficient curve data from data files provided by the windpowerlib, as done for the 'enerconE126'.\n",
+    "\n",
+    "You can execute the following to get a list of all wind turbines for which power or power coefficient curves are provided."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
+    "# print names of wind turbines for which power curves are provided (default)\n",
     "wt.get_turbine_types()\n",
-    "turbines[turbines[\"turbine_id\"].str.contains(\"VESTAS\")]"
+    "\n",
+    "# write names of wind turbines for which power coefficient curves are provided to 'turbines' DataFrame\n",
+    "turbines = wt.get_turbine_types(filename='cp_curves.csv', print_out=False)\n",
+    "# find all Vestas in 'turbines' DataFrame\n",
+    "print(turbines[turbines[\"turbine_id\"].str.contains(\"ENERCON\")])"
    ]
   },
   {
@@ -169,72 +177,80 @@
    },
    "outputs": [],
    "source": [
-    "# Specifications of the wind turbines\n",
-    "enerconE126 = {\n",
-    "    'hub_height': 135,\n",
-    "    'd_rotor': 127,\n",
-    "    'fetch_curve': 'P',  # 'P' vor p-curve and 'cp' for cp-curve\n",
-    "    'turbine_name': 'ENERCON E 126 7500'}  # Turbine name as in register. Use\n",
-    "                                           # wind_turbine.get_turbine_types()\n",
-    "P_data = {0:\n",
-    "         3:\n",
-    "         5:\n",
-    "         10:\n",
-    "         15:\n",
-    "         20:\n",
-    "         25:}\n",
-    "# for a full list.\n",
-    "vestasV90 = {\n",
-    "    'hub_height': 105,\n",
-    "    'd_rotor': 90,\n",
-    "    'fetch_curve': 'P',\n",
-    "    'turbine_name': 'VESTAS V 90 3000'}\n",
+    "# specification of own wind turbine (Note: power coefficient values and nominal power have to be in Watt)\n",
+    "myTurbine = {\n",
+    "    'turbine_name': 'myTurbine',\n",
+    "    'nominal_power': 3e6,  # in W\n",
+    "    'hub_height': 105,  # in m\n",
+    "    'd_rotor': 90,  # in m\n",
+    "    'p_values': pd.DataFrame(\n",
+    "        data={'p': [p * 1000 for p in [0.0, 26.0, 180.0, 1500.0, 3000.0, 3000.0]]},  # in W\n",
+    "        index=[0.0, 3.0, 5.0, 10.0, 15.0, 25.0])\n",
+    "    }\n",
     "\n",
-    "# Initialize WindTurbine objects\n",
+    "# specification of wind turbine where power curve is provided\n",
+    "# if you want to use the power coefficient curve add {}'fetch_curve': 'cp'} to the dictionary\n",
+    "enerconE126 = {\n",
+    "    'turbine_name': 'ENERCON E 126 7500',  # Turbine name as in register\n",
+    "    'hub_height': 135,  # in m\n",
+    "    'd_rotor': 127  # in m\n",
+    "    }\n",
+    "    \n",
+    "# initialise WindTurbine objects\n",
     "e126 = wt.WindTurbine(**enerconE126)\n",
-    "v90 = wt.WindTurbine(**vestasV90)"
+    "my_turbine = wt.WindTurbine(**myTurbine)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Use the ModelChain to generate feedin timeseries"
+    "### Use the ModelChain to generate feedin timeseries\n",
+    "\n",
+    "The ModelChain is a class that provides all necessary steps to calculate the power output of a wind turbine. If you use the 'run_model' method first the wind speed and density (if necessary) at hub height are calculated and then used to calculate the power output. You can either use the default methods for the calculation steps, as done for 'my_turbine', or choose different methods, as done for the 'e126'."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
-    "# Specifications of the modelchain data\n",
+    "# initialise ModelChain with default parameters and use run_model method to calculate power output\n",
+    "mc_my_turbine = modelchain.ModelChain(my_turbine).run_model(\n",
+    "    weather, data_height)\n",
+    "# write power output timeseries to WindTurbine object\n",
+    "my_turbine.power_output = mc_my_turbine.power_output"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# own specifications for ModelChain setup\n",
     "modelchain_data = {\n",
-    "    'obstacle_height': 0,\n",
-    "    'wind_model': 'logarithmic',       # 'logarithmic' or 'hellman'\n",
-    "    'rho_model': 'ideal_gas',          # 'barometric' or 'ideal_gas'\n",
-    "    'power_output_model': 'p_values',  # 'p_values' or 'cp_values'\n",
-    "    'density_corr': False,             # True or False\n",
-    "    'hellman_exp': None}               # Float or None\n",
-    "\n",
-    "# Calculate turbine power output\n",
+    "    'obstacle_height': 0,              # default: 0\n",
+    "    'wind_model': 'logarithmic',       # 'logarithmic' (default) or 'hellman'\n",
+    "    'rho_model': 'ideal_gas',          # 'barometric' (default) or 'ideal_gas'\n",
+    "    'power_output_model': 'p_values',  # 'p_values' (default) or 'cp_values'\n",
+    "    'density_corr': True,              # False (default) or True\n",
+    "    'hellman_exp': None}               # None (default) or None\n",
+    "# initialise ModelChain with own specifications and use run_model method to calculate power output\n",
     "mc_e126 = modelchain.ModelChain(e126, **modelchain_data).run_model(\n",
-    "    weather, coastDat2)\n",
-    "e126.power_output = mc_e126.power_output\n",
-    "mc_v90 = modelchain.ModelChain(v90, **modelchain_data).run_model(\n",
-    "    weather, coastDat2)\n",
-    "v90.power_output = mc_v90.power_output\n",
-    "\n",
-    "\n"
+    "    weather, data_height)\n",
+    "# write power output timeseries to WindTurbine object\n",
+    "e126.power_output = mc_e126.power_output"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Plot results"
+    "### Plot results\n",
+    "\n",
+    "If you have matplotlib installed you can visualise the calculated power output and used power (coefficient) curves."
    ]
   },
   {
@@ -245,42 +261,59 @@
    },
    "outputs": [],
    "source": [
+    "# try to import matplotlib\n",
     "try:\n",
     "    from matplotlib import pyplot as plt\n",
+    "    %matplotlib inline # needed in notebook to plot inline\n",
     "except ImportError:\n",
-    "    plt = None\n",
-    "# Plot turbine power output\n",
+    "    plt = None"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# plot turbine power output\n",
     "if plt:\n",
     "    e126.power_output.plot(legend=True, label='Enercon E126')\n",
-    "    v90.power_output.plot(legend=True, label='Vestas V90')\n",
-    "    plt.show()\n",
-    "else:\n",
-    "    print(e126.power_output)\n",
-    "    print(v90.power_output)\n",
-    "\n",
-    "# Plot power (coefficient) curves\n",
+    "    my_turbine.power_output.plot(legend=True, label='myTurbine')\n",
+    "    plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "# plot power (coefficient) curves\n",
     "if plt:\n",
     "    if e126.cp_values is not None:\n",
     "        e126.cp_values.plot(style='*', title='Enercon E126')\n",
     "        plt.show()\n",
     "    if e126.p_values is not None:\n",
     "        e126.p_values.plot(style='*', title='Enercon E126')\n",
     "        plt.show()\n",
-    "    if v90.cp_values is not None:\n",
-    "        v90.cp_values.plot(style='*', title='Vestas V90')\n",
+    "    if my_turbine.cp_values is not None:\n",
+    "        my_turbine.cp_values.plot(style='*', title='myTurbine')\n",
     "        plt.show()\n",
-    "    if v90.p_values is not None:\n",
-    "        v90.p_values.plot(style='*', title='Vestas V90')\n",
-    "        plt.show()\n",
-    "else:\n",
-    "    if e126.cp_values is not None:\n",
-    "        print(\"The cp value at a wind speed of 5 m/s: {0}\".format(\n",
-    "            e126.cp_values.cp[5.0]))\n",
-    "    if e126.p_values is not None:\n",
-    "        print(\"The P value at a wind speed of 5 m/s: {0}\".format(\n",
-    "            e126.p_values.P[5.0]))\n",
-    "logging.info('Done!')"
+    "    if my_turbine.p_values is not None:\n",
+    "        my_turbine.p_values.plot(style='*', title='myTurbine')\n",
+    "        plt.show()"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {