# qianyesu/skyborn architecture

> Architecture diagram of the GitHub repository qianyesu/skyborn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qianyesu/skyborn
- Repository: https://github.com/qianyesu/skyborn

## Overview

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: [`src/skyborn/__init__.py`](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/__init__.py) (skyborn), [`tests/test_interp_interpolation.py`](https://github.com/qianyesu/skyborn/blob/main/tests/test_interp_interpolation.py) (tests), [`src/skyborn/calc/__init__.py`](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/__init__.py) (calc), [`src/skyborn/spharm/__init__.py`](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/spharm/__init__.py) (spharm)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_python["Python APIs"]
  node_skyborn["skyborn<br/>package root<br/>[__init__.py]"]
  node_calc["calc<br/>analysis hub<br/>[__init__.py]"]
  node_interp["interp<br/>regridding<br/>[__init__.py]"]
  node_gridfill["gridfill<br/>gap fill<br/>[__init__.py]"]
  node_spharm["spharm<br/>spectral core<br/>[__init__.py]"]
  node_windspharm["windspharm<br/>wind diagnostics<br/>[__init__.py]"]
  node_plot["plot<br/>visualization<br/>[__init__.py]"]
  node_cdo["cdo<br/>external wrapper<br/>[__init__.py]"]
  node_rof["ROF<br/>trend workflow<br/>[__init__.py]"]
  node_gpi_iface["GPI iface<br/>domain wrapper<br/>[interface.py]"]
  node_geo_iface["Geo iface<br/>domain wrapper<br/>[interface.py]"]
  node_trop_iface["Tropo iface<br/>domain wrapper<br/>[tropopause.py]"]
end

subgraph group_grp_native["Native Kernels"]
  node_gpi_fort["GPI kernel<br/>fortran module"]
  node_geo_fort["Geo kernel<br/>fortran module<br/>[z2geouv.f90]"]
  node_trop_fort["Tropo kernel<br/>fortran module"]
  node_interp_fort["Interp kernels<br/>fortran kernels<br/>[linint2.f]"]
  node_gridfill_ext["gridfill ext<br/>cython extension<br/>[_gridfill.pyx]"]
  node_spharm_fort["spherepack<br/>fortran core<br/>[shags.f]"]
end

subgraph group_grp_support["Support"]
  node_build["build<br/>packaging<br/>[pyproject.toml]"]
  node_docs["docs<br/>documentation<br/>[index.rst]"]
  node_tests["tests<br/>validation"]
end

node_skyborn -->|"exports"| node_calc
node_skyborn -->|"exports"| node_interp
node_skyborn -->|"exports"| node_gridfill
node_skyborn -->|"exports"| node_spharm
node_skyborn -->|"exports"| node_windspharm
node_skyborn -->|"exports"| node_plot
node_skyborn -->|"exports"| node_cdo
node_calc -->|"includes"| node_gpi_iface
node_calc -->|"includes"| node_geo_iface
node_calc -->|"includes"| node_trop_iface
node_gpi_iface -->|"wraps"| node_gpi_fort
node_geo_iface -->|"wraps"| node_geo_fort
node_trop_iface -->|"wraps"| node_trop_fort
node_interp -->|"wraps"| node_interp_fort
node_gridfill -->|"wraps"| node_gridfill_ext
node_spharm -->|"wraps"| node_spharm_fort
node_windspharm -->|"builds on"| node_spharm
node_build -->|"builds"| node_interp_fort
node_build -->|"builds"| node_gridfill_ext
node_build -->|"builds"| node_spharm_fort
node_docs -->|"documents"| node_calc
node_docs -->|"documents"| node_windspharm
node_tests -->|"verifies"| node_interp
node_tests -->|"verifies"| node_gridfill
node_tests -->|"verifies"| node_spharm
node_tests -->|"verifies"| node_windspharm
node_tests -->|"verifies"| node_gpi_iface
node_tests -->|"verifies"| node_geo_iface
node_tests -->|"verifies"| node_trop_iface

click node_skyborn "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/__init__.py"
click node_calc "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/__init__.py"
click node_interp "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/interp/__init__.py"
click node_gridfill "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/gridfill/__init__.py"
click node_spharm "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/spharm/__init__.py"
click node_windspharm "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/windspharm/__init__.py"
click node_plot "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/plot/__init__.py"
click node_cdo "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/cdo/__init__.py"
click node_rof "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/ROF/__init__.py"
click node_gpi_iface "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/GPI/interface.py"
click node_gpi_fort "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/GPI/fortran/tropical_cyclone_potential_intensity.f90"
click node_geo_iface "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/geostrophic/interface.py"
click node_geo_fort "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/geostrophic/fortran/z2geouv.f90"
click node_trop_iface "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/troposphere/tropopause.py"
click node_trop_fort "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/troposphere/fortran/tropopause_height.f90"
click node_interp_fort "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/interp/fortran/linint2.f"
click node_gridfill_ext "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/gridfill/_gridfill.pyx"
click node_spharm_fort "https://github.com/qianyesu/skyborn/blob/main/src/skyborn/spharm/src/fortran/shags.f"
click node_build "https://github.com/qianyesu/skyborn/blob/main/pyproject.toml"
click node_docs "https://github.com/qianyesu/skyborn/blob/main/docs/source/index.rst"
click node_tests "https://github.com/qianyesu/skyborn/blob/main/tests/test_interp_interpolation.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skyborn,node_calc,node_interp,node_gridfill,node_spharm,node_windspharm,node_plot,node_cdo,node_rof,node_gpi_iface,node_geo_iface,node_trop_iface toneBlue
class node_gpi_fort,node_geo_fort,node_trop_fort,node_interp_fort,node_gridfill_ext,node_spharm_fort toneAmber
class node_build,node_docs,node_tests toneMint
```

## Components

### Python APIs

Public package and domain-level scientific workflows

- [skyborn](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/__init__.py): package root · Top-level public package boundary · `src/skyborn/__init__.py`
- [calc](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/__init__.py): analysis hub · Higher-level climate calculations and diagnostics · `src/skyborn/calc/__init__.py`
- [interp](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/interp/__init__.py): regridding · Interpolation, regridding, and missing-value handling · `src/skyborn/interp/__init__.py`
- [gridfill](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/gridfill/__init__.py): gap fill · Spatial missing-value solver and wrapper layer · `src/skyborn/gridfill/__init__.py`
- [spharm](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/spharm/__init__.py): spectral core · Spherepack-derived spherical harmonic machinery · `src/skyborn/spharm/__init__.py`
- [windspharm](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/windspharm/__init__.py): wind diagnostics · User-facing wind diagnostics built on spectral transforms · `src/skyborn/windspharm/__init__.py`
- [plot](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/plot/__init__.py): visualization · Analysis plotting helpers and presentation utilities · `src/skyborn/plot/__init__.py`
- [cdo](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/cdo/__init__.py): external wrapper · Integration boundary for CDO-based climate operations · `src/skyborn/cdo/__init__.py`
- [ROF](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/ROF/__init__.py): trend workflow · Robust trend and preprocessing workflow module · `src/skyborn/ROF/__init__.py`
- [GPI iface](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/GPI/interface.py): domain wrapper · Genesis Potential Index Python interface layer · `src/skyborn/calc/GPI/interface.py`
- [Geo iface](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/geostrophic/interface.py): domain wrapper · Geostrophic wind derivation interface layer · `src/skyborn/calc/geostrophic/interface.py`
- [Tropo iface](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/troposphere/tropopause.py): domain wrapper · Tropopause and standard-atmosphere interface layer · `src/skyborn/calc/troposphere/tropopause.py`

### Native Kernels

Compiled numerical cores and build boundaries

- [GPI kernel](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/GPI/fortran/tropical_cyclone_potential_intensity.f90): fortran module · Potential intensity and tropical cyclone core routines · `src/skyborn/calc/GPI/fortran/tropical_cyclone_potential_intensity.f90`
- [Geo kernel](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/geostrophic/fortran/z2geouv.f90): fortran module · Geostrophic wind computation kernel · `src/skyborn/calc/geostrophic/fortran/z2geouv.f90`
- [Tropo kernel](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/calc/troposphere/fortran/tropopause_height.f90): fortran module · Tropopause height and atmosphere routines · `src/skyborn/calc/troposphere/fortran/tropopause_height.f90`
- [Interp kernels](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/interp/fortran/linint2.f): fortran kernels · Interpolation and regridding compiled routines · `src/skyborn/interp/fortran/linint2.f`
- [gridfill ext](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/gridfill/_gridfill.pyx): cython extension · Compiled gap-filling solver core · `src/skyborn/gridfill/_gridfill.pyx`
- [spherepack](https://github.com/qianyesu/skyborn/blob/main/src/skyborn/spharm/src/fortran/shags.f): fortran core · Spherical harmonic transform and inverse transform routines · `src/skyborn/spharm/src/fortran/shags.f`

### Support

Docs, tests, examples, and packaging

- [build](https://github.com/qianyesu/skyborn/blob/main/pyproject.toml): packaging · Project build and wheel configuration · `pyproject.toml`
- [docs](https://github.com/qianyesu/skyborn/blob/main/docs/source/index.rst): documentation · Sphinx documentation and tutorials · `docs/source/index.rst`
- [tests](https://github.com/qianyesu/skyborn/blob/main/tests/test_interp_interpolation.py): validation · Repository-wide test suite and reference outputs · `tests/test_interp_interpolation.py`

## Connections

- 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
