== Dynlib diagnostic functions ==

The functions generally operate on real arrays with dimension (nz,ny,nx) where nz is number of times or levels, and ny and nx are the number of latitudes and longitudes, respectively. The function descriptions below contain detailed descriptions of arguments and returns where there is any deviation from this pattern; otherwise they may be assumed to be of the form:

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | u
| real || (nz,ny,nx) || Zonal velocity
|-
! width="80" | v
| real || (nz,ny,nx) || Meridional velocity
|-
! width="80" | pv
| real || (nz,ny,nx) || Potential vorticity
|}

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="120" | Dim
! width="300" | Description
|-
! width="80" | res
| real || (nz,ny,nx) || output data
|}

The ubiquitous inputs ''dx'' and ''dy'' are all of the form
{| border="1" class="wikitable" style="text-align:center;"
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | dx
| real || (ny,nx) || dx(j,i) = x(j, i+1) - x(j, i-1) (in metres)
|-
! width="80" | dy
| real || (ny,nx) || dy(j,i) = y(j+1, i) - y(j-1, i) (in metres)
|}

Typically, the results for each level or time are computed individually in 2-D fashion, though they are returned as a 3-D array of the same size as the input.

=== ''dynlib.diag.ddx'' : partial x derivative ===

<code>res=ddx(dat,dx,dy)</code>

Calculates the partial x derivative of dat, using centred differences. For a non-EW-cyclic grid, 0 is returned on the edges of the x domain.

=== ''dynlib.diag.ddy'' : partial y derivative ===

<code>res=ddy(dat,dx,dy)</code>

Calculates the partial y derivative of dat, using centred differences. For a non-EW-cyclic grid, 0 is returned on all edges of the x,y domain. For an EW-cyclic grid, 0 is returned on the first and last latitudes.

=== ''dynlib.diag.grad'' : 2-D gradient ===

<code>(resx,resy)=grad(dat,dx,dy)</code>

Calculates the 2-D gradient of dat, using centred differences in x and y. For a non-EW-cyclic grid, 0 is returned on all edges of the x,y domain. For an EW-cyclic grid, 0 is returned on the first and last latitudes.

=== ''dynlib.diag.lap2'' : 2-D laplacian ===

<code>res=lap2(dat,dx,dy)</code>

Calculates the 2-D laplacian of dat, using centred differences. For a non-EW-cyclic grid, 0 is returned on all edges of the x,y domain. For an EW-cyclic grid, 0 is returned on the first and last latitudes.

=== ''dynlib.diag.vor'' : 2-D vorticity ===

<code>res=vor(u,v,dx,dy)</code>

Calculates the z component of vorticity of (u,v), using centred differences.

=== ''dynlib.diag.div'' : 2-D divergence===

<code>res=div(u,v,dx,dy)</code>

Calculates the 2-D divergence of (u,v), using centred differences.

=== ''dynlib.diag.def_shear'' : shear deformation ===

<code>res=def_shear(u,v,dx,dy)</code>

Calculates the shear (antisymmetric) deformation of (u,v), using centred differences.

=== ''dynlib.diag.def_stretch'' : stretch deformation ===

<code>res=def_stretch(u,v,dx,dy)</code>

Calculates the stretch (symmetric) deformation of (u,v), using centred differences.

=== ''dynlib.diag.def_total'' : total deformation ===

<code>res=def_total(u,v,dx,dy)</code>

Calculates the total (rotation-independent) deformation of (u,v), using centred differences.

=== ''dynlib.diag.def_angle'' : deformation angle ===

<code>res=def_angle(u,v,dx,dy)</code>

Calculates the angle between the x-axis and the dilatation axis of the deformation of (u,v).

=== ''dynlib.diag.isopv_angle'' : iso-PV contour angle ===

<code>res=isopv_angle(pv,dx,dy)</code>

Calculates the angle between the x-axis and the iso-lines of PV.

=== ''dynlib.diag.beta'' : angle between dilatation axis and iso-PV contours ===

<code>res=beta(u,v,pv,dx,dy)</code>

Calculates the angle between the dilatation axis and the iso-lines of PV.

=== ''dynlib.diag.stretch_stir'' : fractional stretching rate and angular rotation rate of grad(PV)===

<code>(stretch,stir)=stretch_stir(u,v,pv,dx,dy)</code>

Returns real arrays, dim (nz,ny,nx):

stretch
= fractional PV gradient stretching rate
= 1/|gradPV| * d/dt(|gradPV|)
= gamma, 'stretching rate' (Lapeyre Klein Hua).<ref name="LapKleHua1999" />
= -1/|gradPV| * Fn (Keyser Reeder Reed)<cite>KeyReeRee1988</cite>
Fn = 0.5*|gradPV|(D-E*cos(2*beta))
= 1/|gradPV| * F (Markowski Richardson)<cite>Mar2010</cite>

stir
= angular rotation rate of grad(PV) (aka stirring rate)
= d(theta)/dt (Lapeyre Klein Hua)<cite>LapKleHua1999</cite>

= 1/|gradPV| * Fs (Keyser Reeder Reed)<cite>KeyReeRee1988</cite>
Fs = 0.5*|gradPV|(vort+E*sin(2*beta))

=== ''dynlib.diag.geop_from_montgp'' : geopotential ===

<code>res = geop_from_montgp(m,theta,p,dx,dy)</code>

Calculates geopotential (res) from montgomery potential (m), potential temperature (theta) and pressure (p)

=== ''dynlib.diag.rev'' : PV gradient reversal ===

<code>(resa,resc,resai,resci,resaiy,resciy,tested) = rev(pv,highenough,latitudes,ddythres,dx,dy)</code>

Finds the reversals of PV y-gradient (where the negative y-gradient exceeds some threshold) and classifies them as c (cyclonic) or a (anticyclonic). Three measures of c and a reversals are returned (6 in total). Only points flagged in ''highenough'' are tested.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | pv
| real || (nz,ny,nx) || potential vorticity
|-
! width="80" | highenough
| int*1 || (nz,ny,nx) || array of flags denoting whether to test the point for reversal
|-
! width="80" | latitudes
| real || (ny) || vector of latitudes
|-
! width="80" | ddythres
| real || 0 || Cutoff y-gradient for pv
|}

''dynlib.diag.Highenough'' is typically the output of the ''highenough'' function, which returns 1 where the surface is sufficiently above ground level and 0 elsewhere.

''dynlib.diag.ddythres'' is the cutoff y-gradient for pv. The magnitude of (negative) d(pv)/dy must be above ddythres for reversal to be detected; this applies to revc, reva, revci,revai. Typical value: 4E-12.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | revc
| int*1 || (nz,ny,nx) || Flag =1 for cyclonic reversal (threshold test applied)
|-
! width="80" | reva
| int*1 || (nz,ny,nx) || Flag =1 for anticyclonic reversal (threshold test applied)
|-
! width="80" | revci
| real || (nz,ny,nx) || Absolute PV gradient where reversal is cyclonic (threshold test applied)
|-
! width="80" | revai
| real || (nz,ny,nx) || Absolute PV gradient where reversal is anticyclonic (threshold test applied)
|-
! width="80" | revciy
| real || (nz,ny,nx) || Absolute PV y-gradient where reversal is cyclonic (no threshold test applied)
|-
! width="80" | revaiy
| real || (nz,ny,nx) || Absolute PV y-gradient where reversal is anticyclonic (no threshold test applied)
|-
! width="80" | tested
| int*1 || (nz,ny,nx) || flag to 1 all tested points: where highenough==1 and point not on grid edge
|}

=== ''dynlib.diag.prepare_fft'' : make data periodic in y for FFT ===

<code>res = prepare_fft(thedata,dx,dy)</code>

Returns the data extended along complementary meridians (for fft).
For each lon, the reflected (lon+180) is attached below so that data is periodic in x and y.
NOTE: Input data must be lats -90 to 90, and nx must be even.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | thedata
| real || (nz,ny,nx) || input data
|}

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="120" | Dim
! width="300" | Description
|-
! width="80" | res
| real || (nz,2*ny-2,nx) || output data
|}

=== ''dynlib.diag.sum_kix'' : sum along k for flagged k-values ===

<code>(res,nres) = sum_kix(thedata,kix,dx,dy)</code>

Calculates sum along k dimension for k values which are flagged to 1 in kix vector (length nz).

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | thedata
| real || (nz,ny,nx) || input data
|-
! width="80" | kix
| int || (nz) || index flag for summation
|}

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | res
| real || (ny,nx) || (summed) output data
|-
! width="80" | nres
| int || 0 || Number of data summed = sum(kix)
|}

''dynlib.diag.sum_kix'' is typically used for calculating seasonal means. To do this, kix is set to 1 for times in the relevant season and 0 elsewhere. After (further) summing res and nres over all years, res/nres gives the mean for the season for all years.

=== ''dynlib.diag.high_enough'' : flags points which are sufficiently above ground ===

<code>res = high_enough(zdata,ztest,zthres,dx,dy)</code>

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | zdata
| real || (nz,ny,nx) || geopotential of gridpoints
|-
! width="80" | ztest
| real || (1,ny,nx) ||geopotential of topography
|-
! width="80" | zthres
| real || 0 ||threshold geopotential height difference
|}

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | res
| int*1 || (nz,ny,nx) ||
{| style="text-align:left;"
|-
| Flag array set to:
|-
|style="padding-left: 2em" |1 if zdata(t,y,x) > (ztest(1,y,x) + zthres)
|-
|style="padding-left: 2em" |0 otherwise
|}
|}

=== ''dynlib.diag.contour_rwb'' : detects RWB events, Riviere algorithm ===

<code>(beta_a_out,beta_c_out) = contour_rwb(pv_in,lonvalues,latvalues,ncon,lev,dx,dy)</code>

Detects the occurrence of anticyclonic and cyclonic wave-breaking events from a PV field on isentropic coordinates.

Reference: Riviere 2009 <ref>Riv2009</ref> : See the appendix C.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | pv_in
| real || (nz,ny,nx) || isentropic pv. Should be on a regular lat-lon grid and 180W must be the first longitude. (If 180W is not the first longitude, the outputs will have 180W as the first, so must be rearranged)
|-
! width="80" | lonvalues
| real || (nx) || vector of longitudes
|-
! width="80" | latvalues
| real || (ny) || vector of latitudes
|-
! width="80" | ncon
| int || 0 || number of contours to test, normally 41 or 21
|-
! width="80" | lev
| real || 0 || potential temperature of the level
|}

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | beta_a_out
| int || (nz,ny,nx) || flag array, =1 if anticyclonic wave breaking
|-
! width="80" | beta_c_out
| int || (nz,ny,nx) || flag array, =1 if cyclonic wave breaking
|}

=== ''dynlib.diag.v_g'' : geostrophic velocity ===

<code>(resx,resy) = v_g(mont,lat,dx,dy)</code>

Calculates geostrophic velocity. Returns zero on equator.

=== ''dynlib.diag.okuboweiss'' : Okubo-Weiss criterion===

<code>res = okuboweiss(u,v,dx,dy)</code>

Calculates Okubo-Weiss criterion lambda_0=1/4 * (sigma^2-omega^2)= 1/4 W, where ''sigma'' is total deformation and ''omega'' is vorticity.

This is the square of the eigenvalues in Okubo's paper<cite>Oku1969</cite> (assumes divergence is negligible).

=== ''dynlib.diag.laccel'' : Lagrangian acceleration===

<code>(resx,resy) = laccel(u,v,mont,lat,dx,dy)</code>

Calculates Lagrangian acceleration on the isentropic surface, based on Montgomery potential.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | u
| real || (nz,ny,nx) || zonal velocity
|-
! width="80" | v
| real || (nz,ny,nx) || meridional velocity
|-
! width="80" | mont
| real || (nz,ny,nx) || Montgomery potential
|-
! width="80" | lat
| real || (ny) || vector of latitudes
|}

=== ''dynlib.diag.accgrad_eigs'' : Lagrangian acceleration gradient tensor eigenvalues ===

<code>(respr,respi,resmr,resmi) = accgrad_eigs(u,v,mont,lat,dx,dy)</code>

Calculates eigenvalues of the lagrangian acceleration gradient tensor.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | u
| real || (nz,ny,nx) || zonal velocity
|-
! width="80" | v
| real || (nz,ny,nx) || meridional velocity
|-
! width="80" | mont
| real || (nz,ny,nx) || Montgomery potential
|-
! width="80" | lat
| real || (ny) || vector of latitudes
|}

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | respr
| real || (nz,ny,nx) || Real part of positive eigenvalue
|-
! width="80" | respi
| real || (nz,ny,nx) || Imaginary part of positive eigenvalue
|-
! width="80" | resmr
| real || (nz,ny,nx) || Real part of negative eigenvalue
|-
! width="80" | resmi
| real || (nz,ny,nx) || Imaginary part of negative eigenvalue
|-
! width="80" | ncon
| int || 0 || number of contours to test, normally 41 or 21
|-
! width="80" | lev
| real || 0 || potential temperature of the level
|}

=== ''dynlib.diag.dphidt'' : Lagrangian derivative of compression axis angle ===

<code>res = dphidt(u,v,mont,lat,dx,dy)</code>

Calculates Lagrangian time derivative of compression axis angle: d(phi)/dt (ref Lapeyre et. al 1999<cite>LapKleHua1999</cite> ), from deformation and Lagrangian acceleration tensor.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | u
| real || (nz,ny,nx) || zonal velocity
|-
! width="80" | v
| real || (nz,ny,nx) || meridional velocity
|-
! width="80" | mont
| real || (nz,ny,nx) || Montgomery potential
|-
! width="80" | lat
| real || (ny) || vector of latitudes
|}

==References==
<bibtex>
@article{LapKleHua1999,
author = {Lapeyre, G. and Klein, P. and Hua, B. L.},
title = {Does the tracer gradient vector align with the strain eigenvectors in 2D turbulence?},
journal = {Physics of Fluids},
volume = {11},
number = {12},
pages = {3729-3737},
year = {1999},
url = {<Go to ISI>://000083495900013
http://scitation.aip.org/getpdf/servlet/GetPDFServlet?filetype=pdf&id=PHFLE6000011000012003729000001&idtype=cvips&doi=10.1063/1.870234&prog=normal},
}
</bibtex>
<bibtex>
@article{KeyReeRee1988,
author = {Keyser, D. and Reeder, M. J. and Reed, R. J.},
title = {A Generalization of Petterssen Frontogenesis Function and Its Relation to the Forcing of Vertical Motion},
journal = {Monthly Weather Review},
volume = {116},
number = {3},
pages = {762-780},
year = {1988},
url = {<Go to ISI>://A1988N255100017},
}
</bibtex>
<bibtex>
@book{Mar2010,
author = {Markowski, Paul},
title = {Mesoscale meteorology in midlatitudes},
publisher = {Chichester, West Sussex, UK ;Hoboken, NJ : Wiley-Blackwell, 2010},
url = {http://books.scholarsportal.info/viewdoc.html?id=/ebooks/ebooks2/wiley/2011-12-13/2/9780470682104},
year = {2010},
}
</bibtex>
<bibtex>
@article{Riv2009,
author = {Riviere, G.},
title = {Effect of Latitudinal Variations in Low-Level Baroclinicity on Eddy Life Cycles and Upper-Tropospheric Wave-Breaking Processes},
journal = {Journal of the Atmospheric Sciences},
volume = {66},
number = {6},
pages = {1569-1592},
year = {2009},
url = {<Go to ISI>://000267263300006},
}
</bibtex>
<bibtex>
@article{Oku1969,
author = {Okubo, A.},
title = {Horizontal Dispersion of Foreign Particles in Vicinity of Velocity Singularities Such as Convergences},
journal = {Transactions-American Geophysical Union},
volume = {50},
number = {4},
pages = {182-&},
year = {1969},
url = {<Go to ISI>://A1969C982700332},
}
</bibtex>

Dynlib diag functions

2013-01-25T11:35:42Z

Amu006:

== Dynlib diagnostic functions ==

The functions generally operate on real arrays with dimension (nz,ny,nx) where nz is number of times or levels, and ny and nx are the number of latitudes and longitudes, respectively. The function descriptions below contain detailed descriptions of arguments and returns where there is any deviation from this pattern; otherwise they may be assumed to be of the form:

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | u
| real || (nz,ny,nx) || Zonal velocity
|-
! width="80" | v
| real || (nz,ny,nx) || Meridional velocity
|-
! width="80" | pv
| real || (nz,ny,nx) || Potential vorticity
|}

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="120" | Dim
! width="300" | Description
|-
! width="80" | res
| real || (nz,ny,nx) || output data
|}

The ubiquitous inputs ''dx'' and ''dy'' are all of the form
{| border="1" class="wikitable" style="text-align:center;"
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | dx
| real || (ny,nx) || dx(j,i) = x(j, i+1) - x(j, i-1) (in metres)
|-
! width="80" | dy
| real || (ny,nx) || dy(j,i) = y(j+1, i) - y(j-1, i) (in metres)
|}

Typically, the results for each level or time are computed individually in 2-D fashion, though they are returned as a 3-D array of the same size as the input.

=== ''dynlib.diag.ddx'' : partial x derivative ===

<code>res=ddx(dat,dx,dy)</code>

Calculates the partial x derivative of dat, using centred differences. For a non-EW-cyclic grid, 0 is returned on the edges of the x domain.

=== ''dynlib.diag.ddy'' : partial y derivative ===

<code>res=ddy(dat,dx,dy)</code>

Calculates the partial y derivative of dat, using centred differences. For a non-EW-cyclic grid, 0 is returned on all edges of the x,y domain. For an EW-cyclic grid, 0 is returned on the first and last latitudes.

=== ''dynlib.diag.grad'' : 2-D gradient ===

<code>(resx,resy)=grad(dat,dx,dy)</code>

Calculates the 2-D gradient of dat, using centred differences in x and y. For a non-EW-cyclic grid, 0 is returned on all edges of the x,y domain. For an EW-cyclic grid, 0 is returned on the first and last latitudes.

=== ''dynlib.diag.lap2'' : 2-D laplacian ===

<code>res=lap2(dat,dx,dy)</code>

Calculates the 2-D laplacian of dat, using centred differences. For a non-EW-cyclic grid, 0 is returned on all edges of the x,y domain. For an EW-cyclic grid, 0 is returned on the first and last latitudes.

=== ''dynlib.diag.vor'' : 2-D vorticity ===

<code>res=vor(u,v,dx,dy)</code>

Calculates the z component of vorticity of (u,v), using centred differences.

=== ''dynlib.diag.div'' : 2-D divergence===

<code>res=div(u,v,dx,dy)</code>

Calculates the 2-D divergence of (u,v), using centred differences.

=== ''dynlib.diag.def_shear'' : shear deformation ===

<code>res=def_shear(u,v,dx,dy)</code>

Calculates the shear (antisymmetric) deformation of (u,v), using centred differences.

=== ''dynlib.diag.def_stretch'' : stretch deformation ===

<code>res=def_stretch(u,v,dx,dy)</code>

Calculates the stretch (symmetric) deformation of (u,v), using centred differences.

=== ''dynlib.diag.def_total'' : total deformation ===

<code>res=def_total(u,v,dx,dy)</code>

Calculates the total (rotation-independent) deformation of (u,v), using centred differences.

=== ''dynlib.diag.def_angle'' : deformation angle ===

<code>res=def_angle(u,v,dx,dy)</code>

Calculates the angle between the x-axis and the dilatation axis of the deformation of (u,v).

=== ''dynlib.diag.isopv_angle'' : iso-PV contour angle ===

<code>res=isopv_angle(pv,dx,dy)</code>

Calculates the angle between the x-axis and the iso-lines of PV.

=== ''dynlib.diag.beta'' : angle between dilatation axis and iso-PV contours ===

<code>res=beta(u,v,pv,dx,dy)</code>

Calculates the angle between the dilatation axis and the iso-lines of PV.

=== ''dynlib.diag.stretch_stir'' : fractional stretching rate and angular rotation rate of grad(PV)===

<code>(stretch,stir)=stretch_stir(u,v,pv,dx,dy)</code>

Returns real arrays, dim (nz,ny,nx):

stretch
= fractional PV gradient stretching rate
= 1/|gradPV| * d/dt(|gradPV|)
= gamma, 'stretching rate' (Lapeyre Klein Hua)<cite>LapKleHua1999</cite>
= -1/|gradPV| * Fn (Keyser Reeder Reed)<cite>KeyReeRee1988</cite>
Fn = 0.5*|gradPV|(D-E*cos(2*beta))
= 1/|gradPV| * F (Markowski Richardson)<cite>Mar2010</cite>

stir
= angular rotation rate of grad(PV) (aka stirring rate)
= d(theta)/dt (Lapeyre Klein Hua)<cite>LapKleHua1999</cite>

= 1/|gradPV| * Fs (Keyser Reeder Reed)<cite>KeyReeRee1988</cite>
Fs = 0.5*|gradPV|(vort+E*sin(2*beta))

=== ''dynlib.diag.geop_from_montgp'' : geopotential ===

<code>res = geop_from_montgp(m,theta,p,dx,dy)</code>

Calculates geopotential (res) from montgomery potential (m), potential temperature (theta) and pressure (p)

=== ''dynlib.diag.rev'' : PV gradient reversal ===

<code>(resa,resc,resai,resci,resaiy,resciy,tested) = rev(pv,highenough,latitudes,ddythres,dx,dy)</code>

Finds the reversals of PV y-gradient (where the negative y-gradient exceeds some threshold) and classifies them as c (cyclonic) or a (anticyclonic). Three measures of c and a reversals are returned (6 in total). Only points flagged in ''highenough'' are tested.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | pv
| real || (nz,ny,nx) || potential vorticity
|-
! width="80" | highenough
| int*1 || (nz,ny,nx) || array of flags denoting whether to test the point for reversal
|-
! width="80" | latitudes
| real || (ny) || vector of latitudes
|-
! width="80" | ddythres
| real || 0 || Cutoff y-gradient for pv
|}

''dynlib.diag.Highenough'' is typically the output of the ''highenough'' function, which returns 1 where the surface is sufficiently above ground level and 0 elsewhere.

''dynlib.diag.ddythres'' is the cutoff y-gradient for pv. The magnitude of (negative) d(pv)/dy must be above ddythres for reversal to be detected; this applies to revc, reva, revci,revai. Typical value: 4E-12.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | revc
| int*1 || (nz,ny,nx) || Flag =1 for cyclonic reversal (threshold test applied)
|-
! width="80" | reva
| int*1 || (nz,ny,nx) || Flag =1 for anticyclonic reversal (threshold test applied)
|-
! width="80" | revci
| real || (nz,ny,nx) || Absolute PV gradient where reversal is cyclonic (threshold test applied)
|-
! width="80" | revai
| real || (nz,ny,nx) || Absolute PV gradient where reversal is anticyclonic (threshold test applied)
|-
! width="80" | revciy
| real || (nz,ny,nx) || Absolute PV y-gradient where reversal is cyclonic (no threshold test applied)
|-
! width="80" | revaiy
| real || (nz,ny,nx) || Absolute PV y-gradient where reversal is anticyclonic (no threshold test applied)
|-
! width="80" | tested
| int*1 || (nz,ny,nx) || flag to 1 all tested points: where highenough==1 and point not on grid edge
|}

=== ''dynlib.diag.prepare_fft'' : make data periodic in y for FFT ===

<code>res = prepare_fft(thedata,dx,dy)</code>

Returns the data extended along complementary meridians (for fft).
For each lon, the reflected (lon+180) is attached below so that data is periodic in x and y.
NOTE: Input data must be lats -90 to 90, and nx must be even.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | thedata
| real || (nz,ny,nx) || input data
|}

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="120" | Dim
! width="300" | Description
|-
! width="80" | res
| real || (nz,2*ny-2,nx) || output data
|}

=== ''dynlib.diag.sum_kix'' : sum along k for flagged k-values ===

<code>(res,nres) = sum_kix(thedata,kix,dx,dy)</code>

Calculates sum along k dimension for k values which are flagged to 1 in kix vector (length nz).

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | thedata
| real || (nz,ny,nx) || input data
|-
! width="80" | kix
| int || (nz) || index flag for summation
|}

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | res
| real || (ny,nx) || (summed) output data
|-
! width="80" | nres
| int || 0 || Number of data summed = sum(kix)
|}

''dynlib.diag.sum_kix'' is typically used for calculating seasonal means. To do this, kix is set to 1 for times in the relevant season and 0 elsewhere. After (further) summing res and nres over all years, res/nres gives the mean for the season for all years.

=== ''dynlib.diag.high_enough'' : flags points which are sufficiently above ground ===

<code>res = high_enough(zdata,ztest,zthres,dx,dy)</code>

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | zdata
| real || (nz,ny,nx) || geopotential of gridpoints
|-
! width="80" | ztest
| real || (1,ny,nx) ||geopotential of topography
|-
! width="80" | zthres
| real || 0 ||threshold geopotential height difference
|}

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | res
| int*1 || (nz,ny,nx) ||
{| style="text-align:left;"
|-
| Flag array set to:
|-
|style="padding-left: 2em" |1 if zdata(t,y,x) > (ztest(1,y,x) + zthres)
|-
|style="padding-left: 2em" |0 otherwise
|}
|}

=== ''dynlib.diag.contour_rwb'' : detects RWB events, Riviere algorithm ===

<code>(beta_a_out,beta_c_out) = contour_rwb(pv_in,lonvalues,latvalues,ncon,lev,dx,dy)</code>

Detects the occurrence of anticyclonic and cyclonic wave-breaking events from a PV field on isentropic coordinates.

Reference: Riviere 2009 <ref>Riv2009</ref> : See the appendix C.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | pv_in
| real || (nz,ny,nx) || isentropic pv. Should be on a regular lat-lon grid and 180W must be the first longitude. (If 180W is not the first longitude, the outputs will have 180W as the first, so must be rearranged)
|-
! width="80" | lonvalues
| real || (nx) || vector of longitudes
|-
! width="80" | latvalues
| real || (ny) || vector of latitudes
|-
! width="80" | ncon
| int || 0 || number of contours to test, normally 41 or 21
|-
! width="80" | lev
| real || 0 || potential temperature of the level
|}

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | beta_a_out
| int || (nz,ny,nx) || flag array, =1 if anticyclonic wave breaking
|-
! width="80" | beta_c_out
| int || (nz,ny,nx) || flag array, =1 if cyclonic wave breaking
|}

=== ''dynlib.diag.v_g'' : geostrophic velocity ===

<code>(resx,resy) = v_g(mont,lat,dx,dy)</code>

Calculates geostrophic velocity. Returns zero on equator.

=== ''dynlib.diag.okuboweiss'' : Okubo-Weiss criterion===

<code>res = okuboweiss(u,v,dx,dy)</code>

Calculates Okubo-Weiss criterion lambda_0=1/4 * (sigma^2-omega^2)= 1/4 W, where ''sigma'' is total deformation and ''omega'' is vorticity.

This is the square of the eigenvalues in Okubo's paper<cite>Oku1969</cite> (assumes divergence is negligible).

=== ''dynlib.diag.laccel'' : Lagrangian acceleration===

<code>(resx,resy) = laccel(u,v,mont,lat,dx,dy)</code>

Calculates Lagrangian acceleration on the isentropic surface, based on Montgomery potential.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | u
| real || (nz,ny,nx) || zonal velocity
|-
! width="80" | v
| real || (nz,ny,nx) || meridional velocity
|-
! width="80" | mont
| real || (nz,ny,nx) || Montgomery potential
|-
! width="80" | lat
| real || (ny) || vector of latitudes
|}

=== ''dynlib.diag.accgrad_eigs'' : Lagrangian acceleration gradient tensor eigenvalues ===

<code>(respr,respi,resmr,resmi) = accgrad_eigs(u,v,mont,lat,dx,dy)</code>

Calculates eigenvalues of the lagrangian acceleration gradient tensor.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | u
| real || (nz,ny,nx) || zonal velocity
|-
! width="80" | v
| real || (nz,ny,nx) || meridional velocity
|-
! width="80" | mont
| real || (nz,ny,nx) || Montgomery potential
|-
! width="80" | lat
| real || (ny) || vector of latitudes
|}

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Returns:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | respr
| real || (nz,ny,nx) || Real part of positive eigenvalue
|-
! width="80" | respi
| real || (nz,ny,nx) || Imaginary part of positive eigenvalue
|-
! width="80" | resmr
| real || (nz,ny,nx) || Real part of negative eigenvalue
|-
! width="80" | resmi
| real || (nz,ny,nx) || Imaginary part of negative eigenvalue
|-
! width="80" | ncon
| int || 0 || number of contours to test, normally 41 or 21
|-
! width="80" | lev
| real || 0 || potential temperature of the level
|}

=== ''dynlib.diag.dphidt'' : Lagrangian derivative of compression axis angle ===

<code>res = dphidt(u,v,mont,lat,dx,dy)</code>

Calculates Lagrangian time derivative of compression axis angle: d(phi)/dt (ref Lapeyre et. al 1999<cite>LapKleHua1999</cite> ), from deformation and Lagrangian acceleration tensor.

{| border="1" class="wikitable" style="text-align:center;"
|+ style="text-align:left"| Arguments:
|-
|
! width="60" | Type
! width="80" | Dim
! width="300" | Description
|-
! width="80" | u
| real || (nz,ny,nx) || zonal velocity
|-
! width="80" | v
| real || (nz,ny,nx) || meridional velocity
|-
! width="80" | mont
| real || (nz,ny,nx) || Montgomery potential
|-
! width="80" | lat
| real || (ny) || vector of latitudes
|}

==References==
<bibtex>
@article{LapKleHua1999,
author = {Lapeyre, G. and Klein, P. and Hua, B. L.},
title = {Does the tracer gradient vector align with the strain eigenvectors in 2D turbulence?},
journal = {Physics of Fluids},
volume = {11},
number = {12},
pages = {3729-3737},
year = {1999},
url = {<Go to ISI>://000083495900013
http://scitation.aip.org/getpdf/servlet/GetPDFServlet?filetype=pdf&id=PHFLE6000011000012003729000001&idtype=cvips&doi=10.1063/1.870234&prog=normal},
}
</bibtex>
<bibtex>
@article{KeyReeRee1988,
author = {Keyser, D. and Reeder, M. J. and Reed, R. J.},
title = {A Generalization of Petterssen Frontogenesis Function and Its Relation to the Forcing of Vertical Motion},
journal = {Monthly Weather Review},
volume = {116},
number = {3},
pages = {762-780},
year = {1988},
url = {<Go to ISI>://A1988N255100017},
}
</bibtex>
<bibtex>
@book{Mar2010,
author = {Markowski, Paul},
title = {Mesoscale meteorology in midlatitudes},
publisher = {Chichester, West Sussex, UK ;Hoboken, NJ : Wiley-Blackwell, 2010},
url = {http://books.scholarsportal.info/viewdoc.html?id=/ebooks/ebooks2/wiley/2011-12-13/2/9780470682104},
year = {2010},
}
</bibtex>
<bibtex>
@article{Riv2009,
author = {Riviere, G.},
title = {Effect of Latitudinal Variations in Low-Level Baroclinicity on Eddy Life Cycles and Upper-Tropospheric Wave-Breaking Processes},
journal = {Journal of the Atmospheric Sciences},
volume = {66},
number = {6},
pages = {1569-1592},
year = {2009},
url = {<Go to ISI>://000267263300006},
}
</bibtex>
<bibtex>
@article{Oku1969,
author = {Okubo, A.},
title = {Horizontal Dispersion of Foreign Particles in Vicinity of Velocity Singularities Such as Convergences},
journal = {Transactions-American Geophysical Union},
volume = {50},
number = {4},
pages = {182-&},
year = {1969},
url = {<Go to ISI>://A1969C982700332},
}
</bibtex>

2013-01-25T10:59:03Z

Amu006: /* References */