Cross sections format modification and EEDF solver correction

doc/doxygen/cantera.bib

@@ -381,6 +381,18 @@ @article{nishioka1996
     url = {https://doi.org/10.1016/0010-2180(95)00132-8},
     doi = {10.1016/0010-2180(95)00132-8},
     year = {1996}}
+@article{pancheshnyi2012,
+    author = {S.~Pancheshnyi and S.~Biagi and M.~C.~Bordage and
+        G.~J.~M.~Hagelaar and W.~L.~Morgan and A.~V.~Phelps and
+        L.~C.~Pitchford},
+    journal = {Chemical Physics},
+    pages = {148--153},
+    title = {The {LXCat} project: Electron scattering cross sections and swarm
+        parameters for low temperature plasma modeling},
+    doi = {10.1016/j.chemphys.2011.04.020},
+    url = {https://doi.org/10.1016/j.chemphys.2011.04.020},
+    volume = {398},
+    year = {2012}}
 @article{pedersen1993,
     author = {T.~Pedersen and R.~.C.~Brown},
     title = {Simulation of electric field effects in premixed methane flames},

doc/sphinx/reference/kinetics/rate-constants.md

@@ -687,12 +687,12 @@ different representations are the responsibility of the mechanism author.
 ## Electron Collision Plasma Reactions
 
 The electron collision plasma reaction rate uses the electron collision data and the
-electron energy distribution to calculate the reaction rate. Hagelaar and Pitchford
+electron energy distribution to calculate the reaction rate.
 {cite:t}`hagelaar2005` define the reaction rate coefficient (Eqn. 63) as,
 
 $$  k =  \gamma \int_0^{\infty} \epsilon \sigma F_0 d\epsilon  $$
 
-where $\gamma = \sqrt{2/m_e}$ (Eqn.4 in Hagelaar {cite:t}`hagelaar2015`), $m_e$ [kg] is
+where $\gamma = \sqrt{2/m_e}$ (Eqn.4 in {cite:t}`hagelaar2015`), $m_e$ [kg] is
 the electron mass, $\epsilon$ [J] is the electron energy, $\sigma(\epsilon)$ [m²] is the
 reaction collision cross section, $F_0(\epsilon)$ [$\t{J^{-3/2}}$] is the normalized
 electron energy distribution function, and $k$ has units of [m³/s].
@@ -707,13 +707,59 @@ $$
 where $e$ is the elementary charge [C] and $N_A$ is the Avogadro constant
 [$\t{kmol^{-1}}$].
 
+### Effective and elastic cross sections
+
+For a given target species, the momentum-transfer cross section may be provided
+either as an `elastic` cross section or as an `effective` cross section. As detailed in
+{cite:t}`pancheshnyi2012`, an effective cross section already
+includes the contribution of the inelastic collision processes for the same target:
+
+$$
+\sigma_\mathrm{eff}(\epsilon)
+=
+\sigma_\mathrm{el}(\epsilon)
++
+\sum_j \sigma_{\mathrm{inel},j}(\epsilon).
+$$
+
+When an effective cross section is provided, Cantera uses it directly in the total
+momentum-transfer cross section and reconstructs the elastic contribution as
+
+$$
+\sigma_\mathrm{el}(\epsilon)
+=
+\sigma_\mathrm{eff}(\epsilon)
+-
+\sum_j \sigma_{\mathrm{inel},j}(\epsilon).
+$$
+
+When an effective cross section is available, the individual inelastic cross sections
+are therefore not added again to the total momentum-transfer cross section. This avoids
+counting their contribution twice in the electron energy distribution calculation.
+
+Cross sections are linearly interpolated over their tabulated energy range and are
+taken to be zero outside this range. If the reconstructed elastic cross section is
+negative, its value is retained and a warning identifies the affected target species
+and energy intervals during the first calculation of the electron energy distribution.
+Negative reconstructed values may indicate that the effective and inelastic
+cross-section data are not mutually consistent.
+
 ```{versionadded} 3.1
 ```
 
+:::{versionchanged} 4.0
+Cross-section data are now stored in the top-level `electron-collisions` section.
+An `electron-collision-plasma` reaction references one of these definitions using
+the `collision` field. Cross-section data can no longer be specified directly in
+the reaction entry.
+:::
+
 :::{admonition} YAML Usage
 :class: tip
 
-Electron collision reactions can be defined in the YAML format by specifying
-[`electron-collision-plasma`](sec-yaml-electron-collision-plasma) as the reaction `type`
-and providing lists with the `cross-sections` and corresponding `energy-levels`.
+Electron collision reactions are defined by specifying
+[`electron-collision-plasma`](sec-yaml-electron-collision-plasma) as the reaction
+`type`. The reaction references a named cross-section dataset from the top-level
+[`electron-collisions`](sec-yaml-electron-collisions) section using the `collision`
+field.
 :::

doc/sphinx/yaml/lxcat2yaml.md

@@ -1,9 +1,113 @@
 (sec-lxcat2yaml)=
+
 # LXCat to YAML conversion
 
+The `lxcat2yaml` utility converts electron-collision cross-section data
+from an LXCat XML file to Cantera's YAML format. Both the legacy LXCat XML
+format and LXCat XML version 1.1 are supported.
+
+The generated YAML separates collision data from chemical reactions:
+
+- Cross-section data and collision metadata are stored in the root-level
+  `electron-collisions` section.
+- Electron-collision reactions refer to these data using the `collision`
+  field.
+- Elastic and effective collisions are included in `electron-collisions`
+  for calculation of the electron energy distribution function (EEDF), but
+  do not generate chemical reactions.
+
+## Basic conversion
+
+To convert an LXCat XML file without inserting the results into an existing
+mechanism, run:
+
+```bash
+lxcat2yaml --input=my-cross-sections.xml --output=my-cross-sections.yaml
+```
+
+If the `lxcat2yaml` executable is not available on the system path, the
+converter can instead be invoked as a Python module:
+
+```bash
+python -m cantera.lxcat2yaml \
+    --input=my-cross-sections.xml \
+    --output=my-cross-sections.yaml
+```
+
+If `--output` is omitted, the output filename is generated by replacing the
+input filename extension with `.yaml`.
+
+The resulting file contains collision definitions and any associated
+chemical reactions. For example:
+
+```yaml
+electron-collisions:
+- name: Phelps-Ar-ionization-Ar-15-8-eV
+  target: Ar
+  product: Ar+
+  kind: ionization
+  threshold: 15.8
+  energy-levels: [15.8, 16.0, 17.0]
+  cross-sections: [0.0, 2.02e-22, 1.34e-21]
+
+reactions:
+- equation: Ar + e => e + e + Ar+
+  type: electron-collision-plasma
+  collision: Phelps-Ar-ionization-Ar-15-8-eV
+```
+
+Collision names are generated deterministically from the database identifier,
+target species, collision kind, product, and threshold. A numerical suffix is
+added when needed to keep names unique.
+
+## Inserting data into a mechanism
+
+The converted data can be inserted into an existing Cantera mechanism using
+the `--insert` option:
+
+```bash
+lxcat2yaml \
+    --input=my-cross-sections.xml \
+    --database=Phelps \
+    --mech=plasma-mechanism.yaml \
+    --phase=plasma \
+    --insert \
+    --output=plasma-mechanism-with-cross-sections.yaml
+```
+
+The `--mech` option is required when `--insert` is used. If the mechanism
+contains multiple phases, `--phase` selects the phase whose species are used
+when filtering the LXCat processes.
+
+The value supplied to `--database` is matched against the `id` attribute of
+the LXCat `Database` element. If this option is omitted, processes from all
+databases in the XML file are considered.
+
+When a mechanism is supplied:
+
+- Processes whose target species is absent from the selected phase are
+  omitted.
+- A collision definition is retained when its target exists but one or more
+  product species are unavailable.
+- A chemical reaction is generated only when all its product species exist
+  in the selected phase.
+- Reactions with identical equations are marked as duplicates.
+- The generated mechanism is loaded by Cantera after conversion to verify
+  that it is valid.
+
+:::{note}
+Electron energies and cross sections in the LXCat input are expected to be
+expressed in eV and m{sup}`2`, respectively. Species names in the LXCat file
+must correspond to species in the selected Cantera phase. Common electron
+names and LXCat charge notation, such as `e`, `Electron`, `Ar^+`, and `O^-`,
+are normalized automatically.
+:::
+
+## Command-line options
+
 ```{eval-rst}
 .. argparse::
    :module: cantera.lxcat2yaml
    :func: create_argparser
    :prog: lxcat2yaml
-```
+```

doc/sphinx/yaml/reactions.md

@@ -454,74 +454,135 @@ Example:
 ```
 
 (sec-yaml-electron-collision-plasma)=
+
 ### `electron-collision-plasma`
 
-Electron collision plasma reactions involve an electron as one of the reactants, and are
-parameterized by the collision cross section as a function of the electron energy. The
-rate calculation is [described here](sec-electron-collision-plasma-rate). The rate
-parameters are specified using the following additional fields in the reaction entry:
+Electron collision plasma reactions involve an electron and a target species as
+reactants. Their rate coefficient is calculated from the electron energy distribution
+and a named collision cross-section dataset, as
+[described here](sec-electron-collision-plasma-rate).
 
-`energy-levels`
-: A list of electron energy levels [eV]
+The reaction entry uses the following additional field:
 
-`cross-sections`
-: A list of collision cross sections [m²] for the reaction at the specified energy
-  levels.
+`collision`
+: The name of an entry in the top-level
+  [`electron-collisions`](sec-yaml-electron-collisions) section. The referenced entry
+  provides the collision kind, target species, energy levels, and cross sections.
+
+The target specified by the collision definition must match the non-electron reactant
+of the reaction. The collision `kind` must also be consistent with the reaction
+stoichiometry.
 
 Example:
 
 ```yaml
-- equation: O2 + e => e + e + O2+
+- equation: O2 + E => E + E + O2+
   type: electron-collision-plasma
-  energy-levels: [13.0, 15.5, 18, 23]
-  cross-sections: [1.17e-22, 7.3e-22, 1.64e-21, 3.66e-21]
+  collision: O2-ionization
 ```
 
 :::{versionadded} 3.1
 :::
 
+:::{versionchanged} 4.0
+Cross-section data can no longer be specified directly in an
+`electron-collision-plasma` reaction entry. The reaction must instead reference a
+named entry in the top-level `electron-collisions` section using the `collision`
+field.
+:::
+
 (sec-yaml-electron-collisions)=
+
 ### `electron-collisions`
 
-The `electron-collisions` field defines a list of cross-section datasets for
-electron-impact processes that are used in plasma-phase simulations. These entries
-are not formal reactions (they are not added to `Kinetics` objects), but serve
-as data inputs for computing the electron energy distribution function.
+The top-level `electron-collisions` section contains named electron collision
+cross-section datasets used by plasma phases. Every entry is included when calculating
+the electron energy distribution, whether or not it is referenced by a chemical
+reaction.
+
+Entries in this section are not added to the phase's `Kinetics` object. To make a
+collision process contribute to chemical source terms, define an
+[`electron-collision-plasma`](sec-yaml-electron-collision-plasma) reaction whose
+`collision` field references the corresponding dataset.
+
+Cross-section data in this format can be generated from XML files downloaded from the
+[LXCat website](https://nl.lxcat.net/home/news.php) using the
+[`lxcat2yaml`](sec-lxcat2yaml) conversion tool.
+
+Each entry uses the following fields:
 
-Each entry includes:
+`name`
+: A unique, non-empty name identifying the collision dataset.
 
 `target`
-: The name of the species that is the target of the collision
+: The name of the species targeted by the electron collision. The target species must
+  be present in the plasma phase.
+
+`kind`
+: The type of electron collision process. Supported values are:
+
+  - `effective`: An effective momentum-transfer cross section containing the elastic
+    and inelastic contributions for the target.
+  - `elastic`: An elastic momentum-transfer cross section.
+  - `excitation`: An electronic, vibrational, or rotational excitation cross section.
+  - `ionization`: An electron-impact ionization cross section.
+  - `attachment`: An electron attachment cross section.
+
+  At most one `effective` or `elastic` cross-section dataset may be defined for each
+  target species.
 
 `energy-levels`
-: A list of electron energy values [eV] at which the cross-section is provided
+: A list of at least two electron energy values [eV]. Values must be finite,
+  non-negative, and strictly increasing.
 
 `cross-sections`
-: Corresponding cross-section values [m²] for each energy level
+: A list of collision cross sections [m²] corresponding to `energy-levels`. The two
+  lists must have the same length. Cross-section values must be finite and
+  non-negative.
 
-`kind`
-: A string indicating the process type. Options include:
-  - `"effective"` – lumped or total effect of several channels
-  - `"excitation"` – electronic excitation
-  - `"ionization"` – electron-impact ionization
-  - `"attachment"` – electron attachment processes
+`product`
+: An optional description of the product or excited state produced by the collision.
+  This value does not need to correspond to a distinct species in the phase and does
+  not define the products of a chemical reaction.
+
+`threshold`
+: An optional non-negative collision threshold [eV]. If omitted or set to zero for an
+  `excitation`, `ionization`, or `attachment` process, the threshold is inferred from
+  the first energy level whose cross section is greater than zero.
 
 Example:
 
 ```yaml
 electron-collisions:
-- target: N2
-  energy-levels: [0.0, 0.015, 0.03, 0.05, 0.1, 0.15, 0.2, 0.3, 0.4, 0.7, 1.2, 1.5, 1.9,
-    2.2, 2.8, 3.3, 4.0, 5.0, 7.0, 10.0, 15.0, 20.0, 30.0, 75.0, 150.0]
-  cross-sections: [1.1e-20, 2.55e-20, 3.4e-20, 4.33e-20, 5.95e-20, 7.1e-20, 7.9e-20,
-    9e-20, 9.7e-20, 1e-19, 1.04e-19, 1.2e-19, 1.96e-19, 2.85e-19, 2.8e-19, 1.72e-19,
-    1.26e-19, 1.09e-19, 1.01e-19, 1.04e-19, 1.1e-19, 1.02e-19, 9e-20, 6.6e-20, 4.9e-20]
+- name: O2-effective
+  target: O2
   kind: effective
+  energy-levels: [0.0, 1.0, 2.0, 3.0]
+  cross-sections: [3.5e-21, 7.9e-20, 6.5e-20, 5.5e-20]
+
+- name: O2-ionization
+  target: O2
+  product: O2+
+  kind: ionization
+  threshold: 12.06
+  energy-levels: [12.06, 13.0, 18.0, 28.0]
+  cross-sections: [0.0, 2.3e-22, 2.0e-21, 7.4e-21]
 ```
 
+The `O2-effective` entry is used by the electron energy distribution solver without
+requiring a corresponding chemical reaction. The `O2-ionization` entry is additionally
+connected to the chemical mechanism by the `electron-collision-plasma` reaction shown
+above.
+
 :::{versionadded} 3.2
 :::
 
+:::{versionchanged} 4.0
+Each electron collision definition now requires a unique `name`. Electron collision
+reactions reference these definitions using the `collision` field, and tabulated
+cross-section data are stored exclusively in this section.
+:::
+
 (sec-yaml-falloff)=
 ### `falloff`