QGYBJ+.jl

QGYBJ+.jl implements the Quasi-Geostrophic Young-Ben Jelloul Plus (QG-YBJ+) model for simulating the interaction between near-inertial waves and mesoscale ocean eddies.

Start Here

What This Model Does

The ocean contains two important types of motion at different scales:

Mesoscale Eddies (~100 km scale)

• Giant rotating vortices lasting weeks to months
• Contain ~90% of ocean kinetic energy
• Move slowly (~10 cm/s)

Near-Inertial Waves (~10 km scale)

• Wind-generated internal waves oscillating every ~17 hours
• Key driver of ocean mixing
• Propagate through the water column

These two types of motion interact strongly: eddies refract and focus waves, while waves can feed energy back into the mean flow. QGYBJ+.jl simulates this coupled system using:

• Quasi-geostrophic (QG) dynamics for the balanced eddy flow
• YBJ+ equations for the near-inertial wave envelope
• Two-way coupling capturing wave-mean flow energy exchange

Key Features

Quick Example

using QGYBJplus

# Create configuration (domain size is REQUIRED)
config = create_simple_config(
    Lx = 500e3, Ly = 500e3, Lz = 4000.0,  # 500km × 500km × 4km
    nx = 64, ny = 64, nz = 32,
    dt = 0.001, total_time = 1.0
)

# Run simulation
result = run_simple_simulation(config)

# Check energy
println("Kinetic Energy: ", flow_kinetic_energy(result.state.u, result.state.v))

Documentation Guide

For Beginners

• Key Concepts — Core ideas without code
• Installation — How to install QGYBJ+.jl
• Quick Start — Your first simulation in 5 minutes
• Worked Example — Detailed walkthrough with explanations

Physics & Theory

• Model Overview — Physical background and equations
• QG Equations — Quasi-geostrophic dynamics
• YBJ+ Wave Model — Near-inertial wave formulation
• Numerical Methods — Algorithms and discretization

User Guide

• Configuration — Setting up simulations
• Stratification — Ocean density profiles
• I/O and Output — Saving and loading data
• Diagnostics — Energy and analysis tools

Advanced Topics

• MPI Parallelization — Running on clusters
• Particle Advection — Lagrangian tracking
• Performance Tips — Optimization strategies

Reference

• Core Types — QGParams, Grid, State
• Physics Functions — Operators and solvers
• Full Index — Complete function listing

Installation

using Pkg
Pkg.add(url="https://github.com/subhk/QGYBJplus.jl")

MPI parallel support (MPI.jl, PencilArrays.jl, PencilFFTs.jl) is included as a dependency and will be installed automatically.

See Installation Guide for detailed instructions.

How Simulations Work

The typical simulation workflow is:

1. Configure — Create QGParams with grid size, domain, physics options
2. Setup — Initialize Grid, State, FFT plans, and elliptic coefficients
3. Run — Time-step the prognostic fields (q, B) with inversions each step
4. Output — Save fields and diagnostics to NetCDF files

See Worked Example for a complete walkthrough.

Citation

If you use QGYBJ+.jl in your research, please cite:

@software{qgybj_jl,
  author = {Kar, Subhajit},
  title = {QGYBJ+.jl: A Julia Implementation of the QG-YBJ+ Model},
  year = {2025},
  url = {https://github.com/subhk/QGYBJplus.jl}
}

Key References

• Asselin & Young (2019): YBJ+ formulation for penetration of near-inertial waves
• Xie & Vanneste (2015): Wave feedback mechanism (qʷ term)
• Young & Ben Jelloul (1997): Original YBJ wave envelope equation

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

QGYBJ+.jl is released under the MIT License.