SuperFastDepositionSink

Operator model that turns first-order dry + wet deposition loss-rate coefficients into additive sink terms on a SuperFast-family gas-phase mechanism. Each equation is D(<X>) ~ -(k_dry + k_wet)*<X> over the model's OWN species unknowns; when this model is merged with a SuperFast reaction system via an `operator_compose` coupling (systems: [<Chem>, SuperFastDepositionSink]), the flattener matches each sink equation's dependent variable to the chemistry system's state of the same species name and sums the two right-hand sides (dc/dt += -k*c), then retires the sink's own declaration of that name (esm-spec 10.1/10.2 — direct match, else the bare-name match). The deposition rate coefficients are exposed as parameters so they can be driven from the full DryDepositionGas (Wesley 1989) and WetDeposition (EMEP) components via param_to_var edges in an assembly. Species->rate mapping mirrors AtmosphericDeposition.jl/ext/GasChemExt.jl couple2(SuperFastCoupler, DryDepositionGasCoupler / WetDepositionCoupler): NO reuses NO2's dry-dep rate; CH2O uses the formaldehyde (HCHO) dry-dep rate; the wet rate k_wet is the lumped soluble-gas WetDeposition.k_othergas applied to HNO3, H2O2, CH2O, CH3OOH.

Domain: atmospheric_deposition
Type: model
.esm schema: 1.0.0
Source: components/atmospheric_deposition/superfast_deposition_sink.esm
Tags: #atmospheric_deposition #model #gaschem #superfast #deposition-sink #operator-compose

Description

Operator model that turns first-order dry + wet deposition loss-rate coefficients into additive sink terms on a SuperFast-family gas-phase mechanism. Each equation is D() ~ -(k_dry + k_wet) over the model’s OWN species unknowns; when this model is merged with a SuperFast reaction system via an operator_compose coupling (systems: [, SuperFastDepositionSink]), the flattener matches each sink equation’s dependent variable to the chemistry system’s state of the same species name and sums the two right-hand sides (dc/dt += -kc), then retires the sink’s own declaration of that name (esm-spec 10.1/10.2 — direct match, else the bare-name match). The deposition rate coefficients are exposed as parameters so they can be driven from the full DryDepositionGas (Wesley 1989) and WetDeposition (EMEP) components via param_to_var edges in an assembly. Species->rate mapping mirrors AtmosphericDeposition.jl/ext/GasChemExt.jl couple2(SuperFastCoupler, DryDepositionGasCoupler / WetDepositionCoupler): NO reuses NO2’s dry-dep rate; CH2O uses the formaldehyde (HCHO) dry-dep rate; the wet rate k_wet is the lumped soluble-gas WetDeposition.k_othergas applied to HNO3, H2O2, CH2O, CH3OOH.

The species are declared here as ordinary unknowns with the upstream SuperFast initial mixing ratios as defaults, so the applicator is a complete, standalone-loadable, standalone-testable document: on its own it integrates seven decoupled first-order decays whose closed-form solution c(t) = c0exp(-kt) is what the inline tests pin, and the species->rate mapping (NO on NO2’s dry rate, k_wet only on the four soluble species) is asserted rather than only asserted in prose. Composition is unaffected: operator_compose matches on the species NAME.

This replaces an earlier spelling in which the equations were written directly against SuperFast.<X> scoped references. That form hard-coded the partner system’s document-level name into the leaf and, per esm-spec 4.6 (the head segment of a scoped reference MUST name a key of this document’s models / reaction_systems, or a subsystem of the referencing model), referenced a system this document does not declare — so load_path rejected the file with reference '<X>' to undefined system 'SuperFast' and neither the CI gate nor any runner could load it. Mounting SuperFast as a subsystems entry would have silenced that error only by changing the composition: the chemistry would then live INSIDE the sink at SuperFastDepositionSink.SuperFast.* and no longer merge with the sibling chemistry system under operator_compose. Name matching is the construct the spec provides for this, and it is what the flattener implements.

IMPORTANT (esm implementation note, carried over from the migration): the additive sink is delivered as a model whose D() equations are merged by operator_compose, NOT via a couple connector with transform:“additive”. The additive/from/to connector form is accepted by the schema (esm-spec 10.3) but was observed during migration not to reach the ODEs through the flatten pipeline’s _apply_couple! (a {from,to,transform:additive,expression} edge went to opaque_refs and was discarded). operator_compose (which sums equations sharing a dependent variable) is the working construct.

Reference

Wesely, M. L. (1989). Parameterization of surface resistances to gaseous dry deposition in regional-scale numerical models. Atmospheric Environment 23(6):1293-1304.

Variables

Name	Units	Default	Description
`O3`	`ppb`	`40.0`	Ozone mixing ratio the dry-deposition sink acts on. Merged onto the chemistry system’s O3 by operator_compose; the default is SuperFast’s own O3 initial value (40 ppb), used when this applicator is integrated standalone.
`NO2`	`ppb`	`0.0004`	Nitrogen dioxide mixing ratio. Default is SuperFast’s NO2 initial value.
`NO`	`ppb`	`0.0004`	Nitric oxide mixing ratio. Deposits at NO2’s dry-deposition rate, per GasChemExt. Default is SuperFast’s NO initial value.
`HNO3`	`ppb`	`4e-06`	Nitric acid mixing ratio. Soluble: loses to both dry deposition and wet scavenging. Default is SuperFast’s HNO3 initial value.
`H2O2`	`ppb`	`4e-06`	Hydrogen peroxide mixing ratio. Soluble: dry + wet. Default is SuperFast’s H2O2 initial value.
`CH2O`	`ppb`	`4e-06`	Formaldehyde mixing ratio. Soluble: dry (at the HCHO rate) + wet. Default is SuperFast’s CH2O initial value.
`CH3OOH`	`ppb`	`4e-06`	Methyl hydroperoxide mixing ratio. Wet scavenging only — GasChemExt gives it no dry-deposition rate. Default is SuperFast’s CH3OOH initial value.

Parameters

Name	Units	Default	Description
`k_O3`	`1/s`	`0.0`	O3 dry-deposition first-order loss rate (from DryDepositionGas.k_O3).
`k_NO2`	`1/s`	`0.0`	NO2 dry-deposition rate (also applied to NO, per GasChemExt).
`k_HNO3`	`1/s`	`0.0`	HNO3 dry-deposition rate.
`k_H2O2`	`1/s`	`0.0`	H2O2 dry-deposition rate.
`k_HCHO`	`1/s`	`0.0`	CH2O (formaldehyde) dry-deposition rate.
`k_wet`	`1/s`	`0.0`	Lumped soluble-gas wet-scavenging rate (from WetDeposition.k_othergas), applied to HNO3, H2O2, CH2O, CH3OOH.

Equations

$$ \mathrm{D}\left(O3\right) = \left(-k_{O3}\right) \cdot O3 $$ $$ \mathrm{D}\left(NO2\right) = \left(-k_{NO2}\right) \cdot NO2 $$ $$ \mathrm{D}\left(NO\right) = \left(-k_{NO2}\right) \cdot NO $$ $$ \mathrm{D}\left(HNO3\right) = \left(-\left(k_{HNO3} + k_{wet}\right)\right) \cdot HNO3 $$ $$ \mathrm{D}\left(H2O2\right) = \left(-\left(k_{H2O2} + k_{wet}\right)\right) \cdot H2O2 $$ $$ \mathrm{D}\left(CH2O\right) = \left(-\left(k_{HCHO} + k_{wet}\right)\right) \cdot CH2O $$ $$ \mathrm{D}\left(CH3OOH\right) = \left(-k_{wet}\right) \cdot CH3OOH $$

Raw .esm

Raw .esm JSON (this component)

{
  "variables": {
    "O3": {
      "type": "unknown",
      "units": "ppb",
      "default": 40.0,
      "description": "Ozone mixing ratio the dry-deposition sink acts on. Merged onto the chemistry system's O3 by operator_compose; the default is SuperFast's own O3 initial value (40 ppb), used when this applicator is integrated standalone."
    },
    "NO2": {
      "type": "unknown",
      "units": "ppb",
      "default": 0.0004,
      "description": "Nitrogen dioxide mixing ratio. Default is SuperFast's NO2 initial value."
    },
    "NO": {
      "type": "unknown",
      "units": "ppb",
      "default": 0.0004,
      "description": "Nitric oxide mixing ratio. Deposits at NO2's dry-deposition rate, per GasChemExt. Default is SuperFast's NO initial value."
    },
    "HNO3": {
      "type": "unknown",
      "units": "ppb",
      "default": 4e-06,
      "description": "Nitric acid mixing ratio. Soluble: loses to both dry deposition and wet scavenging. Default is SuperFast's HNO3 initial value."
    },
    "H2O2": {
      "type": "unknown",
      "units": "ppb",
      "default": 4e-06,
      "description": "Hydrogen peroxide mixing ratio. Soluble: dry + wet. Default is SuperFast's H2O2 initial value."
    },
    "CH2O": {
      "type": "unknown",
      "units": "ppb",
      "default": 4e-06,
      "description": "Formaldehyde mixing ratio. Soluble: dry (at the HCHO rate) + wet. Default is SuperFast's CH2O initial value."
    },
    "CH3OOH": {
      "type": "unknown",
      "units": "ppb",
      "default": 4e-06,
      "description": "Methyl hydroperoxide mixing ratio. Wet scavenging only — GasChemExt gives it no dry-deposition rate. Default is SuperFast's CH3OOH initial value."
    },
    "k_O3": {
      "type": "parameter",
      "units": "1/s",
      "default": 0.0,
      "description": "O3 dry-deposition first-order loss rate (from DryDepositionGas.k_O3)."
    },
    "k_NO2": {
      "type": "parameter",
      "units": "1/s",
      "default": 0.0,
      "description": "NO2 dry-deposition rate (also applied to NO, per GasChemExt)."
    },
    "k_HNO3": {
      "type": "parameter",
      "units": "1/s",
      "default": 0.0,
      "description": "HNO3 dry-deposition rate."
    },
    "k_H2O2": {
      "type": "parameter",
      "units": "1/s",
      "default": 0.0,
      "description": "H2O2 dry-deposition rate."
    },
    "k_HCHO": {
      "type": "parameter",
      "units": "1/s",
      "default": 0.0,
      "description": "CH2O (formaldehyde) dry-deposition rate."
    },
    "k_wet": {
      "type": "parameter",
      "units": "1/s",
      "default": 0.0,
      "description": "Lumped soluble-gas wet-scavenging rate (from WetDeposition.k_othergas), applied to HNO3, H2O2, CH2O, CH3OOH."
    }
  },
  "equations": [
    {
      "lhs": {
        "op": "D",
        "args": [
          "O3"
        ],
        "wrt": "t"
      },
      "rhs": {
        "op": "*",
        "args": [
          {
            "op": "-",
            "args": [
              "k_O3"
            ]
          },
          "O3"
        ]
      }
    },
    {
      "lhs": {
        "op": "D",
        "args": [
          "NO2"
        ],
        "wrt": "t"
      },
      "rhs": {
        "op": "*",
        "args": [
          {
            "op": "-",
            "args": [
              "k_NO2"
            ]
          },
          "NO2"
        ]
      }
    },
    {
      "lhs": {
        "op": "D",
        "args": [
          "NO"
        ],
        "wrt": "t"
      },
      "rhs": {
        "op": "*",
        "args": [
          {
            "op": "-",
            "args": [
              "k_NO2"
            ]
          },
          "NO"
        ]
      }
    },
    {
      "lhs": {
        "op": "D",
        "args": [
          "HNO3"
        ],
        "wrt": "t"
      },
      "rhs": {
        "op": "*",
        "args": [
          {
            "op": "-",
            "args": [
              {
                "op": "+",
                "args": [
                  "k_HNO3",
                  "k_wet"
                ]
              }
            ]
          },
          "HNO3"
        ]
      }
    },
    {
      "lhs": {
        "op": "D",
        "args": [
          "H2O2"
        ],
        "wrt": "t"
      },
      "rhs": {
        "op": "*",
        "args": [
          {
            "op": "-",
            "args": [
              {
                "op": "+",
                "args": [
                  "k_H2O2",
                  "k_wet"
                ]
              }
            ]
          },
          "H2O2"
        ]
      }
    },
    {
      "lhs": {
        "op": "D",
        "args": [
          "CH2O"
        ],
        "wrt": "t"
      },
      "rhs": {
        "op": "*",
        "args": [
          {
            "op": "-",
            "args": [
              {
                "op": "+",
                "args": [
                  "k_HCHO",
                  "k_wet"
                ]
              }
            ]
          },
          "CH2O"
        ]
      }
    },
    {
      "lhs": {
        "op": "D",
        "args": [
          "CH3OOH"
        ],
        "wrt": "t"
      },
      "rhs": {
        "op": "*",
        "args": [
          {
            "op": "-",
            "args": [
              "k_wet"
            ]
          },
          "CH3OOH"
        ]
      }
    }
  ],
  "tests": [
    {
      "id": "dry_deposition_only_first_order_decay",
      "description": "Dry deposition alone (k_wet = 0), one hour. Each species obeys the closed-form first-order decay c(t) = c0*exp(-k*t), so every expected value below is analytic, not a recorded output: O3 = 40*exp(-1e-4*3600) = 40*exp(-0.36); NO2 = 4e-4*exp(-2e-4*3600) = 4e-4*exp(-0.72). NO is asserted at the SAME value as NO2 because GasChemExt gives NO no rate of its own and reuses k_NO2 — the assertion pins that mapping. CH3OOH is asserted UNCHANGED at its initial 4e-6 ppb, pinning that it carries no dry-deposition term. Tolerance rel=1e-6 is a numerical-integration band over 3600 s of a linear decay, well inside the runner's default accuracy and far tighter than the ~4e-2 relative change the mapping itself is being distinguished by.",
      "time_span": {
        "start": 0.0,
        "end": 3600.0
      },
      "parameter_overrides": {
        "k_O3": 0.0001,
        "k_NO2": 0.0002,
        "k_HNO3": 0.0,
        "k_H2O2": 0.0,
        "k_HCHO": 0.0,
        "k_wet": 0.0
      },
      "assertions": [
        {
          "variable": "O3",
          "time": 3600.0,
          "expected": 27.90705304284124,
          "tolerance": {
            "rel": 1e-06
          }
        },
        {
          "variable": "NO2",
          "time": 3600.0,
          "expected": 0.00019470090238398867,
          "tolerance": {
            "rel": 1e-06
          }
        },
        {
          "variable": "NO",
          "time": 3600.0,
          "expected": 0.00019470090238398867,
          "tolerance": {
            "rel": 1e-06
          }
        },
        {
          "variable": "CH3OOH",
          "time": 3600.0,
          "expected": 4e-06,
          "tolerance": {
            "rel": 1e-09
          }
        }
      ]
    },
    {
      "id": "wet_scavenging_adds_only_to_soluble_species",
      "description": "Wet scavenging switched on (k_wet = 5e-5 1/s) alongside two dry rates, one hour. The four soluble species lose at (k_dry + k_wet) and the insoluble ones at k_dry alone, so the expected values are again analytic: HNO3 = 4e-6*exp(-(1e-4+5e-5)*3600) = 4e-6*exp(-0.54); H2O2 = 4e-6*exp(-5e-5*3600) = 4e-6*exp(-0.18) (no dry rate set, wet only); CH2O = 4e-6*exp(-(3e-5+5e-5)*3600) = 4e-6*exp(-0.288), which pins that CH2O rides the HCHO dry rate k_HCHO; CH3OOH = 4e-6*exp(-0.18), wet only. O3 is asserted UNCHANGED at 40 ppb with every dry rate zeroed, pinning that k_wet is NOT applied to the insoluble species — the half of the GasChemExt mapping that a wet-only assertion on the soluble four cannot distinguish.",
      "time_span": {
        "start": 0.0,
        "end": 3600.0
      },
      "parameter_overrides": {
        "k_O3": 0.0,
        "k_NO2": 0.0,
        "k_HNO3": 0.0001,
        "k_H2O2": 0.0,
        "k_HCHO": 3e-05,
        "k_wet": 5e-05
      },
      "assertions": [
        {
          "variable": "HNO3",
          "time": 3600.0,
          "expected": 2.3309930094959583e-06,
          "tolerance": {
            "rel": 1e-06
          }
        },
        {
          "variable": "H2O2",
          "time": 3600.0,
          "expected": 3.341080845645088e-06,
          "tolerance": {
            "rel": 1e-06
          }
        },
        {
          "variable": "CH2O",
          "time": 3600.0,
          "expected": 2.9990463689561647e-06,
          "tolerance": {
            "rel": 1e-06
          }
        },
        {
          "variable": "CH3OOH",
          "time": 3600.0,
          "expected": 3.341080845645088e-06,
          "tolerance": {
            "rel": 1e-06
          }
        },
        {
          "variable": "O3",
          "time": 3600.0,
          "expected": 40.0,
          "tolerance": {
            "rel": 1e-09
          }
        }
      ]
    }
  ]
}