Merge pull request #53 from wind-python/api_changes_deprecation_warnings

Deprecation warnings for future API changes

Author: birgits

.gitignore

@@ -35,7 +35,9 @@ pip-log.txt
 pip-delete-this-directory.txt
 
 # Doc
-doc/temp/
+doc/temp/*
+!doc/temp/windpowerlib.wind_farm.WindFarm.rst
+!doc/temp/windpowerlib.wind_turbine_cluster.WindTurbineCluster.rst
 .doctrees
 .buildinfo
 

.travis.yml

@@ -14,7 +14,7 @@ matrix:
 
 install:
   - pip install .
-  - pip install coveralls sphinx nbformat pytest-cov jupyter
+  - pip install coveralls sphinx sphinx_rtd_theme nbformat pytest-cov jupyter
 
 # command to run tests
 script:

doc/conf.py

@@ -35,14 +35,23 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.extlinks',  # enables external links with a key
     'sphinx.ext.viewcode',
     'sphinx.ext.imgmath',
     'sphinx.ext.napoleon',
     'sphinx.ext.autosummary',
     'nbsphinx'
-
 ]
 
+autodoc_member_order = 'bysource'
+
+extlinks = {'pandas':('http://pandas.pydata.org/pandas-docs/stable/reference/%s.html',
+                      'pandas.')
+            }
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+
 # 
 autoclass_content = 'both'
 
@@ -117,11 +126,9 @@
 # -- Options for HTML output ----------------------------------------------
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-on_rtd = os.environ.get('READTHEDOCS') == 'True'
-if on_rtd:
-    html_theme = 'default'
-else:
-    html_theme = 'bizstyle'
+import sphinx_rtd_theme
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

doc/temp/windpowerlib.wind_farm.WindFarm.rst

@@ -0,0 +1,8 @@
+windpowerlib.wind\_farm.WindFarm
+======================================
+
+.. currentmodule:: windpowerlib.wind_farm
+
+.. autoclass:: WindFarm
+   :members: 
+

doc/temp/windpowerlib.wind_turbine_cluster.WindTurbineCluster.rst

@@ -0,0 +1,8 @@
+windpowerlib.wind\_turbine\_cluster.WindTurbineCluster
+======================================================
+
+.. currentmodule:: windpowerlib.wind_turbine_cluster
+
+.. autoclass:: WindTurbineCluster
+   :members: 
+

example/test_examples.py

@@ -32,10 +32,9 @@ def test_turbine_cluster_modelchain_example_flh(self):
             example_farm, example_farm_2)
         tc_mc_e.calculate_power_output(weather, example_farm, example_cluster)
         assert_allclose(1956.164053, (example_farm.power_output.sum() /
-                                     example_farm.installed_power), 0.01)
-        example_cluster.installed_power = example_cluster.get_installed_power()
+                                      example_farm.nominal_power), 0.01)
         assert_allclose(2156.794154, (example_cluster.power_output.sum() /
-                                     example_cluster.installed_power), 0.01)
+                                     example_cluster.nominal_power), 0.01)
 
     def _notebook_run(self, path):
         """

windpowerlib/wind_farm.py

@@ -11,6 +11,7 @@
 from windpowerlib import tools, power_curves
 import numpy as np
 import pandas as pd
+import warnings
 
 
 class WindFarm(object):
@@ -54,11 +55,15 @@ class WindFarm(object):
         dimensionless wind farm efficiency. Default: None.
     hub_height : float
         The calculated mean hub height of the wind farm.
-    installed_power : float
-        The calculated installed power of the wind farm.
     power_curve : pandas.DataFrame or None
         The calculated power curve of the wind farm.
     power_output : pandas.Series
+    nominal_power : float
+        The nominal power is the sum of the nominal power of all turbines in
+        the wind farm in W.
+    installed_power : float
+        Installed nominal power of the wind farm in W. Deprecated! Use
+        :attr:`~.wind_farm.WindFarm.nominal_power` instead.
         The calculated power output of the wind farm.
 
     Examples
@@ -77,8 +82,7 @@ class WindFarm(object):
     ...    'wind_turbine_fleet': [{'wind_turbine': e126,
     ...                            'number_of_turbines': 6}]}
     >>> example_farm = wind_farm.WindFarm(**example_farm_data)
-    >>> example_farm.installed_power = example_farm.get_installed_power()
-    >>> print(example_farm.installed_power)
+    >>> print(example_farm.nominal_power)
     25200000.0
 
     """
@@ -91,10 +95,52 @@ def __init__(self, name, wind_turbine_fleet, coordinates=None,
         self.efficiency = efficiency
 
         self.hub_height = None
-        self.installed_power = None
+        self._nominal_power = None
+        self._installed_power = None
         self.power_curve = None
         self.power_output = None
 
+    @property
+    def installed_power(self):
+        r"""
+        The installed nominal power of the wind farm. (Deprecated!)
+
+        """
+        warnings.warn(
+            'installed_power is deprecated, use nominal_power instead.',
+            FutureWarning)
+        return self.nominal_power
+
+    @installed_power.setter
+    def installed_power(self, installed_power):
+        self._installed_power = installed_power
+
+    @property
+    def nominal_power(self):
+        r"""
+        The nominal power of the wind farm.
+
+        See :attr:`~.wind_farm.WindFarm.nominal_power` for further information.
+
+        Parameters
+        -----------
+        nominal_power : float
+            Nominal power of the wind farm in W.
+
+        Returns
+        -------
+        float
+            Nominal power of the wind farm in W.
+
+        """
+        if not self._nominal_power:
+            self.nominal_power = self.get_installed_power()
+        return self._nominal_power
+
+    @nominal_power.setter
+    def nominal_power(self, nominal_power):
+        self._nominal_power = nominal_power
+
     def mean_hub_height(self):
         r"""
         Calculates the mean hub height of the wind farm.
@@ -139,17 +185,13 @@ def mean_hub_height(self):
 
     def get_installed_power(self):
         r"""
-        Calculates the installed power of the wind farm.
-
-        The installed power of wind farms is necessary when a
-        :class:`~.wind_turbine_cluster.WindTurbineCluster` object is used and
-        it's power weighed mean hub height is calculated with
-        :py:func:`~.wind_turbine_cluster.WindTurbineCluster.mean_hub_height`.
+        Calculates :py:attr:`~nominal_power` of the wind farm.
 
         Returns
         -------
         float
-            Installed power of the wind farm.
+            Nominal power of the wind farm in W. See :py:attr:`~nominal_power`
+            for further information.
 
         """
         return sum(

windpowerlib/wind_turbine_cluster.py

@@ -13,6 +13,7 @@
 
 import numpy as np
 import pandas as pd
+import warnings
 
 
 class WindTurbineCluster(object):
@@ -40,6 +41,9 @@ class WindTurbineCluster(object):
         weather data. Default: None.
     hub_height : float
         The calculated average hub height of the wind turbine cluster.
+    nominal_power : float
+        The nominal power is the sum of the nominal power of all turbines in
+        the wind turbine cluster in W.
     installed_power : float
         The calculated installed power of the wind turbine cluster.
     power_curve : pandas.DataFrame or None
@@ -55,10 +59,53 @@ def __init__(self, name, wind_farms, coordinates=None, **kwargs):
         self.coordinates = coordinates
 
         self.hub_height = None
-        self.installed_power = None
+        self._nominal_power = None
+        self._installed_power = None
         self.power_curve = None
         self.power_output = None
 
+    @property
+    def installed_power(self):
+        r"""
+        The installed nominal power of the wind turbine cluster. (Deprecated!)
+
+        """
+        warnings.warn(
+            'installed_power is deprecated, use nominal_power instead.',
+            FutureWarning)
+        return self.nominal_power
+
+    @installed_power.setter
+    def installed_power(self, installed_power):
+        self._installed_power = installed_power
+
+    @property
+    def nominal_power(self):
+        r"""
+        The nominal power of the wind turbine cluster.
+
+        See :attr:`~.wind_turbine_cluster.WindTurbineCluster.nominal_power`
+        for further information.
+
+        Parameters
+        -----------
+        nominal_power : float
+            Nominal power of the wind turbine cluster in w.
+
+        Returns
+        -------
+        float
+            Nominal power of the wind turbine cluster in w.
+
+        """
+        if not self._nominal_power:
+            self.nominal_power = self.get_installed_power()
+        return self._nominal_power
+
+    @nominal_power.setter
+    def nominal_power(self, nominal_power):
+        self._nominal_power = nominal_power
+
     def mean_hub_height(self):
         r"""
         Calculates the mean hub height of the wind turbine cluster.
@@ -99,17 +146,18 @@ def mean_hub_height(self):
 
     def get_installed_power(self):
         r"""
-        Calculates the installed power of a wind turbine cluster.
+        Calculates the :py:attr:`~nominal_power` of a wind turbine cluster.
 
         Returns
         -------
         float
-            Installed power of the wind turbine cluster.
+            Nominal power of the wind farm in W. See :py:attr:`~nominal_power`
+            for further information.
 
         """
         for wind_farm in self.wind_farms:
-            wind_farm.installed_power = wind_farm.get_installed_power()
-        return sum(wind_farm.installed_power for wind_farm in self.wind_farms)
+            wind_farm.nominal_power = wind_farm.get_installed_power()
+        return sum(wind_farm.nominal_power for wind_farm in self.wind_farms)
 
     def assign_power_curve(self, wake_losses_model='power_efficiency_curve',
                            smoothing=False, block_width=0.5,