MASKING_ANGLE

This function computes the masking angle for a point on a collector’s surface in a multi-row array.

The masking angle indicates the portion of the sky dome blocked by the preceding row. It depends on the surface tilt, ground coverage ratio (GCR), and the position up the module slant height.

Excel Usage

=MASKING_ANGLE(surface_tilt, gcr, slant_height)

surface_tilt (list[list], required): Panel tilt from horizontal (degrees).
gcr (float, required): Ground coverage ratio (panel width / row spacing).
slant_height (list[list], required): Fraction of the module’s slant height (0 at bottom, 1 at top).

Returns (list[list]): 2D list of masking angles (degrees), or an error string.

Example 1: Masking angle at the bottom of the row

Inputs:

surface_tilt	gcr	slant_height
20	0.5	0

Excel formula:

=MASKING_ANGLE({20}, 0.5, {0})

Expected output:

17.878

Example 2: Masking angle at the top of the row

Inputs:

surface_tilt	gcr	slant_height
20	0.5	1

Excel formula:

=MASKING_ANGLE({20}, 0.5, {1})

Expected output:

0

Example 3: Masking angle at mid slant height

Inputs:

surface_tilt	gcr	slant_height
20	0.5	0.5

Excel formula:

=MASKING_ANGLE({20}, 0.5, {0.5})

Expected output:

6.37692

Example 4: Vectorized slant-height evaluation

Inputs:

surface_tilt			gcr	slant_height
20	20	20	0.5	0	0.5	1

Excel formula:

=MASKING_ANGLE({20,20,20}, 0.5, {0,0.5,1})

Expected output:

Result
17.878
6.37692
0

Python Code

Show Code

import pandas as pd
import numpy as np
from pvlib.shading import masking_angle as result_func

def masking_angle(surface_tilt, gcr, slant_height):
    """
    Calculate the elevation angle below which diffuse irradiance is blocked.

    See: https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.shading.masking_angle.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        surface_tilt (list[list]): Panel tilt from horizontal (degrees).
        gcr (float): Ground coverage ratio (panel width / row spacing).
        slant_height (list[list]): Fraction of the module's slant height (0 at bottom, 1 at top).

    Returns:
        list[list]: 2D list of masking angles (degrees), or an error string.
    """
    try:
        def flatten_num(data):
            if not isinstance(data, list): return [float(data)]
            flat = []
            for row in data:
                row = row if isinstance(row, list) else [row]
                for val in row:
                    if val == "": flat.append(float('nan'))
                    else: flat.append(float(val))
            return flat

        t_list = flatten_num(surface_tilt)
        h_list = flatten_num(slant_height)

        n = len(t_list)
        if n == 0 or len(h_list) != n:
            return "Error: surface_tilt and slant_height arrays must have the same non-zero length"

        gc = float(gcr) if gcr is not None else 0.5

        res = result_func(
            surface_tilt=np.array(t_list),
            gcr=gc,
            slant_height=np.array(h_list)
        )

        return [[float(v) if not pd.isna(v) else ""] for v in res]
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

surface_tilt *

Panel tilt from horizontal (degrees).

gcr *

Ground coverage ratio (panel width / row spacing).

slant_height *

Fraction of the module's slant height (0 at bottom, 1 at top).