# xinvert
[](https://zenodo.org/badge/latestdoi/323045845)
[](https://xinvert.readthedocs.io/en/latest/?badge=latest)
[](https://badge.fury.io/py/xinvert)
[](https://github.com/miniufo/xinvert/actions/workflows/tests.yml)
[](https://app.travis-ci.com/miniufo/xinvert)
[](https://joss.theoj.org/papers/1fc4ac8f98c0778516971880727a3a94)
## 1. Introduction
Researches on meteorology and oceanography usually encounter [inversion problems](https://doi.org/10.1017/CBO9780511629570) 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`](http://xarray.pydata.org/en/stable/) becomes a popular data structure commonly used in [Big Data Geoscience](https://pangeo.io/). Since the whole 4D data, as well as the coordinate information, are all combined into [`xarray`](http://xarray.pydata.org/en/stable/), solving the inversion problem become quite straightforward and the only input would be just one [`xarray.DataArray`](http://xarray.pydata.org/en/stable/) of vorticity. Inversion on the spherical earth, like some meteorological problems, could utilize the spherical harmonics like [windspharm](https://github.com/ajdawson/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](https://mathworld.wolfram.com/SuccessiveOverrelaxationMethod.html) 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`](https://numba.pydata.org/). 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](./docs/source/notebooks/00_Introduction.ipynb).
Why `xinvert`?
- **Thinking and coding in equations:** User APIs are very close to the equations: unknowns are on the LHS of `=`, whereas the known forcings are on its RHS;
- **Genearlize all the steady-state problems:** All the known steady-state problems in geophysical fluid dynamics can be easily adapted to fit the solvers;
- **Very short parameter list:** Passing a single `xarray` forcing is enough for the inversion. Coordinates information is already encapsulated.
- **Flexible model parameters:** Model paramters can be either a constant, or varying with a specific dimension (like Coriolis $f$), or fully varying with space and time, due to the use of `xarray`'s broadcasting capability;
- **Parallel inverting:** The use of `xarray`, and thus `dask` allow parallel inverting, which is almost transparent to the user;
- **Pure Python code for C-code speed:** The use of `numba` allow pure python code in this package but native speed;
---
## 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**
```bash
pip install xinvert
```
**Install from github**
```bash
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 |
| :-----------: | :-----------: |
| <img src="./pics/Gallery_Streamfunction.png" width="380"><br/>[invert Poisson equation for<br/> horizontal streamfunction](./docs/source/notebooks/01_Poisson_equation_horizontal.ipynb) | <img src="./pics/Gallery_Overturning.png" width="380"><br/>[invert Poisson equation for<br/> overturning streamfunction](./docs/source/notebooks/02_Poisson_equation_vertical.ipynb) |
| <img src="./pics/Gallery_balanceMass.png" width="380"><br/>[invert geostrophic equation for<br/> balanced mass](./docs/source/notebooks/03_Balanced_mass_and_flow.ipynb) | <img src="./pics/Gallery_Eliassen.png" width="380"><br/>[invert Eliassen model for<br/> overturning streamfunction](./docs/source/notebooks/04_Eliassen_model.ipynb) |
| <img src="./pics/Gallery_SWMReference.png" width="380"><br/>[invert PV balance equation for<br/> steady reference state](./docs/source/notebooks/05_reference_SWM.ipynb)| <img src="./pics/Gallery_GillMatsuno.png" width="380"><br/>[invert Gill-Matsuno model for<br/> wind and mass fields](./docs/source/notebooks/07_Gill_Matsuno_model.ipynb) |
| <img src="./pics/Gallery_StommelMunk.png" width="380"><br/>[invert Stommel-Munk model for<br/> wind-driven ocean circulation](./docs/source/notebooks/08_Stommel_Munk_model.ipynb) | <img src="./pics/Gallery_Fofonoff.png" width="380"><br/>[invert Fofonoff model for<br/> inviscid/adiabatic steady state](./docs/source/notebooks/09_Fofonoff_flow.ipynb) |
| <img src="./pics/Gallery_Bretherton.png" width="380"><br/>[invert Bretherton model for<br/> steady flow over topography](./docs/source/notebooks/10_Bretherton_flow_over_topography.ipynb) | <img src="./pics/Gallery_Omega.png" width="380"><br/>[invert Omega equation for<br/> QG vertical velocity](./docs/source/notebooks/11_Omega_equation.ipynb) |
## 4 Animate the convergence of iteration
One can see the whole convergence process of SOR iteration as:
```python
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:
```bibtex
@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}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/miniufo/xinvert",
"name": "xinvert",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "invert inversion atmosphere ocean SOR successive-overrelaxation-iteration",
"author": "miniufo",
"author_email": "miniufo@163.com",
"download_url": "https://files.pythonhosted.org/packages/8f/4b/5e688ad85bfe8484a11d60dc714614e0a9e39e295d3d56896914a7406dce/xinvert-0.1.7.tar.gz",
"platform": null,
"description": "# xinvert\n\n[](https://zenodo.org/badge/latestdoi/323045845)\n\n[](https://xinvert.readthedocs.io/en/latest/?badge=latest)\n[](https://badge.fury.io/py/xinvert)\n\n[](https://github.com/miniufo/xinvert/actions/workflows/tests.yml)\n[](https://app.travis-ci.com/miniufo/xinvert)\n[](https://joss.theoj.org/papers/1fc4ac8f98c0778516971880727a3a94)\n\n\n\n\n\n## 1. Introduction\nResearches on meteorology and oceanography usually encounter [inversion problems](https://doi.org/10.1017/CBO9780511629570) 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.\n\n> $$\\nabla^2\\psi=\\zeta$$\n\nNowadays [`xarray`](http://xarray.pydata.org/en/stable/) becomes a popular data structure commonly used in [Big Data Geoscience](https://pangeo.io/). Since the whole 4D data, as well as the coordinate information, are all combined into [`xarray`](http://xarray.pydata.org/en/stable/), solving the inversion problem become quite straightforward and the only input would be just one [`xarray.DataArray`](http://xarray.pydata.org/en/stable/) of vorticity. Inversion on the spherical earth, like some meteorological problems, could utilize the spherical harmonics like [windspharm](https://github.com/ajdawson/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.\n\nMore importantly, this could be generalized into a numerical solver for elliptical equation using [SOR](https://mathworld.wolfram.com/SuccessiveOverrelaxationMethod.html) method, with spatially-varying coefficients. Various popular inversion problems in geofluid dynamics will be illustrated as examples.\n\nOne 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`](https://numba.pydata.org/). We may try our best to speed things up using more hardwares (possibly GPU).\n\nClassical 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](./docs/source/notebooks/00_Introduction.ipynb).\n\nWhy `xinvert`?\n\n- **Thinking and coding in equations:** User APIs are very close to the equations: unknowns are on the LHS of `=`, whereas the known forcings are on its RHS;\n- **Genearlize all the steady-state problems:** All the known steady-state problems in geophysical fluid dynamics can be easily adapted to fit the solvers;\n- **Very short parameter list:** Passing a single `xarray` forcing is enough for the inversion. Coordinates information is already encapsulated.\n- **Flexible model parameters:** Model paramters can be either a constant, or varying with a specific dimension (like Coriolis $f$), or fully varying with space and time, due to the use of `xarray`'s broadcasting capability;\n- **Parallel inverting:** The use of `xarray`, and thus `dask` allow parallel inverting, which is almost transparent to the user;\n- **Pure Python code for C-code speed:** The use of `numba` allow pure python code in this package but native speed;\n\n---\n## 2. How to install\n**Requirements**\n`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.\n\n\n**Install via pip**\n```bash\npip install xinvert\n```\n\n**Install from github**\n```bash\ngit clone https://github.com/miniufo/xinvert.git\ncd xinvert\npython setup.py install\n```\n\n\n---\n## 3. Examples:\nThis is a list of the problems that can be solved by `xinvert`:\n\n| Gallery | Gallery |\n| :-----------: | :-----------: |\n| <img src=\"./pics/Gallery_Streamfunction.png\" width=\"380\"><br/>[invert Poisson equation for<br/> horizontal streamfunction](./docs/source/notebooks/01_Poisson_equation_horizontal.ipynb) | <img src=\"./pics/Gallery_Overturning.png\" width=\"380\"><br/>[invert Poisson equation for<br/> overturning streamfunction](./docs/source/notebooks/02_Poisson_equation_vertical.ipynb) |\n| <img src=\"./pics/Gallery_balanceMass.png\" width=\"380\"><br/>[invert geostrophic equation for<br/> balanced mass](./docs/source/notebooks/03_Balanced_mass_and_flow.ipynb) | <img src=\"./pics/Gallery_Eliassen.png\" width=\"380\"><br/>[invert Eliassen model for<br/> overturning streamfunction](./docs/source/notebooks/04_Eliassen_model.ipynb) |\n| <img src=\"./pics/Gallery_SWMReference.png\" width=\"380\"><br/>[invert PV balance equation for<br/> steady reference state](./docs/source/notebooks/05_reference_SWM.ipynb)| <img src=\"./pics/Gallery_GillMatsuno.png\" width=\"380\"><br/>[invert Gill-Matsuno model for<br/> wind and mass fields](./docs/source/notebooks/07_Gill_Matsuno_model.ipynb) |\n| <img src=\"./pics/Gallery_StommelMunk.png\" width=\"380\"><br/>[invert Stommel-Munk model for<br/> wind-driven ocean circulation](./docs/source/notebooks/08_Stommel_Munk_model.ipynb) | <img src=\"./pics/Gallery_Fofonoff.png\" width=\"380\"><br/>[invert Fofonoff model for<br/> inviscid/adiabatic steady state](./docs/source/notebooks/09_Fofonoff_flow.ipynb) |\n| <img src=\"./pics/Gallery_Bretherton.png\" width=\"380\"><br/>[invert Bretherton model for<br/> steady flow over topography](./docs/source/notebooks/10_Bretherton_flow_over_topography.ipynb) | <img src=\"./pics/Gallery_Omega.png\" width=\"380\"><br/>[invert Omega equation for<br/> QG vertical velocity](./docs/source/notebooks/11_Omega_equation.ipynb) |\n\n\n\n## 4 Animate the convergence of iteration\nOne can see the whole convergence process of SOR iteration as:\n```python\nfrom xinvert import animate_iteration\n\n# output has 1 more dimension (iter) than input, which could be animated over.\n# Here 40 frames and loop 1 per frame (final state is after 40 iterations) is used.\npsi = animate_iteration(invert_Poisson, vor, iParams=iParams,\n loop_per_frame=1, max_frames=40)\n```\n\nSee the animation at the top.\n\n\n\n## 5 Cite\n\nIf you use the package in research, teaching, or other activities, we would be grateful\nif you mention `xinvert` and cite our paper in JOSS:\n\n```bibtex\n@article{Qian2023,\n doi = {10.21105/joss.05510},\n url = {https://doi.org/10.21105/joss.05510},\n year = {2023},\n publisher = {The Open Journal},\n volume = {8},\n number = {89},\n pages = {5510},\n author = {Yu-Kun Qian},\n title = {xinvert: A Python package for inversion problems in geophysical fluid dynamics}, journal = {Journal of Open Source Software}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Invert geofluid problems based on xarray, using SOR iteration",
"version": "0.1.7",
"project_urls": {
"Homepage": "https://github.com/miniufo/xinvert"
},
"split_keywords": [
"invert",
"inversion",
"atmosphere",
"ocean",
"sor",
"successive-overrelaxation-iteration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b9a106886d2d5634bded5325ece62db1fd5f2252d50a3b65895c5ec737efb88b",
"md5": "c53cfe25cadb3890b067077d7145659a",
"sha256": "e35ae225abbdbfd29ce9b38a1d5ebcc978e3d6b10d273fb51933a3236cebd87d"
},
"downloads": -1,
"filename": "xinvert-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c53cfe25cadb3890b067077d7145659a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 32657,
"upload_time": "2024-04-07T09:34:57",
"upload_time_iso_8601": "2024-04-07T09:34:57.300615Z",
"url": "https://files.pythonhosted.org/packages/b9/a1/06886d2d5634bded5325ece62db1fd5f2252d50a3b65895c5ec737efb88b/xinvert-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f4b5e688ad85bfe8484a11d60dc714614e0a9e39e295d3d56896914a7406dce",
"md5": "61bbc7e2871d1e53c1118db349ad16ed",
"sha256": "8e15bbb6ad3297796eeb0e725e25bc91474d5eaf3e3563b0da56fe9254be44b7"
},
"downloads": -1,
"filename": "xinvert-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "61bbc7e2871d1e53c1118db349ad16ed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 52750,
"upload_time": "2024-04-07T09:34:58",
"upload_time_iso_8601": "2024-04-07T09:34:58.569898Z",
"url": "https://files.pythonhosted.org/packages/8f/4b/5e688ad85bfe8484a11d60dc714614e0a9e39e295d3d56896914a7406dce/xinvert-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-07 09:34:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "miniufo",
"github_project": "xinvert",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "xarray",
"specs": []
},
{
"name": "dask",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "numba",
"specs": []
},
{
"name": "netCDF4",
"specs": []
}
],
"lcname": "xinvert"
}
JSON
