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

# Horizon Shading

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

export const Elevation = () => <Tooltip tip="Angular height of the sun above the horizon (0° at horizon, 90° overhead).">
    elevation
  </Tooltip>;

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

## Summary

Horizon shading accounts for <BeamIrradiance /> losses when the sun is blocked by distant terrain features, tree lines, buildings, or other obstructions far beyond the solar array field. Users define a horizon profile as a series of <Azimuth />-<Elevation /> pairs describing the apparent horizon line around the site. At each timestep, the algorithm compares the solar position to the interpolated horizon elevation at that azimuth and determines whether the sun is visible. When sunrise or sunset occurs within a timestep, the shading factor is prorated based on the duration of terrain blockage. Diffuse horizon shading (sky-view reduction from far-field obstructions) is currently not implemented in PlantPredict.

## Inputs

| Name                    | Symbol              | Units    | Description                                      |
| ----------------------- | ------------------- | -------- | ------------------------------------------------ |
| **Horizon Profile**     | $(\gamma_i, e_i)$   | degrees  | List of azimuth-elevation pairs defining horizon |
| **Solar Zenith Angle**  | $\theta_z$          | degrees  | Angle between sun and vertical                   |
| **Solar Azimuth Angle** | $\gamma_s$          | degrees  | Sun azimuth measured clockwise from north        |
| **Sunrise/Sunset Time** | $t_{rise}, t_{set}$ | datetime | Times when sun crosses geometric horizon (0°)    |

***

## Outputs

| Name                       | Symbol        | Units | Description                                |
| -------------------------- | ------------- | ----- | ------------------------------------------ |
| **Horizon Shading Factor** | $U_{horizon}$ | —     | Unshaded fraction of beam irradiance (0-1) |

***

## Detailed Description

### Horizon Profile Definition

The horizon profile is a user-defined list of obstruction elevations at specified azimuths around the site:

$$
\text{Horizon} = \{(\gamma_1, e_1), (\gamma_2, e_2), \ldots, (\gamma_n, e_n)\}
$$

where:

* $\gamma_i$ is the azimuth direction (0° to 360° measured clockwise from north)
* $e_i$ is the elevation angle of the obstruction at that azimuth (degrees above horizon)

Points should cover the full 360° azimuth range and be ordered by increasing azimuth.

### Horizon Elevation Interpolation

The horizon elevation at the current solar azimuth $\gamma_s$ is determined by linear interpolation between the two nearest profile points:

$$
e_{horizon}(\gamma_s) = e_i + \frac{(\gamma_s - \gamma_i)}{(\gamma_{i+1} - \gamma_i)} (e_{i+1} - e_i)
$$

where $(\gamma_i, e_i)$ and $(\gamma_{i+1}, e_{i+1})$ are the profile points immediately before and after the solar azimuth.

### Sun Visibility Determination

The shading factor depends on whether the sun is above or below the horizon obstruction at the current azimuth. The solar elevation is $e_s = 90° - \theta_z$:

$$
U_{horizon} = \begin{cases}
1 & \text{if } e_s \geq e_{horizon}(\gamma_s) \\
0 & \text{if } e_s < e_{horizon}(\gamma_s) \text{ for entire timestep} \\
\text{prorated} & \text{if sun crosses horizon within timestep}
\end{cases}
$$

### Prorated Shading Calculation

When sunrise $t_{rise}$ or sunset $t_{set}$ occurs within a timestep, the shading factor is prorated based on obstruction duration. The algorithm interpolates solar position from adjacent timesteps in 1-minute increments to find when the sun clears the horizon obstruction. The shading factor is then:

$$
U_{horizon} = 1 - \frac{\Delta t_{blocked}}{\Delta t_{interval}}
$$

where:

* $\Delta t_{blocked}$ is the time between sunrise/sunset and when the sun clears the horizon obstruction
* $\Delta t_{interval}$ is the portion of the timestep when the sun is above the geometric (0°) horizon

**Example:** For a 60-minute timestep with sunrise at minute 20, the sun is above the geometric horizon for 40 minutes ($\Delta t_{interval} = 40$). If a mountain blocks the sun until minute 35, then $\Delta t_{blocked} = 15$ minutes and $U_{horizon} = 1 - 15/40 = 0.625$.

The horizon shading factor $U_{horizon}$ is applied only to the beam irradiance component. Diffuse and ground-reflected components are not modified by this algorithm.