xinvert

xinvert: A Python package for inversion problems in geophysical fluid dynamics - Published in JOSS (2023)

Science Score: 93.0%

This score indicates how likely this project is to be science-related based on various indicators:

○
CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 6 DOI reference(s) in README and JOSS metadata
✓
Academic publication links
Links to: joss.theoj.org, zenodo.org
○
Committers with academic emails
○
Institutional organization owner
✓
JOSS paper metadata
Published in Journal of Open Source Software

Keywords

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

Last synced: 6 months ago · JSON representation

Repository

Invert geophysical fluid dynamic problems (elliptic partial differential equations) using SOR iteration method.

Basic Info

Host: GitHub
Owner: miniufo
License: mit
Language: Python
Default Branch: master
Homepage: https://xinvert.readthedocs.io/
Size: 243 MB

Statistics

Stars: 55
Watchers: 3
Forks: 16
Open Issues: 5
Releases: 7

Topics

Created about 5 years ago · Last pushed 11 months ago

Metadata Files

Readme License Citation

README.md

xinvert

GitHub

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?

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 via conda bash conda install -c conda-forge 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:

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 = animateiteration(invertPoisson, vor, iParams=iParams, loopperframe=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} }

Owner

Name: Yu-Kun Qian
Login: miniufo
Kind: user
Location: Guangzhou, China
Company: South China Sea Institute of Oceanography

Website: https://github.com/miniufo/
Twitter: miniufo
Repositories: 5
Profile: https://github.com/miniufo

geophysical fluid dynamics and python enthusiast

JOSS Publication

xinvert: A Python package for inversion problems in geophysical fluid dynamics

Published

September 06, 2023

DOI

10.21105/joss.05510

Volume 8, Issue 89, Page 5510

Authors

Yu-Kun Qian

State Key Laboratory of Tropical Oceanography, South China Sea Institute of Oceanology, Chinese Academy of Sciences, Guangzhou, China

Editor

Mehmet Hakan Satman

GitHub Events

Total

Watch event: 13
Issue comment event: 1
Push event: 2
Pull request event: 3
Fork event: 1

Last Year

Watch event: 13
Issue comment event: 1
Push event: 2
Pull request event: 3
Fork event: 1

Committers

Last synced: 7 months ago

All Time

Total Commits: 180
Total Committers: 7
Avg Commits per committer: 25.714
Development Distribution Score (DDS): 0.472

Past Year

Commits: 5
Committers: 2
Avg Commits per committer: 2.5
Development Distribution Score (DDS): 0.2

Top Committers

Name	Email	Commits
miniufo	m**o@1**m	95
miniufo	m****m	68
Nora Loose	n**e@g**m	7
Qianye Su	1****e	4
Navid C. Constantinou	n****y	3
Mehmet Hakan Satman	m**n@g**m	2
Damien Irving	i**n@g**m	1

Committer Domains (Top 20 + Academic)

163.com: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 30
Total pull requests: 9
Average time to close issues: 4 months
Average time to close pull requests: about 14 hours
Total issue authors: 12
Total pull request authors: 6
Average comments per issue: 3.53
Average comments per pull request: 1.11
Merged pull requests: 7
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 1
Pull requests: 2
Average time to close issues: N/A
Average time to close pull requests: about 24 hours
Issue authors: 1
Pull request authors: 2
Average comments per issue: 1.0
Average comments per pull request: 0.5
Merged pull requests: 1
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

miniufo (10)
NoraLoose (4)
DamienIrving (4)
ngyawali (3)
PovedaGerman (1)
nngyawali (1)
FuncUny (1)
navidcy (1)
jejjohnson (1)
silver-fox-9244 (1)
hs2112 (1)
ealucy (1)

Pull Request Authors

NoraLoose (3)
SQYQianYe (2)
DamienIrving (2)
jbytecode (1)
navidcy (1)
codacy-badger (1)

Top Labels

Issue Labels

documentation (5) enhancement (4) bug (1)

Pull Request Labels

Packages

Total packages: 1
Total downloads:
- pypi 36 last-month

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 5
Total maintainers: 1

pypi.org: xinvert

Invert geofluid problems based on xarray, using SOR iteration

Homepage: https://github.com/miniufo/xinvert
Documentation: https://xinvert.readthedocs.io/
License: MIT
Latest release: 0.1.7
published almost 2 years ago

Versions: 5
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 36 Last month

Rankings

Dependent packages count: 7.1%

Forks count: 12.1%

Stargazers count: 14.2%

Average: 16.6%

Dependent repos count: 32.8%

Maintainers (1)

MiniUFO

Last synced: 6 months ago

Dependencies

setup.py pypi

dask *
numba *
numpy *
xarray *

.github/workflows/draft-pdf.yml actions

actions/checkout v3 composite
actions/upload-artifact v1 composite
openjournals/openjournals-draft-action master composite

.github/workflows/python-publish.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite
pypa/gh-action-pypi-publish 27b31702a0e7fc50959f5ad993c78deac1bdfc29 composite

.github/workflows/tests.yml actions

actions/checkout v3 composite
conda-incubator/setup-miniconda v2 composite

docs/requirements.txt pypi

dask *
nbsphinx *
numba *
numpydoc *
xarray *

requirements.txt pypi

dask *
netCDF4 *
numba *
scipy *
xarray *

environment.yml pypi

xinvert

Science Score: 93.0%

Keywords

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

xinvert

1. Introduction

2. How to install

3. Examples:

4 Animate the convergence of 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.

5 Cite

Owner

JOSS Publication

xinvert: A Python package for inversion problems in geophysical fluid dynamics

Authors

Editor

Tags

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: xinvert

Rankings

Maintainers (1)

Dependencies