Skip to content

Oceananigans.jl — Agent Rules ​

Project Overview ​

Oceananigans.jl is a Julia package for fast, friendly, flexible, ocean-flavored fluid dynamics on CPUs and GPUs. It solves the incompressible (Boussinesq) Navier-Stokes equations with models including: nonhydrostatic (with free surfaces), hydrostatic free-surface, and shallow water — on RectilinearGrid, LatitudeLongitudeGrid, ConformalCubedSphereGrid, TripolarGrid, and ImmersedBoundaryGrid.

Language & Environment ​

  • Julia 1.10+ | CPU and GPU (CUDA, AMD, Metal, OneAPI)

  • Key packages: KernelAbstractions.jl, CUDA.jl, Enzyme.jl, Reactant.jl

  • Style: ExplicitImports.jl for source code; using Oceananigans for examples/tests

Critical Rules ​

Kernel Functions (GPU compatibility) ​

  • Use @kernel / @index (KernelAbstractions.jl)

  • Kernels must be type-stable and allocation-free

  • Use ifelse — never short-circuiting if/else in kernels

  • No error messages, no Models inside kernels

  • Mark functions called inside kernels with @inline

  • Never loop over grid points outside kernels — use launch!

Type Stability & Memory ​

  • All structs must be concretely typed

  • Type annotations are for dispatch, not documentation

  • Minimize allocation; favor inline computation

  • Never hardcode Float64: no literal 0.0 or 1.0 in kernels or constructors. Use zero(grid), one(grid), convert(FT, 1//2), or rational literals

Imports ​

  • Source code: explicit imports (checked by tests)

  • Never write import in src/ or ext/ — not to extend functions (import Oceananigans.Fields: set!), not to bring in a module (import Dates), not to alias one (import Oceananigans.Utils as UT). Bring names in with using Module: Module, name (or using Module: Module as M), and extend with the qualified name: Module.function_name(...) = ... or function Module.function_name() ... end (e.g. Fields.set!(f::MyField, a) = ..., Base.:+(a::ZeroField, b::AbstractField) = b, @binary Base.:*, CUDA.@device_override @inline function KernelAbstractions.__validindex(...))

  • Examples/docs: rely on using Oceananigans; never explicitly import exported names

Docstrings ​

  • Use $(TYPEDSIGNATURES) when the signature has no default values, and $(SIGNATURES) when it does. Import both from Oceananigans.Utils, not DocStringExtensions: they show defaults with DocStringExtensions v0.10 and fall back to plain signatures with v0.9. Write the signature by hand only when the generated one would mislead, e.g. when it would drop a type the method dispatches on.

  • ALWAYS jldoctest blocks, NEVER plain julia blocks — doctests are tested; plain blocks rot

  • Include # output with verifiable output; prefer show methods over boolean comparisons

  • Use unicode for math (Δt, η, ρ), not LaTeX — LaTeX doesn't render in the REPL

Model Constructors ​

  • grid is positional: NonhydrostaticModel(grid; closure=nothing)

  • ShallowWaterModel(grid, gravitational_acceleration; ...) — both positional

  • Omit semicolon when there are no keyword arguments: NonhydrostaticModel(grid) not NonhydrostaticModel(grid;)

Naming Conventions ​

  • Files: snake_case matching the type they define — nonhydrostatic_model.jl

  • Types/Constructors: PascalCase only for true constructors — NonhydrostaticModel

  • Functions: snake_case — time_step!; functions that return values are never PascalCase

  • Kernels: may prefix with underscore — _compute_tendency_kernel

  • Variables: English long name or readable unicode math notation — never mix abbreviated and full forms (e.g., cond vs condition) to imply a difference; be specific

Module Structure ​

src/
├── Oceananigans.jl                 # Main module, exports
├── Architectures.jl                # CPU/GPU architecture abstractions
├── Grids/                          # Grid types and constructors
├── OrthogonalSphericalShellGrids/  # Tripolar and other curvilinear spherical-shell grids
├── ImmersedBoundaries/             # ImmersedBoundaryGrid and immersed boundary conditions
├── MultiRegion/                    # Multi-region grids (ConformalCubedSphereGrid)
├── DistributedComputations/        # MPI-distributed architectures and halo communication
├── Fields/                         # Field types and operations
├── AbstractOperations/             # Lazy operations on fields (KernelFunctionOperation, etc.)
├── Operators/                      # Finite difference operators
├── BoundaryConditions/             # Boundary condition types
├── Forcings/                       # Forcing functions
├── Coriolis/                       # Coriolis formulations
├── BuoyancyFormulations/           # Buoyancy models
├── Advection/                      # Advection schemes
├── TurbulenceClosures/             # LES and eddy viscosity models
├── Models/                         # Model implementations
│   ├── NonhydrostaticModels/
│   ├── HydrostaticFreeSurfaceModels/
│   ├── ShallowWaterModels/
│   └── LagrangianParticleTracking/
├── TimeSteppers/                   # Time stepping schemes
├── Solvers/                        # Poisson and tridiagonal solvers
├── Simulations/                    # High-level simulation interface
├── Diagnostics/                    # Diagnostics and callbacks
├── OutputWriters/                  # File I/O
├── OutputReaders/                  # FieldTimeSeries and output loading
└── Utils/                          # Utilities and helpers

Common Pitfalls ​

  1. Type instability in kernels ruins GPU performance

  2. Overconstraining types: use annotations for dispatch, not documentation

  3. Missing imports: tests will catch this — add to using statements

  4. Plain julia blocks in docstrings: always use jldoctest

  5. Subtle bugs from missing method imports, especially in extensions

  6. Expecting unexported names: consider exporting them rather than changing user scripts

  7. Extending getproperty to fix undefined property bugs: fix on the caller side instead

  8. "Type is not callable" errors: variable name shadows a function — rename or qualify

  9. Quick fixes that break correctness: if a test fails after a change, revisit the original edit

  10. Commented-out code: delete it. Git is the journal — don't leave commented code, debugging artifacts, or stale copy-paste remnants

  11. 2D indexing on fields: always use 3D indexing (field[i, j, k]). 2D indexing works by coincidence on some fields but is unsupported and will break

  12. Hardcoded Float64: never use 0.0, 1.0 in kernels or constructors; use zero(grid) etc.

  13. Scope creep in PRs: keep changes focused on a single concern. Unrelated cleanup goes in a separate PR

  14. Modifying Project.toml dependencies: never add, remove, or change [deps] or [weakdeps] in the root Project.toml unless the task absolutely requires it. Dependency changes have wide-reaching consequences — they affect CI, load time, and downstream compatibility. Only touch [compat] bounds when explicitly asked.

Git Workflow ​

Follow ColPrac. Feature branches, descriptive commits, update tests and docs with code changes, check CI before merging.

Design Principles ​

  • Dispatch over conditionals: use Julia's type system and multiple dispatch instead of if/else branching. Backend-specific code goes in ext/ extensions, not if branches in src/

  • Use on_architecture for data transfers — never manual Array() / CuArray() calls

  • Defaults serve the common case: avoid nothing defaults when a concrete default (like CPU()) covers 80% of usage. Minimize boilerplate for the typical user.

  • Keyword argument names must be consistent across related types and constructors

  • Always use explicit return in functions longer than one expression

  • One operation per line as default; break long expressions across lines

Agent Behavior ​

  • Prioritize type stability and GPU compatibility

  • Follow established patterns in existing code

  • Add tests for new functionality; update exports when adding public API

  • Reference physics equations in comments when implementing dynamics

Further Reading ​

Detailed reference docs are in .agents/ — read on demand:

DocumentContent
.agents/testing.mdFull testing guidelines, running tests, debugging
.agents/documentation.mdBuilding docs, fast builds, doctest details, writing examples
.agents/validation.mdReproducing paper results step-by-step

Auto-loading Rules ​

Rules in .claude/rules/ load automatically when you touch matching files:

  • kernel-rules.md — GPU kernel requirements (src/)

  • docstring-rules.md — docstring and jldoctest conventions (src/)

  • testing-rules.md — test writing and running (test/)

  • docs-rules.md — documentation building and style (docs/)

  • examples-rules.md — Literate.jl example conventions (examples/)

  • style-rules.md — naming, notation, and comment style (src/, test/, validation/, examples/)

  • restriction-rules.md — small diffs, no scaffolding, scarce comments, and a self-review checklist (src/, test/, validation/, examples/)

  • julia-repl-rules.md — prefer an MCP Julia REPL over Bash when available (always)

Skills (slash commands) ​

  • /run-tests — run targeted tests, prioritized by what's likely to break

  • /build-docs — build documentation locally

  • /add-feature — checklist for adding new physics/features

  • /new-simulation — set up, run, and visualize a new simulation (with or without a reference paper)

  • /babysit-ci — monitor CI, auto-fix small issues, pause on bigger problems, retrigger flaky runs