Adding component sum function calculations to the irradiance module

[kperrynrel]

Hey all, Josh Peterson from the University of Oregon approached me at PVPMC, interested in getting some of his functions based on published works integrated into PVAnalytics. One of the first functions he shared with me is based on the irradiance component sum equations (incredibly similar to what we have for our QCRad checks, but this directly calculates a field based on the other fields, with potential fields being GHI, DNI, or DHI). I'm sharing this function on his behalf to encourage further discussion. From what he's shared, I'd envision it as a way to calculate data fields if they aren't currently present in a data set for future analysis, as I think a lot of the validation of existing irradiance fields (say, comparing ground-based GHI measurements to component sum-calculated GHI using a GHI ratio) is already sitting up there in our QCRad checks. Let me know what you guys think about potentially adding this. I was going to flag an issue for each of the functions he'd like to add to encourage further discussion by the entire team. I can work with Josh to add the algorithms to the package, if we decide as a group to incorporate them.

Here is outline of the functionality, which is being used to estimate GHI using DNI and DHI values:

import numpy as np

def subroutineGHIcalc(dni, dhi, sza, szalimit, fillvalue, fillnightoption):
    '''
    Computes GHI from component sum equation
    ghi = dni * Cos(sza) + dhi

    Inputs: 
    dni is an array of floats
    dhi is an array of floats (Must be same units as DNI)
    sza is an array of floats (degrees)
    
    szalimit: float (degrees) SZA boundary between night and day. SZA values greater than the limit are filled with a constant
        default: 90
        
    fillvalue: float. The value that is used to fill in nighttime values.
        default: NA
    
    fillnightoption: 
        1: fill the nighttime value with the fill value (NA, 0, -99 etc)
        2: fill the nighttime value with the DHI value such that at night (GHI == DHI)
        Other: do nothing to the nighttimie values. compute them as they are. 

    Returns: GHI: array of floats, (same units as DNI)
    '''               
    # Not sure if we want to do a test to make sure the DNI, DHI, SZA are valid values.
    # Specifically are they floats. I don't think we would want to test if they are reasonable..
    # Compute the GHI value from the component sum equation
    ghi = dni * np.cos(sza * np.pi / 180) + dhi
    # Decide what you are going to do with the nighttime values
    if (fillnightoption == 1) |(fillnightoption == 2):
        # Find the locations where the sun is below the sza limit. 
        mask = (szalimit <= sza) 
    if (fillnightoption == 1):    
        # Replace the nighttime values with a fill value
        ghi[mask] = fillvalue
    elif fillnightoption == 2:
        # Replace the nighttime values with the DHI values. 
        # This will put 
        ghi[mask] =dhi[mask]
    return ghi

# A simple test
dni = np.array([1000,900,800])
dhi = np.array([50, 100, 200])
sza = np.array([100, 30, 30 ])

ghi = subroutineGHIcalc(dni, dhi, sza, 90, fillvalue=33, fillnightoption=1)

print(ghi)

[cwhanse]

I don't think there's a function like this in pvlib.irradiance and if not, that's where I would add it.

[kandersolar]

pvlib.irradiance.dni and ModelChain._complete_irradiance are relevant

[PetersonUOregon]

This is my first time on GitHub as an editor, so I don't quite know the protocols that I should follow. Specifically I don't know if I am getting into the weeds too quickly.

1. I think that the function needs to have the default values defined. Something along the lines of
   def subroutineGHIcalc(dni, dhi, sza, szalimit=90, fillvalue=np.nan, fillnightoption=1):

2. There are two ways that the nighttime values can remain unchanged. If the fillnightoption is not 1 or 2. or if the szalimit is set to 180 or greater. In the second way the mask will remain empty and there will not be any values replaced. When I wrote the function, I didn't have a great way to get around this. Any suggestions.

[cwhanse]

If I'm following:

• szalimit defines the separation between day and night,
• fillnightoption indicates if night values are to be filled with fillvalue.
  Is that correct?