Add #GRAPH command to create graph-based representations of the chemical mechanism

[obin1]

KPP Update Submission Form

Describe the update:

Here's a feature to KPP that leverages the pre-existing parsing of stoichiometric structure to create graph-based representations of the chemical mechanism.

Motivation and Context:

My research group has found this code useful in several projects and so I formalized the changes to hopefully have these options in the main codebase!

Here's some documentation:

=======================================================

Off by default, the #GRAPH command currently supports two additional options: #GRAPH stoic and #GRAPH edgelist

This command can be added to your kpp definition file, e.g. small_strato.kpp (small_strato can be replaced with the name of your mechanism).

Option 1: #GRAPH stoic
This option generates two CSV files describing the structure of the mechanism based on stoichiometric balances and species composition.

small_strato_BiadjacencyMatrix.csv: A sparse matrix of the the net stoichiometric coefficients for each species in each reaction. Columns: spc_name,species_index,reaction_index,stoichiometric_coefficient. This is the net, weighted biadjacency matrix of the bipartite species-reaction graph, useful for automated detection of system-wide stoichiometric invariants and other mass conservation enforcing (e.g. Sturm and Wexler 2022)
small_strato_SpeciesCompositionMatrix: This is a species composition dense matrix that for each variable species (row), records the atom count of each element present (columns). Columns: species_index, species_name, followed by one column for each atom present in the mechanism (including IGNORE if used for some species). This matrix can be used for automated mass balance checking of mechanism output or individual reactions(e.g. Sturm and Silva, 2025)

Option 2: #GRAPH edgelist
The previous option uses net stoichiometry, which neglects reciprocal reactions (e.g. when the same species is a reactant and a product its net stoichiometry is zero). This #GRAPH edgelist option generates a small_strato_Edgelist.csv file listing the edges of the species-reaction bipartite graph (e.g. used for GEOS-Chem v14.0 in Li et al., 2025). Each row represents a connection between a species and a reaction, with direction and stoichiometric value.
Columns: # species_index (starts from 1),reaction_index (starts from 1),from,to, directed stoichiometric value

=======================================================

These files are useful for mechanism analysis, visualization, and further processing outside of KPP. Bipartite networks can be projected into unipartite networks, for example a kinetics graph as in Sander (2024). I've been working with @blrodriguez18 and @DanielGetter using this option in KPP to create a 30+ graph library of chemical mechanism edgelists!

In the future, we can add other output options like DOT (for graphviz) or GraphML format as discussed in #2

Type of update:

• Bug fix
• Structural update
• New feature
• Benchmarking update
• Interface to an external model (e.g. NASA/GEOS, CESM, WRF, etc.)
• Other (please specify)

Update submitted as:

• Github pull request (recommended)
• Git patch file
• Data files
• Other (please specify)

How has this update been tested?

Tested against 30+ mechanisms to ensure agreement with .eqn specification and edgelists. No change to integrators, and all C-I tests passed.

Compiler used in testing:

• GNU Fortran Compiler (aka gfortran), version ___
• Intel Fortran Compiler (aka ifort), version ___
• GNU Fortran (Homebrew GCC 14.2.0_1) version 14.2.0

This update was submitted by:

Developers and their affiliations:

Obin Sturm

Lead developer's email address:

psturm@usc.edu

[RolfSander]

Very interesting!

Could you make the example output (small_strato_BiadjacencyMatrix.csv,
small_strato_SpeciesCompositionMatrix and small_strato_Edgelist.csv)
available to us? This would make it easier for me to understand your
work.

[obin1]

Sure! here are the files for small strato. This ouptut might look trivial for such a small mechanism, but is really useful when working with larger mechanisms (GEOS-Chem, MECCA, MCM, etc.)
small_strato_BiadjacencyMatrix.csv
small_strato_SpeciesCompositionMatrix.csv
small_strato_EdgeList.csv

[RolfSander]

Thanks for the files. For large mechanisms, this will be a very useful
new feature! I have a few comments:

• I think that graphvizFile can be removed from code.c and code.h
  as long as the graphviz output option is not implemented yet.

• I noticed that you ignore the fixed species M and O2. Is this
  intentional? (just a question...)

I also have a couple of suggestions for the file format:

• The csv files contain a mix of integers and strings. I suggest to put
  all strings inside quotation marks. This makes it easier to read the
  file.

• The names in the header should be consistent across the three csv
  files. species_name in SpeciesCompositionMatrix and spc_name in
  BiadjacencyMatrix should have the same name.

• I would prefer header names which can be used directly as variable
  names for further processing. Specifically, I would replace spaces by
  underscores, and I would remove explanations in parentheses.

• I think the # as a header prefix in EdgeList can be removed.

[yantosca]

Thanks for this @obin1! Looks good to merge. I'll add the documentation post-merge.