QG-log(p) diagnostics (pyzome.qglogp)

Functions for computing diagnostics based on QG-log(p) assumptions. Most of the diagnostics require that their input data include a log-pressure altitude coordinate (since many of the quantities take derivatives as a function of altitude). The function pyzome.qglogp.add_logp_altitude() can be used to add this coordinate to an xarray Dataset/DataArray.

Functions

pyzome.qglogp.add_logp_altitude(dat: Dataset, plev_coord: str = '', H: float = SCALE_HEIGHT, p0: float = PREF) → Dataset
pyzome.qglogp.add_logp_altitude(dat: DataArray, plev_coord: str = '', H: float = SCALE_HEIGHT, p0: float = PREF) → DataArray

A convenience function for adding a log-pressure altitude coordinate to an xarray Dataset or DataArray

Parameters:

  • dat (xarray.Dataset or xarray.DataArray) – data containing a pressure coordinate in SI units (Pa)

  • plev_coord (string, optional) – The name of the pressure coordinate in the input data. Defaults to an empty string, for which the function will try to infer the pressure coordinate

  • H (float, optional) – Scale height used to compute the log-pressure altitude

  • p0 (float, optional) – Reference pressure for computation of log-pressure altitude. Defaults to 100000 Pa for Earth.

Returns:

The input data with an added log-pressure altitude coordinate named ‘z’

Return type:

xarray.Dataset or xarray.DataArray

pyzome.qglogp.buoyancy_frequency_squared(T: DataArray, Rs: float = 287.058, Cp: float = 1004.64, H: float = 7000) → DataArray

Calculates the buoyancy frequency squared given temperature.

Parameters:

  • T (xarray.DataArray) – The temperature data in units of Kelvin

  • Rs (float, optional) – Specific gas constant. Defaults to 287.058 J/kg/K for dry air of the Earth.

  • Cp (float, optional) – Specific heat capacity at constant pressure. Defaults to 1004.64 J/kg/K for dry air of the Earth.

  • H (float, optional) – The scale height used to calculate the log-pressure altitude. Defaults to 7000 m.

Returns:

Nsq – The buoyancy frequency squared, in units of s-2.

Return type:

xarray.DataArray

pyzome.qglogp.merid_grad_qgpv(u: DataArray, Nsq: DataArray | float, lat_coord: str = '', rho_s: float = 1.2, H: float = 7000, Omega: float = 7.29211e-05, a: float = 6371230.0, terms: bool = False) → DataArray | tuple[DataArray, DataArray, DataArray]

Calculates the meridional gradient in the quasi-geostrophic potential vorticity (QGPV) given the zonal mean zonal winds, and the squared buoyancy frequency.

Parameters:

  • u (xarray.DataArray) – The zonal mean zonal wind data.

  • Nsq (xarray.DataArray or float) – The squared buoyancy frequency. Nsq need not have the same dimensions as u, but it should be consistent with u in the sense that it must be able to be properly broadcasted when used in computations with u (it is common to use a reference Nsq that only varies with altitude, or latitude/altitude)

  • lat_coord (str, optional) – The coordinate name of the latitude dimension. If given an empty string (the default), the function tries to infer which coordinate corresponds to the latitude

  • rho_s (float, optional) – The reference density for air at the surface. Defaults to 1.2 kg m-3 for density of air on Earth.

  • H (float, optional) – The scale height used to calculate the log-pressure altitude. Defaults to 7000 m.

  • Omega (float, optional) – Planetary rotation rate. Defaults to 7.29211e-5 s-1 for the Earth.

  • a (float, optional) – Planetary radius. Defaults to 6.37123e6 m for the Earth.

  • terms (bool, optional) – If False (the default), the function returns the sum of the 3 terms making up the QGPV. If True, the function returns the 3 individual terms as a tuple containing the contributions from (1) the change in planetary vorticity with latitude; (2) the horizontal curvature of the zonal mean zonal wind; and (3) the vertical curvature of the zonal mean zonal wind.

Returns:

qgpv_grad – Depending on the value of the terms keyword argument, either the full meridional QGPV gradient field, or a tuple of the individual terms that make up the total, in units of s-1.

Return type:

xarray.DataArray or tuple of DataArrays

pyzome.qglogp.refractive_index(u: DataArray, q_phi: DataArray, Nsq: DataArray | float, k: int, phase_speed: float = 0, lat_coord: str = '', rho_s: float = 1.2, H: float = 7000, Omega: float = 7.29211e-05, a: float = 6371230.0, cd_approx_term: bool = False, terms: bool = False) → DataArray | tuple[DataArray, DataArray, DataArray]

Calculates the (squared) refractive index for a given distribution of zonal mean zonal winds, meridional QGPV gradients, buoyancy frequency squared, and zonal wavenumber+phase speed.

Parameters:

  • u (xarray.DataArray) – The zonal mean zonal wind data.

  • q_phi (xarray.DataArray) – The meridional QGPV gradient

  • Nsq (xarray.DataArray or float) – The squared buoyancy frequency. Nsq need not have the same dimensions as u, but it should be consistent with u and q_phi in the sense that it must be able to be properly broadcasted when used in computations (it is common to use a reference Nsq that is constant value or time-mean field)

  • k (int) – The zonal wavenumber

  • phase_speed (float, optional) – The phase speed of the wave, in m s-1.

  • lat_coord (str, optional) – The coordinate name of the latitude dimension. If given an empty string (the default), the function tries to infer which coordinate corresponds to the latitude

  • rho_s (float, optional) – The reference density for air at the surface. Defaults to 1.2 kg m-3 for density of air on Earth.

  • H (float, optional) – The scale height used to calculate the log-pressure altitude. Defaults to 7000 m.

  • Omega (float, optional) – Planetary rotation rate. Defaults to 7.29211e-5 s-1 for the Earth.

  • a (float, optional) – Planetary radius. Defaults to 6.37123e6 m for the Earth.

  • cd_approx_term (bool, optional) – If False (the default), the function uses the standard buoyancy frequency term involving only Nsq. If True, the function uses an approximation originally derived by Charney & Drazin involving the vertical curvature of the buoyancy frequency. See Weinberger et al., 2021, “The Efficiency of Upward Wave Propagation near the Tropopause: Importance of the Form of the Refractive Index” for details of this term.

  • terms (bool, optional) – If False (the default), the function returns the sum of the 3 terms making up the squared refractive index. If True, the function returns the 3 individual terms as a tuple containing the contributions from (1) the contribution from the meridional QGPV gradient; (2) the zonal wavenumber; and (3) the buoyancy.

Returns:

RIsq – Depending on the value of the terms keyword argument, either the full squared refractive index field, or a tuple of the individual terms that make the total, in units of m-2.

Return type:

xarray.DataArray or tuple of 3 DataArrays

pyzome.qglogp.plumb_wave_activity_flux(psip: DataArray, Nsq: DataArray | float, components: list[str] = ['x', 'y', 'z'], lat_coord: str = '', lon_coord: str = '', Omega: float = 7.29211e-05, a: float = 6371230.0) → list[DataArray]

Calculates the components of the Plumb wave activity flux given the eddy streamfunction and buoyancy frequency squared.

Parameters:

  • psip (xarray.DataArray) – The eddy streamfunction in units of m+2 s-1

  • Nsq (xarray.DataArray or float) – The squared buoyancy frequency. Nsq need not have the same dimensions as psip, but it should be consistent with psip in the sense that it must be able to be properly broadcasted when used in computations (it is common to use a reference Nsq that is constant value or time-mean field)

  • components (list, optional) – The components of the wave activity flux to compute and return in the output. ‘x’ refers to the east-west component, ‘y’ refers to the north- south component, and ‘z’ refers to the vertical component.

  • lat_coord (str, optional) – The coordinate name of the latitude dimension. If given an empty string (the default), the function tries to infer which coordinate corresponds to the latitude

  • lon_coord (str, optional) – The coordinate name of the longitude dimension. If given an empty string (the default), the function tries to infer which coordinate corresponds to the longitude

  • Omega (float, optional) – Planetary rotation rate. Defaults to 7.29211e-5 s-1 for the Earth.

  • a (float, optional) – Planetary radius. Defaults to 6.37123e6 m for the Earth.

Returns:

waf – The wave activity flux vector components consistent with the desired components keyword argument.

Return type:

list of xarray.DataArray