ft: Add Kinematic Driver (KiD) model configuration

[haakon-e]

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]

@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]

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]

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

[haakon-e]

Summary of variants

With reference to the current code, I observe different behavior depending on whether I comment out treatment of sound waves

Comparisons below are (left to right):

• The PR, as-is: kinematic_driver/output_0222
• Normal sound waves: kinematic_driver/output_0223

figures

[haakon-e]

For clarity, here's how it looks with precipitation sources zeroed out:

figures

[haakon-e]

After discussions with Dennis yesterday, this PR now treats the implicit tendencies as explicit. This exactly cancels the advection term that approximates propagation of sound waves between the "explicit" and "implicit" tendencies.

---

Also, I have to set z_max quite high, since the top boundary condition for humidity advection is zero flux. To more closely resemble the reference implementation, I should override the top boundary condition in the same way I override the bottom bc. I leave this for a future PR if we need it.