Unify grid-mean tracer vertical advection with q_tot/energy (implicit + Jacobian)
- Dominant language
- Julia
- Stars
- 128
- Forks
- 39
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 30
Description
## Summary
Make the vertical transport of grid-mean tracers (`q_lcl`, `q_icl`, `q_rai`, `q_sno`, `n_*`, and user-defined passive tracers) numerically consistent with the transport of `ρq_tot` and `ρe_tot`. After #4637, two of the three vertical-transport pathways are already consistent; the remaining gap is that **grid-mean vertical advection is implicit for `q_tot`/energy but explicit for the other tracers**. Physically, this is justifiable, since `q_tot` and energy actively participate in sound waves, while other tracers such as condenates are passive (mostly for condensates, exactly for passive tracers).
This is a follow-up to #4637 (which unified the EDMFX SGS mass-flux pathway).
## Current state
For a grid-mean scalar in prognostic EDMFX there are three vertical pathways:
| Pathway | `q_tot` / `mse` | other tracers | consistent? |
|---|---|---|---|
| **SGS mass flux** (`edmfx_sgs_mass_flux_tendency!`) | implicit; `edmfx_sgsflux_upwinding` (`:none`); central Jacobian, updraft-only, no env | implicit; `edmfx_sgsflux_upwinding`; central Jacobian, updraft-only, no env | ✅ done in #4637 |
| **Updraft-internal advection** (`χʲ` by `u³ʲ`) | implicit; `edmfx_mse_q_tot_upwinding` (`:first_order`); 1st-order-upwind Jacobian | implicit; `edmfx_tracer_upwinding` (`:first_order`); 1st-order-upwind Jacobian | ✅ (separate knob, same default and treatment) |
| **Grid-mean advection** `−∇·(ρ u³ χ)` | **implicit** (`implicit_vertical_advection_tendency!`); `energy_q_tot_upwinding` (vanleer); central `∂/∂u₃` Jacobian | **explicit** (`explicit_vertical_advection_tendency!`); `tracer_upwinding` (vanleer); **no Jacobian** | ❌ remaining gap |
The horizontal advection of both groups is explicit and already consistent.
Note this is not a conservation bug: the `χ ≡ 1` tracer-mass identity holds across the split (the `vertical_transport` operator reconstructs a constant exactly whether called from the implicit or explicit tendency), and the test added in #4637 passes. The inconsistency is one of numerical treatment (operator splitting, Jacobian coverage, and a small `q_tot`-vs-`Σ qₓ` splitting drift), not of mass balance.
## Proposed change
Move grid-mean tracer advection from the explicit into the implicit tendency, mirroring `q_tot`:
1. **Tendency**: remove the `foreach_gs_tracer` advection loop in `explicit_vertical_advection_tendency!` ([`src/prognostic_equations/advection.jl`](../blob/main/src/prognostic_equations/advection.jl)); add the same loop (excluding `ρe_tot`/`ρq_tot`) to `implicit_vertical_advection_tendency!` immediately after the `q_tot`/`ρe_tot` `vertical_transport` calls, using `energy_q_tot_upwinding` so the reconstruction matches.
2. **Jacobian**: add a `∂ρχ_err/∂u₃` block per tracer, reusing the `ᶜadvection_matrix` machinery the `q_tot` row already uses (`dtγ · ᶜadvection_matrix ⋅ DiagonalMatrixRow(ᶠinterp(χ)·g³³)`), plus the `∂/∂uₕ` topography term. This is the same central-only ("incomplete") Jacobian that `q_tot`/`ρe_tot` use.
3. **Optional knob cleanup**: collapse `tracer_upwinding` → `energy_q_tot_upwinding` and `edmfx_tracer_upwinding` → `edmfx_mse_q_tot_upwinding`. Each pair shares its default (vanleer and `:first_order` respectively), so there is no default-behavior change — just a smaller config surface.
## Watch items / risks
- **Precipitation species** (`q_rai`, `q_sno`) would then carry *both* implicit mean-flow advection (`ᶜadvdivᵥ`, zero-flux BCs) and implicit sedimentation (`ᶜprecipdivᵥ`, free-outflow bottom). These are separate terms, but the Jacobian grows and the interaction with the vertical-water-borrowing limiter and `enforce_physical_constraints` should be re-checked.
- **Positivity**: condensate is positivity-sensitive; the implicitly-solved, vanleer-limited advection must not drive negative values. `q_tot` already does this, but condensate is a harder case; verify.
- Passive user tracers (`q_gas_A`, tracer A) also become implicit.
- Bigger sparse Jacobian → more expensive linear solve.
## Behavior change and validation
This **is** a behavior change for every prognostic-EDMFX run with microphysics or passive tracers, even though the operator and (vanleer) scheme are unchanged: moving the term between the IMEX explicit and implicit tableaus shifts results at ~O(dt²) per step, which accumulates over a climate run.
Required before merge:
- Revalidate the EDMFX column cases (BOMEX, DYCOMS RF01/RF02, RICO, TRMM) and an aquaplanet, checking Newton convergence, condensate positivity, and that the LES-comparison metrics don't regress.
- Prototype steps 1–2 on a branch first and measuring the DYCOMS/aquaplanet delta before committing to it.
## Trade-off to consider
`q_tot` is advected implicitly because it participates in acoustic waves through the equation of state; condensates much less (weaker effect on EOS), so explicit advection of them is a defensible efficiency choice. Full consistency buys uniform treatment and removes a small `q_tot`-vs-`Σ qₓ` operator-splitting drift, at the cost of a larger Jacobian and a broad behavior change. It may not be worth making that trade-off.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.