Package: xinvert
xinvert1. IntroductionResearches on meteorology and oceanography usually encounterinversion problemsthat 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$$Nowadaysxarraybecomes a popular data structure commonly used inBig Data Geoscience.  Since the whole 4D data, as well as the coordinate information, are all combined intoxarray, solving the inversion problem become quite straightforward and the only input would be just onexarray.DataArrayof vorticity.  Inversion on the spherical earth, like some meteorological problems, could utilize the spherical harmonics likewindspharm, 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 usingSORmethod, 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 usingexplicit loops in Pythonwill bee-x-t-r-e-m-e-l-y ... s-l-o-w!  A very suitable solution here is to usenumba.  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 atthis notebook.Whyxinvert?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 singlexarrayforcing 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 ofxarray's broadcasting capability;Parallel inverting:The use ofxarray, and thusdaskallow parallel inverting, which is almost transparent to the user;Pure Python code for C-code speed:The use ofnumbaallow pure python code in this package but native speed;2. How to installRequirementsxinvertis developed under the environment withxarray(=version 0.15.0),dask(=version 2.11.0),numpy(=version 1.15.4), andnumba(=version 0.51.2).  Older versions of these packages are not well tested.Install via pippipinstallxinvertInstall from githubgitclonehttps://github.com/miniufo/xinvert.gitcdxinvert
pythonsetup.pyinstall3. Examples:This is a list of the problems that can be solved byxinvert:GalleryGalleryinvert Poisson equation forhorizontal streamfunctioninvert Poisson equation foroverturning streamfunctioninvert geostrophic equation forbalanced massinvert Eliassen model foroverturning streamfunctioninvert PV balance equation forsteady reference stateinvert Gill-Matsuno model forwind and mass fieldsinvert Stommel-Munk model forwind-driven ocean circulationinvert Fofonoff model forinviscid/adiabatic steady stateinvert Bretherton model forsteady flow over topographyinvert Omega equation forQG vertical velocity4 Animate the convergence of iterationOne can see the whole convergence process of SOR iteration as:fromxinvertimportanimate_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.