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

This issue is a retrospective of completed GSoC work, and it does not identify a remaining code change, file, or test to work on. Read the project summary and linked issues for context; there is no defined completion criterion here, so choose an active issue that describes unfinished work instead.

This issue summarizes my Google Summer of Code 2026 project: its goals, what was accomplished, what remains to be done, and what I learned along the way. This project was carried out under the supervision of @AdamRJensen and @ramaroesilva.

Throughout this process, I posted some reflections and updates in my blog. The official project description can be read on the GSoC website.

Project summary

This project was first introduced in #2750.

Phase 1: Sky diffuse irradiance transposition models and components

Diffuse transposition models calculate diffuse irradiance in the plane of array. This can be total sky diffuse irradiance, or it can be split into different components (sky isotropic, circumsolar, and horizon), which is useful for taking into account the direction from which the irradiance is coming.

In the past, some functions - perez, perez_driesse, and haydavies - supported returning individual components if the user set return_components=True, while the others returned only total diffuse irradiance.

This functionality was therefore extended to all existing transposition models except for klucher, which inherently does not support separation into individual components. After some debate, it was decided that it would be better to keep this as an exception than to force an interpretation of the model that was not intended by its original author.

For the remaining models, it was decided that each should return only the components included by the model. Previously, haydavies included an empty poa_horizon component (all zeros, since it is not supported by the model itself). This component was removed. return_components was also added to isotropic, which supports only the poa_isotropic component, and to reindl, which supports all three: poa_isotropic, poa_circumsolar, and poa_horizon.

king, on the other hand, was set for deprecation, as decided by the community.

This functionality was then expanded to the wrapper functions within pvlib.irradiance: get_sky_diffuse, poa_components, and get_total_irradiance. All three now also include a boolean parameter which, when set to True, ensures that the output includes sky diffuse components. This means that users can access the diffuse components without having to use the individual transposition models directly.

Issues and PRs for this phase:

Main steps:

• #2775
• #2787
• #2788
• #2794
• #2800

Smaller details:

• #2776
• #2783
• #2789
• #2801
• #2827

Phase 2: Extending ModelChain for component-specific IAM

The ModelChain is a high-level class providing a streamlined way for users to model PV systems from weather data down to AC power without having to explicitly model each step of the process.

Previously, the effective irradiance (after transposition and optical as well as spectral losses) was modeled as:

spect_mod * (total_irrad['poa_direct'] * aoi_mod + fd * total_irrad['poa_diffuse'])

While optical losses were well represented for direct irradiance (through aoi_mod, the angle of incidence modifier), the same did not happen for diffuse irradiance. fd , which stands for diffuse fraction, was essentially always 1, meaning that no optical losses were applied to diffuse irradiance.

IAM (incidence angle modifier) functions describe the dependence of optical losses on angle of incidence. This is why the work from Phase 1 was important: by separating diffuse irradiance into components, each component can be treated differently according to the direction from which it reaches the array. In addition to having access to the different diffuse irradiance components, it is necessary to have access to the IAM for each component.

Therefore, before tackling this within ModelChain directly, it was necessary to address it within the Array and PVSystem classes, on which ModelChain depends. These classes had no previous support for accessing the IAM of different diffuse components.

After this functionality was added, it could then be integrated into ModelChain. In simplified form, the effective irradiance calculation now becomes:

spect_mod * (
    (poa_direct + poa_circumsolar) * aoi_mod
    + poa_isotropic * iam_isotropic
    + poa_horizon * iam_horizon
    + poa_ground_diffuse * iam_ground_diffuse
)

Side quests

During this phase, I also found myself involved in two related tasks: integrating iam.schlick into ModelChain, and creating a new version of the marion_diffuse IAM function optimized for trackers.

iam.schlick in ModelChain

iam.schlick is a direct IAM function, and previously the only one in pvlib which could not be used within ModelChain. Now, it too has been integrated into this class.

marion_diffuse optimized for trackers

marion_diffuse computes diffuse IAM values by integrating over a solid angle for a given surface tilt. This works well for fixed-tilt systems, but becomes computationally expensive for trackers, where the surface tilt is a timeseries of values rather than a single value.

The existing implementation effectively performs a new integration for every tilt angle, including repeated tilt angles. For long simulations, this can become both memory- and time-intensive.

To address this, I implemented a new function, marion_diffuse_tracking, specifically designed with tracker systems in mind. Instead of integrating for every individual tilt angle, it:

• precomputes the diffuse IAM values over a range of tilt angles,
• performs the numerical integration only once for each sampled angle, and
• interpolates those results to obtain IAM values for the actual tracker tilt time series.

The performance improvements are substantial. For one example using an 8760-point time series, the new implementation led to a 96% reduction in peak memory and 98% reduction in execution time.

Some implementation details of this are still under discussion.

Issues and PRs for this phase:

Main steps:

• #2811
• #2812
• #2845
• #2846
• #2847

Smaller details:

• #2837
• #2842

Side quests:

• #2824
  • Previous discussion of this in #1402
• #2828
• #2832

Lessons learned

All in all, the most challenging part of this process has not been the coding itself, but everything else around it: testing, GitHub issues and PRs, GitHub checks, ensuring everything remains consistent across different parts of pvlib, handling breaking changes and deprecations, and most of all, managing inter-dependent PRs on a short timeline :)

While I was not new to coding, I was new to most of these things. It has been a very positive experience, and I now feel more comfortable with the idea of contributing not only to this community but also other open-source projects I may be interested in.

I absolutely intend to stick around here, help ensure that every loose thread left by my GSoC project is dealt with, and find some other ways to contribute every now and then - and hopefully continue learning!

Finally, a big thank you to my mentors, as well as to everyone who contributed to my project by reviewing my PRs or participating in discussions :)