sbudget

Tools for computing the spectral kinetic energy budget of a dry, fully compressible, non-hydrostatic atmosphere on regional domains. Designed to analyze energy transfers across scales in both wavenumber and physical space. The package targets model outputs on either regular lon–lat (equiangular) or Cartesian horizontal grids, with a geometric-height vertical coordinate.

Spectral transfer mode (--mode spectral_budget)

This mode computes the budget of horizontal kinetic energy (HKE) in wavenumber space using FFTs, suitable for studying spectral energy transfers across scales. The budget is formulated following Peng et al. (2015), and Wang et al.(2018) as:

$$\partial_t E_h(k)=C_{A\to h}(k)+T_h(k)+L_h(k)+\partial_z F_{\uparrow}(k)+\mathrm{Div}_h(k)+H_h (k)+J_h(k)+D_h(k).$$

• $E_h(k)$ — isotropic spectrum of HKE at wavenumber $k$.
• $C_{A\to h}(k)$ — conversion from available potential energy (APE) to HKE.
• $T_h(k)$ — nonlinear spectral transfer of HKE (across scales).
• $L_h(k)$ — linear spectral transfer of HKE due to Coriolis.
• $F_{\uparrow}(k)$ — net vertical flux of HKE + pressure pressure-work flux
• $\mathrm{Div}_h(k)$ — tendency from 3-D divergence processes.
• $H_h(k)$ — diabatic tendency (heating/cooling).
• $J_h(k)$ — adiabatic nonconservative tendency.
• $D_h(k)$ — diffusive/dissipative tendency (viscosity, filters).

Terms $H_h(k)$ and $D_h(k)$ are model-physics dependent and therefore omitted here.

Features

• FFT backed chunk-friendly xarray/dask implementation (out-of-core). Fully parallel along non-horizontal spatial dimensions
• NetCDF output with CF-style metadata (horizontal coordinates replaced with wavenumber in rad/m)

Inter-scale transfer mode (--mode scale_transfer)

This mode computes local scale-to-scale transfers at specified wavelengths based on third-order structure functions. This code is largely based on LoSSETT . The energy transfer from scales larger than $\ell$ to scales smaller than $\ell$ is derived in Duchon & Robert (2000) as:

$$\mathcal{T}_{\ell} := \frac{1}{4} \int \nabla G _\ell(\mathbf{r}) \cdot \delta \mathbf{u} |\delta \mathbf{u}|^2 \mathrm{d}^d \mathbf{r},$$

where, $\delta\mathbf{u}:=\mathbf{u}(x + r)-\mathbf{u}(x)$ is a velocity increment, and $G_{\ell}(r)$ is a filter kernel with characteristic length scale $\ell$. See refences for more details.

References:

• J. Peng, L. Zhang, and J. Guan (2015). Applications of a Moist Nonhydrostatic Formulation of the Spectral Energy Budget to Baroclinic Waves. J. Atmos. Sci., 70(7), 2055-2073. https://doi.org/10.1175/JAS-D-14-0306.1

• Wang, Y., L. Zhang, J. Peng, and S. Liu, 2018: Mesoscale Horizontal Kinetic Energy Spectra of a Tropical Cyclone. J. Atmos. Sci., 75, 3579–3596, https://doi.org/10.1175/JAS-D-17-0391.1.

• J. Duchon, and R. Robert (2000). Inertial energy dissipation for weak solutions of incompressible Euler and Navier-Stokes equations. Nonlinearity, 13(1), 249. https://doi.org/10.1088/0951-7715/13/1/312

Install

# Install package directly via git
pip install git+https://github.com/deterministic-nonperiodic/sbudget.git

Install manually with clean environment (recommended)

# clone repository
git clone https://github.com/deterministic-nonperiodic/sbudget.git
cd sbudget
# Install clean environment
conda env create -f environment.yml
conda activate budget
# editable install
pip install -e .

Examples

Quick help

 sbudget --help

Inspect configuration file

 sbudget inspect examples/config.yaml

Compute budget based on configuration file

 sbudget compute examples/config.yaml

Inspect input file(s)

 sbudget inspect examples/config.yaml \
--input-path ./data/model_output.nc \
--dims z,lat,lon \
--engine h5netcdf

Write to a different file or store type (NetCDF/Zarr)

 sbudget compute examples/config.yaml \
--output-path ./out/budget.nc \
--store netcdf --overwrite

Switch to scale transfer mode in physical space and define wavelengths (meters). This mode calculates inter-scale transfers at specified wavelengths based on third-order structure functions.

 sbudget compute examples/config.yaml \
--mode scale_transfer \
--scales 1000,5000,10000

Perform analysis on selected levels and scales. Note, level selection is ignored in "spectral_budget" mode since continuous sampling is required for computing vertical gradients

 sbudget compute examples/config.yaml --mode scale_transfer \ 
--levels 60e3 --scales 20e3,35e3