> ## 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.

# Row-to-Row Beam Shading - DC Field Level

export const PolygonClipping = () => <Tooltip tip="Computing the intersection area of overlapping 2D shapes; used in shading calculations.">
    polygon clipping
  </Tooltip>;

export const AlongAxisSlope = () => <Tooltip tip="Terrain slope component parallel to row orientation; affects bay-to-bay shading within rows.">
    along-axis slope
  </Tooltip>;

export const CrossAxisSlope = () => <Tooltip tip="Terrain slope component perpendicular to row orientation; affects row-to-row shading.">
    cross-axis slope
  </Tooltip>;

export const Backtracking = () => <Tooltip tip="Tracker control strategy that rotates modules away from optimal sun-tracking to prevent inter-row shading.">
    backtracking
  </Tooltip>;

export const AngleOfIncidence = () => <Tooltip tip="Angle between the sun's rays and the perpendicular to a surface; 0° when sun is directly facing the surface.">
    angle of incidence
  </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 Bays = () => <Tooltip tip="Sections of a tracker where modules share the same tilt and rotation angle, receiving uniform irradiance.">
    bays
  </Tooltip>;

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

## Summary

This model calculates row-to-row <BeamIrradiance /> shading using geometric algorithms for arrays on uniform terrain. PlantPredict implements two variants: a simple trigonometric model for flat terrain, and a slope-aware vector-based model that handles uniform slopes and accounts for bay-to-bay shading within rows. Both methods provide fast calculations suitable for regular array layouts.

## Inputs

| Name                     | Symbol         | Units   | Description                                                           |
| ------------------------ | -------------- | ------- | --------------------------------------------------------------------- |
| **Collector Width**      | $\ell_m$       | m       | Tracker bay width perpendicular to rotation axis                      |
| **Row-to-Row Pitch**     | $p$            | m       | Horizontal distance between tracker rotation axes                     |
| **Row Length**           | $L$            | m       | Length of array row parallel to axis                                  |
| **Number of Rows**       | $N_{rows}$     | —       | Total rows in array block                                             |
| **Bay Length**           | $L_b$          | m       | Length of individual bay within row                                   |
| **Bay Spacing**          | $s_b$          | m       | Gap between adjacent bays along row                                   |
| **Bays Per Row**         | $N_b$          | —       | Number of bays in each row                                            |
| **Row Tilt Angle**       | $\beta_m$      | degrees | Tilt angle of module from horizontal                                  |
| **Row 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                            |
| **Ground Slope**         | $\beta_g$      | degrees | Terrain slope angle                                                   |
| **Ground Slope Azimuth** | $\gamma_g$     | degrees | Downhill direction of slope, measured clockwise from North            |
| **Angle of Incidence**   | $\theta_{AOI}$ | degrees | Angle between sun vector and module surface normal                    |

***

## Outputs

| Name                    | Symbol      | Units | Description                                        |
| ----------------------- | ----------- | ----- | -------------------------------------------------- |
| **Beam Shading Factor** | $U_{shd,B}$ | —     | Fraction of beam irradiance reaching modules (0-1) |

***

## Detailed Description

### Algorithm Selection

**Version 11+:**

* **Tracker systems**: Always uses slope-aware model (even on flat terrain)
* **Fixed tilt**: Row-to-row trigonometric model if flat terrain (both slopes = 0) and "Infinite Length Rows" algorithm selected; slope-aware otherwise

**Version 8-10:**

* Row-to-row trigonometric model if: flat terrain (both slopes = 0) and "Infinite Length Rows" algorithm selected
* Slope-aware otherwise (sloped terrain or "Infinite Length Rows" not selected)

**Version 7 and earlier:**

* Row-to-row trigonometric model if flat terrain (both slopes = 0)
* Slope-aware if sloped terrain (<CrossAxisSlope /> or <AlongAxisSlope /> ≠ 0)

### Row-to-Row Trigonometric Model

The algorithm calculates the relative height and length of shadows cast by the directly adjacent row to determine the shaded fraction on interior rows, then adjusts for edge effects in finite arrays. This model operates at the row level, treating each row as continuous (omitting spacing between <Bays />), and only considers shadows from the row immediately in front. It does not account for diagonal, second-row, or along-axis bay-to-bay shading.

#### Shaded Fractions

**Shaded height fraction** (relative height of shadow from adjacent row, 0-1):

$$
h_s = 1 - \frac{p}{\ell_m[\cos(\beta_m) + \sin(\beta_m) \cos(\gamma_s - \gamma_m) \tan(\theta_z)]}
$$

**Shaded length fraction** (relative length of shadow from adjacent row, 0-1):

$$
l_s = 1 - \frac{p\sin(\beta_m) |\sin(\gamma_s - \gamma_m)| \tan(\theta_z)}{L[\cos(\beta_m) + \sin(\beta_m) \cos(\gamma_s - \gamma_m) \tan(\theta_z)]}
$$

If $h_s$ or $l_s$ fall outside \[0,1], they are set to 0. For "Infinite Length Rows" mode, $l_s$ is set to 1.

#### Beam Shading Factor

$$
U_{shd,B} = 1 - h_s \times l_s \times \frac{N_{rows} - 1}{N_{rows}}
$$

The factor $(N_{rows} - 1) / N_{rows}$ accounts for the first row being unshaded. If the <AngleOfIncidence /> $\theta_{AOI}$ is $\geq 90°$ (sun behind modules), shading is not applied.

***

### Slope-Aware Linear Shading

This algorithm uses a vector-based approach with <PolygonClipping /> that projects shadows from multiple neighboring bays onto each receiver module. The terrain slope ($\beta_g$, $\gamma_g$) is decomposed into cross-axis (perpendicular to rows) and along-axis (parallel to rows) components to determine bay elevations and shadow geometry. Each row consists of $N_b$ bays of length $L_b$ separated by gaps of $s_b$. Special cases handle array edges where fewer neighbor candidates exist.

#### Step 1: Shading Candidates Identification

For each receiver bay, the algorithm considers shadows from up to 6 neighboring bays. The sun's azimuth position relative to the row orientation determines which side's diagonal bays to evaluate, while the along-axis slope determines the elevation differences that affect whether those bays can actually cast shadows:

1. **Adjacent bay along row** (same row, 1 position along-axis)
2. **Row directly in front** (1 row cross-axis, centered)
3. **Diagonal bay** (1 row cross-axis, 1 position along-axis)
4. **Diagonal bay** (2 rows cross-axis, 1 position along-axis)
5. **Diagonal bay** (1 row cross-axis, 2 positions along-axis)
6. **Diagonal bay** (1 row cross-axis, 3 positions along-axis)

#### Step 2: Shadow Projection via Polygon Clipping

For each shadow source:

1. Project the shading candidate bay's vertices along the sun's direction onto the receiver plane
2. Compute the intersection polygon between the projected shadow and receiver bay boundaries
3. Calculate the intersection polygon area

This 3D vector geometry accounts for module tilt, tracker rotation, and terrain slopes.

#### Step 3: Shadow Overlap Calculation

Multiple shadows can overlap on a single receiver. The total shaded area uses the [inclusion-exclusion principle](https://en.wikipedia.org/wiki/Inclusion%E2%80%93exclusion_principle) to avoid double-counting:

$$
A_{shade} = \sum_i A_i - \sum_{i<j} A_{ij} + \sum_{i<j<k} A_{ijk} - \sum_{i<j<k<l} A_{ijkl} + \ldots
$$

where $A_i$ is the area of shadow $i$, $A_{ij}$ is the overlapping area of shadows $i$ and $j$, etc.

#### Step 4: Beam Shading Factor

The unshaded fraction for each bay position is:

$$
U_{shd,B} = 1 - \frac{A_{shade}}{A_{module}}
$$

where $A_{module}$ is the total area of the receiver bay ($\ell_m \times L_b$).

**Edge effects:** The list of shadow candidates is reduced for bays at the edges of the array:

* Front row bays: Only along-axis shade from adjacent bays within the same row (no shading from rows in front)
* Second row bays: No second-row diagonal shading candidates
* End bays (1st, 2nd, 3rd from edges): Progressively fewer along-axis and diagonal shading candidates

The array-averaged shading factor is a weighted sum over all bay positions, accounting for the specific shading candidates available to each position in the array.