How qianyesu/skyborn works
1. What this repository is: Skyborn is a Python climate/atmospheric analysis toolkit organized as a source-layout package under src/skyborn. The architecture is split between high-level Python APIs, native numerical kernels, and thin wrappers that adapt those kernels to xarray-style gridded data.
2. Top-level package boundary: skyborn/__init__.py exposes the public package, while most functionality lives in domain subpackages: calc, interp, gridfill, spharm, windspharm, geostrophic, troposphere, plot, and cdo. This makes the package feel like a toolkit of mostly independent scientific modules rather than one monolithic application.
3. Native computation layer: The heaviest numerical work is implemented in Fortran, Cython, and f2py-style interfaces inside subpackage fortran/, .pyf, and .pyx files. Each compiled area has a meson.build, so the build boundary is important: Python code orchestrates, native code computes, and the wrappers translate data back and forth.
4. Interpolation and regridding subsystem: src/skyborn/interp provides interpolation, regridding, and missing-value handling. Its flow is Python API → Fortran kernels such as linint2, rcm2rgrid, grid2triple, and triple2grid → optional xarray convenience wrappers, which makes this a core data-shaping layer for gridded meteorological fields.
5. Gap filling subsystem: src/skyborn/gridfill is a separate numerical pipeline for filling missing values, backed by a Cython extension (_gridfill.pyx) and tested against stored .npy reference arrays. The architecture here is “solver core + Python wrapper + xarray adapter,” with the solver focused on Poisson-style spatial reconstruction.
6. Spherical harmonic / wind diagnostics: src/skyborn/spharm contains the low-level spherepack-derived spherical harmonic machinery, while src/skyborn/windspharm builds user-facing wind diagnostics on top of it. The data flow is wind fields → spectral transforms / Helmholtz-related calculations in Fortran-backed code → derived products like streamfunction, velocity potential, divergence, and vorticity.
7. Climate calculation layer: src/skyborn/calc is the analytical hub for higher-level climate computations such as calculations, emergent constraints, Mann-Kendall trend tests, gradients, and causality. This layer sits above the native kernels and packages domain workflows into reusable Python functions and xarray-friendly interfaces.
8. Specialized geophysical modules: Three focused subpackages extend the toolkit into specific atmospheric diagnostics: calc/GPI for Genesis Potential Index calculations, calc/geostrophic for geostrophic wind derivation, and calc/troposphere for tropopause height / standard-atmosphere calculations. Each has its own native interface and xarray wrapper, so they are architecturally parallel rather than deeply coupled.
9. Plotting and presentation: src/skyborn/plot contains visualization helpers such as curved quiver plots and general plotting utilities. These modules consume outputs from the scientific layer and are used mainly for analysis output and documentation figures, not as core compute dependencies.
10. External integration and data-bound artifacts: The repo includes src/skyborn/cdo, indicating a wrapper/integration boundary with external CDO tooling for climate data operations. DATA/hot_model_ECS.xlsx, example notebooks, and .nc files support emergent-constraint and wind-analysis demos, while tests and docs validate the scientific kernels against stored reference outputs and published examples.
11. Build, test, and docs pipeline: The repository is packaged for distribution with pyproject.toml, setup.py, and CI workflows that build wheels, run coverage, and generate docs. Sphinx documentation in docs/ and extensive tests under tests/ and subpackage test folders are part of the architecture because they anchor the public API and verify the compiled-code boundaries across platforms.
Main entry points: skyborn/__init__.py skyborn · test_interp_interpolation.py tests · calc/__init__.py calc · spharm/__init__.py spharm
Components 21
Python APIs
Public package and domain-level scientific workflows
- skyborn · Top-level public package boundary
src/skyborn/__init__.py - calc · Higher-level climate calculations and diagnostics
src/skyborn/calc/__init__.py - interp · Interpolation, regridding, and missing-value handling
src/skyborn/interp/__init__.py - gridfill · Spatial missing-value solver and wrapper layer
src/skyborn/gridfill/__init__.py - spharm · Spherepack-derived spherical harmonic machinery
src/skyborn/spharm/__init__.py - windspharm · User-facing wind diagnostics built on spectral transforms
src/skyborn/windspharm/__init__.py - plot · Analysis plotting helpers and presentation utilities
src/skyborn/plot/__init__.py - cdo · Integration boundary for CDO-based climate operations
src/skyborn/cdo/__init__.py - ROF · Robust trend and preprocessing workflow module
src/skyborn/ROF/__init__.py - GPI iface · Genesis Potential Index Python interface layer
src/skyborn/calc/GPI/interface.py - Geo iface · Geostrophic wind derivation interface layer
src/skyborn/calc/geostrophic/interface.py - Tropo iface · Tropopause and standard-atmosphere interface layer
src/skyborn/calc/troposphere/tropopause.py
Native Kernels
Compiled numerical cores and build boundaries
- GPI kernel · Potential intensity and tropical cyclone core routines
src/skyborn/calc/GPI/fortran/tropical_cyclone_potential_intensity.f90 - Geo kernel · Geostrophic wind computation kernel
src/skyborn/calc/geostrophic/fortran/z2geouv.f90 - Tropo kernel · Tropopause height and atmosphere routines
src/skyborn/calc/troposphere/fortran/tropopause_height.f90 - Interp kernels · Interpolation and regridding compiled routines
src/skyborn/interp/fortran/linint2.f - gridfill ext · Compiled gap-filling solver core
src/skyborn/gridfill/_gridfill.pyx - spherepack · Spherical harmonic transform and inverse transform routines
src/skyborn/spharm/src/fortran/shags.f
Connections 29
- skyborn → calc: exports · Public package exposes domain calculations
- skyborn → interp: exports · Public package exposes interpolation tools
- skyborn → gridfill: exports · Public package exposes gap-filling tools
- skyborn → spharm: exports · Public package exposes spectral machinery
- skyborn → windspharm: exports · Public package exposes wind diagnostics
- skyborn → plot: exports · Public package exposes plotting helpers
- skyborn → cdo: exports · Public package exposes CDO integration
- calc → GPI iface: includes · Specialized GPI workflow lives under calculations
- calc → Geo iface: includes · Geostrophic workflow lives under calculations
- calc → Tropo iface: includes · Troposphere workflow lives under calculations
- GPI iface → GPI kernel: wraps · Python interface delegates to compiled potential-intensity routines
- Geo iface → Geo kernel: wraps · Python interface delegates to compiled geostrophic solver
- Tropo iface → Tropo kernel: wraps · Python interface delegates to compiled tropopause solver
- interp → Interp kernels: wraps · Interpolation API translates to Fortran kernels
- gridfill → gridfill ext: wraps · Python gap-filling API sits on Cython core
- spharm → spherepack: wraps · Spectral transforms are implemented in Fortran-backed spherepack code
- windspharm → spharm: builds on · Wind diagnostics are derived from spherical harmonic operations
- build → Interp kernels: builds · Meson-based build compiles native interpolation kernels
- build → gridfill ext: builds · Project build compiles the Cython extension
- build → spherepack: builds · Project build compiles the spherepack-backed core
- docs → calc: documents · API docs and notebooks describe climate calculations
- docs → windspharm: documents · Tutorials cover wind diagnostics
- tests → interp: verifies · Tests cover interpolation and regridding behavior
- tests → gridfill: verifies · Tests validate the gap-filling solver
- tests → spharm: verifies · Tests validate spherical harmonic computations
- tests → windspharm: verifies · Tests validate derived wind diagnostics
- tests → GPI iface: verifies · Tests exercise the GPI wrapper layer
- tests → Geo iface: verifies · Tests exercise the geostrophic wrapper layer
- tests → Tropo iface: verifies · Tests exercise the troposphere wrapper layer