Tutorials Overview

This section contains comprehensive tutorials that guide you through solving various types of PDEs with Tarang.jl. Each tutorial builds on concepts from previous ones, so we recommend following them in order if you're new to spectral methods or Tarang.jl.

Tutorial Path

For Beginners

If you're new to spectral methods or Tarang.jl, start here:

1. First Steps - Basic workflow and simple diffusion problem
2. 2D Rayleigh-Bénard Convection - Complete fluid dynamics example
3. Boundary Conditions - Master the boundary condition system

Intermediate Topics

Once comfortable with basics:

1. Fluid Dynamics Examples - Navier-Stokes, rotating convection, and turbulence examples
2. Surface Dynamics - Fractional Laplacian, surface quasi-geostrophic dynamics
3. 3D Turbulent Flow - 3D problems with advanced parallelization
4. Analysis and Output - Data management and visualization
5. Eigenvalue Problems - Linear stability analysis

Advanced Topics

For experienced users:

• Custom Operators - Define new differential operators
• Optimization Guide - Performance tuning

Tutorial List

Initial Value Problems (IVP)

Time-evolution problems where you integrate PDEs forward in time.

Boundary Value Problems (BVP)

Steady-state problems with boundary conditions.

Eigenvalue Problems (EVP)

Linear stability analysis and normal modes.

Surface and Boundary Dynamics

Problems with dynamics confined to surfaces or boundaries.

Wave-Mean Flow Analysis

Special Topics

Problem Types Explained

Initial Value Problems (IVP)

When to use: Time-dependent PDEs where you know the initial state and want to evolve forward in time.

Examples:

• Fluid dynamics (Navier-Stokes)
• Heat diffusion
• Wave propagation
• Reaction-diffusion systems

Typical structure:

problem = IVP(fields)
add_equation!(problem, "∂t(u) - nu*Δ(u) = -u*∂x(u)")
solver = InitialValueSolver(problem, RK222())

while solver.sim_time < t_end
    step!(solver, dt)
end

Boundary Value Problems (BVP)

When to use: Steady-state problems where you solve for the spatial distribution given boundary conditions.

Types:

• LBVP: Linear boundary value problems
• NLBVP: Nonlinear boundary value problems (require iteration)

Examples:

• Steady-state heat conduction
• Poisson equation
• Steady Stokes flow

Typical structure:

problem = LBVP(fields)
add_equation!(problem, "lap(T) = f")
add_bc!(problem, "T(z=0) = 0")
add_bc!(problem, "T(z=1) = 1")

solver = BoundaryValueSolver(problem)
solve!(solver)

Eigenvalue Problems (EVP)

When to use: Linear stability analysis, computing normal modes, or finding eigenvalues of differential operators.

Examples:

• Hydrodynamic stability
• Normal mode analysis
• Resonance frequencies

Typical structure:

problem = EVP(fields, eigenvalue=:sigma)
add_equation!(problem, "sigma*u = -lap(u) + f")
add_bc!(problem, "u(z=0) = 0")

solver = EigenvalueSolver(problem)
eigenvalues = solve!(solver, nev=10)

Choosing a Tutorial

By Physics

Fluid Dynamics:

• Start: 2D Rayleigh-Bénard
• Intermediate: Fluid Dynamics Examples, Surface Dynamics
• Advanced: 3D Turbulence, Channel Flow

Geophysical Flows:

• Start: Surface Dynamics (SQG, QG)
• Intermediate: Rotating Shallow Water (wave-mean separation)
• Advanced: GQL Approximation (zonal jets, turbulence closure)

Heat Transfer:

• Start: First Steps (diffusion)
• Advanced: 2D Rayleigh-Bénard (convection)

Stability Analysis:

• Start: Eigenvalue Problems

By Technique

Want to learn:

• MPI parallelization → Running with MPI
• Boundary conditions → Boundary Conditions
• Output and analysis → Analysis and Output
• 3D problems → 3D Turbulence

By Complexity

Beginner: Basic concepts, single field

• First Steps

Intermediate: Multiple fields, coupled equations

• 2D Rayleigh-Bénard
• Fluid Dynamics Examples
• Surface Dynamics
• Boundary Conditions
• Analysis and Output

Advanced: 3D problems, advanced analysis

• 3D Turbulence
• Eigenvalue Problems

Common Patterns

Setting Up a Simulation

Every tutorial follows this pattern:

# 1. MPI initialization
using Tarang, MPI
MPI.Init()

# 2. Domain setup
coords = CartesianCoordinates(...)
dist = Distributor(coords, mesh=...)
bases = (basis1, basis2, ...)
domain = Domain(dist, bases)

# 3. Fields
field1 = ScalarField(...)
field2 = VectorField(...)

# 4. Problem
problem = IVP([field1, field2, ...])
add_equation!(problem, "...")
add_bc!(problem, "...")

# 5. Solver
solver = InitialValueSolver(problem, timestepper)

# 6. Time loop
while solver.sim_time < t_end
    step!(solver, dt)
end

# 7. Cleanup
MPI.Finalize()

Adding Analysis

Common analysis tasks:

# CFL condition
cfl = CFL(problem)
add_velocity!(cfl, u)

# File output
handler = add_netcdf_handler(
    solver,
    "outputs",
    fields=[u, p, T],
    write_interval=0.1
)

# Custom diagnostics
function compute_diagnostics(solver, u, T)
    ke = 0.5 * mean(u.data .^ 2)
    temp_mean = mean(T.data)
    return (ke=ke, temp=temp_mean)
end

Getting Help

If you're stuck on a tutorial:

1. Check the complete example at the end of each tutorial
2. Look at the source code in the examples/ directory
3. Search the API reference for function documentation
4. Ask on GitHub Discussions for community help

Contributing Tutorials

We welcome tutorial contributions! See the Contributing Guide for details on:

• Tutorial format and style
• Adding Jupyter notebooks
• Including visualizations
• Testing tutorial code

Next Steps

Ready to start? Pick a tutorial from the list above or continue with:

• 2D Rayleigh-Bénard Convection for a complete fluid dynamics example
• Boundary Conditions to master BC specification
• Running with MPI for parallel computing details