KelvinEffect

{
  "reference": {
    "citation": "Seinfeld, J. H., and Pandis, S. N. (2006). Atmospheric Chemistry and Physics: From Air Pollution to Climate Change, 2nd Edition, John Wiley & Sons, Chapter 10. Kelvin equation: Eq. 10.86.",
    "notes": "source_ref: Aerosol.jl@c8c640bb636b22f2425460e9ed5cba50793bfee1:src/seinfeld_pandis_ch10/kelvin_effect.jl:51\n\nUpstream `KelvinEffect` is an MTK `@component` (no parameterization). It declares one `@constants` entry (`R_gas`, the universal gas constant, 8.314 J/mol/K), five scalar `@parameters` — `T` (temperature, K), `R_p` (particle/droplet radius, m), `σ` (surface tension, N/m), `M_mol` (molar mass, kg/mol), `ρ_l` (liquid density, kg/m^3) — and two scalar `@variables` (`ln_S`, `S`, both dimensionless). The two equations are `ln_S ~ 2 σ M_mol / (R_gas T ρ_l R_p)` (the exponent of Eq. 10.86, the Kelvin equation) and `S ~ exp(ln_S)` (the saturation ratio p_A/p°_A).\n\n@constants to parameter: `R_gas` is carried as `type: parameter` with the fixed default 8.314 — the .esm schema has no constant variable type, so every MTK `@constant` migrates as a fixed-default parameter (the convention applied across the rig's prior @constant migrations). The upstream symbol name `R_gas` is kept verbatim; it is deliberately not the schema's reserved physical-constant name `R`, so the reserved-name dimensional check (`_KNOWN_PHYSICAL_CONSTANTS`) does not apply.\n\nObserved classification: KelvinEffect has no `D()` time-derivative anywhere — it is a purely-algebraic component. `ln_S` and `S` are both algebraic outputs (`ln_S ~ ...`, `S ~ exp(ln_S)`). After MTK `mtkcompile` / `structural_simplify` the compiled system has zero ODE states and both become observed quantities — the upstream `ModelingToolkit Integration` test exercises exactly this compiled form (`mtkcompile(KelvinEffect())` then `ODEProblem(compiled, [], (0.0, 1.0))`). They are therefore serialized as `type: observed` with an `expression` (not `type: state` with an equation), and the `equations` array is empty, matching the sibling pure-algebraic Aerosol.jl sp_ch10 migration `zsr.esm`. `S`'s expression references the observed `ln_S`, preserving the upstream `S ~ exp(ln_S)` two-equation structure as an observed dependency chain (`ln_S` resolves from parameters, then `S` from `ln_S`).\n\nUnicode identifiers `σ` and `ρ_l` are kept verbatim from the upstream `@parameters` declaration; the ESM identifier pattern permits unicode and the sibling sp_ch10 migration `zsr.esm` keeps the Greek symbol `α_w`, so no ASCII rename is applied. (The upstream `KelvinEffect Structure` test accepts either `:sigma` or `:σ` for the parameter name; the actual `@parameters` declaration uses `σ`.)\n\nNot migrated: the file-level helper `kelvin_saturation_ratio(T, R_p, σ, M_mol, ρ_l)` in kelvin_effect.jl is a plain Julia function — a scalar closed-form evaluator of Eq. 10.86 — not an MTK component, and is out of scope for this component migration. Its physics is identical to the component, so the upstream `Kelvin Effect Calculation` testset's limiting-case checks (large-droplet S→1, small-droplet S>1.1, temperature and surface-tension monotonicity, multi-compound applicability) are reproduced here as component-level inline tests against `ln_S`/`S`.\n\nTolerance rationale (model-level rel=1e-8): the model is a small closed-form algebraic system — one division of two short products followed by one `exp` — so float64 evaluation roundoff is at the few-ULP (~1e-15 relative) level; rel=1e-8 leaves ample headroom."
  },
  "variables": {
    "R_gas": {
      "type": "parameter",
      "units": "J/mol/K",
      "default": 8.314,
      "description": "Universal (ideal) gas constant — the Eq. 10.86 denominator term R. Migrated from the upstream `@constants` block; the .esm schema has no constant variable type, so it is carried as a fixed-default parameter."
    },
    "T": {
      "type": "parameter",
      "units": "K",
      "default": 298.15,
      "description": "Temperature of the droplet and the surrounding vapor (Eq. 10.86 term T). Appears in the exponent denominator, so a colder droplet has a larger Kelvin enhancement."
    },
    "R_p": {
      "type": "parameter",
      "units": "m",
      "default": 5e-08,
      "description": "Droplet (particle) radius — the radius of curvature of the liquid surface (Eq. 10.86 term R_p). The Kelvin enhancement grows as R_p shrinks and vanishes as R_p → ∞."
    },
    "σ": {
      "type": "parameter",
      "units": "N/m",
      "default": 0.072,
      "description": "Surface tension of the droplet liquid (Eq. 10.86 term σ). The default 0.072 N/m is the surface tension of water near room temperature."
    },
    "M_mol": {
      "type": "parameter",
      "units": "kg/mol",
      "default": 0.018,
      "description": "Molar mass of the condensing species (Eq. 10.86 term M). The default 0.018 kg/mol is the molar mass of water."
    },
    "ρ_l": {
      "type": "parameter",
      "units": "kg/m^3",
      "default": 1000.0,
      "description": "Liquid density of the droplet (Eq. 10.86 term ρ_l). The default 1000 kg/m³ is the density of liquid water."
    },
    "ln_S": {
      "type": "unknown",
      "units": "1",
      "description": "Natural logarithm of the Kelvin saturation ratio — the exponent of Eq. 10.86: ln S = 2 σ M / (R T ρ_l R_p). Dimensionless and non-negative for physical parameters."
    },
    "S": {
      "type": "unknown",
      "units": "1",
      "description": "Kelvin saturation ratio S = p_A / p°_A (Eq. 10.86): the ratio of the equilibrium vapor pressure over the curved droplet surface to that over a flat surface. S ≥ 1 — surface curvature always enhances vapor pressure — and S → 1 as R_p → ∞ (the flat-surface limit)."
    }
  },
  "equations": [
    {
      "lhs": "ln_S",
      "rhs": {
        "op": "/",
        "args": [
          {
            "op": "*",
            "args": [
              2,
              "σ",
              "M_mol"
            ]
          },
          {
            "op": "*",
            "args": [
              "R_gas",
              "T",
              "ρ_l",
              "R_p"
            ]
          }
        ]
      }
    },
    {
      "lhs": "S",
      "rhs": {
        "op": "exp",
        "args": [
          "ln_S"
        ]
      }
    }
  ],
  "tolerance": {
    "rel": 1e-08
  },
  "tests": [
    {
      "id": "default_parameters",
      "description": "Eq. 10.86 at the upstream default parameterization: a 50 nm water droplet at 298.15 K (σ = 0.072 N/m, M = 0.018 kg/mol, ρ_l = 1000 kg/m³). The Kelvin exponent ln S = 2σM/(R T ρ_l R_p) = 0.0209132 and the saturation ratio S = exp(ln S) = 1.021134 — a 2.1% vapor-pressure enhancement. Both outputs are algebraic and time-invariant, so the same values are asserted at t = 0 and t = 1.",
      "parameter_overrides": {},
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "ln_S",
          "time": 0.0,
          "expected": 0.02091318402379585
        },
        {
          "variable": "ln_S",
          "time": 1.0,
          "expected": 0.02091318402379585
        },
        {
          "variable": "S",
          "time": 0.0,
          "expected": 1.0211333970965655
        },
        {
          "variable": "S",
          "time": 1.0,
          "expected": 1.0211333970965655
        }
      ]
    },
    {
      "id": "small_droplet_strong_enhancement",
      "description": "For a small droplet the Kelvin effect is large (upstream `S_small > 1.1`). At R_p = 10 nm — one-fifth the default radius — the exponent scales inversely with R_p to ln S = 0.104566, giving S = 1.110229, an 11% vapor-pressure enhancement.",
      "parameter_overrides": {
        "R_p": 1e-08
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "ln_S",
          "time": 0.0,
          "expected": 0.10456592011897924
        },
        {
          "variable": "S",
          "time": 0.0,
          "expected": 1.110228577853988
        }
      ]
    },
    {
      "id": "large_droplet_negligible_enhancement",
      "description": "For a large droplet the Kelvin effect is negligible (upstream `S_large ≈ 1`, atol 0.002). At R_p = 1 μm — twenty times the default radius — S = 1.001046, within 0.2% of the flat-surface value.",
      "parameter_overrides": {
        "R_p": 1e-06
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "S",
          "time": 0.0,
          "expected": 1.0010462060933767
        }
      ]
    },
    {
      "id": "macroscopic_droplet_flat_surface_limit",
      "description": "The curved-surface enhancement vanishes in the flat-surface limit (upstream `S_very_large ≈ 1`, atol 1e-5). At R_p = 1 mm the saturation ratio S = 1.0000010 differs from unity by ~1e-6 — Eq. 10.86 reduces to p_A = p°_A as R_p → ∞.",
      "parameter_overrides": {
        "R_p": 0.001
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "S",
          "time": 0.0,
          "expected": 1.000001045659748
        }
      ]
    },
    {
      "id": "temperature_dependence",
      "description": "Eq. 10.86 carries temperature in the exponent denominator, so a colder droplet has a larger Kelvin enhancement (upstream `S_cold > S > S_warm`). Cooling from the default 298.15 K to 250 K raises the exponent to ln S = 0.0249411 and S = 1.025255, above the default S = 1.021133.",
      "parameter_overrides": {
        "T": 250.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "ln_S",
          "time": 0.0,
          "expected": 0.024941063266778928
        },
        {
          "variable": "S",
          "time": 0.0,
          "expected": 1.0252546935814038
        }
      ]
    },
    {
      "id": "surface_tension_dependence",
      "description": "Eq. 10.86 carries surface tension linearly in the exponent numerator, so a lower-σ liquid has a smaller Kelvin enhancement (upstream `S_high_sigma > S_low_sigma`). Reducing σ from the default 0.072 N/m to 0.030 N/m lowers the exponent proportionally to ln S = 0.0087138 and S = 1.008752, below the default S = 1.021133.",
      "parameter_overrides": {
        "σ": 0.03
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "ln_S",
          "time": 0.0,
          "expected": 0.008713826676581602
        },
        {
          "variable": "S",
          "time": 0.0,
          "expected": 1.0087519025795066
        }
      ]
    },
    {
      "id": "benzene_droplet",
      "description": "Eq. 10.86 applies to any condensing species, not just water (upstream Table 10.6 multi-compound check `S_benzene > 1`). A 50 nm benzene droplet at 298 K (σ = 0.02821 N/m, M = 0.07811 kg/mol, ρ_l = 879 kg/m³) gives S = 1.041302 — benzene's larger molar mass outweighs its lower surface tension and density, yielding a stronger enhancement than water at the same radius.",
      "parameter_overrides": {
        "T": 298.0,
        "σ": 0.02821,
        "M_mol": 0.07811,
        "ρ_l": 879.0
      },
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "assertions": [
        {
          "variable": "S",
          "time": 0.0,
          "expected": 1.0413021421178397
        }
      ]
    }
  ],
  "analyses": [
    {
      "id": "saturation_ratio_vs_particle_radius",
      "description": "The Kelvin saturation ratio rises steeply as the droplet shrinks (Eq. 10.86). Sweeping the particle radius R_p over the 5 nm – 1 μm range on a logarithmic axis traces S = exp(2σM/(R T ρ_l R_p)) decaying from a strong enhancement for the smallest droplets toward the flat-surface limit S → 1 for the largest.",
      "parameters": {},
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "R_p",
            "range": {
              "start": 5e-09,
              "stop": 1e-06,
              "count": 50,
              "scale": "log"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "s_vs_r_p",
          "type": "line",
          "description": "Kelvin saturation ratio S as a function of droplet radius R_p (water droplet at the default 298.15 K).",
          "x": {
            "variable": "R_p",
            "label": "Droplet radius R_p (m)"
          },
          "y": {
            "variable": "S",
            "label": "Kelvin saturation ratio S (dimensionless)"
          }
        }
      ]
    },
    {
      "id": "saturation_ratio_vs_temperature",
      "description": "The Kelvin enhancement weakens with temperature — Eq. 10.86 carries T in the exponent denominator. Sweeping temperature over the 250–350 K range at the default 50 nm radius traces S decreasing monotonically as the droplet warms.",
      "parameters": {},
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "T",
            "range": {
              "start": 250.0,
              "stop": 350.0,
              "count": 50,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "s_vs_t",
          "type": "line",
          "description": "Kelvin saturation ratio S as a function of temperature T (water droplet at the default 50 nm radius).",
          "x": {
            "variable": "T",
            "label": "Temperature T (K)"
          },
          "y": {
            "variable": "S",
            "label": "Kelvin saturation ratio S (dimensionless)"
          }
        }
      ]
    },
    {
      "id": "saturation_ratio_radius_temperature_heatmap",
      "description": "Joint dependence of the Kelvin saturation ratio on droplet radius and temperature (Eq. 10.86). The heatmap of S(R_p, T) shows the enhancement strongest for small, cold droplets and fading toward unity for large, warm droplets.",
      "parameters": {},
      "time_span": {
        "start": 0.0,
        "end": 1.0
      },
      "parameter_sweep": {
        "type": "cartesian",
        "dimensions": [
          {
            "parameter": "R_p",
            "range": {
              "start": 5e-09,
              "stop": 5e-07,
              "count": 30,
              "scale": "log"
            }
          },
          {
            "parameter": "T",
            "range": {
              "start": 250.0,
              "stop": 350.0,
              "count": 25,
              "scale": "linear"
            }
          }
        ]
      },
      "plots": [
        {
          "id": "s_r_p_t_heatmap",
          "type": "heatmap",
          "description": "S(R_p, T) heatmap — Kelvin saturation ratio over droplet radius and temperature.",
          "x": {
            "variable": "R_p",
            "label": "Droplet radius R_p (m)"
          },
          "y": {
            "variable": "T",
            "label": "Temperature T (K)"
          },
          "value": {
            "variable": "S",
            "reduce": "final"
          }
        }
      ]
    }
  ]
}