Simplify Relaxation: drop ContinuousForcing dependency, add transform and Field targets

[glwagner]

Summary

Eliminates the two parallel materialize paths Relaxation had after #5575 — Number/function targets went through ContinuousForcing, while FieldTimeSeries targets used a bespoke FieldTimeSeriesTarget wrapper with a type-parameter-as-index trick and its own discrete-form callable. The asymmetry forced ~80 lines of duplicated machinery just because the FTS path couldn't fit through ContinuousForcing's parameter slot.

Now there's one Relaxation{R,M,T,F,L,Tr} that carries the forced field directly, one kernel callable, and one evaluate_target dispatch family handling all four target types: Number, function, AbstractField, FieldTimeSeries. As discussed in #5575 (#5575 (comment)...), storing the forced field directly is the underlying simplification that unlocks both the unified machinery and the new transform feature.

What changed

Storage of FTS grid (real fix, not workaround)

GPUAdaptedFieldTimeSeries now carries its grid (previously dropped to Nothing). The kernel can call interpolate(X, t, fts, loc, fts.grid) post-adapt without any wrapper. This deletes the entire FieldTimeSeriesTarget machinery (struct + type-param index trick + helper + custom Adapt) from #5575 in favor of a one-field change in OutputReaders.

transform kwarg

# Relax tracer to its own horizontal average:
Relaxation(rate=1/τ, transform=:horizontal_average)

# Or supply your own closure:
Relaxation(rate=1/τ, transform = f -> Field(Average(f, dims=(1, 2))))

transform builds a lazy target from the forced field at materialize time. Refreshed each step via the new compute_forcing! hook, which is wired into update_state! for all three model types.

Field targets

Relaxation(rate=1/τ, target=my_field) now works for any AbstractField sharing the forced field's grid + location. Validation throws clear errors on mismatch.

Type aliases

FieldRelaxation and FieldTimeSeriesRelaxation for tests and user-side type assertions.

Deletions

• FieldTimeSeriesTarget{L,F,G,I} and _field_index helper
• materialize_forcing(::Relaxation, …) ContinuousForcing wrapper
• Six (::Relaxation)(x,y,z,t,field) / (x₁,x₂,t,field) / (x₁,t,field) continuous-form callable overloads
• using …: ContinuousForcing dep from relaxation.jl

Files

• src/OutputReaders/field_time_series.jl — +1 grid field on GPUAdaptedFieldTimeSeries
• src/Forcings/relaxation.jl — rewrite (185 lines changed, net -10)
• src/Forcings/compute_forcing.jl — new (15 lines): default no-op + Tuple/NamedTuple/MultipleForcings recursion + Relaxation method
• src/Forcings/Forcings.jl — include + export compute_forcing!
• src/Models/{Nonhydrostatic,HydrostaticFreeSurface,ShallowWater}Models/update_*_state.jl — call compute_forcing!(model.forcing) after update_model_field_time_series!
• test/test_forcings.jl — updated FTS testset assertions, new Field-target testset, new transform=:horizontal_average testset (analytical decay verified)
• docs/src/models/forcing_functions.md — doctest updated

Test plan

• test_forcings.jl on CPU: 1215/1215 pass (+9 new tests covering Field target validation, location/grid mismatch errors, transform decay tracking, transform+FTS rejection, closure-form equivalence)
• test_output_readers.jl on CPU: 11540/11540 pass — confirms GPUAdaptedFTS grid addition is non-breaking
• Analytical verification: transform=:horizontal_average decay factor matches exp(-t/τ) to 8 decimal places, confirming compute_forcing! fires each step
• Doctests in relaxation.jl and forcing_functions.md verified manually
• GPU run via CI

Follow-ups

• transform-shortcuts beyond :horizontal_average (e.g. :vertical_average, :domain_average) — trivial 1-line apply_transform methods, add on demand
• Cross-grid AbstractField targets — currently FTS-only (validator enforces matching grid+location for plain Field targets); the kernel path already supports it via evaluate_target(::AbstractArray, …), just needs a different validator

🤖 Generated with Claude Code

[glwagner]

@simone-silvestri @ewquon this is the refactor that we discussed on #5575

[ewquon]

Thanks for taking the lead on this @glwagner

[ewquon]

This should be good to go after addressing the forcing.target issue #5620 (comment).

[simone-silvestri]

This refactor adds the grid as an field to the GPUAdaptedFieldTimeSeries. Will this create performance or parameter space issues?

[glwagner]

This refactor adds the grid as an field to the GPUAdaptedFieldTimeSeries. Will this create performance or parameter space issues?

It could. Another option is to have a special adaptor for Relaxation (we need the grid for interpolation)

[simone-silvestri]

right, I guess this is the same scheme adopted by DatasetBackend. However, I like the idea to add the adapt to relaxation so we don't change the behavior for other code paths. With DatasetBackend sometimes I saw the registers explode not still sure why.

[glwagner]

right, I guess this is the same scheme adopted by DatasetBackend. However, I like the idea to add the adapt to relaxation so we don't change the behavior for other code paths. With DatasetBackend sometimes I saw the registers explode not still sure why.

ok, i'll make that change