Expanding the vectorization capability of pvsystem.i_from_v and v_from_i.

[reepoi]

A single call to pvsystem.singlediode using its ivcurves_pnts parameter can calculate multiple current-voltage pairs for a set of IV curves (see this example). If the ivcurve_pnts parameter is removed (see this comment), pvsystem.i_from_v and pvsystem.v_from_i can be used to calculate these pairs instead. However, unlike singlediode, these functions do not support calculating multiple current-voltage pairs for more than one IV curve with a single function call. The linked example would need to call i_from_v once per IV curve. Here I propose a design for i_from_v and v_from_i that allows calculating multiple currents/voltages for more than one IV curve with a single function call. I only discuss i_from_v, but the ideas also apply to v_from_i.

Four cases determine what i_from_v should return. These cases depend on the number of IV curves passed and the number of voltages given for each IV curve. The number of IV curves is determined by the maximum length of photocurrent, saturation_current, resistance_series, resistance_shunt, and nNsVth (the SDE parameters) when viewed as 1d arrays. Let $C$ be the number of IV curves and $(P_k)_{k = 1}^C$ where $P_k$ is the number of voltages for the $k$-th IV curve. These are the four cases depending on $C$ and $(P_k)_{k = 1}^C$:

1. $C = 1$ and $P_1 = 1$: i_from_v should return one current value. This case is like passing all SDE parameters and voltage as scalars, 0d arrays, or 1d arrays of size one.
2. $C = 1$ and $P_1 \geq 1$: i_from_v should return $P_1$ current values. This case is like passing all SDE parameters as scalars, 0d arrays, or 1d arrays of size one, and voltage as a 1d array.
3. $C \geq 1$ and $\forall i, P_i = 1$: i_from_v should return $C$ current values. This case is like passing all SDE parameters as 1d arrays and voltage as a scalar, 0d array, or 1d array of size 1 or $C$.
4. $C \geq 1$ and $\forall i, P_i \geq 1$: i_from_v should return $\sum_i P_i$ current values. This case is like passing all SDE parameters as 1d arrays and voltage as a 2d array.

i_from_v supports the first three cases but not the fourth one. To support case four, i_from_v will allow voltage to be passed as a 2d array. A limitation of 2d arrays is that they require $\forall k, l, P_k = P_l$, so when the 2d array for voltage is created, the voltage lists for each IV curve must be padded to the same length.

When passing a 2d array for voltage, we need to choose whether a column or a row represents the list of voltages for an IV curve. Since case three and case four are equivalent when $\forall i, P_i = 1$, this decision comes down to whether a 1d array of shape (C,) is a row vector or a column vector. To illustrate this, consider using i_from_v to find i_mp given v_mp where $C > 1$ and each IV curve has a different voltage at maximum power.

1. Use columns for voltage lists: This implies (C,) is a row vector (equivalent to (1, C)); that is, for $C = 3$, passing v_mp as np.array([a, b, c]) or as np.array([[a, b, c]]) will compute i_mp = np.array([d, e, f]) or i_mp = np.array([[d, e, f]]), respectively. On the other hand, passing v_mp as np.array([[a], [b], [c]]) (shape: (C, 1)) tells i_from_v to find the currents corresponding to a, b, c for only one curve. In that case, we can allow broadcasting so that i_from_v finds the currents corresponding to a, b, c for all three curves and returns a shape (3, 3) array.
2. Use rows for voltage lists: This implies (C,) is a column vector (equivalent to (C, 1)); that is, for $C = 3$, passing v_mp as np.array([a, b, c]) or as np.array([[a], [b], [c]]) will compute i_mp = np.array([d, e, f]) or i_mp = np.array([[d], [e], [f]]), respectively. On the other hand, passing v_mp as np.array([[a, b, c]]) (shape: (1, C)) tells i_from_v to find the currents corresponding to a, b, c for only one curve. In that case, we can allow broadcasting so that i_from_v finds the currents corresponding to a, b, c for all three curves and returns a shape (3, 3) array.

I believe columns should represent the list of voltages for an IV curve; however, I have not yet found a strong reason for choosing columns over rows.

Next, it is important for the user experience that the result returned by i_from_v has the same dimension and Python type as voltage, when possible. Below is a table of examples containing the expected shapes to be returned by i_from_v given the shapes of its parameters. In these examples, the shape (1,) can represent scalars, 0d arrays, and 1d arrays of length one. All other shapes are at least 1d arrays.

Here are the test cases for i_from_v case four support:

• https://github.com/reepoi/pvlib-python/blob/cols-singlediode-return-values/pvlib/tests/test_pvsystem.py#L1217
• https://github.com/reepoi/pvlib-python/blob/cols-singlediode-return-values/pvlib/tests/test_pvsystem.py#L1275

Here is what the linked example looks like with case four support and ivcurve_pnts removed from singlediode:

• https://github.com/reepoi/pvlib-python/blob/cols-singlediode-return-values/docs/examples/iv-modeling/plot_singlediode.py#L99

In conclusion, i_from_v should allow voltage to be passed as a 2d array so that, with a single function call, multiple current values can be calculated for more than one IV curve. Let me know your thoughts on supporting case four and whether to choose columns or rows. My current implementation of case four support can be found here.

Example #	Max SDE parameter shape	voltage array shape	Returned current array shape	$C$	Notes
1	(1,)	(1,)	(1,)	1	Current returned with the same type as voltage: scalar, 0d array, or 1d array
2	(1, 1)	(1,)	(1,)	1	Current returned with the same type as voltage: scalar, 0d array, or 1d array
3	(1,)	(1, 1)	(1, 1)	1	Current returned with same shape as voltage
4	(1, 1)	(1, 1)	(1, 1)	1
5	(1, 1)	(5, 1)	(5, 1)	1
6	(5,)	(1,)	(5,)	5
7	(5,)	(1, 1)	(1, 5)	5	Current returned with same shape as voltage
8	(1, 5)	(1,)	(5,)	5	Current returned with same shape as voltage
9	(1, 5)	(1, 1)	(1, 5)	5
10	(5,)	(10, 1)	(10, 5)	5	Current for 5 IV curves at the same ten voltage values
11	(1, 5)	(10, 1)	(10, 5)	5	Current for 5 IV curves at the same ten voltage values
12	(1, 5)	(10, 5)	(10, 5)	5	Current for 5 IV curves at possibly different voltage values

[mikofski]

Thanks for your thorough suggestion. I’m curious what are the use cases for this change? What are the potential consequences in terms of execution speed and maintenance burden? And what alternatives have you considered?

[cwhanse]

@mikofski this is motivated by the suggestion to remove the ivcurve_pnts argument from pvsystem.singlediode. Without the kwarg, i_from_v becomes the way to calculate a curve. Do you disagree with the premise and we should keep ivcurve_pnts?

[mikofski]

I forgot about that discussion. Was it here or on the Google group? Might be useful to link to it here for context.

In principle if removing ivcurve_pnts then allowing *_from_*() to take vector input, if it doesn’t already, makes sense. How does ivcurve_pnts work now?

[kandersolar]

Previous discussion in #418, and more recently a suggestion to remove ivcurve_pnts: #1626 (comment)

[kandersolar]

My first thought is questioning the value of being so general that separate voltages can be passed for each set of SDE parameters (i.e., do we really need to allow 2D voltage input). I don't calculate I-V curves very often, but naively I'd have thought it more natural to use the same voltages for all curves. Users who need different voltages for different curves can always iterate and calculate one curve at a time. Maybe someone that more frequently uses these functions could comment?

[cwhanse]

The use for 2D voltage input is when comparing modeled curves with measurements. That could be done one at a time in a loop. The other use of 2D input is when computing a composite IV curve as a "sum" of series-connected curves. There, it is advantageous that the same currents be provided to v_from_i; if not the same currents, then adding the curves requires interpolation to a common set of currents.

I'm neutral on the need to pass 2D input - if it's possible and clean enough to maintain, there will be a performance advantage over any looping. But if it's python gymnastics, perhaps not worth the effort.

[reepoi]

I found pvlib actually supports case four already, and uses columns to represent a list of voltages for an IV curve. Case four functionality is used in singlediode.py. The PR #1743 also has examples of using case four in docs/examples/iv-modeling/plot_singlediode.py and tests/ivtools/test_sdm.py. Case four works when using methods 'lambertw', 'newton', and 'brentq', except when the SDE parameters are passed as pd.Series and method='brentq'. In this case singlediode.bishop88 fails at this line because pandas has different broadcasting rules than numpy. For nd-arrays a, b where a.shape = (C,) and b.shape = (N, C) for some N > 0, a / b results in an nd-array with shape (N, C). However, if a was a pd.Series, pandas would throw an error. This can be checked by changing 'lambertw' to 'brentq' on this line. singlediode._lambertw_i_from_v handles this issue by converting all pd.Series to np.ndarray here.