Development Guide

Running the tests

julia --project=. -e 'using Pkg; Pkg.test()'

Or from the Julia REPL:

using Pkg
Pkg.test("Pelagos")

Tests are organised by development phase:

test/
├── eos/             # Phase 1: UNESCO EOS and pressure
├── velocity/        # Phases 2–4: velocity solver
│   ├── test_islands.jl
│   ├── test_baroclinic.jl
│   ├── test_barotropic.jl
│   └── test_continuity.jl
├── tracers/         # Phase 5: diffusion closures, forcing
├── integration/     # Phase 6: spinup (requires fixtures)
└── fixtures/        # Reference NetCDF output (not in git)

Fixture-based validation

Integration tests require NetCDF reference output from CLIMBER-X. See test/fixtures/README.md for how to generate and place these files.

Adding a new module

1. Create the source file in the appropriate src/ subdirectory.
2. Add include and using statements in src/Pelagos.jl.
3. Export public functions in src/Pelagos.jl.
4. Create a corresponding test file in test/.
5. Include the test file in test/runtests.jl.
6. Add documentation in docs/src/api/.

Coding conventions

• All 3D arrays: (nlon, nlat, nz) — longitude varies fastest.
• No magic numbers: all constants in src/parameters.jl.
• Type-stable functions: verify with @code_warntype.
• No module-level mutable globals.
• Default precision: Float64 throughout.
• No explicit horizontal loops in the baroclinic solve — use broadcasting.
• See CLAUDE.md for the full list of conventions.

Referencing the Fortran source

When implementing a physics module, read the corresponding CLIMBER-X Fortran file first:

Fortran files are in the CLIMBER-X repository at src/ocn/.

Validation tolerances

The rigid-lid residual is now constrained at machine precision because the corner-ψ barotropic correction makes the depth-integrated transport discretely divergence-free. See Architecture for details.