add more comments

Author: sajjadazimi

src/initial_conditions/initial_conditions.jl

@@ -1224,7 +1224,7 @@ function (initial_condition::PrecipitatingColumn)(params)
             thermo_state = ts,
             velocity = Geometry.UVVector(u(z), v(z)),
             turbconv_state = nothing,
-            precip_state = PrecipState2M(;
+            precip_state = PrecipStateMassNum(;
                 n_liq = nₗ(z),
                 n_rai = nᵣ(z),
                 q_rai = qᵣ(z),

src/initial_conditions/local_state.jl

@@ -104,18 +104,22 @@ struct NoPrecipState{FT} <: PrecipState{FT} end
 """
     PrecipState2M(; q_rai, q_sno)
 
-Stores the values of `n_liq`, `n_rai`, `q_rai` and `q_sno`for the `precip_model`. 
-If no values are provided, they are set to zero.
+
+Stores the values of `n_liq`, `n_rai`, `q_rai`, and `q_sno` for the `precip_model`.
+This struct includes both mass and number densities and can be used for initializing 
+precipitation states in both one-moment and two-moment microphysics schemes. 
+In one-moment schemes, the number densities (`n_liq`, `n_rai`) are ignored.
+If no values are provided, all fields are initialized to zero.
 """
-struct PrecipState2M{FT} <: PrecipState{FT}
+struct PrecipStateMassNum{FT} <: PrecipState{FT}
     n_liq::FT
     n_rai::FT
     q_rai::FT
     q_sno::FT
 end
-PrecipState2M(;
+PrecipStateMassNum(;
     n_liq = 0,
     n_rai = 0,
     q_rai = 0,
     q_sno = 0,
-) = PrecipState2M{typeof(q_rai)}(n_liq, n_rai, q_rai, q_sno)
+) = PrecipStateMassNum{typeof(q_rai)}(n_liq, n_rai, q_rai, q_sno)

src/parameterized_tendencies/microphysics/microphysics_wrappers.jl

@@ -370,14 +370,14 @@ end
  - Sᵖ, S₂ᵖ - temporary containters to help compute precipitation source terms
  - Snₗᵖ, Snᵣᵖ, Sqₗᵖ, Sqᵣᵖ - cached storage for precipitation source terms
  - ρ - air density
- - nₗ, nᵣ - cloud liquid and rain number concentration per mass
+ - nₗ, nᵣ - cloud liquid and rain number concentration per mass [1 / kg of moist air]
  - qₗ, qᵣ - cloud liquid and rain specific humidity
  - ts - thermodynamic state (see td package for details)
  - dt - model time step
  - thp, mp - structs with thermodynamic and microphysics parameters
 
 Computes precipitation number and mass sources due to warm precipitation processes based on the 2-moment 
-Seifert and Beheng (2006) scheme.
+[Seifert and Beheng (2006) scheme](https://clima.github.io/CloudMicrophysics.jl/dev/Microphysics2M/).
 """
 function compute_warm_precipitation_sources_2M!(
     Sᵖ,
@@ -413,7 +413,7 @@ function compute_warm_precipitation_sources_2M!(
             ρ,
             ρ * nₗ,
         ).dq_rai_dt,
-        limit(qₗ, dt, 5),
+        limit(qₗ, dt, 5), # cap rate to at most 20% of qₗ per timestep to ensure stability
     )
     @. Sqₗᵖ -= Sᵖ
     @. Sqᵣᵖ += Sᵖ
@@ -430,14 +430,17 @@ function compute_warm_precipitation_sources_2M!(
         ).dN_liq_dt / ρ,
         limit(nₗ, dt, 10),
     )
+    # triangle_inequality_limiter assumes positive rates and limits.
+    # Here the physical rate is negative (a sink), so we negate it before passing,
+    # and negate the result again to preserve the original sign.
     @. S₂ᵖ =
         -triangle_inequality_limiter(
             -CM2.liquid_self_collection(mp.sb.acnv, mp.sb.pdf_c, qₗ, ρ, Sᵖ) / ρ,
             limit(nₗ / ρ, dt, 5),
         )
     @. Snₗᵖ += Sᵖ
     @. Snₗᵖ += S₂ᵖ
-    @. Snᵣᵖ -= 0.5 * Sᵖ
+    @. Snᵣᵖ -= 0.5 * Sᵖ # each raindrop forms from two cloud particles → factor 0.5
 
     # rain self-collection and breakup
     @. Sᵖ =