Add support for return_components to Reindl

[cbcrespo]

• 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.

This PR is part of my GSoC 2026 project. One of the goals is to add support for return_components to all diffuse transposition models in pvlib, which currently is supported by some models (e.g. perez) but not others. This parameter allows the user to choose whether they want only the total diffuse irradiance, or are interested in the split between different diffuse components (sky diffuse, circumsolar, horizon brightening).

This first PR starts by implementing return_components in reindl.

Reindl expands the Hay and Davies model, which considers only the isotropic and circumsolar components, and is defined as:

with A Rb being the circumsolar component and the rest being the isotropic component.

Reindl expands this by adding a horizon brightening component, but this new component is not additive but rather multiplied by the existing isotropic component:

In my implementation, I essentially considered that the isotropic term was:

while the horizon brightening term was:

I updated the function docstrings accordingly. I haven't yet added a test. I saw that e.g. haydavies has two separate tests, for return_components=False and return_components=True. However, from what I gathered, the test values came from the matlab implementation of pvlib, and therefore it seems kind of silly to create a test using values derived from the python implementation to test the python implementation. Curious as to what are the community's thoughts on this.

[github-actions]

Hey @cbcrespo! 🎉

Thanks for opening your first pull request! We appreciate your
contribution. Please ensure you have reviewed and understood the
contributing guidelines.

If AI is used for any portion of this PR, you must vet the content
for technical accuracy.

[kandersolar]

Nice PR @cbcrespo! I think your interpretation of the horizon component is reasonable, although since it is not stated in the reference, I think we need to document it ourselves. A sentence in the Notes section of the docstring would be appropriate, I think.

I haven't yet added a test. I saw that e.g. haydavies has two separate tests, for return_components=False and return_components=True. However, from what I gathered, the test values came from the matlab implementation of pvlib, and therefore it seems kind of silly to create a test using values derived from the python implementation to test the python implementation. Curious as to what are the community's thoughts on this.

Yes, ideally the test values would come from an independent implementation. If you wanted, you could reimplement the model in Excel (or whatever you like) and calculate test values that way. In this case, I personally would just use the python implementation to compute the test values, for two reasons:

1. the math is not very complicated, so we can be fairly confident that there is no bug in the code
2. the test's intent is only partially to check that the correct numeric values are returned; equally important is that the test verifies that return_components=True produces a dict with the correct structure.

Also, a few comments below regarding whether the returned object should be OrderedDict or dict.

[kandersolar]

I know this would be consistent with existing functions, but at some point we will switch those to normal dictionaries (see #1684). I suggest getting ahead of that change here and using a normal dictionary.

[kandersolar]

If switching the return from OrderedDict to dict, change here as well

[kandersolar]

And here

[ramaroesilva]

I think your interpretation of the horizon component is reasonable, although since it is not stated in the reference, I think we need to document it ourselves. A sentence in the Notes section of the docstring would be appropriate, I think.

@kandersolar just for clarification, this interpretation can be seen as factual rather than reasonable since, while it is not explicit in the paper, it is remaining term after subtracting the hay-davies models which predeces it (and to which reindl only adds an horizon term).

@cbcrespo explanation of the interpretation is a bit convoluted because in the beginning we we're trying too much to make a physical interpretation of the term and we wanted to open up a bite the discussion. but then, when talking to Adam, we noticed that indeed this is simply the extra term when we multiply the multiplicative terms.

Anyway, something can be added to the Notes if that is deemed relevant, but it should be really short imo.