ft: Add Kinematic Driver (KiD) model configuration #4095

haakon-e · 2025-11-11T23:57:23Z

This pull request introduces a new "kinematic driver" configuration and framework for running prescribed flow field simulations based on the Shipway & Hill (2012) setup. The main changes add support for prescribed velocity profiles, new initial and surface conditions, and associated configuration and plotting tools. These updates enable direct comparison and testing of microphysics schemes in a controlled, kinematic environment.

Key changes include:

Support for Prescribed Flow (Kinematic Driver):

Added a new prescribed_flow option to the configuration system, allowing users to specify a prescribed velocity profile (currently ShipwayHill2012VelocityProfile). The model infrastructure and types are updated to support this option and propagate it through the simulation. [1] [2] [3] [4] [5] [6] [7]
Implemented logic in the solver and prognostic equations to apply the prescribed flow, including setting velocities and fixing energy to initial temperature profiles as needed. [1] [2]

New Initial and Surface Conditions:

Added ShipwayHill2012 initial condition and surface setup, matching the profiles and boundary conditions described in Shipway & Hill (2012). These are now selectable via configuration. [1] [2] [3]

Kinematic Driver Configuration and Example:

Introduced a new model configuration file (kinematic_driver.yml) and a corresponding example script (KiD_driver.jl) to demonstrate and test the kinematic driver setup. [1] [2]

Upwinding and Advection Improvements:

Added a new upwinding scheme (first_order_kid) for vertical advection, with special handling for the prescribed flow scenario. [1] [2] [3]

Postprocessing and Documentation Updates:

Added plotting routines and bibliography entry for Shipway & Hill (2012), supporting analysis and reproducibility of the kinematic driver results. [1] [2]

These changes collectively enable controlled, reproducible kinematic microphysics experiments within the modeling framework.

Illustrative results

Simulation with Equil+0M, with precipitation turned off:

KiD comparison: https://buildkite.com/clima/kinematicdriver-ci/builds/913/steps/canvas?sid=019a1277-c888-440f-a2b7-8eb2e6b6242e

Simulation with Equil+0M, with precipitation turned on:

KiD comparison: https://buildkite.com/clima/kinematicdriver-ci/builds/913/steps/canvas?sid=019a1277-c889-4001-b378-396d34aa2a8a

haakon-e · 2025-11-21T01:39:08Z

@dennisYatunin, @trontrytel

Probably needs some more cleanup, but would value your input.

Dennis: Could you provide feedback on whether the proposed interface isn't too obtrusive for everyone else who wants to do "normal" ClimaAtmos simulations?

Anna: We can externalize some parameters later, but given the results (expand the sections above), I think this is a great start and we should merge this!

dennisYatunin · 2025-11-26T00:29:11Z

src/initial_conditions/initial_conditions.jl

+        (; z) = local_geometry.coordinates
+        return LocalState(; params, geometry = local_geometry,
+            thermo_state = TD.PhaseEquil_pθq(thermo_params, p(z), θ(z), q_tot(z)),
+            precip_state = PrecipStateMassNum(; q_rai = FT(0), q_sno = FT(0)),


Suggested change

precip_state = PrecipStateMassNum(; q_rai = FT(0), q_sno = FT(0)),

Removing this line will probably enable GPU compatibility, since FT is not inferable here.

Wouldn't that mean we are initializing the state vector without precipitation in it?

The current version also initializes the state without precipitation. The new version should be identical, as long as the LocalState constructor automatically pads with zeros.

dennisYatunin · 2025-11-26T00:29:59Z

examples/hybrid/KiD_driver.jl

@@ -0,0 +1,68 @@
+import ClimaComms


It looks like everything in this file can be handled by the current driver, so there is no need to add a new one.

dennisYatunin · 2025-11-26T01:33:49Z

src/prognostic_equations/implicit/implicit_tendency.jl

+        if p.atmos.numerics.energy_q_tot_upwinding == Val(:first_order_kid)
+            vtt = NullBroadcasted()  # Turn off implicit energy q_tot advection
+        end


Suggested change

if p.atmos.numerics.energy_q_tot_upwinding == Val(:first_order_kid)

vtt = NullBroadcasted() # Turn off implicit energy q_tot advection

end

This will make the implicit solver's sound wave propagation inconsistent, with ∂ᶜρq_tot/∂ᶠu₃ being zeroed out while ∂ᶠu₃/∂ᶜρq_tot (and all other ᶜρχ blocks) retains its current nonzero value. To handle sound waves like we do in other configurations, leave the implicit tendency and its Jacobian as they are now.

dennisYatunin · 2025-11-26T01:58:41Z

src/prognostic_equations/advection.jl

+        if energy_q_tot_upwinding == Val(:first_order_kid)
+            vtt = vertical_transport_kid(ᶜρ, ᶠu³, ᶜq_tot, FT(dt), FT(t))
+            vtt_central = NullBroadcasted()  # turn off implicit advection
+        end
        @. Yₜ.c.ρq_tot += vtt - vtt_central


Suggested change

if energy_q_tot_upwinding == Val(:first_order_kid)

vtt = vertical_transport_kid(ᶜρ, ᶠu³, ᶜq_tot, FT(dt), FT(t))

vtt_central = NullBroadcasted() # turn off implicit advection

end

@. Yₜ.c.ρq_tot += vtt - vtt_central

vtt_bc = ᶜρq_tot_vertical_transport_bc(ᶠu³, p.atmos.prescribed_flow, t)

@. Yₜ.c.ρq_tot += vtt - vtt_central + vtt_bc

If the implicit tendency change is reverted, you can simplify this explicit term by keeping the current first-order upwinding tendency (minus the implicit sound wave component) and just adding a new boundary term, which could look something like

function ᶜρq_tot_vertical_transport_bc(ᶠu³, flow::PrescribedFlow{FT}, t) where {FT} ρ_sfc = FT(1.1650101) q_tot_sfc = FT(0.014778325) u₃_sfc = Geometry.WVector(flow(FT(0), t)) ᶜadvdivᵥ = Operators.DivergenceF2C(; bottom = Operators.SetValue(ρ_sfc * q_tot_sfc * u₃_sfc), ) return @. lazy(-(ᶜadvdivᵥ(zero(ᶠu³))) end

Also, since this term is treated explicitly, it should probably be defined here in advection.jl instead of implicit_tendency.jl.

dennisYatunin · 2025-11-26T02:03:55Z

src/prognostic_equations/dss.jl

    if do_dss(axes(Y.c))
        Spaces.weighted_dss!(Y.c => p.ghost_buffer.c, Y.f => p.ghost_buffer.f)
    end
+    prescribe_flow!(Y, p, t, p.atmos.prescribed_flow)


Suggested change

if do_dss(axes(Y.c))

Spaces.weighted_dss!(Y.c => p.ghost_buffer.c, Y.f => p.ghost_buffer.f)

end

prescribe_flow!(Y, p, t, p.atmos.prescribed_flow)

prescribe_flow!(Y, p, t, p.atmos.prescribed_flow)

if do_dss(axes(Y.c))

Spaces.weighted_dss!(Y.c => p.ghost_buffer.c, Y.f => p.ghost_buffer.f)

end

It would be safer to do this in the opposite order, so that DSS is always the last operation in a Runge-Kutta stage. Roundoff errors in the prescribed flow could potentially introduce discontinuities across element boundaries, which will be propagated to the next stage if DSS is not applied afterward.

dennisYatunin · 2025-11-26T02:08:38Z

src/prognostic_equations/dss.jl

+    @. Y.c.ρ = ᶜρ_init_dry + Y.c.ρq_tot
+    ᶜts = @. lazy(TD.PhaseEquil_ρTq(thermo_params, Y.c.ρ, ᶜT_init, Y.c.ρq_tot / Y.c.ρ))
+    ᶜe_kin = compute_kinetic(Y.c.uₕ, Y.f.u₃)
+    ᶜe_pot = @. lazy(grav * z)


Suggested change

ᶜe_pot = @. lazy(grav * z)

(; ᶜΦ) = p.core

This is already cached in p.

dennisYatunin · 2025-11-26T02:30:55Z

src/cache/precomputed_quantities.jl

+    if !(p.atmos.prescribed_flow isa PrescribedFlow)
+        set_velocity_at_surface!(Y, ᶠuₕ³, turbconv_model)
+        set_velocity_at_top!(Y, turbconv_model)
+    end


In simulations with topography, set_velocity_at_surface! and set_velocity_at_top! are needed to ensure that the state's velocity components match its advective tendency. If the advective tendency assumes zero-flux (CT3(0)) boundary conditions, these functions modify Y.f.u₃ to enforce that. In your case, fluxes at the surface are prescribed some nonzero value (i.e., the projection CT3(ρ_sfc * q_tot_sfc * u₃_sfc), where u₃_sfc is specified as a WVector), so set_velocity_at_surface! and set_velocity_at_top! should make Y.c.uₕ and Y.f.u₃ consistent with that.

If you never intend to run this configuration with topography, then you can leave this as is, but add a check somewhere in type_getters.jl to make sure that there is no topography.

Hmmm - we saw some inconsistency at the surface in our advected fields that went away only when we removed those set_velocity functions from our Kid run

dennisYatunin · 2025-11-26T02:31:39Z

config/model_configs/kinematic_driver.yml

+z_max: 2e3
+z_elem: 128
+z_stretch: false
+use_auto_jacobian: true # Needed!! (+only 1 Newton iteration, which is the default)


Suggested change

use_auto_jacobian: true # Needed!! (+only 1 Newton iteration, which is the default)

This shouldn't be needed if you leave the current implicit tendency unchanged.

trontrytel · 2025-11-27T00:01:42Z

src/surface_conditions/surface_setups.jl

+        Cd = FT(0.0)
+        Ch = FT(0.0)
+        parameterization = ExchangeCoefficients(; Cd, Ch)
+        # <<<


Suggested change

# <<<

trontrytel · 2025-11-27T00:02:27Z

src/surface_conditions/surface_setups.jl

+struct ShipwayHill2012 end
+function (::ShipwayHill2012)(params)
+    function surface_state(surface_coordinates, interior_z, t)
+        FT = eltype(surface_coordinates)


We don't need most of it since we ended up setting the coefficients to zero and prescribing the flux?

trontrytel · 2025-11-27T00:04:11Z

src/prognostic_equations/implicit/implicit_tendency.jl

+    FT = eltype(ᶜρ)
+    ᶜJ = Fields.local_geometry_field(axes(ᶜρ)).J
+    ᶠJ = Fields.local_geometry_field(axes(ᶠu³)).J
+    ρ_sfc = FT(1.1650101)  # TODO: Get from initial conditions or state


Would be great to avoid hardcoding. But we can also solve it later

trontrytel

LGTM! But I was also there when most of it was written so I may be biased ;)

haakon-e marked this pull request as draft November 11, 2025 23:59

haakon-e force-pushed the he/ft-add-kinematic-driver-kid branch 4 times, most recently from 7160992 to 874b360 Compare November 20, 2025 17:39

haakon-e marked this pull request as ready for review November 21, 2025 01:37

haakon-e requested review from dennisYatunin and trontrytel November 21, 2025 01:37

haakon-e linked an issue Nov 21, 2025 that may be closed by this pull request

Add Shipway and Hill 2012 kinematic driver tests to ClimaAtmos #4100

Open

8 tasks

haakon-e added 2 commits November 24, 2025 16:52

ft: Add Kinematic Driver (KiD) model configuration

d7db4d3

make it work

6fe6b70

haakon-e force-pushed the he/ft-add-kinematic-driver-kid branch from c8252b9 to 6fe6b70 Compare November 25, 2025 00:55

dennisYatunin approved these changes Nov 26, 2025

View reviewed changes

trontrytel reviewed Nov 27, 2025

View reviewed changes

trontrytel self-requested a review November 27, 2025 00:04

trontrytel approved these changes Nov 27, 2025

View reviewed changes

	if p.atmos.numerics.energy_q_tot_upwinding == Val(:first_order_kid)
	vtt = NullBroadcasted() # Turn off implicit energy q_tot advection
	end

ft: Add Kinematic Driver (KiD) model configuration #4095

Are you sure you want to change the base?

ft: Add Kinematic Driver (KiD) model configuration #4095

Uh oh!

Conversation

haakon-e commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Illustrative results

Uh oh!

haakon-e commented Nov 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dennisYatunin Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

trontrytel left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

haakon-e commented Nov 11, 2025 •

edited

Loading

dennisYatunin Nov 26, 2025 •

edited

Loading