MASK_ANGLE_PASSIAS

This function computes the average masking angle for a row in a large multi-row PV array using the Passias model.

Unlike the standard masking angle which is evaluated at a specific point, this function integrates the view factor over the entire module surface to provide a representative average value for diffuse shading models.

Excel Usage

=MASK_ANGLE_PASSIAS(surface_tilt, gcr)

surface_tilt (list[list], required): Panel tilt from horizontal (degrees).
gcr (float, required): Ground coverage ratio (panel width / row spacing).

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

Example 1: Average masking angle for 20 deg tilt

Inputs:

surface_tilt	gcr
20	0.5

Excel formula:

=MASK_ANGLE_PASSIAS({20}, 0.5)

Expected output:

7.20981

Example 2: Higher tilt increases average masking angle

Inputs:

surface_tilt	gcr
35	0.5

Excel formula:

=MASK_ANGLE_PASSIAS({35}, 0.5)

Expected output:

11.1343

Example 3: Lower ground coverage ratio case

Inputs:

surface_tilt	gcr
25	0.3

Excel formula:

=MASK_ANGLE_PASSIAS({25}, 0.3)

Expected output:

4.44217

Example 4: Vectorized surface tilt inputs

Inputs:

surface_tilt			gcr
10	20	30	0.5

Excel formula:

=MASK_ANGLE_PASSIAS({10,20,30}, 0.5)

Expected output:

Result
3.79416
7.20981
10.0028

Python Code

Show Code

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

def mask_angle_passias(surface_tilt, gcr):
    """
    Calculate the average masking angle over the slant height of a row.

    See: https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.shading.masking_angle_passias.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).

    Returns:
        list[list]: 2D list of average 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)
        if len(t_list) == 0:
            return "Error: surface_tilt array cannot be empty"

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

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

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