GSoC 2026: Standardizing Diffuse Irradiance Components and Extending ModelChain Optical Loss Modeling

[cbcrespo]

This issue tracks my work for Google Summer of Code 2026 on improving diffuse irradiance handling and optical loss modeling in pvlib. This project will be carried out under the supervision of @AdamRJensen and @ramaroesilva, and has two main goals:

1. Standardizing the outputs of diffuse transposition models
2. Extending ModelChain to support component-specific optical loss calculations, via component-specific incident angle modifiers (IAM)

Motivation

Currently, diffuse transposition models in pvlib.irradiance provide inconsistent outputs. Some models (e.g., Perez) can return individual components (circumsolar, isotropic, horizon), while others only return total diffuse irradiance. This was previously identified and discussed in issue #1553.

This inconsistency limits the ModelChain workflow, which:

• Applies a single angle of incidence (AOI) model
• Uses one IAM value for total irradiance
• Cannot distinguish between irradiance components. Since optical losses depend strongly on incidence angle, this reduces physical accuracy.

Proposed Changes

Phase 1: Standardize diffuse component outputs

• Introduce a consistent return_components parameter across all diffuse transposition models. PR Adapts irradiance.isotropic to return_components framework. #2527 has begun addressing this by modifying irradiance.isotropic to support this parameter, as previously implemented in irradiance.perez.
• Ensure all models return:
  • Circumsolar
  • Isotropic
  • Horizon
  • Total diffuse irradiance
• For models that lack explicit components, return zeros for missing components
• Follow the structure used in pvlib.irradiance.perez

Phase 2: Extend ModelChain for component-specific IAM

• Consider plane-of-array (POA) components instead of global irradiance
• Add use of component-specific IAM when calculating effective $G_{POA}$
• Allow users to pass a dictionary to aoi_model, specifying IAM model for each component
• Maintain full backward compatibility

My name is Carolina Crespo, I am a PhD student at the University of Lisbon working on firm power in Iberia using PyPSA-Eur. I am a regular user of pvlib, which I teach (although at a superficial level) to 1st-year Bachelors students.

Any feedback on this plan will be very welcome, especially since this is my first time contributing to an open source project. Looking forward to getting started!

[markcampanelli]

Thanks for taking this on @cbcrespo.

I posted this fixed-tilt-focused code on the Google groups page a while back. I am interested in a clean and performant way of extending the IAM corrections for diffuse POA components to trackers.

https://groups.google.com/g/pvlib-python/c/Jue2gKzaXnU/m/ndtf6HQABAAJ

[cwhanse]

For models that lack explicit components, return zeros for missing components

We'll need to agree on rules for assigning the missing diffuse irradiance components to the components that are returned. E.g., if a model does not separately quantify circumsolar diffuse, we include that portion of diffuse irradiance with direct normal irradiance.

[adriesse]

Welcome @cbcrespo !!

Another option I would raise for consideration is to do this in a way that does not hard-code these three specific categories of diffuse irradiance. So one or two could simply be missing (rather than set to zero), or a new and different one could be added or substituted by a new transposition model.

At least, evaluate the consequences of the chosen code design if a new model comes along with more diffuse categories.