On-the-fly nested-atmosphere boundary conditions + Davies relaxation

[glwagner]

Follow-up to #386. Derives a Breeze nested child's lateral boundary conditions and interior Davies relaxation on the fly from a coarse parent atmosphere's raw state — eliminating the materialized breeze_prognostic_state parent series. Builds on the ERA5PrescribedAtmosphere / PrescribedAtmosphere refactor from #386 (now on main).

The abstraction

• ParentStateBoundary (NestedSimulations) — a multi-field boundary condition: at each boundary-face node it interpolates a NamedTuple of parent FieldTimeSeries (each with its own interpolation transform — log for the strictly-positive p/T, identity otherwise) and applies a pointwise transform to the resulting state. Carrier-only; knows nothing about which prognostic or dataset.
• ParentStateTarget — the interior-relaxation analogue: a Relaxation target(x, y, z, t) using the same _query_source machinery at an arbitrary node.
• Both use Oceananigans' interpolate(f, …) (Add interpolate(f, …): map source values through f before blending CliMA/Oceananigans.jl#5726) for the log-space interpolation; the local shim is gone.

Breeze wiring (in NumericalEarthBreezeExt)

• Prognostic transforms (isbits callables over the pointwise maps): AirDensity, MomentumDensity, EnergyDensity, MoistureDensity (density-weighted, for the BCs); LiquidIcePotentialTemperature, TotalWater (specific, for the relaxation).
• atmosphere_simulation(grid; parent_atmosphere, relaxation_rate, relaxation_mask):
  • lateral BCs for ρ, ρu, ρv, ρe, <moisture> via ParentStateBoundary (ρu/ρv → NormalFlowBC, the rest → ValueBC), merged per-side with the coupling bottom-flux BCs;
  • interior Davies relaxation keyed (u, v, θ, qᵉ) for Breeze's SpecificForcing (u/v toward the raw parent velocities, θ/qᵉ toward on-the-fly specific targets).
  • The parent kwarg was named parent_atmosphere to avoid shadowing Base.parent / Oceananigans parent(field).

Workflow: build parent → atmosphere_simulation(grid; parent_atmosphere) → NestedModel.

Dependency

interpolate(f, …) is merged to Oceananigans main but not yet tagged, so this PR points Oceananigans at main via [sources] (root/test/docs). Swap to a [compat] bump once a release is tagged (TODOs in place).

Status / TODO (draft)

• Rewrite examples/breeze_downscaling_era5.jl to use atmosphere_simulation(grid; parent_atmosphere, relaxation_rate, …), deleting the parent_series materialization loop + single-source parent_boundary_conditions.
• Tests for ParentStateBoundary / ParentStateTarget (CDS-free, toy parent FTS).
• Benchmark the on-the-fly cost (vs. a precomputed parent series) — precomputing is a possible later optimization (would move the conversion into parent construction).
• Not yet exercised locally (dev env can't precompile here); relying on CI against Oceananigans main.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 33.24675% with 257 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...umericalEarthBreezeExt/breeze_nested_atmosphere.jl	0.00%	95 Missing ⚠️
ext/NumericalEarthMakieExt.jl	0.00%	42 Missing ⚠️
...icalEarthBreezeExt/breeze_atmosphere_simulation.jl	16.12%	26 Missing ⚠️
ext/NumericalEarthNaturalEarthExt.jl	0.00%	19 Missing ⚠️
src/Atmospheres/hydrostatic_pressure.jl	40.00%	12 Missing ⚠️
.../NumericalEarthBreezeExt/breeze_state_exchanger.jl	84.93%	11 Missing ⚠️
src/NestedModels/nested_model.jl	56.52%	10 Missing ⚠️
src/NestedModels/parent_terrain.jl	0.00%	10 Missing ⚠️
...rc/Grids/pressure_level_vertical_discretization.jl	20.00%	8 Missing ⚠️
ext/NumericalEarthCopernicusClimateDataStoreExt.jl	0.00%	6 Missing ⚠️
... and 7 more

📢 Thoughts on this report? Let us know!

[ewquon]

Suggested change

	# Cosine-ramp Davies mask: 1 at the lateral walls, ramping to 0 over the outermost `width` cells.
	# Captures plain numbers so the closure is GPU-compilable.
	function davies_relaxation_mask(grid, width)
	λ₁, λ₂ = extrema(λnodes(grid, Face(), Center(), Center()))
	φ₁, φ₂ = extrema(φnodes(grid, Center(), Face(), Center()))
	Nx, Ny, _ = size(grid)
	w = width * max((λ₂ - λ₁) / Nx, (φ₂ - φ₁) / Ny)
	return (λ, φ, z) -> begin
	d = min(λ - λ₁, λ₂ - λ, φ - φ₁, φ₂ - φ)
	d >= w && return zero(λ)
	return oftype(λ, (1 + cos(π * d / w)) / 2)
	end
	end
	# Ramp shapes (isbits callables) for a nudging zone: weight vs. normalized distance from the wall, s ∈ [0, 1].
	# Contract: ramp(0)=1, ramp(1)=0, monotone between.
	struct CosineRamp end
	struct SmoothStepRamp end
	@inline (::CosineRamp)(s) = (1 + cos(π * s)) / 2
	@inline (::SmoothStepRamp)(s) = 1 - s^2 * (3 - 2s)
	# Davies mask: 1 at the lateral walls, ramping to 0 over the outermost `width` cells.
	function davies_relaxation_mask(grid, width; ramp = CosineRamp())
	λ₁, λ₂ = extrema(λnodes(grid, Face(), Center(), Center()))
	φ₁, φ₂ = extrema(φnodes(grid, Center(), Face(), Center()))
	Nx, Ny, _ = size(grid)
	w = width * max((λ₂ - λ₁) / Nx, (φ₂ - φ₁) / Ny)
	return (λ, φ, z) -> begin
	d = min(λ - λ₁, λ₂ - λ, φ - φ₁, φ₂ - φ)
	s = clamp(d / w, zero(d), one(d))
	return oftype(d, ramp(s))
	end
	end

Is now a good time to change the ramping function to something more computationally efficient?

[glwagner]

I think so! I doubt the precise structure of the ramping matters? So efficiency is good.

[ewquon]

Suggested change

	function lid_sponge_mask(grid, depth)
	z_top = @allowscalar znode(1, 1, size(grid, 3) + 1, grid, Center(), Center(), Face())
	d = convert(eltype(grid), depth)
	return (λ, φ, z) -> (s = clamp((z - (z_top - d)) / d, zero(z), one(z)); s * s * (3 - 2s))
	end
	function lid_sponge_mask(grid, depth; ramp = SmoothStepRamp())
	z_top = @allowscalar znode(1, 1, size(grid, 3) + 1, grid, Center(), Center(), Face())
	d = convert(eltype(grid), depth)
	return (λ, φ, z) -> (s = clamp((z - (z_top - d)) / d, zero(z), one(z)); ramp(s))
	end

with the change above

[ewquon]

max dt = 20 s is pretty conservative (small) for dx ~ 12 km

[ewquon]

Inconsistent use of ρ vs ρᵈ here.

[glwagner]

I think the dycore does actually evolve ρ · qᵛ = ρᵛ so this may be correct?