Quick Start Tutorial

Run your first QGYBJ+.jl simulation in 5 minutes.

Minimal Example

using QGYBJplus

# Configure (Lx, Ly, Lz are REQUIRED)
config = create_simple_config(
    Lx=500e3, Ly=500e3, Lz=4000.0,  # Domain size [m]
    nx=64, ny=64, nz=32,             # Grid points
    dt=0.001, total_time=1.0,        # Time stepping
    output_interval=100
)

# Run
result = run_simple_simulation(config)

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

Step-by-Step Breakdown

Step 1: Create Configuration

config = create_simple_config(
    Lx = 500e3,        # Domain length x [m] (REQUIRED)
    Ly = 500e3,        # Domain length y [m] (REQUIRED)
    Lz = 4000.0,       # Domain depth [m] (REQUIRED)
    nx = 64, ny = 64, nz = 32,  # Grid dimensions
    dt = 0.001,        # Time step
    total_time = 1.0,  # Total simulation time
)

Step 2: Run Simulation

result = run_simple_simulation(config)

This returns a Simulation object containing:

• result.state — Final state with all fields
• result.grid — Grid information
• result.params — Simulation parameters

Step 3: Access Results

state = result.state

# Spectral fields (complex, in Fourier space)
state.psi    # Streamfunction
state.L⁺A    # Wave envelope (L⁺A where L⁺ = L - k_h²/4)
state.A      # Wave amplitude (diagnosed from L⁺A)
state.C      # Vertical derivative of A

# Physical fields (real, in physical space)
state.u      # Zonal velocity
state.v      # Meridional velocity
state.w      # Vertical velocity

Step 4: Compute Diagnostics

# Mean flow kinetic energy
KE = flow_kinetic_energy(state.u, state.v)

# Wave energy components per YBJ+ equation (4.7)
WKE, WPE, WCE = compute_detailed_wave_energy(state, result.grid, result.params)

# Vertically-averaged wave kinetic energy (uses LA = L⁺A + k_h²/4 * A)
WE = wave_energy_vavg(state.L⁺A, state.A, grid, plans)

Common Configuration Options

config = create_simple_config(
    Lx=500e3, Ly=500e3, Lz=4000.0,
    nx=64, ny=64, nz=32,

    # Physics options
    ybj_plus = true,          # YBJ+ formulation (default)
    linear = false,           # Set true to disable nonlinear terms
    inviscid = true,          # Set true for no dissipation
    no_wave_feedback = true,  # Set true for one-way coupling (eddies → waves only)

    # Stratification
    stratification_type = :constant_N,  # or :skewed_gaussian
)

Output Files

By default, simulations save to ./output_simple/:

output_simple/
├── state0001.nc          # Field snapshots
├── state0002.nc
└── diagnostic/           # Energy time series
    ├── wave_KE.nc
    ├── mean_flow_KE.nc
    └── total_energy.nc

What's Next?