Diffuse components with Klucher

[cbcrespo]

Is your feature request related to a problem? Please describe.
As part of my GSoC 2026 project, I am adding support for return_components to all diffuse transposition models in pvlib, which currently is supported by some models (e.g. perez) but not others (e.g. klucher). While some models provide separable components, klucher does not, because its component terms are multiplicatively coupled.

Describe the solution you'd like
Separating the transposed diffuse irradiance into sky diffuse, circumsolar and horizon brightening components under a proportional allocation assumption (detailed below) which, of course, should be clearly documented.

Describe alternatives you've considered
Not supporting diffuse components for this model, and having return_components=True return a dictionary (in order to keep consistency with other models) returning a single value, the total diffuse irradiance.

Additional context
The following is the expression for total diffuse irradiance via klucher:
$I_d = \mathrm{DHI} \frac{1 + \cos\beta}{2} \left(1 + F' \sin^3\left(\frac{\beta}{2}\right)\right)\left(1 + F' \cos^2\theta \sin^3\theta_z\right)$

If we consider (as identified by Loutzenhiser et al.):

• Isotropic: $I = \frac{1 + \cos\beta}{2}$
• Horizon brightening: $h = F' \sin^3\left(\frac{\beta}{2}\right)$
• Circumsolar: $c = F' \cos^2\theta \sin^3\theta_z$

Then we can simplify the full expression into:
$I (1+h) (1+c) = I (1+c+h+hc)$

That $hc$ term is problematic if we want to separate components. @adriesse proposed a solution here which was to distribute this $hc$ term between $h$ and $c$ proportionally. We would get:
$c' = c + \frac{c}{h+c} hc$
$h' = h + \frac{h}{h+c} hc$

And the full expression then becomes:
$I_d = I(1 + c' + h')$

Thus enabling the separation of components.

I would like feedback on whether this decomposition is acceptable for inclusion in pvlib, or whether klucher should instead not expose component breakdowns at all (i.e., return_components is still used to maintain consistency with other models, but returns a dict with only total irradiance for this model).

[cwhanse]

I'm moderately opposed to altering the klucher function to return circumsolar and horizon components not described in the reference:
#2527 (comment)

If we want a version of klucher that returns these components, the proportional approach seems as good as any. But that's essentially a new diffuse component model and should have its own reference and name.

[adriesse]

I think if we're on a path to allowing a variable number of components there is less motivation to do this split in the code. It could be described in the Notes section or demonstrated in an example, or indeed it could be considered as a new model.