pvlib.shading.shaded_fraction1d(solar_zenith, solar_azimuth, axis_azimuth, shaded_row_rotation, *, collector_width, pitch, axis_tilt=0, surface_to_axis_offset=0, cross_axis_slope=0, shading_row_rotation=None)[source]#

Shaded fraction in the vertical dimension of tilted rows, or perpendicular to the axis of horizontal rows.

If shading_row_rotation isn’t provided, it is assumed that both the shaded row and the shading row (the one blocking the direct beam) have the same rotation and azimuth values.


The function assumes that the roles of the shaded and shading rows remain the same during the day. In the case where the shading and shaded rows change throughout the day, e.g. a N-S single-axis tracker, the inputs must be switched depending on the sign of the projected solar zenith angle. See the Examples section below.

New in version 0.11.0.

  • solar_zenith (numeric) – Solar zenith angle, in degrees.

  • solar_azimuth (numeric) – Solar azimuth angle, in degrees.

  • axis_azimuth (numeric) – Axis azimuth of the rotation axis of a tracker, in degrees. Fixed-tilt arrays can be considered as a particular case of a tracker. North=0º, South=180º, East=90º, West=270º.

  • shaded_row_rotation (numeric) – Right-handed rotation of the row receiving the shade, with respect to axis_azimuth. In degrees \(^{\circ}\).

  • collector_width (numeric) – Vertical length of a tilted row. The returned shaded_fraction is the ratio of the shadow over this value.

  • pitch (numeric) – Axis-to-axis horizontal spacing of the row.

  • axis_tilt (numeric, default 0) – Tilt of the rows axis from horizontal. In degrees \(^{\circ}\).

  • surface_to_axis_offset (numeric, default 0) – Distance between the rotating axis and the collector surface. May be used to account for a torque tube offset.

  • cross_axis_slope (numeric, default 0) – Angle of the plane containing the rows’ axes from horizontal. Right-handed rotation with respect to the rows axes. In degrees \(^{\circ}\).

  • shading_row_rotation (numeric, optional) – Right-handed rotation of the row casting the shadow, with respect to the row axis. In degrees \(^{\circ}\).


shaded_fraction (numeric) – The fraction of the collector width shaded by an adjacent row. A value of 1 is completely shaded and 0 is no shade.


All length parameters must have the same units.

Parameters are defined as follow:

Diagram showing the two rows and the parameters of the model.

Figure 3 of 1. See correspondence between this nomenclature and the function parameters in the table below.#






Degrees \(^{\circ}\)







Any consistent length unit across all these parameters, e.g. \(m\).






Return value



Fixed-tilt south-facing array on flat terrain

Tilted row with a pitch of 3 m, a collector width of 2 m, and row rotations of 30°. In the morning.

>>> shaded_fraction1d(solar_zenith=80, solar_azimuth=104.5,
...     axis_azimuth=90, shaded_row_rotation=30, shading_row_rotation=30,
...     collector_width=2, pitch=3, axis_tilt=0,
...     surface_to_axis_offset=0.05, cross_axis_slope=0)

Fixed-tilt north-facing array on sloped terrain

Tilted row with a pitch of 4 m, a collector width of 2.5 m, and row rotations of 50° for the shaded row and 30° for the shading row. The rows are on a 10° slope, where their axis is on the most inclined direction (zero cross-axis slope). Shaded in the morning.

>>> shaded_fraction1d(solar_zenith=65, solar_azimuth=75.5,
...     axis_azimuth=270, shaded_row_rotation=50, shading_row_rotation=30,
...     collector_width=2.5, pitch=4, axis_tilt=10,
...     surface_to_axis_offset=0.05, cross_axis_slope=0)

N-S single-axis tracker on sloped terrain

Horizontal trackers with a pitch of 3 m, a collector width of 1.4 m, and tracker rotations of 30° pointing east, in the morning. Terrain slope is 7° west-east (east-most tracker is higher than the west-most tracker).

>>> shaded_fraction1d(solar_zenith=50, solar_azimuth=90, axis_azimuth=180,
...     shaded_row_rotation=-30, collector_width=1.4, pitch=3, axis_tilt=0,
...     surface_to_axis_offset=0.10, cross_axis_slope=7)

Note the previous example only is valid for the shaded fraction of the west-most tracker in the morning, and assuming it is the shaded tracker during all the day is incorrect. During the afternoon, it is the one casting the shadow onto the east-most tracker.

To calculate the shaded fraction for the east-most tracker, you must input the corresponding shaded_row_rotation in the afternoon.

>>> shaded_fraction1d(solar_zenith=50, solar_azimuth=270, axis_azimuth=180,
...     shaded_row_rotation=30, collector_width=1.4, pitch=3, axis_tilt=0,
...     surface_to_axis_offset=0.10, cross_axis_slope=7)

You must switch the input/output depending on the sign of the projected solar zenith angle. See projected_solar_zenith_angle() and the example Shaded fraction of a horizontal single-axis tracker



Kevin S. Anderson, Adam R. Jensen; Shaded fraction and backtracking in single-axis trackers on rolling terrain. J. Renewable Sustainable Energy 1 March 2024; 16 (2): 023504. DOI: 10.1063/5.0202220

Examples using pvlib.shading.shaded_fraction1d#

Shaded fraction of a horizontal single-axis tracker

Shaded fraction of a horizontal single-axis tracker