I will start by tackling phase 1 of the project: standardizing the outputs of diffuse transposition models.

Currently, only some models, such as perez, support a return_components parameter. When set to True, the function returns an OrderedDict or DataFrame containing the different diffuse irradiance components: isotropic, circumsolar and horizon, along with the total diffuse irradiance. This is also true for perez_driesse and haydavies, although the horizon component for haydavies is always zero.

The remaining transposition models currently return only the total diffuse irradiance:

• isotropic
• klucher
• reindl
• king

The original idea was to fully standardize the outputs by having all functions support return_components and return the same four values as perez, perez_driesse, and haydavies. However, one thing to have in mind is that some transposition models do not inherently cover the three diffuse components (e.g., isotropic and haydavies). Our initial thought was to return zeros for missing components (as currently implemented for haydavies), but feedback from the pvlib GitHub community suggested avoiding this approach: since other transposition models that have yet to be implemented in pvlib-python may include different or additional diffuse components, it makes more sense to keep the interface flexible.

The approach we settled on is therefore:

• All transposition models will support return_components
• Each model will return whichever diffuse components it can physically represent

In practice, this means:

• Investigating which components can reasonably be extracted from klucher and reindl
• Updating these functions to expose those components
• Removing the empty horizon component from haydavies
• Having isotropic return an OrderedDict or DataFrame containing a single diffuse component

That last point may feel a bit silly, but it is probably the cleanest path toward a more consistent interface 🤓

As for king, previous discussions suggest that deprecating the model may be the best option. Its documentation is misleading, it mixes sky diffuse and ground-reflected irradiance, and it does not appear to be widely used. Adding a deprecation warning may therefore become part of this project.

Once these changes are in place, the next step will be updating the functions below so that they make use of the diffuse components:

• irradiance.get_sky_diffuse
• irradiance.poa_components
• irradiance.get_total_irradiance

Currently, since not all transposition models return diffuse components, the functions above only consider the total diffuse.

More updates soon!

I’m excited to share that I’ll be participating in Google Summer of Code 2026 with pvlib-python, working on a project focused on improving diffuse irradiance handling and optical loss modeling within the library.

My mentors will be Adam R. Jensen and Rodrigo Amaro e Silva.

Project Summary

The project centers around two closely related improvements in pvlib:

• Standardizing the outputs of diffuse transposition models
• Extending ModelChain to support more physically consistent optical loss calculations

At the moment, diffuse irradiance models in pvlib.irradiance return outputs with different levels of detail. Some models can provide individual diffuse components — such as circumsolar, isotropic, and horizon diffuse irradiance — while others only provide total diffuse irradiance. One of the goals of this project is to make these outputs more consistent across models through a shared framework.

Once all models are able to return diffuse components, component-specific optical losses can be determined, and in particular, can be implemented within the ModelChain framework. Therefore, I will also be working on improvements to ModelChain so that users can choose irradiance component-specific IAM (Incident Angle Modifier) models. This should make optical loss modeling more flexible and physically realistic, while keeping the current behavior fully backward compatible.

Motivation

Diffuse irradiance is often treated as a single quantity, but in reality it comes from different regions of the sky with different angular distributions. This makes it so that the incidence angle is also varied, and as a result, the optical losses due to reflection at the PV module surface.

By exposing and handling these components more consistently, pvlib users will be able to:

• Access richer irradiance information from transposition models
• Use more advanced optical loss workflows
• Apply all existing IAM models more naturally within the ModelChain

Looking Forward

I’m excited to contribute to pvlib-python and work with the community over the summer. I’ve used pvlib in both teaching and research, so it’s very rewarding to now contribute back to the project.

I will be posting bi-weekly updates throughout the summer to share progress, implementation details, and lessons learned.

Feel free to look at my full work plan and join the discussion over on GitHub.

Looking forward to collaborating with everyone!