diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4f8931c --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.DS_Store +docs/build diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/README.md b/README.md new file mode 100644 index 0000000..ffeee8d --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +# Chemistry Across Multiple Phases Configuration diff --git a/_sources/aerosol_phases/index.rst.txt b/_sources/aerosol_phases/index.rst.txt new file mode 100644 index 0000000..6bc3dde --- /dev/null +++ b/_sources/aerosol_phases/index.rst.txt @@ -0,0 +1,7 @@ +############## +Aerosol Phases +############## + +.. toctree:: + :maxdepth: 2 + :caption: Contents: diff --git a/_sources/aerosol_representations/index.rst.txt b/_sources/aerosol_representations/index.rst.txt new file mode 100644 index 0000000..eb8f385 --- /dev/null +++ b/_sources/aerosol_representations/index.rst.txt @@ -0,0 +1,7 @@ +###################### +Aerosol Representation +###################### + +.. toctree:: + :maxdepth: 2 + :caption: Contents: diff --git a/_sources/bibliography.rst.txt b/_sources/bibliography.rst.txt new file mode 100644 index 0000000..9b775c8 --- /dev/null +++ b/_sources/bibliography.rst.txt @@ -0,0 +1,6 @@ +############ +Bibliography +############ + +.. bibliography:: + :all: \ No newline at end of file diff --git a/_sources/chemical_species/index.rst.txt b/_sources/chemical_species/index.rst.txt new file mode 100644 index 0000000..cd7d2cf --- /dev/null +++ b/_sources/chemical_species/index.rst.txt @@ -0,0 +1,56 @@ +.. _chemical-species: + +################ +Chemical Species +################ + +An object containing information about a chemical species has the following format: + +.. tab-set:: + + .. tab-item:: YAML + + .. code-block:: yaml + :force: + + camp-data: + - name: my species name + type: CHEM_SPEC + - name: my other species name + type: CHEM_SPEC + "molecular weight [kg mol-1]": 0.025 + "diffusion coefficient [m2 s-1]": 2.3e2 + + + .. tab-item:: JSON + + .. code-block:: json + :force: + + { + "camp-data": [ + { + "name": "my species name", + "type": "CHEM_SPEC" + }, + { + "name": "my other species name", + "type": "CHEM_SPEC", + "molecular weight [kg mol-1]": 0.025, + "diffusion coefficient [m2 s-1]": 2.3e2 + } + ] + } + + +The key-value pair ``name`` is required and must contain the unique name used for this +species. +The key-value pair ``type`` is also required, and must be ``CHEM_SPEC``. +Optional key-value pairs are used to define physical and chemical properties. +These include: + +- ``"molecular weight [kg mol-1]"`` +- ``"diffusion coefficient [m2 s-1]"`` + +These optional properties are only required when a species participates in a +reaction that requires that a particular property be defined (e.g., surface reactions). diff --git a/_sources/examples/index.rst.txt b/_sources/examples/index.rst.txt new file mode 100644 index 0000000..4a7fc4c --- /dev/null +++ b/_sources/examples/index.rst.txt @@ -0,0 +1,69 @@ +########## +Examples +########## + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + +Chapman +======= + +Top Level Config +---------------- + +.. raw:: html + +
+ + +.. tab-set:: + + .. tab-item:: YAML + + .. literalinclude:: ../_static/examples/yaml/chapman/config.yaml + :language: yaml + + .. tab-item:: JSON + + .. literalinclude:: ../_static/examples/json/chapman/config.json + :language: json + + +Reactions +--------- + +.. tab-set:: + + .. tab-item:: YAML + + .. literalinclude:: ../_static/examples/yaml/chapman/reactions.yaml + :language: yaml + + .. tab-item:: JSON + + .. literalinclude:: ../_static/examples/json/chapman/reactions.json + :language: json + +Species +--------- + +.. tab-set:: + + .. tab-item:: YAML + + .. literalinclude:: ../_static/examples/yaml/chapman/species.yaml + :language: yaml + + .. tab-item:: JSON + + .. literalinclude:: ../_static/examples/json/chapman/species.json + :language: json \ No newline at end of file diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt new file mode 100644 index 0000000..fdf902a --- /dev/null +++ b/_sources/index.rst.txt @@ -0,0 +1,39 @@ +.. OpenAtmos Mechanism Configuration documentation master file, created by + sphinx-quickstart on Fri Jul 21 21:05:33 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. open atmos mechanism configuration documentation HTML titles +.. +.. # (over and under) for module headings +.. = for sections +.. - for subsections +.. ^ for subsubsections +.. ~ for subsubsubsections +.. " for paragraphs + +.. |project_version| replace:: 1.0.0 + +############################################################### +Welcome to the OpenAtmos Mechanism Configuration documentation! +############################################################### + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview + chemical_species/index + mechanisms/index + reactions/index + examples/index + bibliography + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/_sources/mechanisms/index.rst.txt b/_sources/mechanisms/index.rst.txt new file mode 100644 index 0000000..3c2ba03 --- /dev/null +++ b/_sources/mechanisms/index.rst.txt @@ -0,0 +1,50 @@ +.. _mechanisms: + +########## +Mechanisms +########## + +Mechanisms are collections of reactions and have the following format: + +.. tab-set:: + + .. tab-item:: YAML + + .. code-block:: yaml + :force: + + camp-data: + - name: my mechanism + type: MECHANISM + reactions: + - type: RXN_ARRHENIUS + ... + - type: RXN_TROE + ... + + .. tab-item:: JSON + + .. code-block:: json + :force: + + { + "camp-data": [ + "name": "my mechanism", + "type": "MECHANISM", + "reactions": [ + { + "type": "RXN_ARRHENIUS", + ... + }, + { + "type": "RXN_TROE", + ... + } + ] + ] + + +The ``name`` is required and must be unique. +Mechanisms with the same name will be merged into a single mechanism. +The ``type`` is also required and must be ``MECHANISM``. +The ``reactions`` should be an array of :ref:`reactions`. diff --git a/_sources/overview.rst.txt b/_sources/overview.rst.txt new file mode 100644 index 0000000..4acb078 --- /dev/null +++ b/_sources/overview.rst.txt @@ -0,0 +1,95 @@ +######## +Overview +######## + +Chemical mechnanisms can be organized across a number of files in +whatever way makes sense for the specific user and application. +Every configuration should include one top-level file that +lists the relative or absolute path to every configuration +file that includes mechanism configuration data. + +Individual mechanism configuration files are combined to +collectively describe the chemical system and processes. +The order of files in the list is arbitrary. + +The file list configuration has the following format: + +.. tab-set:: + + .. tab-item:: YAML + + .. code-block:: yaml + + camp-files: + - path/to/foo.yml + - path/to/bar.yml + + .. tab-item:: JSON + + .. code-block:: json + + { + "camp-files": [ + "path/to/foo.json", + "path/to/bar.json" + ] + } + + +Individual configuration files have the following format: + +.. tab-set:: + + .. tab-item:: YAML + + .. code-block:: yaml + :force: + + camp-data: + - type: OBJECT_TYPE + ... + - type: OBJECT_TYPE + ... + + .. tab-item:: JSON + + .. code-block:: json + :force: + + { + "camp-data": [ + { + "type": "OBJECT_TYPE", + ... + }, + { + "type": "OBJECT_TYPE", + ... + } + ] + } + + +Each input file should contain exactly one object with a single key-value +pair ``camp-data`` whose value is an array of objects. +Additional top-level key-value pairs will be ignored. +Each of the objects in the ``camp-data`` array must contain a key-value pair ``type`` +whose value is a string referencing a valid configuration class. + +The valid top-level configuration objects that can appear in the ``camp-data`` +array are described here: + +:ref:`chemical-species` + +:ref:`mechanisms` + +The arrangement of objects within the ``camp-data`` array and between input files is arbitrary. +Additionally, some objects, such as chemical species and mechanisms may be split into +multiple objects within the ``camp-data`` array and/or between files, +and will be combined based on their unique name. +This flexibility is provided so that the chemical mechanism data can be organized +in a way that makes sense to the designer of the mechanism. +For example, files could be split based on species source (biogenic, fossil fuel, etc.) +or based on properties (molecular weight, density, etc.) or any combination of criteria. +However, if a single property of an object (e.g., the molecular weight of a chemical species) +is set in more than one location, this should cause an error. \ No newline at end of file diff --git a/_sources/reactions/aqueous_equilibrium.rst.txt b/_sources/reactions/aqueous_equilibrium.rst.txt new file mode 100644 index 0000000..bd9e56e --- /dev/null +++ b/_sources/reactions/aqueous_equilibrium.rst.txt @@ -0,0 +1,76 @@ +Aqueous-Phase Equilibrium +========================= + +Aqueous equilibrium reactions are calculated as forward and reverse reactions. +The reverse rate constant must be provided as part of the input data, and the forward rate constant is calculated using the provided +reverse rate constant and an equilibrium constant of the following format: + +.. math:: + + A e^{C \left(\frac{1}{T} - \frac{1}{298}\right)} + +where: + +- :math:`A` is the pre-exponential factor (:math:`\mathrm{s}^{-1}`), +- :math:`C` is a constant, +- :math:`T` is the temperature :math:`(\mathrm{K})`. + +Input data for aqueous equilibrium equations should take the form: + +.. tabs:: + + .. tab:: YAML + + .. code-block:: yaml + + type: AQUEOUS_EQUILIBRIUM + A: 123.45 + C: 123.45 + k_reverse: 123.45 + phase: "my aqueous phase" + time unit: MIN + aqueous-phase water: "H2O_aq" + ion pair: "spec3-spec4" + reactants: + spec1: {} + spec2: + qty: 2 + # ... (other reactants) + products: + spec3: {} + spec4: + qty: 0.65 + # ... (other products) + + .. tab:: JSON + + .. code-block:: json + + { + "type" : "AQUEOUS_EQUILIBRIUM", + "A" : 123.45, + "C" : 123.45, + "k_reverse" : 123.45, + "phase" : "my aqueous phase", + "time unit" : "MIN", + "aqueous-phase water" : "H2O_aq", + "ion pair" : "spec3-spec4", + "reactants" : { + "spec1" : {}, + "spec2" : { "qty" : 2 }, + }, + "products" : { + "spec3" : {}, + "spec4" : { "qty" : 0.65 }, + } + } + +The key-value pairs ``reactants`` and ``products`` are required. Reactants and products without a ``qty`` value are assumed to appear once +in the reaction equation. Reactant and product species must be present in the specified phase and include a ``molecular weight [kg mol-1]`` +parameter in :math:`\mathrm{kg}\ \mathrm{mole}^{-1}`. The parameter ``aqueous-phase water`` is required and must be the name of the aerosol-phase species that is used for water. +The parameter ``ion pair`` is optional. When it is included, its value must be the name of an ion pair that is present in the specified aerosol phase. +Its mean binary activity coefficient will be applied to the reverse reaction. + +When ``A`` is not included, it is assumed to be 1.0; when ``C`` is not included, it is assumed to be 0.0. The reverse reaction rate constant ``k_reverse`` is required. + +The unit for time is assumed to be s, but inclusion of the optional key-value pair ``time unit = MIN`` can be used to indicate a rate with minutes as the time unit. diff --git a/_sources/reactions/arrhenius.rst.txt b/_sources/reactions/arrhenius.rst.txt new file mode 100644 index 0000000..19fa921 --- /dev/null +++ b/_sources/reactions/arrhenius.rst.txt @@ -0,0 +1,86 @@ +Arrhenius Reaction Rates +======================== + +Arrhenius-like reaction rate constant equations are calculated as follows: + +.. math:: + + A e^{-\frac{E_a}{k_bT}} \left(\frac{T}{D}\right)^B (1.0 + E \cdot P) + +where: + +- :math:`A` is the pre-exponential factor (:math:`(\mbox{molecule}\,\mathrm{cm}^{-3})^{-(n-1)}\,\mathrm{s}^{-1}`), +- :math:`n` is the number of reactants, +- :math:`E_a` is the activation energy :math:`(\mathrm{J})`, +- :math:`k_b` is the Boltzmann constant :math:`(\mathrm{J}/\mathrm{K})`, +- :math:`D` :math:`(\mathrm{K})`, :math:`B` (unitless), and :math:`E` (:math:`\mathrm{Pa}^{-1}`) are reaction parameters, +- :math:`T` is the temperature :math:`(\mathrm{K})`, and :math:`P` is the pressure :math:`(\mathrm{Pa})`. + +The first two terms are described in Finlayson-Pitts and Pitts (2000) :cite:`Finlayson-Pitts2000`. +The final term is included to accommodate CMAQ EBI solver type 7 rate constants. + +Input data for Arrhenius equations has the following format: + +.. tab-set:: + + .. tab-item:: YAML + + .. code-block:: yaml + :force: + + type: ARRHENIUS + A: 123.45 + Ea: 123.45 + B: 1.3 + D: 300.0 + E: 6.0e-06 + time unit: MIN + reactants: + spec1: + spec2: + qty: 2 + ... + products: + spec3: + spec4: + yield: 0.65 + ... + + + + .. tab-item:: JSON + + .. code-block:: json + :force: + + { + "type" : "ARRHENIUS", + "A" : 123.45, + "Ea" : 123.45, + "B" : 1.3, + "D" : 300.0, + "E" : 0.6E-5, + "time unit" : "MIN", + "reactants" : { + "spec1" : {}, + "spec2" : { "qty" : 2 }, + ... + }, + "products" : { + "spec3" : {}, + "spec4" : { "yield" : 0.65 }, + ... + } + } + +The key-value pairs ``reactants`` and ``products`` are required. Reactants without a ``qty`` value +are assumed to appear once in the reaction equation. Products without a specified ``yield`` are +assumed to have a yield of 1.0. + +Optionally, a parameter ``C`` may be included, and is taken to equal :math:`\frac{-E_a}{k_b}`. +Note that either ``Ea`` or ``C`` may be included, but not both. When neither ``Ea`` nor ``C`` are +included, they are assumed to be 0.0. When ``A`` is not included, it is assumed to be 1.0. When +``D`` is not included, it is assumed to be 300.0 K. When ``B`` is not included, it is assumed to be +0.0. When ``E`` is not included, it is assumed to be 0.0. The unit for time is assumed to be s, but +inclusion of the optional key-value pair ``time unit = MIN`` can be used to indicate a rate with +minutes as the time unit. diff --git a/_sources/reactions/branched.rst.txt b/_sources/reactions/branched.rst.txt new file mode 100644 index 0000000..3c5c70e --- /dev/null +++ b/_sources/reactions/branched.rst.txt @@ -0,0 +1,95 @@ +Branched(Wennberg NO + RO2 Reaction) +==================================== + +Wennberg NO + RO2 reactions are branched reactions with one branch forming +alkoxy radicals plus NO2 and the other forming organic nitrates :cite:`Wennberg2018`. +The rate constants for each branch are based on an Arrhenius rate constant and +a temperature- and structure-dependent branching ratio calculated as: + +.. math:: + + k_{\text{nitrate}} = (X e^{-Y/T}) \left(\frac{A(T, [\text{M}], n)}{A(T, [\text{M}], n) + Z}\right) + +.. math:: + + k_{\text{alkoxy}} = (X e^{-Y/T})\left(\frac{Z}{Z + A(T, [\text{M}], n)}\right) + +.. math:: + + A(T, [\text{M}], n) = \frac{2 \times 10^{-22} e^n [\text{M}]}{1 + \frac{2 \times 10^{-22} e^n [\text{M}]}{0.43(T/298)^{-8}}} 0.41^{(1+[\log( \frac{2 \times 10^{-22} e^n [\text{M}]}{0.43(T/298)^{-8}})]^2)^{-1}} + +where :math:`T` is temperature :math:`(\mathrm{K})`, :math:`[\mathrm{M}]` is the number density of air :math:`(\mathrm{molecules}\ \mathrm{cm}^{-3})`, +:math:`X` and :math:`Y` are Arrhenius parameters for the overall reaction, :math:`n` is the number of +heavy atoms in the RO2 reacting species (excluding the peroxy moiety), and :math:`Z` +is defined as a function of two parameters :math:`(\alpha_0, n)`: + +.. math:: + + Z(\alpha_0, n) = A(T = 293 K, [M] = 2.45 \times 10^{19} \frac{\text{molec}}{\text{cm}^3}, n) \frac{(1-α_0)}{α_0} + +More details can be found in Wennberg et al. (2018) :cite:`Wennberg2018`. + +Input data for Wennberg NO + RO2 equations has the following format: + +.. tab-set:: + + .. tab-item:: YAML + + .. code-block:: yaml + + type: WENNBERG_NO_RO2 + X: 123.45 + Y: 1200.0 + a0: 1.0e8 + n: 6 + time unit: MIN + reactants: + spec1: + spec2: + qty: 2 + alkoxy products: + spec3: + spec4: + yield: 0.65 + nitrate products: + spec5: + spec6: + yield: 0.32 + + + .. tab-item:: JSON + + .. code-block:: json + + { + "type" : "WENNBERG_NO_RO2", + "X" : 123.45, + "Y" : 1200.0, + "a0" : 1.0e8, + "n" : 6, + "time unit" : "MIN", + "reactants" : { + "spec1" : {}, + "spec2" : { "qty" : 2 }, + }, + "alkoxy products" : { + "spec3" : {}, + "spec4" : { "yield" : 0.65 }, + }, + "nitrate products" : { + "spec5" : {}, + "spec6" : { "yield" : 0.32 }, + } + } + + +The key-value pairs ``reactants``, ``alkoxy products``, and ``nitrate products`` are required. +Reactants without a ``qty`` value are assumed to appear once in the reaction equation. +Products without a specified ``yield`` are assumed to have a yield of 1.0. + +When ``X`` is not included, it is assumed to be 1.0, when ``Y`` is not +included, it is assumed to be 0.0 K, when ``a0`` is not included, it is +assumed to be 1.0, and when ``n`` is not included, it is assumed to be 0. +The unit for time is assumed to be s, but inclusion of the optional +key-value pair ``time unit`` = ``MIN`` can be used to indicate a rate +with min as the time unit. diff --git a/_sources/reactions/cmaq_H2O2.rst.txt b/_sources/reactions/cmaq_H2O2.rst.txt new file mode 100644 index 0000000..0ab7e99 --- /dev/null +++ b/_sources/reactions/cmaq_H2O2.rst.txt @@ -0,0 +1,80 @@ +Special CMAQ Reaction for H2O2 +============================== + +For the reactions: + +.. math:: + + \ce{ + HO2 + HO2 ->[k] H2O2 + } + +.. math:: + + \ce{ + HO2 + HO2 + H2O ->[k] H2O2 + } + +CMAQ rate constants are calculated as: + +.. math:: + + k = k_1 + k_2 [\mathrm{M}] + +where :math:`k_1` and :math:`k_2` are `Arrhenius` rate constants with :math:`D = 300` and :math:`E = 0`, and :math:`[\mathrm{M}]` is the concentration of air :cite:`Gipson`. + +Input data for CMAQ :math:`\ce{H2O2}` reactions have the following format: + +.. tabs:: + + .. tab:: YAML + + .. code-block:: yaml + + type: CMAQ_H2O2 + k1_A: 5.6E-12 + k1_B: -1.8 + k1_C: 180.0 + k2_A: 3.4E-12 + k2_B: -1.6 + k2_C: 104.1 + time unit: MIN + reactants: + spec1: {} + spec2: + qty: 2 + # ... (other reactants) + products: + spec3: {} + spec4: + yield: 0.65 + # ... (other products) + + .. tab:: JSON + + .. code-block:: json + + { + "type": "CMAQ_H2O2", + "k1_A": 5.6E-12, + "k1_B": -1.8, + "k1_C": 180.0, + "k2_A": 3.4E-12, + "k2_B": -1.6, + "k2_C": 104.1, + "time unit": "MIN", + "reactants": { + "spec1": {}, + "spec2": { "qty": 2 }, + }, + "products": { + "spec3": {}, + "spec4": { "yield": 0.65 }, + } + } + +The key-value pairs ``reactants`` and ``products`` are required. Reactants without a ``qty`` value are assumed to appear once in the reaction equation. Products without a specified ``yield`` are assumed to have a yield of 1.0. + +The two sets of parameters beginning with ``k1_`` and ``k2_`` are the `Arrhenius` parameters for the :math:`k_1` and :math:`k_2` rate constants, respectively. When not present, ``_A`` parameters are assumed to be 1.0, ``_B`` to be 0.0, and ``_C`` to be 0.0. + +The unit for time is assumed to be s, but inclusion of the optional key-value pair ``time unit = MIN`` can be used to indicate a rate with minutes as the time unit. diff --git a/_sources/reactions/cmaq_OH_HNO3.rst.txt b/_sources/reactions/cmaq_OH_HNO3.rst.txt new file mode 100644 index 0000000..858e9e9 --- /dev/null +++ b/_sources/reactions/cmaq_OH_HNO3.rst.txt @@ -0,0 +1,80 @@ +Special CMAQ Reaction for OH+HNO3 +================================= + +For the reaction: + +.. math:: + + \ce{ + OH + HNO3 ->[k] NO3 + H2O + } + +CMAQ rate constants are calculated as: + +.. math:: + + k = k_0 + \left( \frac{k_3 [\mathrm{M}]}{1 + \frac{k_3 [\mathrm{M}]}{k_2}} \right) + +where :math:`k_0`, :math:`k_2`, and :math:`k_3` are `Arrhenius` rate constants with :math:`D = 300` and :math:`E = 0`, and :math:`[\mathrm{M}]` is the concentration of air :cite:`Gipson`. + +Input data for CMAQ :math:`\ce{OH + HNO3}` reactions have the following format: + +.. tabs:: + + .. tab:: YAML + + .. code-block:: yaml + + type: CMAQ_OH_HNO3 + k0_A: 5.6E-12 + k0_B: -1.8 + k0_C: 180.0 + k2_A: 3.4E-12 + k2_B: -1.6 + k2_C: 104.1 + k3_A: 3.2E-11 + k3_B: -1.5 + k3_C: 92.0 + time unit: MIN + reactants: + spec1: {} + spec2: + qty: 2 + # ... (other reactants) + products: + spec3: {} + spec4: + yield: 0.65 + # ... (other products) + + .. tab:: JSON + + .. code-block:: json + + { + "type": "CMAQ_OH_HNO3", + "k0_A": 5.6E-12, + "k0_B": -1.8, + "k0_C": 180.0, + "k2_A": 3.4E-12, + "k2_B": -1.6, + "k2_C": 104.1, + "k3_A": 3.2E-11, + "k3_B": -1.5, + "k3_C": 92.0, + "time unit": "MIN", + "reactants": { + "spec1": {}, + "spec2": { "qty": 2 }, + }, + "products": { + "spec3": {}, + "spec4": { "yield": 0.65 }, + } + } + +The key-value pairs ``reactants`` and ``products`` are required. Reactants without a ``qty`` value are assumed to appear once in the reaction equation. Products without a specified ``yield`` are assumed to have a yield of 1.0. + +The three sets of parameters beginning with ``k0_``, ``k2_``, and ``k3_`` are the `Arrhenius` parameters for the :math:`k_0`, :math:`k_2`, and :math:`k_3` rate constants, respectively. When not present, ``_A`` parameters are assumed to be 1.0, ``_B`` to be 0.0, and ``_C`` to be 0.0. + +The unit for time is assumed to be s, but inclusion of the optional key-value pair ``time unit = MIN`` can be used to indicate a rate with minutes as the time unit. diff --git a/_sources/reactions/condensed_phase_arrhenius.rst.txt b/_sources/reactions/condensed_phase_arrhenius.rst.txt new file mode 100644 index 0000000..c6842f9 --- /dev/null +++ b/_sources/reactions/condensed_phase_arrhenius.rst.txt @@ -0,0 +1,84 @@ +Condensed-Phase Arrhenius Reaction +================================== + +Condensed-phase Arrhenius reactions are calculated using an Arrhenius-like rate constant that takes the form: + +.. math:: + + A e^{-\frac{E_a}{k_bT}} \left(\frac{T}{D}\right)^B (1.0 + E \cdot P) + +where: + +- :math:`A` is the pre-exponential factor (:math:`[U]^{-(n-1)}\,\mathrm{s}^{-1}`), +- :math:`U` is the unit of the reactants and products, which can be :math:`M` for aqueous-phase reactions or :math:`\mathrm{mol\,m}^{-3}` for all other condensed-phase reactions, +- :math:`n` is the number of reactants, +- :math:`E_a` is the activation energy :math:`(\mathrm{J})`, +- :math:`k_b` is the Boltzmann constant :math:`(\mathrm{J}/\mathrm{K})`, +- :math:`D` :math:`(\mathrm{K})`, :math:`B` (unitless), and :math:`E` (:math:`\mathrm{Pa}^{-1}`) are reaction parameters, +- :math:`T` is the temperature :math:`(\mathrm{K})`, and :math:`P` is the pressure :math:`(\mathrm{Pa})`. + +The first two terms are described in Finlayson-Pitts and Pitts (2000) :cite:`Finlayson-Pitts2000`. The final term is included to accommodate CMAQ EBI solver type 7 rate constants :cite:`Gipson`. + +Input data for condensed-phase Arrhenius reactions have the following format: + +.. tabs:: + + .. tab:: YAML + + .. code-block:: yaml + + type: CONDENSED_PHASE_ARRHENIUS + A: 123.45 + Ea: 123.45 + B: 1.3 + D: 300.0 + E: 0.6E-5 + units: M + time unit: MIN + aerosol phase: my aqueous phase + aerosol-phase water: H2O_aq + reactants: + spec1: {} + spec2: + qty: 2 + # ... (other reactants) + products: + spec3: {} + spec4: + yield: 0.65 + # ... (other products) + + .. tab:: JSON + + .. code-block:: json + + { + "type": "CONDENSED_PHASE_ARRHENIUS", + "A": 123.45, + "Ea": 123.45, + "B": 1.3, + "D": 300.0, + "E": 0.6E-5, + "units": "M", + "time unit": "MIN", + "aerosol phase": "my aqueous phase", + "aerosol-phase water": "H2O_aq", + "reactants": { + "spec1": {}, + "spec2": { "qty": 2 }, + }, + "products": { + "spec3": {}, + "spec4": { "yield": 0.65 }, + } + } + +The key-value pairs ``reactants`` and ``products`` are required. Reactants without a ``qty`` value are assumed to appear once in the reaction equation. Products without a specified ``yield`` are assumed to have a yield of 1.0. + +Units for the reactants and products must be specified using the key ``units`` and can be either ``M`` or ``mol m-3``. If units of ``M`` are specified, a key-value pair ``aerosol-phase water`` must also be included, whose value is a string specifying the name for water in the aerosol phase. + +The unit for time is assumed to be s, but inclusion of the optional key-value pair ``time unit = MIN`` can be used to indicate a rate with minutes as the time unit. + +The key-value pair ``aerosol phase`` is required and must specify the name of the aerosol phase in which the reaction occurs. + +Optionally, a parameter ``C`` may be included, and is taken to equal :math:`\frac{-E_a}{k_b}`. Note that either ``Ea`` or ``C`` may be included, but not both. When neither ``Ea`` nor ``C`` are included, they are assumed to be 0.0. When ``A`` is not included, it is assumed to be 1.0. When ``D`` is not included, it is assumed to be 300.0 K. When ``B`` is not included, it is assumed to be 0.0. When ``E`` is not included, it is assumed to be 0.0. diff --git a/_sources/reactions/condensed_phase_photolysis.rst.txt b/_sources/reactions/condensed_phase_photolysis.rst.txt new file mode 100644 index 0000000..47422c3 --- /dev/null +++ b/_sources/reactions/condensed_phase_photolysis.rst.txt @@ -0,0 +1,63 @@ +Condensed-Phase Photolysis Reaction +=================================== + +Condensed-Phase Photolysis reactions take the form: + +.. math:: + + \ce{X + h \nu -> Y_1 (+ Y_2 \dots)} + +where :math:`\ce{X}` is the species being photolyzed, and :math:`\ce{Y_n}` are the photolysis products. + +The reaction rate can be scaled by providing the "scaling factor" keyword in the JSON configuration. + +Input data for condensed-phase Photolysis reactions have the following format: + +.. tabs:: + + .. tab:: YAML + + .. code-block:: yaml + + type: CONDENSED_PHASE_PHOTOLYSIS + rate: 123.45 + units: M + aerosol phase: my aqueous phase + aerosol-phase water: H2O_aq + reactants: + spec1: {} + ... + products: + spec3: {} + spec4: + yield: 0.65 + ... + scaling factor: 11.20 + + .. tab:: JSON + + .. code-block:: json + + { + "type": "CONDENSED_PHASE_PHOTOLYSIS", + "rate": 123.45, + "units": "M", + "aerosol phase": "my aqueous phase", + "aerosol-phase water": "H2O_aq", + "reactants": { + "spec1": {}, + }, + "products": { + "spec3": {}, + "spec4": { "yield": 0.65 }, + }, + "scaling factor": 11.20 + } + +The key-value pairs ``reactants`` and ``products`` are required. Reactants without a ``qty`` value are assumed to appear once in the reaction equation. Products without a specified ``yield`` are assumed to have a yield of 1.0. + +Units for the reactants and products must be specified using the key ``units`` and can be either ``M`` or ``mol m-3``. If units of ``M`` are specified, a key-value pair ``aerosol-phase water`` must also be included, whose value is a string specifying the name for water in the aerosol phase. + +The unit for time is assumed to be s, but inclusion of the optional key-value pair ``time unit = MIN`` can be used to indicate a rate with minutes as the time unit. + +The key-value pair ``aerosol phase`` is required and must specify the name of the aerosol phase in which the reaction occurs. diff --git a/_sources/reactions/emission.rst.txt b/_sources/reactions/emission.rst.txt new file mode 100644 index 0000000..3395a70 --- /dev/null +++ b/_sources/reactions/emission.rst.txt @@ -0,0 +1,41 @@ +Emission +======== + +Emission reactions take the form: + +.. math:: + + \rightarrow \ce{X} + +where :math:`\ce{X}` is the species being emitted. + +Emission rates are constant. +A conforming implementation of version |version| of the configuration will provide ways to dynamically update wet deposition rates if nonconstant rates are needed. + +Input data for emission reactions have the following format: + +.. tab-set:: + + .. tab-item:: YAML + + .. code-block:: yaml + + type: EMISSION + species: species name + scaling factor: 1.2 + + + .. tab-item:: JSON + + .. code-block:: json + + { + "type": "EMISSION", + "species": "species name", + "scaling factor": 1.2, + } + +The key-value pair ``species`` is required, and its value must be the name of the species being emitted. +The ``scaling factor`` is optional and can be used to set a constant scaling factor for the rate. +When a ``scaling factor`` is not provided, it is assumed to be 1.0. +Rates are in :math:`\mbox{molecule}\,\mathrm{cm}^{-3}\,\mathrm{s^{-1}}`. diff --git a/_sources/reactions/first_order_loss.rst.txt b/_sources/reactions/first_order_loss.rst.txt new file mode 100644 index 0000000..600ef5f --- /dev/null +++ b/_sources/reactions/first_order_loss.rst.txt @@ -0,0 +1,42 @@ +First-Order Loss +================ + +First-Order Loss reactions take the form: + +.. math:: + + \ce{X} \rightarrow + +where :math:`\ce{X}` is the species being lost. + +First-Order loss rate constants are constant. +A conforming implementation of version |version| of the configuration will provide ways to dynamically update wet deposition rates if nonconstant rates are needed. + +Input data for first-order loss reactions have the following format: + +.. tab-set:: + + .. tab-item:: YAML + + .. code-block:: yaml + + type: FIRST_ORDER_LOSS + species: species name + scaling factor: 1.2 + + + .. tab-item:: JSON + + .. code-block:: json + + { + "type": "FIRST_ORDER_LOSS", + "species": "species name", + "scaling factor": 1.2 + } + +The key-value pair ``species`` is required, and its value must be the name of the species being removed by the reaction. +The ``scaling factor`` is optional and can be used to set a constant scaling factor for the rate constant. +When a ``scaling factor`` is not provided, it is assumed to be 1.0. +All other data is optional and will be available to external modules during initialization. +Rate constants are in units of :math:`(\mathrm{s}^{-1})`. diff --git a/_sources/reactions/hl_phase_transfer.rst.txt b/_sources/reactions/hl_phase_transfer.rst.txt new file mode 100644 index 0000000..6bc673b --- /dev/null +++ b/_sources/reactions/hl_phase_transfer.rst.txt @@ -0,0 +1,79 @@ +Henry's Law Phase-Transfer Reaction +=================================== + +Henry's Law phase-transfer reactions use equilibrium rate constants that are calculated as: + +.. math:: + + HLC(298K) \cdot e^{C({1/T-1/298})} + +where :math:`HLC(298K)` is the Henry's Law constant at 298 K [M\,Pa^{-1}], :math:`C` is a constant [K], and :math:`T` is the temperature [K]. Uptake kinetics are based on the particle effective radius, :math:`r_{eff}` [m], the condensing species gas-phase diffusion coefficient, :math:`D_g` [m^2\,s^{-1}], its molecular weight :math:`MW` [kg\,mol^{-3}], and :math:`N^{*}`, which is used to calculate the mass accommodation coefficient. + +Mass accommodation coefficients and condensation rate constants are calculated using the method of Ervans et al. (2003) [Ervens2003] and references therein. Mass accommodation coefficients (:math:`\alpha`) are calculated as: + +.. math:: + + \Delta H_{obs} = -10 \times (N^*-1) + 7.53 \times (N^{*2/3}-1) - 0.1 \times 10 \quad (\text{kcal}\,\text{M}^{-1}) + + +.. math:: + + \Delta S_{obs} = -13 \times (N^*-1) - 19 \times (N^*-1) + 9.21 \times (N^{*2/3}-1) - 0.1 \times 13 \quad (\text{cal}\,\text{M}^{-1}\,\text{K}^{-1}) + +.. math:: + + \frac{\alpha}{1-\alpha} = e^{\frac{-\Delta G^{*}}{RT}} + +If :math:`\Delta H` and :math:`\Delta S` are not provided, :math:`\alpha` is set to 0.1 [Zaveri2008]. + +Condensation rate constants are calculated following [Zaveri2008] as: + +.. math:: + + k_c = 4 \pi r D_g f_{fs}( K_n, \alpha ) + +where :math:`r` is the radius of the particle(s) [m], :math:`D_g` is the diffusion coefficient of the gas-phase species [m^2\,s^{-1}], :math:`f_{fs}( K_n, \alpha )` is the Fuchs Sutugin transition regime correction factor [unitless], :math:`K_n` is the Knudsen Number [unitless], and :math:`\alpha` is the mass accommodation coefficient. + +Rates can be calculated as: + +.. math:: + + r_c = [G] N_a k_c + +where :math:`[G]` is the gas-phase species concentration [ppm], :math:`N_a` is the number concentration of particles [particle\,m^{-3}], and the rate :math:`r_c` is in [ppm\,s^{-1}]. The particle radius used to calculate :math:`k_f` is the effective radius [:math:`r_{eff}`], which is taken as the "least-wrong" choice for condensation rates, as it is weighted to surface area [Zender2002]. + +Input data for Phase transfer equations have the following format: + +.. tabs:: + + .. tab:: YAML + + .. code-block:: yaml + + type: HL_PHASE_TRANSFER + gas-phase species: my gas spec + aerosol-phase species: my aero spec + aerosol phase: my aqueous phase + aerosol-phase water: H2O_aq + ... + + .. tab:: JSON + + .. code-block:: json + + { + "type": "HL_PHASE_TRANSFER", + "gas-phase species": "my gas spec", + "aerosol-phase species": "my aero spec", + "aerosol phase": "my aqueous phase", + "aerosol-phase water": "H2O_aq", + } + +The key-value pairs ``gas-phase species`` and ``aerosol-phase species`` are required. +Only one gas-phase and one aerosol-phase species are allowed per phase-transfer reaction. +Additionally, gas-phase species must include parameters named ``HLC(298K)`` :math:`[\mathrm{M}\ \mathrm{Pa}^{-1}]`, +which is the Henry's Law constant at 298 K, ``HLC exp factor`` :math:`[\mathrm{K}]`, which is the Henry's Law constant exponential factor ``C``, +``diffusion coeff [m2 s-1]`` which specifies the diffusion coefficient in +:math:`\mathrm{m}^2\,\mathrm{s}^{-1}`, and ``molecular weight``, which specifies the molecular weight of the species in :math:`\mathrm{kg}\,\mathrm{mol}^{−1}`. +They may optionally include the parameter ``N star``, which will be used to calculate the mass accomodation coefficient. +When this parameter is not included, the mass accomodation coefficient is assumed to be 1.0. diff --git a/_sources/reactions/index.rst.txt b/_sources/reactions/index.rst.txt new file mode 100644 index 0000000..d6a447d --- /dev/null +++ b/_sources/reactions/index.rst.txt @@ -0,0 +1,37 @@ +.. _reactions: + +######### +Reactions +######### + +These reactions are implemented in a few chemical solvers that read version |version| of the mechanism configuraiton. + +====================================== ============================================= ======================================= =============================================== +Reaction Type `CAMP