[DOC] improve singlediode.bishop88 docstring formatting

[kandersolar]

• I am familiar with the contributing guidelines
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels and Milestone are assigned to the Pull Request and linked Issue.

Some rendering improvements for the bishop88 docstring. Link to published docs page showing the issues: https://pvlib-python.readthedocs.io/en/latest/generated/pvlib.singlediode.bishop88.html

The primary issue was mismatched braces in the main equation's latex code -- please verify that the fixed version is accurate to Bishop's paper. I think I got it right, but it's always good to check.

PR docs: https://pvlib-python--967.org.readthedocs.build/en/967/generated/pvlib.singlediode.bishop88.html

[cwhanse]

Looks correct to me, thanks @kanderso-nrel

[CameronTStark]

LGTM, thanks!

[wholmgren]

The fixes to the equation are great, thanks.

But @cwhanse stated in #960 (comment) that he's -1 on using :math: in parameters unless really necessary, and I agree. Or was that just for units? I'm not sure where that leaves us on the change to the Parameters section of this docstring.

[kandersolar]

The Parameters section changes were for consistency with the other entries in this docstring, though it is true that they are inconsistent with much of the rest of pvlib. I'm happy to change them all to not use the math tag -- are double backticks the preferred alternative, or just plaintext? And do you feel similarly about the gradients in the Returns section?

[cwhanse]

But @cwhanse stated in #960 (comment) that he's -1 on using :math: in parameters unless really necessary, and I agree. Or was that just for units? I'm not sure where that leaves us on the change to the Parameters section of this docstring.

I'm -1 on using :math: formatting for units in the docstrings. In this case the :math: formatting helps connect argument names e.g. diode_voltage with terms in the equation being evaluation :math:V_d which I think is worth doing.

[mikofski]

LGTM! Thanks! Perhaps we can update the docstring for singlediode to match this typesetting?

pvlib-python/pvlib/pvsystem.py

Lines 1958 to 2146 in f8921bd

	def singlediode(photocurrent, saturation_current, resistance_series,
	resistance_shunt, nNsVth, ivcurve_pnts=None,
	method='lambertw'):
	"""
	Solve the single-diode model to obtain a photovoltaic IV curve.
	Singlediode solves the single diode equation [1]_
	.. math::
	I = IL - I0*[exp((V+I*Rs)/(nNsVth))-1] - (V + I*Rs)/Rsh
	for ``I`` and ``V`` when given ``IL, I0, Rs, Rsh,`` and ``nNsVth
	(nNsVth = n*Ns*Vth)`` which are described later. Returns a DataFrame
	which contains the 5 points on the I-V curve specified in
	SAND2004-3535 [3]_. If all IL, I0, Rs, Rsh, and nNsVth are scalar, a
	single curve will be returned, if any are Series (of the same
	length), multiple IV curves will be calculated.
	The input parameters can be calculated using calcparams_desoto from
	meteorological data.
	Parameters
	----------
	photocurrent : numeric
	Light-generated current (photocurrent) in amperes under desired
	IV curve conditions. Often abbreviated ``I_L``.
	0 <= photocurrent
	saturation_current : numeric
	Diode saturation current in amperes under desired IV curve
	conditions. Often abbreviated ``I_0``.
	0 < saturation_current
	resistance_series : numeric
	Series resistance in ohms under desired IV curve conditions.
	Often abbreviated ``Rs``.
	0 <= resistance_series < numpy.inf
	resistance_shunt : numeric
	Shunt resistance in ohms under desired IV curve conditions.
	Often abbreviated ``Rsh``.
	0 < resistance_shunt <= numpy.inf
	nNsVth : numeric
	The product of three components. 1) The usual diode ideal factor
	(n), 2) the number of cells in series (Ns), and 3) the cell
	thermal voltage under the desired IV curve conditions (Vth). The
	thermal voltage of the cell (in volts) may be calculated as
	``k*temp_cell/q``, where k is Boltzmann's constant (J/K),
	temp_cell is the temperature of the p-n junction in Kelvin, and
	q is the charge of an electron (coulombs).
	0 < nNsVth
	ivcurve_pnts : None or int, default None
	Number of points in the desired IV curve. If None or 0, no
	IV curves will be produced.
	method : str, default 'lambertw'
	Determines the method used to calculate points on the IV curve. The
	options are ``'lambertw'``, ``'newton'``, or ``'brentq'``.
	Returns
	-------
	OrderedDict or DataFrame
	The returned dict-like object always contains the keys/columns:
	* i_sc - short circuit current in amperes.
	* v_oc - open circuit voltage in volts.
	* i_mp - current at maximum power point in amperes.
	* v_mp - voltage at maximum power point in volts.
	* p_mp - power at maximum power point in watts.
	* i_x - current, in amperes, at ``v = 0.5*v_oc``.
	* i_xx - current, in amperes, at ``V = 0.5*(v_oc+v_mp)``.
	If ivcurve_pnts is greater than 0, the output dictionary will also
	include the keys:
	* i - IV curve current in amperes.
	* v - IV curve voltage in volts.
	The output will be an OrderedDict if photocurrent is a scalar,
	array, or ivcurve_pnts is not None.
	The output will be a DataFrame if photocurrent is a Series and
	ivcurve_pnts is None.
	Notes
	-----
	If the method is ``'lambertw'`` then the solution employed to solve the
	implicit diode equation utilizes the Lambert W function to obtain an
	explicit function of :math:`V=f(I)` and :math:`I=f(V)` as shown in [2]_.
	If the method is ``'newton'`` then the root-finding Newton-Raphson method
	is used. It should be safe for well behaved IV-curves, but the ``'brentq'``
	method is recommended for reliability.
	If the method is ``'brentq'`` then Brent's bisection search method is used
	that guarantees convergence by bounding the voltage between zero and
	open-circuit.
	If the method is either ``'newton'`` or ``'brentq'`` and ``ivcurve_pnts``
	are indicated, then :func:`pvlib.singlediode.bishop88` [4]_ is used to
	calculate the points on the IV curve points at diode voltages from zero to
	open-circuit voltage with a log spacing that gets closer as voltage
	increases. If the method is ``'lambertw'`` then the calculated points on
	the IV curve are linearly spaced.
	References
	----------
	.. [1] S.R. Wenham, M.A. Green, M.E. Watt, "Applied Photovoltaics" ISBN
	0 86758 909 4
	.. [2] A. Jain, A. Kapoor, "Exact analytical solutions of the
	parameters of real solar cells using Lambert W-function", Solar
	Energy Materials and Solar Cells, 81 (2004) 269-277.
	.. [3] D. King et al, "Sandia Photovoltaic Array Performance Model",
	SAND2004-3535, Sandia National Laboratories, Albuquerque, NM
	.. [4] "Computer simulation of the effects of electrical mismatches in
	photovoltaic cell interconnection circuits" JW Bishop, Solar Cell (1988)
	https://doi.org/10.1016/0379-6787(88)90059-2
	See also
	--------
	sapm
	calcparams_desoto
	pvlib.singlediode.bishop88
	"""
	# Calculate points on the IV curve using the LambertW solution to the
	# single diode equation
	if method.lower() == 'lambertw':
	out = _singlediode._lambertw(
	photocurrent, saturation_current, resistance_series,
	resistance_shunt, nNsVth, ivcurve_pnts
	)
	i_sc, v_oc, i_mp, v_mp, p_mp, i_x, i_xx = out[:7]
	if ivcurve_pnts:
	ivcurve_i, ivcurve_v = out[7:]
	else:
	# Calculate points on the IV curve using either 'newton' or 'brentq'
	# methods. Voltages are determined by first solving the single diode
	# equation for the diode voltage V_d then backing out voltage
	args = (photocurrent, saturation_current, resistance_series,
	resistance_shunt, nNsVth) # collect args
	v_oc = _singlediode.bishop88_v_from_i(
	0.0, *args, method=method.lower()
	)
	i_mp, v_mp, p_mp = _singlediode.bishop88_mpp(
	*args, method=method.lower()
	)
	i_sc = _singlediode.bishop88_i_from_v(
	0.0, *args, method=method.lower()
	)
	i_x = _singlediode.bishop88_i_from_v(
	v_oc / 2.0, *args, method=method.lower()
	)
	i_xx = _singlediode.bishop88_i_from_v(
	(v_oc + v_mp) / 2.0, *args, method=method.lower()
	)
	# calculate the IV curve if requested using bishop88
	if ivcurve_pnts:
	vd = v_oc * (
	(11.0 - np.logspace(np.log10(11.0), 0.0,
	ivcurve_pnts)) / 10.0
	)
	ivcurve_i, ivcurve_v, _ = _singlediode.bishop88(vd, *args)
	out = OrderedDict()
	out['i_sc'] = i_sc
	out['v_oc'] = v_oc
	out['i_mp'] = i_mp
	out['v_mp'] = v_mp
	out['p_mp'] = p_mp
	out['i_x'] = i_x
	out['i_xx'] = i_xx
	if ivcurve_pnts:
	out['v'] = ivcurve_v
	out['i'] = ivcurve_i
	if isinstance(photocurrent, pd.Series) and not ivcurve_pnts:
	out = pd.DataFrame(out, index=photocurrent.index)
	return out

specifically:

• escape exp to change it from a variable to be a function -> \exp
• use implicit multiplication instead of asterisks
• use \frac{}{} instead of a slash for division
• use underscores for subscripts in IL, Rs, Rsh, Ns, Vth etc
• either use ``code`` or use :math: to render variables and expressions consistently

[CameronTStark]

Thanks @kanderso-nrel!