Remove orientation_strategy from Modelchain (#1181)

kandersolar · web-flow · commit 85cd89cbed13 · 2021-03-01T12:58:27.000-07:00
* remove orientation_strategy parameter from modelchain.py

* update tests

* scrub docs

* whatsnew
diff --git a/docs/sphinx/source/api.rst b/docs/sphinx/source/api.rst
@@ -609,7 +609,6 @@ ModelChain properties that are aliases for your specific modeling functions.
 .. autosummary::
    :toctree: generated/
 
-   modelchain.ModelChain.orientation_strategy
    modelchain.ModelChain.dc_model
    modelchain.ModelChain.ac_model
    modelchain.ModelChain.aoi_model
diff --git a/docs/sphinx/source/introtutorial.rst b/docs/sphinx/source/introtutorial.rst
@@ -190,12 +190,6 @@ by examining the parameters defined for the module.
     from pvlib.location import Location
     from pvlib.modelchain import ModelChain
 
-    system = PVSystem(
-        module_parameters=module,
-        inverter_parameters=inverter,
-        temperature_model_parameters=temperature_model_parameters,
-    )
-
     energies = {}
     for location, weather in zip(coordinates, tmys):
         latitude, longitude, name, altitude, timezone = location
@@ -206,11 +200,15 @@ by examining the parameters defined for the module.
             altitude=altitude,
             tz=timezone,
         )
-        mc = ModelChain(
-            system,
-            location,
-            orientation_strategy='south_at_latitude_tilt',
+        system = PVSystem(
+            surface_tilt=latitude,
+            surface_azimuth=180,
+            module_parameters=module,
+            inverter_parameters=inverter,
+            temperature_model_parameters=temperature_model_parameters,
         )
+
+        mc = ModelChain(system, location)
         results = mc.run_model(weather)
         annual_energy = results.ac.sum()
         energies[name] = annual_energy
diff --git a/docs/sphinx/source/whatsnew/v0.9.0.rst b/docs/sphinx/source/whatsnew/v0.9.0.rst
@@ -40,6 +40,11 @@ Breaking changes
   ``ModelChain.adrinverter`` changed to ``ModelChain.adr_inverter``.
   (:pull:`1150`)
 
+* The ``orientation_strategy`` parameter has been removed from the various
+  :py:class:`pvlib.modelchain.ModelChain` constructors and ``surface_tilt``,
+  ``surface_azimuth`` are now required parameters for
+  :py:func:`pvlib.modelchain.basic_chain` (:issue:`1028`, :pull:`1181`)
+
 
 Deprecations
 ~~~~~~~~~~~~
diff --git a/docs/tutorials/forecast.ipynb b/docs/tutorials/forecast.ipynb
@@ -6664,7 +6664,6 @@
       "text/plain": [
        "ModelChain: \n",
        "  name: None\n",
-       "  orientation_strategy: south_at_latitude_tilt\n",
        "  clearsky_model: ineichen\n",
        "  transposition_model: haydavies\n",
        "  solar_position_method: nrel_numpy\n",
@@ -6692,15 +6691,16 @@
     "inverter = sapm_inverters['ABB__MICRO_0_25_I_OUTD_US_208__208V_']\n",
     "\n",
     "system = PVSystem(module_parameters=module,\n",
-    "                  inverter_parameters=inverter)\n",
+    "                  inverter_parameters=inverter,\n",
+    "                  surface_tilt=latitude,\n",
+    "                  surface_azimuth=180)\n",
     "\n",
     "# fx is a common abbreviation for forecast\n",
     "fx_model = GFS()\n",
     "fx_data = fx_model.get_processed_data(latitude, longitude, start, end)\n",
     "\n",
     "# use a ModelChain object to calculate modeling intermediates\n",
-    "mc = ModelChain(system, fx_model.location,\n",
-    "                orientation_strategy='south_at_latitude_tilt')\n",
+    "mc = ModelChain(system, fx_model.location)\n",
     "\n",
     "# extract relevant data for model chain\n",
     "mc.run_model(weather=fx_data)"
diff --git a/pvlib/modelchain.py b/pvlib/modelchain.py
@@ -63,11 +63,10 @@
 
 
 def basic_chain(times, latitude, longitude,
+                surface_tilt, surface_azimuth,
                 module_parameters, temperature_model_parameters,
                 inverter_parameters,
                 irradiance=None, weather=None,
-                surface_tilt=None, surface_azimuth=None,
-                orientation_strategy=None,
                 transposition_model='haydavies',
                 solar_position_method='nrel_numpy',
                 airmass_model='kastenyoung1989',
@@ -91,6 +90,17 @@ def basic_chain(times, latitude, longitude,
         Positive is east of the prime meridian.
         Use decimal degrees notation.
 
+    surface_tilt : numeric
+        Surface tilt angles in decimal degrees.
+        The tilt angle is defined as degrees from horizontal
+        (e.g. surface facing up = 0, surface facing horizon = 90)
+
+    surface_azimuth : numeric
+        Surface azimuth angles in decimal degrees.
+        The azimuth convention is defined
+        as degrees east of north
+        (North=0, South=180, East=90, West=270).
+
     module_parameters : None, dict or Series
         Module parameters as defined by the SAPM. See pvsystem.sapm for
         details.
@@ -112,23 +122,6 @@ def basic_chain(times, latitude, longitude,
         wind speed is 0 m/s.
         Columns must be 'wind_speed', 'temp_air'.
 
-    surface_tilt : None, float or Series, default None
-        Surface tilt angles in decimal degrees.
-        The tilt angle is defined as degrees from horizontal
-        (e.g. surface facing up = 0, surface facing horizon = 90)
-
-    surface_azimuth : None, float or Series, default None
-        Surface azimuth angles in decimal degrees.
-        The azimuth convention is defined
-        as degrees east of north
-        (North=0, South=180, East=90, West=270).
-
-    orientation_strategy : None or str, default None
-        The strategy for aligning the modules.
-        If not None, sets the ``surface_azimuth`` and ``surface_tilt``
-        properties of the ``system``. Allowed strategies include 'flat',
-        'south_at_latitude_tilt'. Ignored for SingleAxisTracker systems.
-
     transposition_model : str, default 'haydavies'
         Passed to system.get_irradiance.
 
@@ -157,17 +150,6 @@ def basic_chain(times, latitude, longitude,
         power (Series).
     """
 
-    # use surface_tilt and surface_azimuth if provided,
-    # otherwise set them using the orientation_strategy
-    if surface_tilt is not None and surface_azimuth is not None:
-        pass
-    elif orientation_strategy is not None:
-        surface_tilt, surface_azimuth = \
-            get_orientation(orientation_strategy, latitude=latitude)
-    else:
-        raise ValueError('orientation_strategy or surface_tilt and '
-                         'surface_azimuth must be provided')
-
     if altitude is None and pressure is None:
         altitude = 0.
         pressure = 101325.
@@ -332,12 +314,6 @@ class ModelChain:
         A :py:class:`~pvlib.location.Location` object that represents
         the physical location at which to evaluate the model.
 
-    orientation_strategy : None or str, default None
-        The strategy for aligning the modules. If not None, sets the
-        ``surface_azimuth`` and ``surface_tilt`` properties of the
-        ``system``. Allowed strategies include 'flat',
-        'south_at_latitude_tilt'. Ignored for SingleAxisTracker systems.
-
     clearsky_model : str, default 'ineichen'
         Passed to location.get_clearsky.
 
@@ -395,7 +371,6 @@ class ModelChain:
                          'dc', 'ac', 'diode_params', 'tracking']
 
     def __init__(self, system, location,
-                 orientation_strategy=None,
                  clearsky_model='ineichen',
                  transposition_model='haydavies',
                  solar_position_method='nrel_numpy',
@@ -421,7 +396,6 @@ def __init__(self, system, location,
         self.temperature_model = temperature_model
 
         self.losses_model = losses_model
-        self.orientation_strategy = orientation_strategy
 
         self.weather = None
         self.times = None
@@ -451,7 +425,6 @@ def __setattr__(self, key, value):
 
     @classmethod
     def with_pvwatts(cls, system, location,
-                     orientation_strategy=None,
                      clearsky_model='ineichen',
                      airmass_model='kastenyoung1989',
                      name=None,
@@ -469,12 +442,6 @@ def with_pvwatts(cls, system, location,
             A :py:class:`~pvlib.location.Location` object that represents
             the physical location at which to evaluate the model.
 
-        orientation_strategy : None or str, default None
-            The strategy for aligning the modules. If not None, sets the
-            ``surface_azimuth`` and ``surface_tilt`` properties of the
-            ``system``. Allowed strategies include 'flat',
-            'south_at_latitude_tilt'. Ignored for SingleAxisTracker systems.
-
         clearsky_model : str, default 'ineichen'
             Passed to location.get_clearsky.
 
@@ -502,7 +469,6 @@ def with_pvwatts(cls, system, location,
         >>> ModelChain.with_pvwatts(system, location)
         ModelChain:
           name: None
-          orientation_strategy: None
           clearsky_model: ineichen
           transposition_model: perez
           solar_position_method: nrel_numpy
@@ -518,7 +484,6 @@ def with_pvwatts(cls, system, location,
         config.update(kwargs)
         return ModelChain(
             system, location,
-            orientation_strategy=orientation_strategy,
             clearsky_model=clearsky_model,
             airmass_model=airmass_model,
             name=name,
@@ -527,7 +492,6 @@ def with_pvwatts(cls, system, location,
 
     @classmethod
     def with_sapm(cls, system, location,
-                  orientation_strategy=None,
                   clearsky_model='ineichen',
                   transposition_model='haydavies',
                   solar_position_method='nrel_numpy',
@@ -548,12 +512,6 @@ def with_sapm(cls, system, location,
             A :py:class:`~pvlib.location.Location` object that represents
             the physical location at which to evaluate the model.
 
-        orientation_strategy : None or str, default None
-            The strategy for aligning the modules. If not None, sets the
-            ``surface_azimuth`` and ``surface_tilt`` properties of the
-            ``system``. Allowed strategies include 'flat',
-            'south_at_latitude_tilt'. Ignored for SingleAxisTracker systems.
-
         clearsky_model : str, default 'ineichen'
             Passed to location.get_clearsky.
 
@@ -589,7 +547,6 @@ def with_sapm(cls, system, location,
         >>> ModelChain.with_sapm(system, location)
         ModelChain:
           name: None
-          orientation_strategy: None
           clearsky_model: ineichen
           transposition_model: haydavies
           solar_position_method: nrel_numpy
@@ -605,7 +562,6 @@ def with_sapm(cls, system, location,
         config.update(kwargs)
         return ModelChain(
             system, location,
-            orientation_strategy=orientation_strategy,
             clearsky_model=clearsky_model,
             transposition_model=transposition_model,
             solar_position_method=solar_position_method,
@@ -616,7 +572,7 @@ def with_sapm(cls, system, location,
 
     def __repr__(self):
         attrs = [
-            'name', 'orientation_strategy', 'clearsky_model',
+            'name', 'clearsky_model',
             'transposition_model', 'solar_position_method',
             'airmass_model', 'dc_model', 'ac_model', 'aoi_model',
             'spectral_model', 'temperature_model', 'losses_model'
@@ -634,21 +590,6 @@ def getmcattr(self, attr):
         return ('ModelChain: \n  ' + '\n  '.join(
             f'{attr}: {getmcattr(self, attr)}' for attr in attrs))
 
-    @property
-    def orientation_strategy(self):
-        return self._orientation_strategy
-
-    @orientation_strategy.setter
-    def orientation_strategy(self, strategy):
-        if strategy == 'None':
-            strategy = None
-
-        if strategy is not None:
-            self.system.surface_tilt, self.system.surface_azimuth = \
-                get_orientation(strategy, latitude=self.location.latitude)
-
-        self._orientation_strategy = strategy
-
     @property
     def dc_model(self):
         return self._dc_model
diff --git a/pvlib/tests/test_modelchain.py b/pvlib/tests/test_modelchain.py
