Support diffuse component-specific IAM in `Array.get_iam()`

[cbcrespo]

This issue is intended to discuss the API for adding diffuse component-specific IAM calculations to the Array class.

This is part of my GSoC 2026 project, more specifically, part of the second phase of the project, with the goal of adding support for diffuse components and component-wise IAM in ModelChain. The plan is described in more detail in #2811.

Once diffuse irradiance components are available from Array.get_irradiance(), Array.get_iam() must also be updated to support diffuse component-specific IAM (isotropic sky, horizon, and ground). Currently, only direct IAM is returned.

There are a few ways this can be done:

• Split the existing get_iam into get_iam_direct (preserving the current behavior) and get_iam_diffuse (returning diffuse component-specific IAM)
• Keep a single get_iam method that can optionally return both direct and diffuse IAM
• Keep a single get_iam method that computes either direct or diffuse IAM depending on the requested arguments

Personally, I am partial to the first option since the functionality of each becomes clearer to the user, but I believe there should be a consensus on this. It's worth mentioning that renaming get_iam() is a breaking change and would need a deprecation period.

Another API question is how diffuse IAM values should be returned. Should they be returned as a dict or DataFrame, keeping in line with the treatment of diffuse components in pvlib.irradiance?

[markcampanelli]

Note: Just to keep The Tracking of Things™ fun, perez returns the diffuse circumsolar component, which is adjusted using the direct IAM :).