Inconsistent output types between diffuse IAM functions

[cbcrespo]

The diffuse IAM functions currently have inconsistent return types:

• marion_diffuse returns a dictionary containing values for the different diffuse components.
• martin_ruiz_diffuse and schlick_diffuse return two values corresponding to the sky and ground components.

It would be beneficial for these functions to have a consistent API, making them easier to use interchangeably throughout pvlib (and in users' own workflows). I propose that all three functions ultimately return dictionaries with named diffuse components, matching the behavior of marion_diffuse.

Since this would be a breaking change, it would require a deprecation period, and I'm not sure what the preferred deprecation strategy is for outputs.

In the shorter term, this inconsistency is blocking work for my GSoC project (see #2750 and #2812). As a temporary compatibility measure, one possible approach would be to add an optional keyword argument (defaulting to False) that enables the new dictionary return format. This would allow downstream code to adopt the new interface before the default behavior changes.

[ramaroesilva]

For further clarification, a clean, coherent output structure would be ideal to have a clean, clear handling of the "data flow" within ModelChain when computing IAM losses. Besides the "for the sake of coherent API".

[AdamRJensen]

I support changing the outputs to dictionaries. I don't see a way for having a deprecation period though, it think it'll just have to be a breaking change.

[cwhanse]

Can we do something like this:

if version<0.16:
    raise deprecation message
    return tuple
else:
    return dict

[AdamRJensen]

Can we do something like this:

if version<0.16:
    raise deprecation message
    return tuple
else:
    return dict

I don't see how that's possible. All versions <0.16 have already been shipped and cannot be edited, so this code would only appear in versions >=0.16 and thus not have any effect.

[cwhanse]

Good point.

If we aim it into the future if version < 0.17 does that unblock @cbcrespo 's work?