HoltslagBovilleLocalDiffusion

{
  "reference": {
    "notes": "source_ref: AtmosphericDynamics.jl@816cc391:src/holtslag_boville_1993.jl:184\n\nHoltslagBovilleLocalDiffusion is an MTK `@component` implementing the local boundary-layer diffusion scheme of Holtslag & Boville (1993), Journal of Climate 6, 1825-1842, Section 3. The six equations are the asymptotic length scale (Eq. 3.6), the harmonic mixing length (Eq. 3.4), the local shear magnitude (Eq. 3.3), the gradient Richardson number (Eq. 3.5), the stability function (Eq. 3.7 unstable / Eq. 2.11 stable), and the eddy diffusivity (Eq. 3.2). All six are algebraic diagnostics — there is no ODE integration.\n\nConstants: the upstream `@constants` g, κ, z_ref, λ_min, λ_range, S_min, and zero_Ri are serialized as parameter-type variables with fixed defaults — the .esm schema has no dedicated constant variable type, and physical constants are carried as parameters. This mirrors the GeneralCirculation and ScaleHeight migrations from the same upstream package.\n\nVariable names: the upstream Unicode identifiers are kept verbatim (θᵥ, ∂θᵥ_∂z, ∂u_∂z, ∂v_∂z, λc, λ_min, λ_range, κ) — mtk2esm serializes MTK symbols as-is and Unicode variable names are used throughout the committed .esm corpus.\n\nStability function: Fc is a two-branch `ifelse` on the sign of Ri. The unstable branch (Ri < 0) is Eq. 3.7, Fc = (1 - 18 Ri)^(1/2); since Ri < 0 there, 1 - 18 Ri > 1 and the square root is always real. The stable branch (Ri >= 0) is Eq. 2.11, Fc = 1/(1 + 10 Ri(1 + 8 Ri)); the denominator 1 + 10 Ri + 80 Ri^2 has no real roots, so it never vanishes. The branch boundary Ri = 0 evaluates the stable branch to exactly Fc = 1, matching the unstable-branch limit, so Fc is continuous.\n\nRegularization and finiteness: the shear S carries an additive floor S_min = 1e-6 1/s (upstream 'Minimum shear for regularization'), so Ri = (g/θᵥ)(∂θᵥ/∂z)/S^2 and Kc stay finite even at zero wind shear. The mixing length lc = 1/(1/(κ z) + 1/λc) tends to 0 (not 0/0) as z -> 0. There is no singular test point for this component, so every inline test asserts at its nominal parameter values.\n\nTolerance rationale (rel=1e-6, abs=1e-9): an algebraic diagnostic system with no ODE integration. rel=1e-6 covers float64 round-off in the closed-form exp / sqrt / divide chain; abs=1e-9 covers the intended exact zero (Ri = 0 in the neutral_richardson test, where ∂θᵥ/∂z = 0 makes the numerator identically zero)."
  },
  "tolerance": {
    "rel": 1e-06,
    "abs": 1e-09
  },
  "variables": {
    "g": {
      "type": "parameter",
      "units": "m/s^2",
      "default": 9.81,
      "description": "Gravitational acceleration"
    },
    "κ": {
      "type": "parameter",
      "units": "1",
      "default": 0.4,
      "description": "von Karman constant (dimensionless)"
    },
    "z_ref": {
      "type": "parameter",
      "units": "m",
      "default": 1000.0,
      "description": "Reference height for λc calculation (Eq. 3.6)"
    },
    "λ_min": {
      "type": "parameter",
      "units": "m",
      "default": 30.0,
      "description": "Free atmosphere asymptotic length scale (Eq. 3.6)"
    },
    "λ_range": {
      "type": "parameter",
      "units": "m",
      "default": 270.0,
      "description": "Range of asymptotic length scale (Eq. 3.6)"
    },
    "S_min": {
      "type": "parameter",
      "units": "1/s",
      "default": 1e-06,
      "description": "Minimum shear for regularization"
    },
    "zero_Ri": {
      "type": "parameter",
      "units": "1",
      "default": 0.0,
      "description": "Zero Richardson number for comparison"
    },
    "z": {
      "type": "parameter",
      "units": "m",
      "default": 100.0,
      "description": "Height above surface"
    },
    "θᵥ": {
      "type": "parameter",
      "units": "K",
      "default": 300.0,
      "description": "Virtual potential temperature"
    },
    "∂θᵥ_∂z": {
      "type": "parameter",
      "units": "K/m",
      "default": 0.003,
      "description": "Vertical gradient of virtual potential temperature"
    },
    "∂u_∂z": {
      "type": "parameter",
      "units": "1/s",
      "default": 0.01,
      "description": "Vertical gradient of zonal wind"
    },
    "∂v_∂z": {
      "type": "parameter",
      "units": "1/s",
      "default": 0.0,
      "description": "Vertical gradient of meridional wind"
    },
    "λc": {
      "type": "unknown",
      "units": "m",
      "description": "Asymptotic length scale (Eq. 3.6)"
    },
    "lc": {
      "type": "unknown",
      "units": "m",
      "description": "Mixing length scale (Eq. 3.4)"
    },
    "S": {
      "type": "unknown",
      "units": "1/s",
      "description": "Local wind shear magnitude (Eq. 3.3)"
    },
    "Ri": {
      "type": "unknown",
      "units": "1",
      "description": "Gradient Richardson number (Eq. 3.5) (dimensionless)"
    },
    "Fc": {
      "type": "unknown",
      "units": "1",
      "description": "Stability function (Eq. 3.7/2.11) (dimensionless)"
    },
    "Kc": {
      "type": "unknown",
      "units": "m^2/s",
      "description": "Eddy diffusivity (Eq. 3.2)"
    }
  },
  "equations": [
    {
      "lhs": "λc",
      "rhs": {
        "op": "+",
        "args": [
          "λ_min",
          {
            "op": "*",
            "args": [
              "λ_range",
              {
                "op": "exp",
                "args": [
                  {
                    "op": "-",
                    "args": [
                      1,
                      {
                        "op": "/",
                        "args": [
                          "z",
                          "z_ref"
                        ]
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    },
    {
      "lhs": "lc",
      "rhs": {
        "op": "/",
        "args": [
          1,
          {
            "op": "+",
            "args": [
              {
                "op": "/",
                "args": [
                  1,
                  {
                    "op": "*",
                    "args": [
                      "κ",
                      "z"
                    ]
                  }
                ]
              },
              {
                "op": "/",
                "args": [
                  1,
                  "λc"
                ]
              }
            ]
          }
        ]
      }
    },
    {
      "lhs": "S",
      "rhs": {
        "op": "+",
        "args": [
          {
            "op": "sqrt",
            "args": [
              {
                "op": "+",
                "args": [
                  {
                    "op": "^",
                    "args": [
                      "∂u_∂z",
                      2
                    ]
                  },
                  {
                    "op": "^",
                    "args": [
                      "∂v_∂z",
                      2
                    ]
                  }
                ]
              }
            ]
          },
          "S_min"
        ]
      }
    },
    {
      "lhs": "Ri",
      "rhs": {
        "op": "/",
        "args": [
          {
            "op": "*",
            "args": [
              {
                "op": "/",
                "args": [
                  "g",
                  "θᵥ"
                ]
              },
              "∂θᵥ_∂z"
            ]
          },
          {
            "op": "^",
            "args": [
              "S",
              2
            ]
          }
        ]
      }
    },
    {
      "lhs": "Fc",
      "rhs": {
        "op": "ifelse",
        "args": [
          {
            "op": "<",
            "args": [
              "Ri",
              "zero_Ri"
            ]
          },
          {
            "op": "sqrt",
            "args": [
              {
                "op": "-",
                "args": [
                  1,
                  {
                    "op": "*",
                    "args": [
                      18,
                      "Ri"
                    ]
                  }
                ]
              }
            ]
          },
          {
            "op": "/",
            "args": [
              1,
              {
                "op": "+",
                "args": [
                  1,
                  {
                    "op": "*",
                    "args": [
                      10,
                      "Ri",
                      {
                        "op": "+",
                        "args": [
                          1,
                          {
                            "op": "*",
                            "args": [
                              8,
                              "Ri"
                            ]
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    },
    {
      "lhs": "Kc",
      "rhs": {
        "op": "*",
        "args": [
          {
            "op": "^",
            "args": [
              "lc",
              2
            ]
          },
          "S",
          "Fc"
        ]
      }
    }
  ],
  "tests": [
    {
      "id": "default_parameters",
      "description": "All parameters at their declared defaults (z = 100 m, θᵥ = 300 K, ∂θᵥ/∂z = 0.003 K/m, ∂u/∂z = 0.01 1/s, ∂v/∂z = 0). Verifies the declared defaults are wired correctly and exercises all six diagnostic outputs. With ∂θᵥ/∂z > 0 the regime is weakly stable (Ri > 0, Fc < 1).",
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "λc",
          "time": 0.0,
          "expected": 694.0928400123764
        },
        {
          "variable": "lc",
          "time": 0.0,
          "expected": 37.8204391695565
        },
        {
          "variable": "S",
          "time": 0.0,
          "expected": 0.010001
        },
        {
          "variable": "Ri",
          "time": 0.0,
          "expected": 0.9808038294260766
        },
        {
          "variable": "Fc",
          "time": 0.0,
          "expected": 0.011393916935737379
        },
        {
          "variable": "Kc",
          "time": 0.0,
          "expected": 0.16299324698202905
        }
      ]
    },
    {
      "id": "length_scale_at_1km",
      "description": "Asymptotic and mixing length scales at z = 1000 m (Holtslag & Boville Eq. 3.6, 3.4). At z = z_ref the exponential is exp(0) = 1, so λc = 30 + 270 = 300 m (the paper's stated λc ≈ 300 m for z ≤ 1 km); the harmonic mixing length is lc = 1/(1/(κ z) + 1/λc).",
      "parameter_overrides": {
        "z": 1000.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "λc",
          "time": 0.0,
          "expected": 300.0
        },
        {
          "variable": "lc",
          "time": 0.0,
          "expected": 171.42857142857142
        }
      ]
    },
    {
      "id": "length_scale_free_atmosphere",
      "description": "Asymptotic and mixing length scales at z = 5000 m. High above the boundary layer λc = 30 + 270 exp(1 - 5) = 30 + 270 exp(-4) ≈ 34.95 m, approaching the free-atmosphere floor λ_min = 30 m (Eq. 3.6).",
      "parameter_overrides": {
        "z": 5000.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "λc",
          "time": 0.0,
          "expected": 34.94522249995823
        },
        {
          "variable": "lc",
          "time": 0.0,
          "expected": 34.345123508560626
        }
      ]
    },
    {
      "id": "unstable_eddy_diffusivity",
      "description": "Full eddy-diffusivity chain at z = 500 m in unstable conditions (∂θᵥ/∂z = -0.005 K/m) with two-component shear (∂u/∂z = 0.02, ∂v/∂z = 0.01 1/s). Exercises Eq. 3.3 (shear magnitude S), Eq. 3.5 (Ri < 0), Eq. 3.7 (unstable Fc = (1 - 18 Ri)^(1/2) > 1) and the Eq. 3.2 product Kc = lc^2 S Fc.",
      "parameter_overrides": {
        "z": 500.0,
        "∂θᵥ_∂z": -0.005,
        "∂u_∂z": 0.02,
        "∂v_∂z": 0.01
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "lc",
          "time": 0.0,
          "expected": 140.75432275423552
        },
        {
          "variable": "S",
          "time": 0.0,
          "expected": 0.022361679774997898
        },
        {
          "variable": "Ri",
          "time": 0.0,
          "expected": -0.32697075419273725
        },
        {
          "variable": "Fc",
          "time": 0.0,
          "expected": 2.6240185928208035
        },
        {
          "variable": "Kc",
          "time": 0.0,
          "expected": 1162.504961014828
        }
      ]
    },
    {
      "id": "stable_conditions",
      "description": "Stable stratification at z = 500 m (∂θᵥ/∂z = 0.01 K/m > 0). A positive virtual-potential-temperature gradient gives Ri > 0, so the stability function takes the stable branch Eq. 2.11 Fc = 1/(1 + 10 Ri(1 + 8 Ri)) < 1 (suppressed mixing) and Kc stays positive.",
      "parameter_overrides": {
        "z": 500.0,
        "∂θᵥ_∂z": 0.01,
        "∂u_∂z": 0.01,
        "∂v_∂z": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "Ri",
          "time": 0.0,
          "expected": 3.269346098086922
        },
        {
          "variable": "Fc",
          "time": 0.0,
          "expected": 0.0011251335585061304
        },
        {
          "variable": "Kc",
          "time": 0.0,
          "expected": 0.22293126917193654
        }
      ]
    },
    {
      "id": "unstable_conditions",
      "description": "Unstable stratification at z = 500 m (∂θᵥ/∂z = -0.01 K/m < 0), the hemispheric mirror of stable_conditions. A negative gradient gives Ri < 0, so Fc takes the unstable branch Eq. 3.7 Fc = (1 - 18 Ri)^(1/2) > 1 (enhanced mixing) and Kc exceeds its stable-case value.",
      "parameter_overrides": {
        "z": 500.0,
        "∂θᵥ_∂z": -0.01,
        "∂u_∂z": 0.01,
        "∂v_∂z": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "Ri",
          "time": 0.0,
          "expected": -3.269346098086922
        },
        {
          "variable": "Fc",
          "time": 0.0,
          "expected": 7.736163762845548
        },
        {
          "variable": "Kc",
          "time": 0.0,
          "expected": 1532.824963876238
        }
      ]
    },
    {
      "id": "neutral_richardson",
      "description": "Neutral stratification at z = 500 m (∂θᵥ/∂z = 0 exactly). Eq. 3.5 gives Ri = 0, which selects the stable branch at its boundary: Fc = 1/(1 + 0) = 1. Mixing is then governed purely by the local shear, Kc = lc^2 S.",
      "parameter_overrides": {
        "z": 500.0,
        "∂θᵥ_∂z": 0.0,
        "∂u_∂z": 0.01,
        "∂v_∂z": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "S",
          "time": 0.0,
          "expected": 0.010001
        },
        {
          "variable": "Ri",
          "time": 0.0,
          "expected": 0.0
        },
        {
          "variable": "Fc",
          "time": 0.0,
          "expected": 1.0
        },
        {
          "variable": "Kc",
          "time": 0.0,
          "expected": 198.137605519409
        }
      ]
    }
  ],
  "analyses": [
    {
      "id": "length_scales_vs_height",
      "description": "Asymptotic length scale λc (Eq. 3.6) and harmonic mixing length lc (Eq. 3.4) as functions of height over 10-2000 m. λc decays from ~757 m near the surface toward the free-atmosphere floor of 30 m; lc is the harmonic blend of the surface-proportional κ z and λc, so it peaks in the mid-boundary-layer. Reproduces the length-scale behaviour behind the AtmosphericDynamics.jl 'Local Scheme Eddy Diffusivity Profile' documentation figure.",
      "initial_state": {},
      "parameters": {
        "θᵥ": 300.0,
        "∂θᵥ_∂z": 0.003,
        "∂u_∂z": 0.01,
        "∂v_∂z": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "z",
            "range": {
              "start": 10.0,
              "stop": 2000.0,
              "count": 100,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "lambda_c_vs_z",
          "type": "line",
          "description": "Asymptotic length scale λc as a function of height.",
          "x": {
            "variable": "z",
            "label": "Height z (m)"
          },
          "y": {
            "variable": "λc",
            "label": "Asymptotic length scale λc (m)"
          }
        },
        {
          "id": "l_c_vs_z",
          "type": "line",
          "description": "Harmonic mixing length lc as a function of height.",
          "x": {
            "variable": "z",
            "label": "Height z (m)"
          },
          "y": {
            "variable": "lc",
            "label": "Mixing length lc (m)"
          }
        }
      ]
    },
    {
      "id": "unstable_eddy_diffusivity_profile",
      "description": "Eddy diffusivity Kc (Eq. 3.2) versus height for unstable stratification (∂θᵥ/∂z = -0.005 K/m). Reproduces the unstable curve of the AtmosphericDynamics.jl 'Local Scheme Eddy Diffusivity Profile (Eq. 3.2)' documentation figure: enhanced mixing (Fc > 1) lifts Kc above its stable-case value.",
      "initial_state": {},
      "parameters": {
        "θᵥ": 300.0,
        "∂θᵥ_∂z": -0.005,
        "∂u_∂z": 0.01,
        "∂v_∂z": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "z",
            "range": {
              "start": 10.0,
              "stop": 2000.0,
              "count": 100,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "Kc_vs_z",
          "type": "line",
          "description": "Eddy diffusivity Kc as a function of height (unstable).",
          "x": {
            "variable": "z",
            "label": "Height z (m)"
          },
          "y": {
            "variable": "Kc",
            "label": "Eddy diffusivity Kc (m^2/s)"
          }
        }
      ]
    },
    {
      "id": "stable_eddy_diffusivity_profile",
      "description": "Eddy diffusivity Kc (Eq. 3.2) versus height for stable stratification (∂θᵥ/∂z = 0.005 K/m). Reproduces the stable curve of the AtmosphericDynamics.jl 'Local Scheme Eddy Diffusivity Profile (Eq. 3.2)' documentation figure: suppressed mixing (Fc < 1) holds Kc below its unstable-case value.",
      "initial_state": {},
      "parameters": {
        "θᵥ": 300.0,
        "∂θᵥ_∂z": 0.005,
        "∂u_∂z": 0.01,
        "∂v_∂z": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "z",
            "range": {
              "start": 10.0,
              "stop": 2000.0,
              "count": 100,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "Kc_vs_z",
          "type": "line",
          "description": "Eddy diffusivity Kc as a function of height (stable).",
          "x": {
            "variable": "z",
            "label": "Height z (m)"
          },
          "y": {
            "variable": "Kc",
            "label": "Eddy diffusivity Kc (m^2/s)"
          }
        }
      ]
    },
    {
      "id": "stability_function_vs_richardson",
      "description": "Local-diffusion stability function Fc as a function of the gradient Richardson number Ri, swept by varying ∂θᵥ/∂z at fixed z = 500 m and shear. Shows the two-branch behaviour: the unstable branch Eq. 3.7 Fc = (1 - 18 Ri)^(1/2) rising above 1 for Ri < 0, and the stable branch Eq. 2.11 Fc = 1/(1 + 10 Ri(1 + 8 Ri)) decaying below 1 for Ri > 0, joined continuously at Fc = 1 for neutral Ri = 0.",
      "initial_state": {},
      "parameters": {
        "θᵥ": 300.0,
        "z": 500.0,
        "∂u_∂z": 0.01,
        "∂v_∂z": 0.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "∂θᵥ_∂z",
            "range": {
              "start": -0.01,
              "stop": 0.01,
              "count": 101,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "Fc_vs_Ri",
          "type": "line",
          "description": "Stability function Fc as a function of gradient Richardson number Ri.",
          "x": {
            "variable": "Ri",
            "label": "Gradient Richardson number Ri"
          },
          "y": {
            "variable": "Fc",
            "label": "Stability function Fc"
          }
        }
      ]
    }
  ]
}