Add mismatch.py and function to combine curves

[ajonesr]

• I am familiar with the contributing guidelines
• Tests added
• Updates entries in docs/sphinx/source/reference for API changes.
• Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
• New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels (including remote-data) and Milestone are assigned to the Pull Request and linked Issue.

Adds a function combine_curves that combines curves (in series) and a function that prepares inputs for combine_curves. This is part of the work to move some of the functionality of PVMismatch over to pvlib.

[cwhanse]

Just need to add two tests that raise the ValueErrors.

[cwhanse]

@pvlib/pvlib-maintainer would appreciate your look at this, when you can.

[AdamRJensen]

Would it be possible to add a simple example to the documentation?

[ajonesr]

@AdamRJensen I've added an example in docs/examples/iv-modeling, though I'm not sure that's the right place to put it. Let me know if I should move it somewhere else

[AdamRJensen]

@AdamRJensen I've added an example in docs/examples/iv-modeling, though I'm not sure that's the right place to put it. Let me know if I should move it somewhere else

Thanks a lot @ajonesr !
Could you add a legend for the individual lines, e.g., just panel 1, panel 2, and panel 3. Also, if you could add just a tiny bit more text in the example about what is going on and why it is useful :)

You also need to move the whatsnew entry from v0.10.0 to v0.10.2.

[ajonesr]

@AdamRJensen I've added an example in docs/examples/iv-modeling, though I'm not sure that's the right place to put it. Let me know if I should move it somewhere else

Thanks a lot @ajonesr ! Could you add a legend for the individual lines, e.g., just panel 1, panel 2, and panel 3. Also, if you could add just a tiny bit more text in the example about what is going on and why it is useful :)

You also need to move the whatsnew entry from v0.10.0 to v0.10.2.

Sure thing! Just pushed those changes.

[kandersolar]

I can do a review (sorry for the wait!) but I'm a little hesitant about the current approach this PR takes. To me, this code feels more like an application than it does reusable functions. For example, combine_curves is pretty specific in its requirements, which makes it suitable for use with prepare_curves, but difficult to use if the curves come from anywhere else.

I wonder if these functions would make more sense as a gallery example page than functions in pvlib itself?

[cwhanse]

@kandersolar I'm interested to hear your thoughts on different ways to organize this capability.

I don't think a gallery example is enough here. We've heard several requests for capabilities native to pvlib to model mismatch. It is clear that pvmismatch, while useful, has some limits and is not going to be further developed. It seems reasonable to include functions in pvlib that one could use to get beyond the limits of pvmismatch.

Curves are added by aligning current and summing the corresponding voltage. The functions in this PR meet one use case: I have diode equation parameters for the series-connected modules/cells and I want the string-level IV curve.I can see a second use case: I have non-aligned IV curves (measured perhaps) and want the string-level curve. These functions don't meet the measured-curve use case.

I think separate function(s) that align the currents are useful, so that the function which adds curves is more reusable. We would want to align currents starting either from diode equation values (prepare_curves does this now) and from curve data itself (by interpolation, likely with extrapolation to negative voltages).

Maybe combine_curves should be add_curves. That would free the more general combine_curves name for the measured-curve use case, combine_curves(current_array, voltage_array). In that context, combine_curves would handle interpolation to align currents, then call add_curves.

[kandersolar]

I think my hesitation was centered around not being able to use the addition function with the existing methods for generating IV curves. It felt somewhat disconnected from the rest of pvlib. A function to align curves on one of the two dimensions would address that.

The tight coupling of prepare_curves to the SDE makes me wonder if it should live in pvlib.singlediode as a new bishop88_* function.

Series vs parallel connection is something else to consider when choosing names to leave room for future functionality.

[adriesse]

I don't think a gallery example is enough here.

It could be a start though...

[cwhanse]

Documenting an offline conversation about this PR. One concern is that the draft prepare_curves function contains a new model for reverse bias current that ought to live in singlediode. Another concern is that only one of two use cases are addressed:

"I have diode model parameters and want a series-combined IV curve."

The other use case is

"I have IV curves and want to combine them in series"

This second use case doesn't assume that the IV curves in hand are aligned to common currents, a job which prepare_curves is doing for modeled curves.

We propose the following next steps:

1. Move the reverse bias current calculation out of pvlib.singlediode.bishop88 to a helper function, tentatively named _reverse_bias_exp
2. Add a second reverse bias current model to pvlib.singlediode, tentatively named _reverse_bias_simple, which models the negative voltage portion of the IV curve with the single diode equation (without the diode breakdown current term from bishop88) and a vertical asymptote at the breakdown voltage.
3. Add a kwarg to the bishop88 functions to select either the exponential or simple model for reverse bias current. This kwarg would replace the overloading of breakdown_factor as a flag to turn on the reverse bias current term.
4. Rework the prepare_curves function to use these revised bishop88 functions. prepare_curves accepts diode model parameters and returns curves aligned to common currents.
5. Add a new function align_curves that accepts IV curves and returns those curves aligned to common currents. This function will use an interpolator, extrapolate to negative voltage and use the simple reverse bias current model, as necessary.