NCL Home > Documentation > Functions > Meteorology, Crop

radext_fao56

Compute extraterrestrial radiation for daily periods as described in FAO 56.

Available in version 6.4.0 and later.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/crop.ncl"  ; This library is automatically loaded
                                                      ; from NCL V6.5.0 onward.
                                                      ; No need for user to explicitly load.

	function radext_fao56 (
		jday  [*] : integer,  
		lat       : numeric,  
		ounit [1] : integer   
	)

Arguments

jday

A integer scalar or one dimensional array containing day of year.

lat

A scalar or one dimensional array containing latitudes (degrees).

ounit

A scalar integer which specifies the units of the returned extraterrestrial radiation:

  • ounit=0 yields units of mm/day
  • ounit=1 yields units of MJ/(m2-day)
  • ounit=2 yields units of W/m2

Return value

If both jday and lat are scalars then a scalar is returned. Otherwise, a two- or three-dimensional array is returned. If jday(ntim) and lat(nlat), The returned array will be (ntim,nlat). If lat(nlat,mlon), the returned array will be (ntim,nlat,mlon). The returned arrays will contain metadata where applicable.

Description

Computes extraterrestrial radiation for daily periods as described in the Food and Agriculture Organization (FAO) Irrigation and Drainage Paper 56 entitled: Crop evapotranspiration - Guidelines for computing crop water requirement. Specifically, see equation 21 of Chapter 3.

Note;

  • The FAO 56 equations have limited validity at high latitudes ( > 55 ) due to the approximations used.
  • On certain Julian days at high latitudes, the returned values be set to _FillValue
If the user wishes all returned _FillValue to be set to zero (0.0), then after the radext_fao56 function use the where and ismissing functions to set all _FillValue to zero.

  radext = radext_fao56(jday, lat, ounit)   
  radext = where(ismissing(radext), 0, radext)  ; set all _FillValue = 0.0

See Also

Crop & Evapotranspiration functions

Examples

After reading the simple examples below, please see some examples with figures at: here:

Example 1: Replicate example 8 in Chapter 3. Here tunit=0.

  jday   = 246               ; 3 September
  lat    = -20.0
  radext = radext_fao56(jday, lat, 0)   ;  13.135 mm/day 
  radext = radext_fao56(jday, lat, 1)   ;  32.194 MJ/(m2-day) 
  radext = radext_fao56(jday, lat, 2)   ; 372.617 W/m2   

  printVarSummary(radext)

The output for 'radext' with ounit=1 [ MJ/(m2-day) ] is

     Variable: radext
     Type: float
     Total Size: 4 bytes
                 1 values
     Number of Dimensions: 1
     Dimensions and sizes:   [1]
     Coordinates: 
     umber Of Attributes: 4
       long_name :   extraterrestrial radiation: FAO_56
       units :       MJ/(m2-day)
       url : http://www.fao.org/docrep/X0490E/x0490e07.htm
       info :        FAO 56; EQN 21
     (0)     32.194


Example 2: Consider lat(lat) and jday(time): calculate 'radext' with ounit=0 [ mm/day ].


    lat     = (/ -20, 0, 45 /)
    lat@units = "degrees_north"
    lat!0   = "lat"
    lat&lat =  lat

    time    = (/ 15, 180, 246, 306 /)
    time@long_name = "julian day"
    time!0    = "time"
    time&time =  time  

    ra        = radext_fao56(time, lat, 0)   

The output would be

     Variable: ra
     Type: float
     Total Size: 48 bytes
                 12 values
     Number of Dimensions: 2
     Dimensions and sizes:   [time | 4] x [lat | 3]
     Coordinates: 
                 time: [15..306]
                 lat:  [-20..45]
     Number Of Attributes: 5
       long_name :   extraterrestrial radiation: FAO_56
       units :       mm/day
       url : http://www.fao.org/docrep/X0490E/x0490e07.htm
       info :        FAO 56; EQN 21

Example 3: Given julian day and latitude calculate the daily extraterrestrial radiation for every day of the year. Calculate 'radext' with ounit=2 [ W/m2 ].


   jday   = ispan(1,365,1)                ; every day of year
   jday@long_name = "day oy year"
   jday!0 = "jday"                        ; make a coordinate variable
   jday&jday = jday

   nlat   = 73
   lat    = latGlobeF(nlat, "lat", "latitude", "degrees_north")

   radext = radext_fao56(jday, lat, 2)  ; [jday | 365] x [lat | 73]

   printVarSummary(radext)
   print("radext: min="+min(radext)+"  max="+max(radext))

The output looks like:

     Variable: radext
     Type: float
     Total Size: 262800 bytes
                 32850 values
     Number of Dimensions: 2
     Dmensions and sizes:   [jday | 365] x [lat | 73]
     Coordinates: 
            jday: [1..365]
            lat: [-90..90]
       Number Of Attributes: 5
       long_name :	extra terrestrial radiation: FAO_56
       units :	W/m2                                      <=== ounit=2
       url :	http://www.fao.org/docrep/X0490E/x0490e07.htm
       info :	FAO 56; EQN 21; radext_fao56

     (0)        extra terrestrial radiation: FAO_56 (W/m2) : min=0.000519285   max=559.908

Adding the following print statement will print the vales at specified latitudes. The { ... } is NCL syntax for 'coordinate subscripting.'

   radext@_FillValue = -999.9              ; change for a nicer print

   print(sprinti("%3.0i", jday)+"  "+ \
         sprintf("%5.1f", radext(:,{-90}) )+" "+ \
         sprintf("%5.1f", radext(:,{-80}) )+" "+sprintf("%5.1f", radext(:,{-70}) )+" "+ \
         sprintf("%5.1f", radext(:,{-60}) )+" "+sprintf("%5.1f", radext(:,{-50}) )+" "+ \ 
         sprintf("%5.1f", radext(:,{-40}) )+" "+sprintf("%5.1f", radext(:,{-30}) )+" "+ \ 
         sprintf("%5.1f", radext(:,{-20}) )+" "+sprintf("%5.1f", radext(:,{-10}) )+" "+ \ 
         sprintf("%5.1f", radext(:,{ 0 }) )+" "+ \
         sprintf("%5.1f", radext(:,{ 10}) )+" "+sprintf("%5.1f", radext(:,{ 20}) )+" "+ \
         sprintf("%5.1f", radext(:,{ 30}) )+" "+sprintf("%5.1f", radext(:,{ 40}) )+" "+ \
         sprintf("%5.1f", radext(:,{ 50}) )+" "+sprintf("%5.1f", radext(:,{ 60}) )+" "+ \
         sprintf("%5.1f", radext(:,{ 70}) )+" "+sprintf("%5.1f", radext(:,{ 80}) )+" "+ \
         sprintf("%5.1f", radext(:,{ 90}) ) )

The (edited) output is here.

---------

Example 4: Read a netCDF file containing daily values with 'time' and compute the extra terrestrial radiation using radext_fao56.

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/crop.ncl"

;----------------------------------------------------------------------------
;                             MAIN
;----------------------------------------------------------------------------
  diri   = "./"
  filmin = "E-OBS_tasmin.nc"           ; file with daily minimum; (time,latitude,longitude)
  fmin   = addfile(diri+filmin, "r") 

;---Create 'day_of_year' [jday] using 'time'
  time   = fmin->time                  ; "days since 1949-12-1 00:00:00" , [10958] 
  ntim   = dimsizes(time)

  TIME   = cd_calendar(time, 0)        ; convert to yyyy,mm,dd
  yyyy   = toint( TIME(:,0) )           ; clarity; explicitly extract/assign to variables
  mm     = toint( TIME(:,1) )
  dd     = toint( TIME(:,2) )

  jday   = day_of_year( yyyy, mm, dd )
;;jday   = day_of_year( toint(TIME(:,0)), toint(TIME(:,1)), toint(TIME(:,2)) )

;---Create multi-dimensional latitude array
;---Broadcast (replicate) lat at each longitude via conform_dims
  lat    = fmin->latitude               ; [*]
  lon    = fmin->longitude              ; [*]
  nlat   = dimsizes(lat)                ; [201]    
  mlon   = dimsizes(lon)                ; [464]
  lat2d  = conform_dims( (/nlat,mlon/), lat, 0)  ; (nlat,mlon); replicate lat

  print("ntim="+ntim+"  nlat="+nlat+"  mlon="+mlon)
  print("---")

;---Calculate 'radext'
  radunit= 0                             ; return units: mm/day
  radext = radext_fao56(jday, lat2d, radunit)       ; (ntim,nlat,mlon)
  radext = where(radext.lt.0.001, 0.0, radext)

;---Add meta data for netCDF
  radext!0         = "time"
  radext!1         = "latitude"
  radext!2         = "longitude"
  radext&time      =  time
  radext&latitude  =  lat
  radext&longitude =  lon
  printVarSummary(radext)
  printMinMax(radext,0)

;===================================================================
;---Write to netCDF: 'simple' way
;---http://www.ncl.ucar.edu/Applications/o-netcdf.shtml
;===================================================================

  dir_nc = "./"
  fil_nc = "EOBS.radext.nc"
  pth_nc = dir_nc + fil_nc

  system("/bin/rm -f "+pth_nc)   ; remove any pre-existing file
  ncdf = addfile(pth_nc ,"c")  ; open output netCDF file

;---Create global attributes of the file (optional)

  fAtt               = True            ; assign file attributes
  fAtt@title         = "Extra Terrestrial Radiation: E-OBS"
  fAtt@NCL           = get_ncl_version()
  fAtt@Conventions   = "None"
  fAtt@creation_date = systemfunc("date")
  fileattdef( ncdf, fAtt )            ; copy file attributes

;---Make time an UNLIMITED dimension; recommended  for most applications

  filedimdef(ncdf,"time",-1,True)

;---Output variable(s) directly; NCL will call appropriate functions
;---to write the meta data associated with each variable

  ncdf->RADEXT =  radext

; ========================================================================

The printed output is:

     (0)	ntim=10958  nlat=201  mlon=464
     (0)	---
     
     
     Variable: radext
     Type: float
     Total Size: 4087947648 bytes
                 1021986912 values
     Number of Dimensions: 3
     Dimensions and sizes:   [time | 10958] x [latitude | 201] x [longitude | 464]
     Coordinates: 
                 time: [7701..18658]
                 latitude: [25.375..75.375]
                 longitude: [-40.375..75.375]
     Number Of Attributes: 5
       _FillValue :  1e+20
       long_name :   extra terrestrial radiation: FAO_56
       units :       mm/day
       url : http://www.fao.org/docrep/X0490E/x0490e07.htm
       info :        FAO 56; EQN 21; radext_fao56
     
     (0)     extra terrestrial radiation: FAO_56 (mm/day) : min=0   max=17.9267