Create iam.py, consistent naming for IAM functions (#783)

* move iam functions to iam.py

* move function tests to test_iam.py

* adjust PVSystem methods, add deprecation for functions and PVSystem methods

* adjust PVSystem tests, test for function deprecation

* move sapm aoi function, adjust ModelChain methods

* remove _ typo

* lint fixes

* move fixture to correct place

* move sapm_module_params fixture to conftest.py

* fix cut/paste errors

* add missing keys to fixture, add missing text to pvsystem.sapm docstring

* fix and update pvsystem.sapm tests

* remove DataFrame test for sapm, lint fixes

* implement PVSystem.get_iam, add deprecation test for pvsystem.sapm_aoi_loss

* lint

* test fixes, add Material to sapm_module_params fixture

* test fixes

* add martin_ruiz to modelchain

* finish adding martin_ruiz to modelchain

* add test for ModelChain.infer_aoi_model, improve coverage

* repair delete mistake

* test for invalid aoi model parameters in ModelChain

* update api, whatsnew

* test fix

* fixture for aoi_model tests

* bad indent

* docstring and lint

* lint

* module docstring, changes to tests

* test fixes

* another test fix

* improve coverage

* fix exception test

* fix the fix

Author: cwhanse

docs/sphinx/source/api.rst

@@ -211,15 +211,17 @@ wrap the functions listed below. See its documentation for details.
    pvsystem.PVSystem
    pvsystem.LocalizedPVSystem
 
-AOI modifiers
--------------
+Incident angle modifiers
+------------------------
 
 .. autosummary::
    :toctree: generated/
 
-   pvsystem.physicaliam
-   pvsystem.ashraeiam
-   pvsystem.sapm_aoi_loss
+   iam.physical
+   iam.ashrae
+   iam.martin_ruiz
+   iam.sapm
+   iam.interp
 
 PV temperature models
 ---------------------

docs/sphinx/source/whatsnew/v0.7.0.rst

@@ -69,6 +69,20 @@ API Changes
       - `modelchain.basic_chain` has a new required argument
         `temperature_model_parameters`.
 
+* Changes related to IAM (AOI loss) functions (:issue:`680`):
+   * Changes to functions
+      - Moved functions from `pvsystem.py` to `iam.py`. `pvsystem` IAM
+       functions are deprecated and will be removed in v0.8.
+      - Functions are renamed to a consistent pattern:
+         - `pvsystem.physicaliam` is `iam.physical`
+         - `pvsystem.ashraeiam` is `iam.ashrae`
+         - `pvsystem.sapm_aoi_loss` is `iam.sapm`
+      - Created dict `iam.IAM_MODEL_PARAMS` to aid in identifying IAM models
+   * Changes to `PVSystem` class
+      - IAM models are provided by `PVSystem.get_iam` with kwarg `iam_model`.
+      - Methods `PVSystem.ashraeiam`, `PVSystem.physicaliam` and
+       `PVSystem.sapm_aoi_loss` are deprecated and will be removed in v0.8.
+
 * Calling :py:func:`pvlib.pvsystem.retrieve_sam` with no parameters will raise
   an exception instead of displaying a dialog.
 * The `times` keyword argument has been deprecated in the
@@ -83,8 +97,9 @@ API Changes
 
 Enhancements
 ~~~~~~~~~~~~
-* Created two new incidence angle modifier functions: :py:func:`pvlib.pvsystem.iam_martin_ruiz`
-  and :py:func:`pvlib.pvsystem.iam_interp`. (:issue:`751`)
+* Created two new incidence angle modifier (IAM) functions:
+  :py:func:`pvlib.iam.martin_ruiz` and :py:func:`pvlib.iam.interp`. (:issue:`751`)
+* Add the `martin_ruiz` IAM function as an option for `ModelChain.aoi_model`.
 * Updated the file for module parameters for the CEC model, from the SAM file
   dated 2017-6-5 to the SAM file dated 2019-03-05. (:issue:`761`)
 * Updated the file for inverter parameters for the CEC model, from the SAM file
@@ -96,6 +111,7 @@ Enhancements
   the single diode equation to an IV curve.
 * Add :py:func:`~pvlib.ivtools.fit_sdm_cec_sam`, a wrapper for the CEC single
   diode model fitting function '6parsolve' from NREL's System Advisor Model.
+* Add `timeout` to :py:func:`pvlib.iotools.get_psm3`.
 
 Bug fixes
 ~~~~~~~~~
@@ -113,6 +129,8 @@ Testing
   in NSRDB (:issue:`733`)
 * Added tests for methods in bifacial.py.
 * Added tests for changes to cell temperature models.
+* Added tests for changes to IAM models.
+* Added test for `ModelChain.infer_aoi_model`.
 
 Documentation
 ~~~~~~~~~~~~~
@@ -133,11 +151,6 @@ Removal of prior version deprecations
 * Removed `ModelChain.prepare_inputs` clearsky assumption when no irradiance
   data was provided.
 
-Enhancements
-~~~~~~~~~~~~
-* Add `timeout` to :py:func:`pvlib.iotools.get_psm3`.
-
-
 Contributors
 ~~~~~~~~~~~~
 * Mark Campanellli (:ghuser:`markcampanelli`)