> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plantpredict.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ground-Reflected Shading

export const IAM = () => <Tooltip tip="Incidence Angle Modifier: correction factor for optical losses at non-perpendicular light angles.">
    IAM
  </Tooltip>;

export const POA = () => <Tooltip tip="Plane-of-Array: solar irradiance on the tilted module surface (beam + diffuse + reflected).">
    POA
  </Tooltip>;

export const GHI = () => <Tooltip tip="Global Horizontal Irradiance: total solar radiation on a horizontal surface (direct + diffuse).">
    GHI
  </Tooltip>;

export const DNI = () => <Tooltip tip="Direct Normal Irradiance: solar radiation received perpendicular to the sun's rays (direct beam only).">
    DNI
  </Tooltip>;

export const DHI = () => <Tooltip tip="Diffuse Horizontal Irradiance: solar radiation from the sky dome (excluding direct beam) on a horizontal surface.">
    DHI
  </Tooltip>;

export const DiffuseIrradiance = () => <Tooltip tip="Solar radiation scattered by the atmosphere, arriving from all sky directions rather than directly from the sun.">
    diffuse irradiance
  </Tooltip>;

export const BeamIrradiance = () => <Tooltip tip="Direct component of solar radiation traveling in a straight line from the sun.">
    beam irradiance
  </Tooltip>;

export const Azimuth = () => <Tooltip tip="Horizontal angle measured clockwise from north; applies to sun direction or surface orientation.">
    azimuth
  </Tooltip>;

export const ZenithAngle = () => <Tooltip tip="Angle between the local vertical and the sun (0° = overhead, 90° = horizon).">
    zenith angle
  </Tooltip>;

export const Albedo = () => <Tooltip tip="Ground reflectance (0–1); fraction of incident light reflected by the surface.">
    albedo
  </Tooltip>;

export const ViewFactor = () => <Tooltip tip="Fraction of radiation leaving one surface that reaches another; determined by geometry.">
    view factor
  </Tooltip>;

## Summary

Ground-reflected shading accounts for the reduction in ground-reflected irradiance reaching a module due to neighboring array rows blocking portions of the ground plane. Unlike sky diffuse shading, this calculation includes <IAM /> effects, since ground reflection arrives at oblique angles.

This model uses a 2D representation of the PV array, analyzing geometry in the plane perpendicular to the row axis.

## Inputs

| Name                              | Symbol     | Units   | Description                                                           |
| --------------------------------- | ---------- | ------- | --------------------------------------------------------------------- |
| **Row-to-Row Pitch**              | $p$        | m       | Horizontal distance between tracker rotation axes                     |
| **Collector Width**               | $\ell_m$   | m       | Tracker bay width perpendicular to rotation axis                      |
| **Module Tilt Angle**             | $\beta_m$  | degrees | Tilt angle of module from horizontal                                  |
| **Module Azimuth Angle**          | $\gamma_m$ | degrees | Azimuth angle of module surface normal, measured clockwise from North |
| **Solar Zenith Angle**            | $\theta_z$ | degrees | Angle between sun and vertical                                        |
| **Solar Azimuth Angle**           | $\gamma_s$ | degrees | Sun azimuth, measured clockwise from North                            |
| **Albedo**                        | $\rho$     | —       | Ground reflectance (0–1)                                              |
| **Global Horizontal Irradiance**  | $GHI$      | W/m²    | Total irradiance on horizontal surface                                |
| **Direct Normal Irradiance**      | $DNI$      | W/m²    | Beam irradiance perpendicular to sun's rays                           |
| **Diffuse Horizontal Irradiance** | $DHI$      | W/m²    | Diffuse irradiance on horizontal surface                              |
| **IAM Parameter**                 | $b_0$      | —       | ASHRAE IAM coefficient                                                |

***

## Outputs

| Name                               | Symbol       | Units | Description                                                                          |
| ---------------------------------- | ------------ | ----- | ------------------------------------------------------------------------------------ |
| **Ground Diffuse Shading Factor**  | $U_{shd,Gd}$ | —     | Shading factor for ground-reflected irradiance from diffuse-illuminated ground (0-1) |
| **Ground Direct Shading Factor**   | $U_{shd,Gb}$ | —     | Shading factor for ground-reflected irradiance from sunlit ground (0-1)              |
| **Combined Ground Shading Factor** | $U_{shd,G}$  | —     | Combined shading factor for all ground-reflected irradiance (0-1)                    |

***

## Detailed Description

Ground-reflected irradiance reaching the front of the module depends on which portions of the ground between rows are visible from the module surface and whether those portions are sunlit or shaded.

The model separates this into two components:

* **Sunlit ground**: Receives direct <BeamIrradiance /> and <DiffuseIrradiance />
* **Shaded ground**: Receives only diffuse irradiance

The model uses numerical integration across the row spacing to calculate what fraction of each ground type is visible from the module.

### Step 1: Define Integration Geometry

The algorithm integrates over the ground strip between rows, from $x_1$ to $x_2$. Using a coordinate system centered at the module's rotation axis:

* **$x_1 = -p$**: Adjacent row's rotation axis (integration start)
* **$x_2 = -k / \tan(\beta_m)$**: Limit of module's downward field of view, where the assumed module center height is $k = \frac{\ell_m}{2} \sin(45°) + 1$ m (1 meter ground clearance, 45° max tilt)

Using $x_1 = -p$ is a simplification—the exact geometric view angle would extend beyond the adjacent row. This conservative approximation slightly underestimates ground-reflected irradiance.

### Step 2: Calculate Shadow Boundary

The shadow boundary $s$ marks where direct beam irradiance begins on the ground. Beyond $s$, the ground is sunlit; before $s$, the ground is shaded by the adjacent row.

**Project the sun into the cross-axis plane:**

The shadow calculation is performed in 2D, looking along the row axis (tracker or fixed-tilt). The sun's position in 3D (zenith $\theta_z$, azimuth $\gamma_s$) must be projected onto this cross-axis plane.

The angle between the sun's <Azimuth /> and the row axis is $(\gamma_s - \gamma_m)$. The effective solar <ZenithAngle /> in the cross-axis plane is:

$$
\tan(\theta_{z,eff}) = \tan(\theta_z) \cdot |\cos(\gamma_s - \gamma_m)|
$$

The shadow cast by a vertical object of height $h$ extends horizontally in the cross-axis direction by:

$$
L_{shadow} = h \cdot \tan(\theta_{z,eff}) = h \cdot \tan(\theta_z) \cdot |\cos(\gamma_s - \gamma_m)|
$$

**Locate the shadow-casting edge:**

The top edge of the adjacent front row casts the shadow boundary. This edge is located at:

* Horizontal position: $x_{adj,top} = -p + \frac{\ell_m}{2} \cos(\beta_m)$
* Height above ground: $h_{top} = k + \frac{\ell_m}{2} \sin(\beta_m)$

**Shadow boundary position:**

The shadow boundary is located at the shadow-casting edge plus the projected shadow length:

$$
s = x_{adj,top} + L_{shadow} = \left( -p + \frac{\ell_m}{2} \cos(\beta_m) \right) + \left( k + \frac{\ell_m}{2} \sin(\beta_m) \right) \tan(\theta_z) |\cos(\gamma_s - \gamma_m)|
$$

Rearranging:

$$
s = \left( k + \frac{\ell_m}{2} \sin(\beta_m) \right) \tan(\theta_z) |\cos(\gamma_s - \gamma_m)| - p + \frac{\ell_m}{2} \cos(\beta_m)
$$

The shadow boundary is clamped to the integration limits: if $s < x_1$, all visible ground is sunlit; if $s > x_2$, all visible ground is shaded.

### Step 3: Calculate Sky View Factor

The sky view factor at ground position $x$ is the angular extent of sky visible from that point, bounded by the current row (above) and the adjacent row (in front):

$$
f_{sky}(x) = \sigma_{adj,top}(x) - \sigma_{top}(x)
$$

The angle to the top edge of the current row is:

$$
\sigma_{top}(x) = \text{atan}\left( \frac{h_{top}}{x_{top} - x} \right)
$$

The angle to the top edge of the adjacent row is:

$$
\sigma_{adj,top}(x) = \text{atan}\left( \frac{h_{top}}{x_{adj,top} - x} \right)
$$

where $x_{top} = \frac{\ell_m}{2} \cos(\beta_m)$ is the horizontal position of the current row's top edge and $x_{adj,top} = -p + \frac{\ell_m}{2} \cos(\beta_m) = x_{top} - p$ is the horizontal position of the adjacent row's top edge.

### Step 4: Calculate IAM Factor

The incidence angle for light traveling from ground position $x$ to the module center, measured from the module surface normal, is:

$$
\theta_{inc}(x) = \frac{\pi}{2} + \text{atan}\left( \frac{k}{|x|} \right) - \beta_m
$$

The ASHRAE IAM factor is then:

$$
f_{IAM}(x) = 1 - b_0 \left( \frac{1}{\cos(\theta_{inc})} - 1 \right)
$$

with $f_{IAM} = 0$ when $\theta_{inc} > 87°$.

### Step 5: Integrate Shading Factors

The algorithm divides the ground between rows into 100 segments and integrates to calculate:

**Ground diffuse shading factor** — Accounts for sky view factor and IAM effects on diffuse-illuminated ground, integrated over the entire ground strip:

$$
U_{shd,Gd} = \frac{1}{|x_2 - x_1|} \int_{x_1}^{x_2} f_{sky}(x) \cdot f_{IAM}(x) \, dx
$$

**Ground direct shading factor** — Accounts for IAM effects on sunlit ground, integrated from the shadow boundary $s$ to the field-of-view limit:

$$
U_{shd,Gb} = \frac{1}{|x_2 - x_1|} \int_{s}^{x_2} f_{IAM}(x) \, dx
$$

Diffuse irradiance originates from the entire sky hemisphere (extended source), so $f_{sky}(x)$ is needed to determine what portion of the sky each ground position can see. Direct beam irradiance comes from a single direction (point source), so we only need to determine if ground is sunlit (starting integration at $s$) and apply the IAM correction.

### Step 6: Combine Ground Shading Factors

The two ground shading factors are applied separately to the diffuse (<DHI />) and direct (<DNI />) components of horizontal irradiance before transposition:

$$
G_{H,eff} = U_{shd,Gd} \cdot \text{DHI} + U_{shd,Gb} \cdot \text{DNI} \cdot \cos(\theta_z)
$$

This effective horizontal irradiance is then transposed to the tilted plane using the standard ground-reflected formula with <Albedo /> $\rho$:

$$
G_{gnd,POA} = \rho \cdot G_{H,eff} \cdot \frac{1 - \cos(\beta_m)}{2}
$$

A **combined ground shading factor** $U_{shd,G}$ is back-calculated for reporting:

$$
U_{shd,G} = \frac{G_{gnd,POA}}{G_{gnd,POA,unshaded}}
$$

where $G_{gnd,POA,unshaded} = \rho \cdot \text{GHI} \cdot \frac{1 - \cos(\beta_m)}{2}$ is the ground-reflected irradiance without shading effects. Here <GHI /> is the total horizontal irradiance and <POA /> refers to plane-of-array irradiance on the tilted module surface.

Substituting the definitions of $G_{gnd,POA}$ and $G_{H,eff}$:

$$
U_{shd,G} = \frac{U_{shd,Gd} \cdot \text{DHI} + U_{shd,Gb} \cdot \text{DNI} \cdot \cos(\theta_z)}{\text{GHI}}
$$

This combined factor is what users see in output reports and represents the net effect of both shaded and sunlit ground contributions.