Welcome to xomega’s documentation!¶

xomega is a Python package for solving the generalized omega equation which takes the form

\[N^2\nabla_\text{h}w_\text{b} + f_0^2\frac{\partial^2w_\text{b}}{\partial z^2} = \beta\frac{\partial b}{\partial x} + \nabla_\text{h}\cdot{\bf Q}(u,v,\theta,\Phi).\]

Given the right-hand side of the equation, the package inverts the vertical velocity fields at each time and depth in wavenumber space, i.e.

\[-\kappa^2N^2\hat{w}_\text{b} + f_0^2\frac{\partial^2 \hat{w}_\text{b}}{\partial z^2} = ik\beta\hat{b} + (ik\hat{Q}_x + il\hat{Q}_y).\]

where \(\mathbf{\kappa} = (k,l)\) is the horizontal wavenumber vector. The right-hand side, neglecting the turbulent correlation terms is \({\bf Q} = {\bf Q}_\text{tw} + {\bf Q}_\text{da}\) where

\[{\bf Q}_\text{tw} = -2\Big(\frac{\partial {\bf u}}{\partial x} \cdot \nabla b, \frac{\partial {\bf u}}{\partial y} \cdot \nabla b\Big)\]

\[{\bf Q}_\text{da} = f \Big( \frac{\partial v}{\partial x}\frac{\partial u_\text{a}}{\partial z} - \frac{\partial u}{\partial x}\frac{\partial v_\text{a}}{\partial z}, \frac{\partial v}{\partial y}\frac{\partial u_\text{a}}{\partial z} - \frac{\partial u}{\partial y}\frac{\partial v_\text{a}}{\partial z} \Big).\]

where \({\bf u}_\text{a}\ (={\bf u}-{\bf u}_\text{g})\) is the ageotrophic velocity. Assuming the total flow to be in geostrophic balance \({\bf u}={\bf u}_\text{g}=\frac{\hat{z}}{f}\times\nabla_\text{h}\Phi\), the generalized form reduces to the quasi-geostrophic Omega equation.

Note

xomega is at early stage of development and will keep improving in the future. The rigid-lid API should be quite stable, but minor utilities could change in the next version. If you find any bugs or would like to request any enhancements, please raise an issue on GitHub.

Contents¶

Current limitations¶

Uniform Vertical Grid¶

The algorithm used in xomega currently only supports input on uniform vertical grid. Calculation using data on non-uniform grid will give no error but the discretization error may be significant.

Rigid-lid Boundary Conditions¶

Currently, only rigid-lid boundary conditions are implemented.

Installation¶

The quickest way¶

xomega is compatible both with Python 2 and 3. The major dependencies are xarray and dask. The best way to install them is using Anaconda.:

$ conda install xarray dask .

Install xomega from GitHub repo¶

To get the latest version:

$ git clone https://github.com/roxyboy/xomega.git
$ cd xomega
$ python setup.py install .

Developers can track source code changes by:

$ git clone https://github.com/roxyboy/xomega.git
$ cd xomega
$ python setup.py build .

API¶

xomega¶

xomega.xomega.w_rigid(N2, f0, beta, Frhs, kx, ky, dZ, dZ0=None, dZ1=None, zdim='Zl', dim=None, coord=None)[source]¶

Inverts the Omega equation given by Giordani and Planton (2000) to get the balanced vertical velocity (\(w_b\)) for rigid-lid boundary conditions given the right-hand side fo the equation.

Parameters:

N2 : float or xarray.DataArray: The buoyancy frequency.
f0 : float: Coriolis parameter.
beta : float: Meridional gradient of the Coriolis parameter for a beta-plane approximation.
Frhs : xarray.DataArray: The Fourier transform of the right-hand side of the Omega equation. The last two dimensions should be the meridional and zonal wavenumber.
kx : xarray.DataArray: Zonal wavenumber.
ky : xarray.DataArray: Meridional wavenumber.
dZ : float or xarray.DataArray: Vertical distance between grid. This should take constant value(s) for best numerical percision.
dZ0 : float or xarray.DataArray, optional: Top vertical distance between grids.
dZ1 : float or xarray.DataArray, optional: Bottom vertical distance between grids.
zdim : str, optional: Dimension name of the vertical axis of Frhs.
dim : list, optional: List of the xarray.DataArray output.
coord : dict, optional: Dictionary of the xarray.DataArray output.

Returns:

wa : xarray.DataArray: The quasi-geostrophic vertical velocity.