NCL Home > Documentation > Functions > Meteorology

advect_variable

Use "highly accurate" spherical harmonics to estimate gradients and advect a variable horizontally on a global rectilinear grid.

Available in version 6.3.0 and later.

Prototype

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

	function advect_variable (
		u            : numeric,  
		v            : numeric,  
		x            : numeric,  
		gridType [1] : integer,  
		longName [1] : string,   
		units    [1] : string,   
		opt          : integer   
	)

	return_val [dimsizes(x)] :  float or double

Arguments

Array containing zonal wind components (m/s). The array must be global and ordered south to north.

Array containing meridional wind components (m/s). Same size and shape as u.

Array containing a scalar quantity (eg: temperature, specific humidity, etc). Same size and shape as u.

gridType

Grid type. gridType=0 means gaussian grid; gridType=1 means regular or fixed grid.

longName

A string to be used as the long_name of the advected variable.

units

A string specifying the units of the returned variable.

opt

option.

opt=0 means return the advection result.
opt=1 means return the advection result, longitudinal and latitudinal gradients as part of a three-element variable of type list

Return value

A multi-dimensional array of the same size and shape as x. The output will be double if u, v or x is of type double.

Description

Calculate the horizontal advection of a quantity on the globe using spherical harmonics to estimate the gradients,.


             adv_X =  U*(dX/dlon) + V*(dX/dlat)

NOTE: This is a non-linear quantity. Generally, it is not appropriate to use (say) monthly means quantities. Rather, high-frequency (hourly, 3-hr, 6-hr, daily) quantities should be used.

This function requires that the grids be global because the "highly accurate" spherical harmonic functions are used to derive the gradients.

To see gradients derived via spherical harmonics and 'simple' centered finite differences, see: gradients.

Examples

Example 1: See the example which calculate local vorticity tendency: Example 6.

Example 2 Here the variables u,v (m/s) and T (degK) are ordered south to north and are on a global grid..


   f = addfile ("...", "r")
   u = f->U    ; (time,lev,lat,lon); m/s
   v = f->V
   T = f->T    ; degK
               
   gridType  = 0   ; global gaussian grid
   opt_adv   = 0   ; return only the advected variable
 
   long_name = "advection of temperature"
   units     = "K/s"

   Tadv = advect_variable(u,v,T,gridType,long_name,units,opt_adv)

   printVarSummary(Tadv)  
   printMinMax(Tadv, 0)

The edited output:


          Variable: Tadv
          Type: float
          Total Size: 5003712 bytes
                      1250928 values
          Number of Dimensions: 4
          Dimensions and sizes:   [time | 7] x [level | 17] x [lat | 73] x [lon | 144]
          Coordinates: 
                      time: [1823280..1823424]
                      level: [1000..10]
                      lat: [-90..90]
                      lon: [ 0..357.5]
          Number Of Attributes: 3
            _FillValue :  -9.96921e+36
            long_name :   advection of temperature"
            units :       m-K/s
             
          (0)     Tadv: Spherical Harmonics:  (m-K/s) : min=-0.00109299   max=0.000927749
          (0)     ===

If opt_adv=1, then:


   T_list = advect_variable(u,v,T,gridType,long_name,units,opt_adv)

; For clarity: explicitly extract the returned elements of the list variable. All meta data is present. 

   Tadv = T_list[0]           ; advected quantity
   Tgrx = T_list[1]           ; longitudinal gradient
   Tgry = T_list[2]           ; latitudinal  gradient

   printVarSummary(Tadv)    ; advection of temperature
   printVarSummary(Tgrx)    ; longitudinal gradient
   printVarSummary(Tgry)    ; latitudinal gradient

If opt_adv=1, then, additionally, after extraction from the list variable: