miniufo / xinvert

Invert geophysical fluid dynamic problems (elliptic partial differential equations) using SOR iteration method.
https://xinvert.readthedocs.io/
MIT License
43 stars 16 forks source link
atmospheric-science eliassen-model geophysical-fluid-dynamics gill-matsuno-model inversion-problem meteorology munk-stommel oceanography omega-equation poisson-equation pv-inversion streamfunction successive-over-relaxation velocity-potential wind-driven-circulation

xinvert

DOI GitHub Documentation Status PyPI version Workflow pytest Build Status status

animate plot

1. Introduction

Researches on meteorology and oceanography usually encounter inversion problems that need to be solved numerically. One of the classical inversion problem is to solve Poisson equation for a streamfunction $\psi$ given the vertical component of vorticity $\zeta$ and proper boundary conditions.

$$\nabla^2\psi=\zeta$$

Nowadays xarray becomes a popular data structure commonly used in Big Data Geoscience. Since the whole 4D data, as well as the coordinate information, are all combined into xarray, solving the inversion problem become quite straightforward and the only input would be just one xarray.DataArray of vorticity. Inversion on the spherical earth, like some meteorological problems, could utilize the spherical harmonics like windspharm, which would be more efficient using FFT than SOR used here. However, in the case of ocean, SOR method is definitely a better choice in the presence of irregular land/sea mask.

More importantly, this could be generalized into a numerical solver for elliptical equation using SOR method, with spatially-varying coefficients. Various popular inversion problems in geofluid dynamics will be illustrated as examples.

One problem with SOR is that the speed of iteration using explicit loops in Python will be e-x-t-r-e-m-e-l-y ... s-l-o-w! A very suitable solution here is to use numba. We may try our best to speed things up using more hardwares (possibly GPU).

Classical problems include Gill-Matsuno model, Stommel-Munk model, QG omega model, PV inversion model, Swayer-Eliassen balance model... A complete list of the classical inversion problems can be found at this notebook.

Why xinvert?


2. How to install

Requirements xinvert is developed under the environment with xarray (=version 0.15.0), dask (=version 2.11.0), numpy (=version 1.15.4), and numba (=version 0.51.2). Older versions of these packages are not well tested.

Install via pip

pip install xinvert

Install from github

git clone https://github.com/miniufo/xinvert.git
cd xinvert
python setup.py install

3. Examples:

This is a list of the problems that can be solved by xinvert:

Gallery Gallery

invert Poisson equation for
horizontal streamfunction

invert Poisson equation for
overturning streamfunction

invert geostrophic equation for
balanced mass

invert Eliassen model for
overturning streamfunction

invert PV balance equation for
steady reference state

invert Gill-Matsuno model for
wind and mass fields

invert Stommel-Munk model for
wind-driven ocean circulation

invert Fofonoff model for
inviscid/adiabatic steady state

invert Bretherton model for
steady flow over topography

invert Omega equation for
QG vertical velocity

4 Animate the convergence of iteration

One can see the whole convergence process of SOR iteration as:

from xinvert import animate_iteration

# output has 1 more dimension (iter) than input, which could be animated over.
# Here 40 frames and loop 1 per frame (final state is after 40 iterations) is used.
psi = animate_iteration(invert_Poisson, vor, iParams=iParams,
                        loop_per_frame=1, max_frames=40)

See the animation at the top.

5 Cite

If you use the package in research, teaching, or other activities, we would be grateful if you mention xinvert and cite our paper in JOSS:

@article{Qian2023,
    doi = {10.21105/joss.05510},
    url = {https://doi.org/10.21105/joss.05510},
    year = {2023},
    publisher = {The Open Journal},
    volume = {8},
    number = {89},
    pages = {5510},
    author = {Yu-Kun Qian},
    title = {xinvert: A Python package for inversion problems in geophysical fluid dynamics}, journal = {Journal of Open Source Software}
}