SurfaceFluxes.jl AGENTS.md

SurfaceFluxes.jl Agent Guide

Ecosystem Guidelines

Please refer to the shared CliMA agent index for ecosystem-wide rules regarding architecture, performance, code quality, infrastructure, and workflows:

• docs/dev-guides/AGENTS.md — Shared CliMA agent guidelines.

Shared guides live at docs/dev-guides/ and are vendored from the canonical source: https://github.com/CliMA/DeveloperGuides. Edit shared guides there, not here. They are synced automatically each month by .github/workflows/update_dev_guides.yml.

Before You Act: Agent Autonomy

Before making changes that are externally visible or consequential (git push, version bumps, CI config changes, public API renames), check docs/dev-guides/workflow/agent_autonomy.md. The boundaries listed there require explicit user approval.

Repo-Specific Guidelines

SurfaceFluxes.jl computes turbulent surface fluxes of momentum, heat, and moisture using Monin-Obukhov Similarity Theory (MOST). It is GPU-compatible, AD-compatible (ForwardDiff), and designed to be broadcast over arrays of heterogeneous surfaces.

Architecture

• Two modules: the top-level SurfaceFluxes module (physics, solver, fluxes) and the nested SurfaceFluxes.UniversalFunctions submodule (stability functions ϕ, ψ, Ψ). SurfaceFluxes.Parameters holds the parameter struct and accessors.
• Pure, stateless functions: physics functions take a param_set, state, and configuration and return values or a SurfaceFluxConditions struct; they do not mutate global state.
• GPU/AD compatibility: hot paths use ifelse rather than branches to avoid warp divergence; both branches of an ifelse must be evaluable (guard invalid inputs with min/max so the discarded branch never errors). Avoid keyword-argument constructors in kernels. Do not contaminate the Float32 path with Float64 literals — wrap constants in FT(...). See docs/dev-guides/performance/.
• Solver design: surface_fluxes dispatches to one of four modes (prescribed coefficients, prescribed fluxes, prescribed heat+drag, or the iterative MOST solve). The iterative solve finds the stability parameter ζ as the root of Ri_b(state) − Ri_b(ζ) via RootSolvers.jl, using a fixed iteration count by default for branch-free GPU execution.