Merge pull request #510 from CliMA/aj/cloud_diagnostics

Add cloud diagnostics

docs/make.jl

@@ -45,6 +45,7 @@ Parameterizations = [
     "Water Activity" => "WaterActivity.md",
     "Ice Nucleation" => "IceNucleation.md",
     "Aerosol Nucleation" => "AerosolNucleation.md",
+    "Cloud diagnostics" => "CloudDiagnostics.md",
     "Precipitation Susceptibility" => "PrecipitationSusceptibility.md",
 ]
 
@@ -83,6 +84,7 @@ format = Documenter.HTML(
     prettyurls = get(ENV, "CI", nothing) == "true",
     mathengine = mathengine,
     collapselevel = 1,
+    size_threshold_ignore = ["API.md"],
 )
 
 makedocs(

docs/src/API.md

@@ -27,7 +27,6 @@ Microphysics1M
 Microphysics1M.get_v0
 Microphysics1M.get_n0
 Microphysics1M.lambda
-Microphysics1M.radar_reflectivity
 Microphysics1M.terminal_velocity
 Microphysics1M.conv_q_liq_to_q_rai
 Microphysics1M.conv_q_ice_to_q_sno_no_supersat
@@ -56,9 +55,6 @@ Microphysics2M.rain_breakup
 Microphysics2M.rain_self_collection_and_breakup
 Microphysics2M.rain_terminal_velocity
 Microphysics2M.rain_evaporation
-Microphysics2M.radar_reflectivity
-Microphysics2M.effective_radius
-Microphysics2M.effective_radius_Liu_Hallet_97
 Microphysics2M.conv_q_liq_to_q_rai
 ```
 
@@ -121,6 +117,16 @@ HomIceNucleation.homogeneous_J_cubic
 HomIceNucleation.homogeneous_J_linear
 ```
 
+# Cloud diagnostics
+```@docs
+CloudDiagnostics
+CloudDiagnostics.radar_reflectivity_1M
+CloudDiagnostics.radar_reflectivity_2M
+CloudDiagnostics.effective_radius_const
+CloudDiagnostics.effective_radius_Liu_Hallet_97
+CloudDiagnostics.effective_radius_2M
+```
+
 # Common utility functions
 
 ```@docs

docs/src/CloudDiagnostics.md

@@ -0,0 +1,130 @@
+# Diagnostics
+
+`CloudMicrophysics.jl` offers a couple of options to compute cloud and precipitation
+radiative properties based on different available parameterizations and their
+underlying assumptions about the size distribution and properties of particles.
+
+Available diagnostics are:
+ - Radar reflectivity
+ - Effective radius
+
+## Radar reflectivity
+
+The radar reflectivity factor ``Z`` is used to measure the power returned
+  by a radar signal when it encounters particles (cloud, rain droplets, etc),
+  and is defined as the sixth moment of the particles distributions ``n(r)``:
+
+```math
+\begin{equation}
+Z = {\int_0^\infty r^{6} \, n(r) \, dr}.
+\label{eq:Z}
+\end{equation}
+```
+
+``Z`` is typically normalized by radar reflectivity factor ``Z_0``
+of a drop of radius ``1 mm`` in a volume of ``1 m^3``, and is reported
+as a decimal logarithm to obtain the normalized
+logarithmic rain radar reflectivity ``L_Z``.
+```math
+\begin{equation}
+L_Z = {10 \, \log_{10} \left( \frac{Z}{Z_0} \right)}.
+\end{equation}
+```
+The resulting logarithmic dimensionless unit is decibel relative to ``Z_0``, or ``dBZ``.
+
+### 1-moment microphysics
+
+For the [1-moment scheme](https://clima.github.io/CloudMicrophysics.jl/dev/Microphysics1M/)
+  we only consider the rain drop size distribution.
+Integrating over the assumed Marshall-Palmer distribution leads to
+```math
+\begin{equation}
+Z = {\frac{6! \, n_{0}^{rai}}{\lambda^7}},
+\end{equation}
+```
+where:
+ - ``n_{0}^{rai}`` and ``\lambda`` - rain drop size distribution parameters.
+
+### 2-moment microphysics
+
+For the [2-moment scheme](https://clima.github.io/CloudMicrophysics.jl/dev/Microphysics2M/)
+  we take into consideration the effect of both cloud and rain droplets.
+Integrating over the assumed cloud droplets Gamma distribution leads to
+```math
+\begin{equation}
+Z_c = A_c C^{\nu_c+1} \frac{ (B_c C^{\mu_c})^{-\frac{3+\nu_c}{\mu_c}} \, \Gamma \left(\frac{3+\nu_c}{\mu_c}\right)}{\mu_c},
+\end{equation}
+```
+where:
+ - ``\Gamma \,(x) = \int_{0}^{\infty} \! t^{x - 1} e^{-t} \mathrm{d}t`` is the gamma function,
+ - ``C = \frac{4}{3} \pi \rho_w``.
+
+Similar for rain drop exponential distribution
+```math
+\begin{equation}
+Z_r = A_r C^{\nu_r+1} \frac{ (B_r C^{\mu_r})^{-\frac{3+\nu_r}{\mu_r}} \, \Gamma \left(\frac{3+\nu_r}{\mu_r}\right)}{\mu_r},
+\end{equation}
+```
+The final radar reflectivity factor is a sum of ``Z_c`` and ``Z_r``.
+
+## Effective radius
+
+The effective radius of hydrometeors (``r_{eff}``) is defined as
+the area weighted radius of the population of particles.
+It can be computed as the ratio of the third to the second moment
+of the size distribution.
+
+### 2-moment microphysics
+
+We compute the total third and second moment as a sum of cloud condensate and
+precipitation moments:
+```math
+\begin{equation}
+r_{eff} = \frac{M_{3}^c + M_{3}^r}{M_{2}^c + M_{2}^r} = \frac{{\int_0^\infty r^{3} \, (n_c(r) + n_r(r)) \, dr}}{{\int_0^\infty r^{2} \, (n_c(r) + n_r(r)) \, dr}}.
+\label{eq:reff}
+\end{equation}
+```
+After integrating we obtain
+```math
+\begin{equation}
+M_{3}^c + M_{3}^r = A_c C^{\nu_c+1} \frac{ (B_c C^{\mu_c})^{-\frac{2+\nu_c}{\mu_c}} \, \Gamma \left(\frac{2+\nu_c}{\mu_c}\right)}{\mu_c} + A_r C^{\nu_r+1} \frac{ (B_r C^{\mu_r})^{-\frac{2+\nu_r}{\mu_r}} \, \Gamma \left(\frac{2+\nu_r}{\mu_r}\right)}{\mu_r}.
+\end{equation}
+```
+```math
+\begin{equation}
+M_{2}^c + M_{2}^r = A_c C^{\nu_c+1} \frac{ (B_c C^{\mu_c})^{-\frac{5+3\nu_c}{3\mu_c}} \, \Gamma \left(\frac{5+3\nu_c}{3\mu_c}\right)}{\mu_c} + A_r C^{\nu_r+1} \frac{ (B_r C^{\mu_r})^{-\frac{5+3\nu_r}{3\mu_r}} \, \Gamma \left(\frac{5+3\nu_r}{3\mu_r}\right)}{\mu_r}.
+\end{equation}
+```
+
+### Liu and Hallett 1997
+
+For 1-moment microphysics scheme the effective radius
+is parameterized following [Liu1997](@cite):
+
+```math
+\begin{equation}
+  r_{eff} = \frac{r_{vol}}{k^{\frac{1}{3}}},
+\end{equation}
+```
+where:
+  - ``r_{vol}`` represents the volume-averaged radius,
+  - ``k = 0.8``.
+
+Where the volume-averaged radius is computed using
+```math
+\begin{equation}
+  r_{vol} = \left(\frac{3}{4 \pi \rho_w}\right)^{\frac{1}{3}} \, \left(\frac{L}{N}\right)^{\frac{1}{3}} = \left(\frac{3  \rho (q_{liq} + q_{rai})}{4 \pi \rho_w (N_{liq} + N_{rai})}\right)^{\frac{1}{3}},
+\end{equation}
+```
+where:
+  - ``L = \rho q``, is the liquid water content,
+  - ``N = N_{liq} + N_{rai}``.
+
+By default for the 1-moment scheme we don't consider precipitation and assume
+a constant cloud droplet number concentration of 100 $cm^{-3}$.
+
+### Constant
+
+For testing purposes we also provide a constant effective radius option.
+The default values are 14 $\mu m$ for liquid clouds and 25 $\mu m$ for ice clouds,
+and can be easily overwritten via `ClimaParams.jl`.

docs/src/Microphysics1M.md

@@ -634,35 +634,6 @@ If ``T > T_{freeze}``:
 \end{equation}
 ```
 
-## Rain radar reflectivity
-
-The rain radar reflectivity factor Z is used to measure the power
-  returned by a radar signal when it encounters rain particles.
-It is defined as the 6th moment of the rain particle size distribution:
-```math
-\begin{equation}
-Z = {\int_0^\infty r^{6} \, n(r) \, dr}.
-\label{eq:Z}
-\end{equation}
-```
-Integrating over the assumed Marshall-Palmer distribution (eq. 6) leads to
-```math
-\begin{equation}
-Z = {\frac{6! \, n_{0}^{rai}}{\lambda^7}},
-\end{equation}
-```
-where:
- - ``n_{0}^{rai}`` - rain drop size distribution parameter,
- - ``\lambda`` - as defined in eq. 7
-
-By dividing ``Z`` by the radar reflectivity factor ``Z_0`` for a drop of radius ``1 mm`` in a volume of ``1 m^3`` and applying the decimal logarithm to the result, we obtain the normalized logarithmic rain radar reflectivity ``L_Z``, which is the variable that is commonly referenced for radar reflectivity values:
-```math
-\begin{equation}
-L_Z = {10 \, \log_{10} \left( \frac{Z}{Z_0} \right)}.
-\end{equation}
-```
-The resulting logarithmic dimensionless unit is decibel relative to ``Z_0``.
-
 ## Example figures
 
 ```@example

docs/src/Microphysics2M.md

@@ -451,88 +451,6 @@ $\lambda$ is the size distribution parameter.
 The velocity $\overline{v_k}$ is the number-weighted mean terminal velocity when k = 0,
 and the mass-weighted mean terminal velocity when k = 3.
 
-## Diagnostics
-
-### Radar reflectivity
-
-The radar reflectivity factor (``Z``) is used to measure the power returned by a radar signal when it encounters atmospheric particles (cloud and rain droplets), and it is defined as the sixth moment of the particles distributions (``n(r)``) :
-```math
-\begin{equation}
-Z = {\int_0^\infty r^{6} \, n(r) \, dr}.
-\label{eq:Z}
-\end{equation}
-```
-To take into consideration the effect of both cloud and rain droplets, we integrate separately over the two distributions defined in equations (2) and (4).
-
-After defining ``C = \frac{4}{3} \pi \rho_w``, integrating over the assumed cloud droplets Gamma distribution (eq. 6) leads to
-```math
-\begin{equation}
-Z_c = A_c C^{\nu_c+1} \frac{ (B_c C^{\mu_c})^{-\frac{3+\nu_c}{\mu_c}} \, \Gamma \left(\frac{3+\nu_c}{\mu_c}\right)}{\mu_c},
-\end{equation}
-```
-where ``\Gamma \,(x) = \int_{0}^{\infty} \! t^{x - 1} e^{-t} \mathrm{d}t`` is the gamma function.
-
-By performing an analogous integration for the rain droplets exponential distribution, we obtain
-```math
-\begin{equation}
-Z_r = A_r C^{\nu_r+1} \frac{ (B_r C^{\mu_r})^{-\frac{3+\nu_r}{\mu_r}} \, \Gamma \left(\frac{3+\nu_r}{\mu_r}\right)}{\mu_r},
-\end{equation}
-```
-
-To obtain the logarithmic radar reflectivity ``L_z``, which is commonly used to refer to the radar reflectivity values, we sum ``Z_c`` and ``Z_r``, and we normalize the result with the equivalent return of a ``1 mm`` drop in a volume of a meter cube (``Z_0``).
-Then, we apply the decimal logarithm, and multiply the result by ``10``:
-```math
-\begin{equation}
-L_z = 10 \log_{10}\left(\frac{Z_c + Z_r}{Z_0}\right).
-\end{equation}
-```
-The resulting logarithmic dimensionless unit is decibel relative to ``Z``, or ``dBZ``.
-
-### Effective radius
-
-The effective radius of hydrometeors (``r_{eff}``) is the area weighted radius of the population of particles.  It can be computed as the ratio of the third  to the second moment of the size distribution.
-In our case, since we have two separate distributions for cloud and rain, after applying the appropriate transformation to express the distributions as functions of the radius, we obtain:
-```math
-\begin{equation}
-r_{eff} = \frac{(M_{3}^c + M_{3}^r)}{M_{2}^c + M_{2}^r} = \frac{{\int_0^\infty r^{5} \, (n_c(r) + n_r(r)) \, dr}}{{\int_0^\infty r^{4} \, (n_c(r) + n_r(r)) \, dr}}.
-\label{eq:reff}
-\end{equation}
-```
-By computing each integral, the numerator becomes
-```math
-\begin{equation}
-M_{3}^c + M_{3}^r = A_c C^{\nu_c+1} \frac{ (B_c C^{\mu_c})^{-\frac{2+\nu_c}{\mu_c}} \, \Gamma \left(\frac{2+\nu_c}{\mu_c}\right)}{\mu_c} + A_r C^{\nu_r+1} \frac{ (B_r C^{\mu_r})^{-\frac{2+\nu_r}{\mu_r}} \, \Gamma \left(\frac{2+\nu_r}{\mu_r}\right)}{\mu_r}.
-\end{equation}
-```
-Analogously, at the denominator we have
-```math
-\begin{equation}
-M_{2}^c + M_{2}^r = A_c C^{\nu_c+1} \frac{ (B_c C^{\mu_c})^{-\frac{5+3\nu_c}{3\mu_c}} \, \Gamma \left(\frac{5+3\nu_c}{3\mu_c}\right)}{\mu_c} + A_r C^{\nu_r+1} \frac{ (B_r C^{\mu_r})^{-\frac{5+3\nu_r}{3\mu_r}} \, \Gamma \left(\frac{5+3\nu_r}{3\mu_r}\right)}{\mu_r}.
-\end{equation}
-```
-
-### Effective radius - Liu and Hallett, 1997
-An additional option for the parametrization of the effective radius is obtained following [Liu1997](@cite).
-In this case
-```math
-\begin{equation}
-  r_{eff} = \frac{r_{vol}}{k^{\frac{1}{3}}},
-\end{equation}
-```
-where:
-  - ``r_{vol}`` represents the volume-averaged radius,
-  - ``k = 0.8``.
-
-Where the volume-averaged radius is computed using
-```math
-\begin{equation}
-  r_{vol} = \left(\frac{3}{4 \pi \rho_w}\right)^{\frac{1}{3}} \, \left(\frac{L}{N}\right)^{\frac{1}{3}} = \left(\frac{3  \rho (q_{liq} + q_{rai})}{4 \pi \rho_w (N_{liq} + N_{rai})}\right)^{\frac{1}{3}},
-\end{equation}
-```
-where:
-  - ``L = \rho q``, is the liquid water content,
-  - ``N = N_{liq} + N_{rai}``.
-
 ## Additional 2-moment microphysics options
 
 The other autoconversion and accretion rates in the `Microphysics2M.jl` module