Two-Term Boltzmann Equation solver

.github/workflows/linters.yml

@@ -65,3 +65,25 @@ jobs:
           git config --global core.whitespace \
             -cr-at-eol,tab-in-indent,blank-at-eol,blank-at-eof
           git diff --check ${{ github.event.pull_request.base.sha }}
+  example-data:
+    name: Check for unmerged example-data pull request
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        name: Checkout the repository
+        with:
+          fetch-depth: 100
+          persist-credentials: true
+
+      - name: Find matching PR in example_data
+        env:
+          BASE_PR: ${{ github.event.number }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          cd data/example_data
+          DATA_PR=$(gh pr list --repo Cantera/cantera-example-data --jq '.[] | select(.title | test("Cantera/cantera#'${BASE_PR}'")) | .number'  --json title,number)
+          if [ -n "$DATA_PR" ]; then
+            echo ":exclamation: Merge https://github.com/Cantera/cantera-example-data/pull/${DATA_PR} and update the submodule commit before merging this PR" >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi

.github/workflows/main.yml

@@ -105,6 +105,18 @@ jobs:
       with:
         submodules: recursive
         persist-credentials: false
+    - name: Check out updated example data
+      if: github.event_name == 'pull_request'
+      env:
+        BASE_PR: ${{ github.event.number }}
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        cd data/example_data
+        gh repo set-default Cantera/cantera-example-data
+        DATA_PR=$(gh pr list --repo Cantera/cantera-example-data --jq '.[] | select(.title | test("Cantera/cantera#'${BASE_PR}'")) | .number'  --json title,number)
+        if [ -n "$DATA_PR" ]; then
+          gh pr checkout --repo Cantera/cantera-example-data $DATA_PR
+        fi
     - name: Setup Python
       uses: actions/setup-python@v5
       with:
@@ -419,6 +431,17 @@ jobs:
         with:
           submodules: recursive
           persist-credentials: false
+      - name: Check out updated example data
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_PR: ${{ github.event.number }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          cd data/example_data
+          DATA_PR=$(gh pr list --repo Cantera/cantera-example-data --jq '.[] | select(.title | test("Cantera/cantera#'${BASE_PR}'")) | .number'  --json title,number)
+          if [ -n "$DATA_PR" ]; then
+            gh pr checkout --repo Cantera/cantera-example-data $DATA_PR
+          fi
       - name: Set up micromamba
         uses: mamba-org/setup-micromamba@b09ef9b599704322748535812ca03efb2625677b # v2.0.5
         with:

AUTHORS.md

@@ -12,6 +12,7 @@ update, please report on Cantera's
 - **Halla Ali** [@hallaali](https://github.com/hallaali)
 - **Emil Atz** [@EmilAtz](https://github.com/EmilAtz)
 - **Jongyoon Bae** [@jongyoonbae](https://github.com/jongyoonbae) - Brown University
+- **Nicolas Barléon** [@NicolasBarleon](https://github.com/NicolasBarleon) - CERFACS
 - **Philip Berndt**
 - **Guus Bertens** [@guusbertens](https://github.com/guusbertens) - Eindhoven University of Technology
 - **Wolfgang Bessler** [@wbessler](https://github.com/wbessler) - Offenburg University of Applied Science
@@ -49,6 +50,7 @@ update, please report on Cantera's
 - **Kyle Linevitch, Jr.** [@KyleLinevitchJr](https://github.com/KyleLinevitchJr)
 - **Christopher Leuth**
 - **Nicholas Malaya** [@nicholasmalaya](https://github.com/nicholasmalaya) - University of Texas at Austin
+- **Quentin Malé** [@QuentinMale](https://github.com/QuentinMale) - Harvard University
 - **Thanasis Mattas** [@ThanasisMattas](https://github.com/ThanasisMattas) - Aristotle University of Thessaloniki
 - **Manik Mayur** [@manikmayur](https://github.com/manikmayur)
 - **Evan McCorkle** [@emccorkle](https://github.com/emccorkle)
@@ -61,6 +63,7 @@ update, please report on Cantera's
 - **Paul Northrop** [@pwcnorthrop](https://github.com/pwcnorthrop)
 - **Chris Pilko** [@cpilko](https://github.com/cpilko)
 - **Sebastian Pinnau** [@spinnau](https://github.com/spinnau)
+- **Matthew Quiram** [@mquiram](https://github.com/mquiram) - Massachusetts Institute of Technology
 - **Corey R. Randall** [@c-randall](https://github.com/c-randall) - Colorado School of Mines
 - **Andreas Rücker** [@cannondale1492](https://github.com/cannondale1492)
 - **Jeff Santner** [@jsantner](https://github.com/jsantner)

doc/sphinx/yaml/index.md

@@ -31,6 +31,8 @@ state](sec-yaml-species-eos), [transport property](sec-yaml-species-transport),
 YAML reaction definitions include specification of common elements such as the reaction
 equation and [efficiencies](sec-yaml-efficiencies), as well as parameters specific to
 the type of [rate parameterization](sec-yaml-rate-types).
+See also the {ref}`electron collision data format <sec-yaml-electron-collisions>`
+used in plasma-phase simulations.
 
 ## Mechanism Conversion
 

doc/sphinx/yaml/phases.md

@@ -862,6 +862,7 @@ Additional fields:
 
     - `isotropic`
     - `discretized`
+    - `Boltzmann-two-term`
 
   `shape-factor`
   : A constant in the isotropic distribution, which is shown as x in the detailed
@@ -909,6 +910,9 @@ Examples:
     normalize: False
 ```
 
+See also {ref}`sec-yaml-electron-collisions`,
+which is used to specify electron-impact cross sections relevant to plasma simulations.
+
 :::{versionadded} 2.6
 :::
 

doc/sphinx/yaml/reactions.md

@@ -18,6 +18,7 @@ The fields common to all `reaction` entries are:
   - [`Blowers-Masel`](sec-yaml-Blowers-Masel)
   - [`two-temperature-plasma`](sec-yaml-two-temperature-plasma)
   - [`electron-collision-plasma`](sec-yaml-electron-collision-plasma)
+  - [`electron-collisions`](sec-yaml-electron-collisions)
   - [`falloff`](sec-yaml-falloff)
   - [`chemically-activated`](sec-yaml-chemically-activated)
   - [`pressure-dependent-Arrhenius`](sec-yaml-pressure-dependent-Arrhenius)
@@ -308,6 +309,48 @@ Example:
 :::{versionadded} 3.1
 :::
 
+(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.
+
+Each entry includes:
+
+`target`
+: The name of the species that is the target of the collision
+
+`energy-levels`
+: A list of electron energy values [eV] at which the cross-section is provided
+
+`cross-sections`
+: Corresponding cross-section values [m²] for each energy level
+
+`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
+
+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]
+  kind: effective
+```
+
+:::{versionadded} 3.2
+:::
+
 (sec-yaml-falloff)=
 ### `falloff`
 

include/cantera/base/utilities.h

@@ -179,7 +179,7 @@ void checkFinite(const double tmp);
  * @param values  Array of *N* values to be checked
  * @param N       Number of elements in *values*
  */
-void checkFinite(const string& name, double* values, size_t N);
+void checkFinite(const string& name, const double* values, size_t N);
 
 //! Const accessor for a value in a map.
 /*

include/cantera/kinetics/ElectronCollisionPlasmaRate.h

@@ -7,10 +7,10 @@
 #ifndef CT_ELECTRONCOLLISIONPLASMARATE_H
 #define CT_ELECTRONCOLLISIONPLASMARATE_H
 
-#include "cantera/thermo/PlasmaPhase.h"
 #include "cantera/kinetics/ReactionData.h"
 #include "ReactionRate.h"
 #include "MultiRate.h"
+#include "cantera/numerics/eigen_dense.h"
 
 namespace Cantera
 {
@@ -32,19 +32,17 @@ struct ElectronCollisionPlasmaData : public ReactionData
         energyLevels.resize(0);
         distribution.resize(0);
         m_dist_number = -1;
-        m_level_number = -1;
     }
 
     vector<double> energyLevels; //!< electron energy levels
     vector<double> distribution; //!< electron energy distribution
-    bool levelChanged;
+
+    //! integer that is incremented when electron energy levels change
+    int levelNumber = -1;
 
 protected:
     //! integer that is incremented when electron energy distribution changes
     int m_dist_number = -1;
-
-    //! integer that is incremented when electron energy level changes
-    int m_level_number = -1;
 };
 
 
@@ -103,9 +101,16 @@ struct ElectronCollisionPlasmaData : public ReactionData
 class ElectronCollisionPlasmaRate : public ReactionRate
 {
 public:
-
     ElectronCollisionPlasmaRate() = default;
-
+    //! Constructor from YAML input for ElectronCollisionPlasmaRate.
+    /*!
+    * This constructor is used to initialize an electron collision plasma rate
+    * from an input YAML file. It extracts the energy levels, cross-sections,
+    * and reaction metadata used in the rate coefficient calculation.
+    *
+    * @param node         The AnyMap node containing rate fields from YAML
+    * @param rate_units   Units used for interpreting the rate fields
+    */
     ElectronCollisionPlasmaRate(const AnyMap& node,
                                 const UnitStack& rate_units={})
     {
@@ -133,6 +138,10 @@ class ElectronCollisionPlasmaRate : public ReactionRate
      */
     double evalFromStruct(const ElectronCollisionPlasmaData& shared_data);
 
+    //! Calculate the reverse rate coefficient for super-elastic collisions
+    //! @param shared_data Data structure with energy levels and EEDF
+    //! @param kf Forward rate coefficient (input, unused)
+    //! @param kr Reverse rate coefficient (output, modified)
     void modifyRateConstants(const ElectronCollisionPlasmaData& shared_data,
                              double& kf, double& kr);
 
@@ -143,6 +152,47 @@ class ElectronCollisionPlasmaRate : public ReactionRate
         throw NotImplementedError("ElectronCollisionPlasmaRate::ddTScaledFromStruct");
     }
 
+    //! The kind of the process which will be one of the following:
+    //! - `"effective"`: A generic effective collision
+    //! - `"excitation"`: Electronic or vibrational excitation
+    //! - `"ionization"`: Electron-impact ionization
+    //! - `"attachment"`: Electron attachment
+    //! @since New in Cantera 3.2.
+    const string& kind() const {
+        return m_kind;
+    }
+
+    //! Get the target species of the electron collision process.
+    //! This is the name of the neutral or ionic species that the electron interacts with
+    //! @since New in Cantera 3.2.
+    const string& target() const {
+        return m_target;
+    }
+
+    //! Get the product of the electron collision process.
+    //! This is the name of the species or excited state of
+    //! some species resulting from the process.
+    //! @note this may not necessarily be represented by
+    //! a distinct species in the mixture.
+    //! @since New in Cantera 3.2.
+    const string& product() const {
+        return m_product;
+    }
+
+    //! Get the energy threshold of electron collision [eV]
+    //!
+    //! By default, the threshold is set to the first non-zero energy value
+    //! listed in the tabulated cross section data.
+    //!
+    //! @note This behavior may be subject to change. A more robust approach
+    //! may use the energy corresponding to the first non-zero cross section
+    //! value, rather than the first non-zero energy point in the data table.
+    //!
+    //! @since New in Cantera 3.2.
+    double threshold() const {
+        return m_threshold;
+    }
+
     //! The value of #m_energyLevels [eV]
     const vector<double>& energyLevels() const {
         return m_energyLevels;
@@ -162,9 +212,28 @@ class ElectronCollisionPlasmaRate : public ReactionRate
     void updateInterpolatedCrossSection(const vector<double>&);
 
 private:
+    //! The name of the kind of electron collision
+    string m_kind;
+
+    //! The name of the target of electron collision
+    string m_target;
+
+    //! The product of electron collision
+    string m_product;
+
+    //! The energy threshold of electron collision
+    double m_threshold;
+
     //! electron energy levels [eV]
     vector<double> m_energyLevels;
 
+    //! Counter used to indicate when #m_energyLevels needs to be synced with the phase
+    int m_levelNumber = -3;
+
+    //! Counter used to indicate when #m_crossSectionsOffset needs to be synced with the
+    //! phase
+    int m_levelNumberSuperelastic = -2;
+
     //! collision cross sections [m2] at #m_energyLevels
     vector<double> m_crossSections;
 

include/cantera/kinetics/Kinetics.h

@@ -1474,9 +1474,6 @@ class Kinetics
     Eigen::SparseMatrix<double> m_stoichMatrix;
     //! @}
 
-    //! Boolean indicating whether Kinetics object is fully configured
-    bool m_ready = false;
-
     //! The number of species in all of the phases
     //! that participate in this kinetics mechanism.
     size_t m_kk = 0;