renaming, update api.rst

pvlib · cwhanse · Aug 28, 2020 · Aug 1, 2016 · Oct 4, 2018 · May 4, 2019
commit 9fc68b53dde7be2aaa5a2023caa8f1acadad74ee
diff --git a/docs/sphinx/source/api.rst b/docs/sphinx/source/api.rst
@@ -303,10 +303,14 @@ Functions for fitting PV models
 .. autosummary::
   :toctree: generated/

-    ivtools.fit_sde_sandia
-    ivtools.fit_sdm_cec_sam
-    ivtools.fit_sdm_desoto
-    ivtools.pvsyst_parameter_estimation
+    ivtools.fit_sde.fit_sandia
+    ivtools.fit_sde.fit_cocontent
+    ivtools.fit_sdm.fit_cec_sam
+    ivtools.fit_sdm.fit_desoto
+    ivtools.fit_sdm.fit_pvsyst_sandia
+    ivtools.utility.numdiff
+    ivtools.utility.rectify_iv_curve
+    ivtools.utility.schumaker_qspline

 Other
 -----

diff --git a/pvlib/ivtools/fit_sde.py b/pvlib/ivtools/fit_sde.py
@@ -10,8 +10,8 @@
 from pvlib.ivtools.utility import schumaker_qspline


-def fit_sde_sandia(voltage, current, v_oc=None, i_sc=None, v_mp_i_mp=None,
-                   vlim=0.2, ilim=0.1):
+def fit_sandia(voltage, current, v_oc=None, i_sc=None, v_mp_i_mp=None,
+               vlim=0.2, ilim=0.1):
    r"""
    Fits the single diode equation (SDE) [1]_ to an IV curve. Uses the method
    described in [2]_.
@@ -75,7 +75,7 @@ def fit_sde_sandia(voltage, current, v_oc=None, i_sc=None, v_mp_i_mp=None,
    assumed to be from a single IV curve at constant irradiance and cell
    temperature.

-    :py:func:`fit_single_diode_sandia` obtains values for the five parameters
+    :py:func:`fit_sandia` obtains values for the five parameters
    for the single diode equation [1]:

    .. math::
@@ -192,7 +192,7 @@ def _find_mp(voltage, current):


 def _sandia_beta0_beta1(v, i, vlim, v_oc):
-    # Helper for fit_sde_sandia.
+    # Helper for fit_sandia.
    # Get intercept and slope of linear portion of IV curve.
    # Start with V =< vlim * v_oc, extend by adding points until slope is
    # negative (downward).
@@ -215,7 +215,7 @@ def _sandia_beta0_beta1(v, i, vlim, v_oc):


 def _sandia_beta3_beta4(voltage, current, beta0, beta1, ilim, i_sc):
-    # Helper for fit_sde_sandia.
+    # Helper for fit_sandia.
    # Subtract the IV curve from the linear fit.
    y = beta0 - beta1 * voltage - current
    x = np.array([np.ones_like(voltage), voltage, current]).T
@@ -233,7 +233,7 @@ def _sandia_beta3_beta4(voltage, current, beta0, beta1, ilim, i_sc):


 def _sandia_calc_sde_params(beta0, beta1, beta3, beta4, v_mp, i_mp, v_oc):
-    # Helper for fit_sde_sandia.
+    # Helper for fit_sandia.
    nNsVth = 1.0 / beta3
    Rs = beta4 / beta3
    Gp = beta1 / (1.0 - Rs * beta1)
@@ -257,7 +257,7 @@ def _calc_I0(IL, I, V, Gp, Rs, nNsVth):
    return (IL - I - Gp * V - Gp * Rs * I) / np.exp((V + Rs * I) / nNsVth)


-def fit_sde_cocontent(voltage, current, nsvth):
+def fit_cocontent(voltage, current, nsvth):
    """
    Regression technique to fit the single diode equation to data for a single
    IV curve.
@@ -363,7 +363,7 @@ def fit_sde_cocontent(voltage, current, nsvth):


 def _cocontent(v, c, isc, kflag):
-    # Used by fit_sde_cocontent
+    # Used by fit_cocontent
    # calculate co-content integral by numerical integration of
    # i = (Isc - I) over v
    # Here, i = Isc - I is assumed to be represented by the quadratic spline
@@ -397,7 +397,7 @@ def _cocontent(v, c, isc, kflag):


 def _cocontent_regress(v, i, voc, isc, cci):
-    # Used by fit_sde_content
+    # Used by fit_content
    # For the method coded here see Appendix C of [2] SAND2015-2065
    # predictor variables for regression of CC
    x = np.vstack((v, isc - i, v * (isc - i), v * v, (i - isc) ** 2)).T

diff --git a/pvlib/ivtools/fit_sdm.py b/pvlib/ivtools/fit_sdm.py
@@ -1,7 +1,7 @@
 """
 The ``fit_sdm`` module contains functions to fit single diode models.

-Function names should follow the pattern "fit_sdm_" + name of model + "_" +
+Function names should follow the pattern "fit_" + name of model + "_" +
 fitting method.

 """
@@ -14,11 +14,11 @@
 from pvlib.pvsystem import singlediode, v_from_i

 from pvlib.ivtools.utility import constants, rectify_iv_curve, numdiff
-from pvlib.ivtools.fit_sde import fit_sde_cocontent
+from pvlib.ivtools.fit_sde import fit_cocontent


-def fit_sdm_cec_sam(celltype, v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc,
-                    gamma_pmp, cells_in_series, temp_ref=25):
+def fit_cec_sam(celltype, v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc,
+                gamma_pmp, cells_in_series, temp_ref=25):
    """
    Estimates parameters for the CEC single diode model (SDM) using the SAM
    SDK. Uses the method described in [1]_.
@@ -116,9 +116,9 @@ def fit_sdm_cec_sam(celltype, v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc,
        raise RuntimeError('Parameter estimation failed')


-def fit_sdm_desoto(v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc,
-                   cells_in_series, EgRef=1.121, dEgdT=-0.0002677,
-                   temp_ref=25, irrad_ref=1000, root_kwargs={}):
+def fit_desoto(v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc,
+               cells_in_series, EgRef=1.121, dEgdT=-0.0002677,
+               temp_ref=25, irrad_ref=1000, root_kwargs={}):
    """
    Calculates the parameters for the De Soto single diode model [1]_ using the
    procedure described in [2]_. This procedure has the advantage of
@@ -213,7 +213,7 @@ def fit_sdm_desoto(v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc,
        from scipy.optimize import root
        import scipy.constants
    except ImportError:
-        raise ImportError("The fit_sdm_desoto function requires scipy.")
+        raise ImportError("The fit_desoto function requires scipy.")

    # Constants
    k = scipy.constants.value('Boltzmann constant in eV/K')
@@ -260,7 +260,7 @@ def fit_sdm_desoto(v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc,
 def _system_of_equations_desoto(params, specs):
    """Evaluates the systems of equations used to solve for the single
    diode equation parameters. Function designed to be used by
-    scipy.optimize.root() in fit_sdm_desoto().
+    scipy.optimize.root() in fit_desoto().

    Parameters
    ----------
@@ -449,7 +449,7 @@ def fit_pvsyst_sandia(ivcurves, specs, const=constants, maxiter=5,
        # initial estimate of Rsh, from integral over voltage regression
        # [5] Step 3a; [6] Step 3a
        _, _, _, rsh[j], _ = \
-            fit_sde_cocontent(voltage, current, vth[j] * specs['ns'])
+            fit_cocontent(voltage, current, vth[j] * specs['ns'])

    gamma_ref, mugamma = _fit_pvsyst_sandia_gamma(isc, voc, rsh, vth, tck,
                                                  const, specs)
@@ -942,7 +942,7 @@ def _update_rsh_fixed_pt(rsh, rs, io, il, nnsvth, imp, vmp):
    for i in range(niter):
        z = _calc_phi_exact(imp, il, io, rsh, nnsvth)
        next_rsh = (1 + z) / z * ((il + io) * rsh / imp - nnsvth * z / imp
-            - 2 * vmp / imp)
+                    - 2 * vmp / imp)
        rsh = next_rsh

    return next_rsh

diff --git a/pvlib/ivtools/utility.py b/pvlib/ivtools/utility.py
@@ -22,7 +22,7 @@

 def numdiff(x, f):
    """
-    NUMDIFF computes first and second order derivative using possibly unequally
+    Compute first and second order derivative using possibly unequally
    spaced data.

    Parameters
@@ -45,16 +45,17 @@ def numdiff(x, f):
    Description
    -----------
    numdiff computes first and second order derivatives using a 5th order
-    formula that accounts for possibly unequally spaced data. Because a 5th
-    order centered difference formula is used, numdiff returns NaNs for the
-    first 2 and last 2 points in the input vector for x.
+    formula that accounts for possibly unequally spaced data [1]_. Because a
+    5th order centered difference formula is used, numdiff returns NaNs for the
+    first 2 and last 2 points in the input vector for x. Ported from PVLib
+    Matlab [2]_.

    References
    ----------
-    [1] PVLib MATLAB
-    [2] M. K. Bowen, R. Smith, "Derivative formulae and errors for
-        non-uniformly spaced points", Proceedings of the Royal Society A, vol.
-        461 pp 1975 - 1997, July 2005. DOI: 10.1098/rpsa.2004.1430
+    .. [1] M. K. Bowen, R. Smith, "Derivative formulae and errors for
+       non-uniformly spaced points", Proceedings of the Royal Society A, vol.
+       461 pp 1975 - 1997, July 2005. DOI: 10.1098/rpsa.2004.1430
+    .. [2] PVLib MATLAB https://github.com/sandialabs/MATLAB_PV_LIB
    """

    n = len(f)
@@ -133,8 +134,8 @@ def numdiff(x, f):

 def rectify_iv_curve(voltage, current, decimals=None):
    """
-    ``rectify_IV_curve`` sorts the IV curve data, removes NaN and negative
-    values, and combines points with duplicate voltage.
+    Sort the IV curve data, remove NaNs and negative
+    values, and combine points with duplicate voltage.

    Parameters
    ----------
@@ -157,9 +158,9 @@ def rectify_iv_curve(voltage, current, decimals=None):
    -----------
    ``rectify_IV_curve`` ensures that the IV curve lies in the first quadrant
    of the (voltage, current) plane. The returned IV curve:
-    * contains no NaNs
    * increases in voltage
    * contains no negative current or voltage values
+    * contains no NaNs
    * contains no points with duplicate voltage values. Where voltage values
      are repeated, a single data point is substituted with current equal to
      the average of current at duplicated voltages.
@@ -190,7 +191,7 @@ def rectify_iv_curve(voltage, current, decimals=None):

 def schumaker_qspline(x, y):
    """
-    schumaker_qspline fits a quadratic spline which preserves monotonicity and
+    Fit a quadratic spline which preserves monotonicity and
    convexity in the data.

    Parameters
@@ -227,11 +228,12 @@ def schumaker_qspline(x, y):

    References
    ----------
-    [1] PVLib MATLAB
-    [2] L. L. Schumaker, "On Shape Preserving Quadratic Spline Interpolation",
-        SIAM Journal on Numerical Analysis 20(4), August 1983, pp 854 - 864
-    [3] M. H. Lam, "Monotone and Convex Quadratic Spline Interpolation",
-        Virginia Journal of Science 41(1), Spring 1990
+    .. [1] PVLib MATLAB https://github.com/sandialabs/MATLAB_PV_LIB
+    .. [2] L. L. Schumaker, "On Shape Preserving Quadratic Spline
+       Interpolation", SIAM Journal on Numerical Analysis 20(4), August 1983,
+       pp 854 - 864
+    .. [3] M. H. Lam, "Monotone and Convex Quadratic Spline Interpolation",
+       Virginia Journal of Science 41(1), Spring 1990
    """
    # Make sure vectors are 1D arrays
    x = x.flatten()

diff --git a/pvlib/test/ivtools_tests/test_fit_sde.py b/pvlib/test/ivtools_tests/test_fit_sde.py
@@ -11,7 +11,7 @@ def get_test_iv_params():


 @requires_scipy
-def test_fit_sde_sandia(get_test_iv_params, get_bad_iv_curves):
+def test_fit_sandia(get_test_iv_params, get_bad_iv_curves):
    test_params = get_test_iv_params
    testcurve = pvsystem.singlediode(photocurrent=test_params['IL'],
                                     saturation_current=test_params['I0'],
@@ -21,35 +21,35 @@ def test_fit_sde_sandia(get_test_iv_params, get_bad_iv_curves):
                                     ivcurve_pnts=300)
    expected = tuple(test_params[k] for k in ['IL', 'I0', 'Rsh', 'Rs',
                     'nNsVth'])
-    result = fit_sde.fit_sde_sandia(voltage=testcurve['v'],
-                                    current=testcurve['i'])
+    result = fit_sde.fit_sandia(voltage=testcurve['v'],
+                                current=testcurve['i'])
    assert np.allclose(result, expected, rtol=5e-5)
-    result = fit_sde.fit_sde_sandia(voltage=testcurve['v'],
-                                    current=testcurve['i'],
-                                    v_oc=testcurve['v_oc'],
-                                    i_sc=testcurve['i_sc'])
+    result = fit_sde.fit_sandia(voltage=testcurve['v'],
+                                current=testcurve['i'],
+                                v_oc=testcurve['v_oc'],
+                                i_sc=testcurve['i_sc'])
    assert np.allclose(result, expected, rtol=5e-5)
-    result = fit_sde.fit_sde_sandia(voltage=testcurve['v'],
-                                    current=testcurve['i'],
-                                    v_oc=testcurve['v_oc'],
-                                    i_sc=testcurve['i_sc'],
-                                    v_mp_i_mp=(testcurve['v_mp'],
-                                    testcurve['i_mp']))
+    result = fit_sde.fit_sandia(voltage=testcurve['v'],
+                                current=testcurve['i'],
+                                v_oc=testcurve['v_oc'],
+                                i_sc=testcurve['i_sc'],
+                                v_mp_i_mp=(testcurve['v_mp'],
+                                testcurve['i_mp']))
    assert np.allclose(result, expected, rtol=5e-5)
-    result = fit_sde.fit_sde_sandia(voltage=testcurve['v'],
-                                    current=testcurve['i'], vlim=0.1)
+    result = fit_sde.fit_sandia(voltage=testcurve['v'],
+                                current=testcurve['i'], vlim=0.1)
    assert np.allclose(result, expected, rtol=5e-5)


 @requires_scipy
 def test_fit_sde_sandia_bad_iv(get_bad_iv_curves):
    # bad IV curves for coverage of if/then in _calculate_sde_parameters
    v1, i1, v2, i2 = get_bad_iv_curves
-    result = fit_sde.fit_sde_sandia(voltage=v1, current=i1)
+    result = fit_sde.fit_sandia(voltage=v1, current=i1)
    assert np.allclose(result, (-2.4322856072799985, 8.854688976836396,
                                -63.56227601452038, 111.18558915546389,
                                -137.9965046659527))
-    result = fit_sde.fit_sde_sandia(voltage=v2, current=i2)
+    result = fit_sde.fit_sandia(voltage=v2, current=i2)
    assert np.allclose(result, (2.62405311949227, 1.8657963912925288,
                                110.35202827739991, -65.652554411442,
                                174.49362093001415))

diff --git a/pvlib/test/ivtools_tests/test_fit_sdm.py b/pvlib/test/ivtools_tests/test_fit_sdm.py
@@ -29,10 +29,10 @@ def get_cec_params_cansol_cs5p_220p():


 @requires_pysam
-def test_fit_sdm_cec_sam(get_cec_params_cansol_cs5p_220p):
+def test_fit_sdm_sam(get_cec_params_cansol_cs5p_220p):
    input_data = get_cec_params_cansol_cs5p_220p['input']
    I_L_ref, I_o_ref, R_sh_ref, R_s, a_ref, Adjust = \
-        fit_sdm.fit_sdm_cec_sam(
+        fit_sdm.fit_cec_sam(
            celltype='polySi', v_mp=input_data['V_mp_ref'],
            i_mp=input_data['I_mp_ref'], v_oc=input_data['V_oc_ref'],
            i_sc=input_data['I_sc_ref'], alpha_sc=input_data['alpha_sc'],
@@ -51,18 +51,18 @@ def test_fit_sdm_cec_sam(get_cec_params_cansol_cs5p_220p):
    # test for fitting failure
    with pytest.raises(RuntimeError):
        I_L_ref, I_o_ref, R_sh_ref, R_s, a_ref, Adjust = \
-            fit_sdm.fit_sdm_cec_sam(
+            fit_sdm.fit_cec_sam(
                celltype='polySi', v_mp=0.45, i_mp=5.25, v_oc=0.55, i_sc=5.5,
                alpha_sc=0.00275, beta_voc=0.00275, gamma_pmp=0.0055,
                cells_in_series=1, temp_ref=25)


 @requires_scipy
-def test_fit_sdm_desoto():
-    result, _ = fit_sdm.fit_sdm_desoto(v_mp=31.0, i_mp=8.71, v_oc=38.3,
-                                       i_sc=9.43, alpha_sc=0.005658,
-                                       beta_voc=-0.13788,
-                                       cells_in_series=60)
+def test_fit_desoto():
+    result, _ = fit_sdm.fit_desoto(v_mp=31.0, i_mp=8.71, v_oc=38.3,
+                                   i_sc=9.43, alpha_sc=0.005658,
+                                   beta_voc=-0.13788,
+                                   cells_in_series=60)
    result_expected = {'I_L_ref': 9.45232,
                       'I_o_ref': 3.22460e-10,
                       'a_ref': 1.59128,
@@ -80,9 +80,9 @@ def test_fit_sdm_desoto():
 @requires_scipy
 def test_fit_sdm_desoto_failure():
    with pytest.raises(RuntimeError) as exc:
-        fit_sdm.fit_sdm_desoto(v_mp=31.0, i_mp=8.71, v_oc=38.3, i_sc=9.43,
-                               alpha_sc=0.005658, beta_voc=-0.13788,
-                               cells_in_series=10)
+        fit_sdm.fit_desoto(v_mp=31.0, i_mp=8.71, v_oc=38.3, i_sc=9.43,
+                           alpha_sc=0.005658, beta_voc=-0.13788,
+                           cells_in_series=10)
    assert ('Parameter estimation failed') in str(exc.value)