Journal Pre-proof

A Python Multiscale Thermochemistry Toolbox (pMuTT)

for thermochemical and kinetic parameter estimation

Charles, Jonathan Lym, Gerhard R. Wittreich, Dionisios G. Vlachos

PII: S0010-4655(19)30251-6
DOI: https://doi.org/10.1016/j.cpc.2019.106864
Reference: COMPHY 106864

To appear in: Computer Physics Communications

Received date : 13 June 2017

Revised date : 17 June 2017
Accepted date : 6 August 2017

Please cite this article as:Charles, J. Lym, G.R. Wittreich and D.G. Vlachos, A Python
Multiscale Thermochemistry Toolbox (pMuTT) for thermochemical and kinetic parameter
estimation, Computer Physics Communications (2019), doi:
https://doi.org/10.1016/j.cpc.2019.106864.

This is a PDF file of an article that has undergone enhancements after acceptance, such as the
addition of a cover page and metadata, and formatting for readability, but it is not yet the definitive
version of record. This version will undergo additional copyediting, typesetting and review before it
is published in its final form, but we are providing this version to give early visibility of the article.
Please note that, during the production process, errors may be discovered which could affect the
content, and all legal disclaimers that apply to the journal pertain.

© 2017 Published by Elsevier B.V.

 Journal Pre-proof

A Python Multiscale Thermochemistry Toolbox

(pMuTT) for Thermochemical and Kinetic
Parameter Estimation
*
Charles, Jonathan Lym, Gerhard R. Wittreich, and Dionisios G. Vlachos
Department of Chemical and Biomolecular Engineering Rapid
Advancement in Process Intensification Deployment (RAPID) Institute
University of Delaware, Newark, DE 19716, United States
*Corresponding author: vlachos@udel.edu

Abstract
Estimating the thermochemical properties of systems is important in many fields such as material
science and catalysis. The Python multiscale thermochemistry toolb x (pMuTT) is a Python software
library developed to streamline the conversion of ab-initio data to therm chemical properties using
statistical mechanics, to perform thermodynamic analysis, and to create input files for kinetic
modeling software. Its open-source implementation in Python leve ages existing scientific codes,
encourages users to write scripts for their needs, and allows the code to be expanded easily. The core
classes developed include a statistical mechanical model in which energy modes can be included or
excluded to suit the application, empirical models for rapid thermodynamic property estimation, and
a reaction model to calculate kinetic parameters or changes in thermodynamic properties. In addition,
pMuTT supports other features, such as Brønsted-Evans-Polanyi (BEP) relationships, coverage
effects, and ab-initio phase diagrams.

Program summary
Program title: pMuTT
Program files doi: http://dx.doi.org/10.17632/b7f7d28ynd.1
Licensing provisions: MIT license (MIT)
Programming language: Python
External routines: ASE, NumPy, P nd s, SciPy, Matplotlib, Pygal, PyMongo, dnspython

Nature of problem: Conversion of ab-initio properties to thermochemical properties and rate

constants is time consuming and error-pro e.

Solution method: Python package with a modular approach to statistical thermodynamics and
rate constant estimation.

Keywords
Thermochemistry, statistical mechanics, rate constant, catalysis, microkinetics
 Journal Pre-proof

1 Introduction
Multiscale modeling, linking quantum mechanical properties with process design, is
increasingly popular in fields such as material design and heterogeneous catalysis. Computational
tools are the powerhouse behind multiscale modeling as any scale can be simulated efficiently,
especially with the rapid development of computing power.
Thermochemistry is a part of chemistry that studies the enthalpy changes that accompany a
reaction. In the chemical process, there is always a change in enthalpy. The magnitude of the change
in enthalpy is as large as the difference between the enthalpy of the reaction product and the amount
of reactant enthalpy.
Several thermochemical estimators exist in the literature and are listed in Table 1. pMuTT is
unique for several reasons. First, pMuTT is open-source and modular in design (especially the
StatMech and Reaction classes) so new models can be added based on users’ needs. Second,
other packages provide limited functionality for heterogeneous catalysis (instead either specializing in
materials science applications or the thermodynamics is not th ir main focus) whereas pMuTT strives
to support a wide range of functionality for heterogen ous catalysis. Third, pMuTT provides
functionality to directly read quantum data from ab-initio software and to create input files for
various kinetic modeling tools.

Table 1. Existing thermochemistry estimator packages in the literature.

Name Remarks References

Atomic Simulation Open-source package that [1]
Environment (ASE) supports statistical
thermodynamic models
including ideal gas, hindered
tr nsl tor/hindered rotor
model, h rmonic limit and
crystal statistical mechanical
models.
Python Materials Genomics Open-source package that uses [2]
(pymatgen) electronic energies to predict a
wide array of properties
including phase diagrams and
Pourbaix diagrams. Supports
Shomate polynomials and
calculating reaction energies of
bulk species.
Reaction Mechanism Open-source package that [3]
Generator (RMG) predicts thermodynamic
properties using databases. If
no entry for the adjacency list
exists, properties can be
estimated using group
additivity, hydrogen bond
 Journal Pre-proof

increment method, and on-the-

fly quantum-chemical
calculations.
ThermoCalc Offers a wide range of [4]
functionality but requires a
license and its functionality is
built around its database.
PanEngine Primarily focused on phase [5]
diagrams but requires a license
and its functionality is built
around its database.
MatCalc Similar to PanEngine, [6]
primarily focusing on phase
diagrams. It requires a license.

pMuTT aims to be lightweight with few dependencies while leveraging scientific libraries.
The dependencies are listed below:

• Atomic Simulation Environment (ASE) [1] provides an interface with several ab-initio codes.
pMuTT utilizes the Atoms object to calculate ro erties like the moments of inertia of
molecules in an efficient manner.
• NumPy [7] provides an efficient implementation of multidimensional arrays and matrix
manipulations.
• Pandas [8] builds upon NumPy with DataFrame obj cts for easier processing of data.
pMuTT primarily uses this library to read from Excel spreadsheets.
• SciPy [9–11], like Pandas, builds upon NumPy for extra functionality for scientific
applications. pMuTT uses spline interpolation for reaction coordinate diagrams and curve
fitting when initializing empirical models.
• Matplotlib [12] provides visualization tools for pMuTT.
• Pygal provides pMuTT the capability to make interactive SVG plots.
• PyMongo allows pMuTT to interface with MongoDB databases.
• dnspython, like PyMongo, a ows pMuTT to interface with MongoDB databases.
Python, one of the leading langu ges used in the scientific community, has a diverse set of readily
available scientific libraries. Python’s object-oriented design allows molecules and reactions to be
intuitively described by objects with associated attributes and methods. Python’s automatic memory
management and dynamically typed sy tax makes coding short scripts or large-scale projects
straightforward to write and read. Another advantage of Python is dynamic binding in which methods are
looked up at runtime, which allows objects to be used interchangeably if they have the necessary
methods. Most of pM TT’s f nctionality does not require expensive computations so Python’s reduced
performance compared to compiled languages like C++ or Fortran is not significant.

In the first secti n f this paper, we discuss the theoretical foundations of pMuTT. In the second, we
describe the anal g us data structures in the package and show some of its capabilities. In the third,
we demonstrate how pMuTT can be used to convert ab-initio data to Chemkin input files for the
ammonia decomposition mechanism on Ru(0001).
 Journal Pre-proof

2 Theory
2.1 Statistical mechanics
The collective body of statistical mechanics is based on two main postulates. The equal a priori
probability postulate states that all microstates of the system of volume V that have the same energy
and the same number of particles are equally probable. The ergodic hypothesis states the (long) time
average of any mechanical property in a macroscopic system is equal to the average value of that
property over all the microscopic states of the system, each weighted with its probability of
occurrence, provided that the microscopic states replicate the thermodynamic state and environment
of the actual system [13]. These statements, while simple, have powerful implications. The
macroscopic properties of a system can be estimated by applying models describing the microscopic
properties. Ab-initio techniques, such as DFT, are less computationally expensive for small systems so
extrapolating to calculate the bulk properties is especially valuable.

2.1.1 Partition functions and thermodynamic properties

The molecular partition function q for a single molecule can be expressed as:
−

=∑ (1)

where is the energy of state , is the Boltzmann constant and is the temperature.

The molecular partition function is fundamental to statistical mechanics treatment and describes the
probability distribution of possible states but alone is insufficient to describe macroscopic
properties. Here we focus on how relevant thermochemical prop rti s are calculated using the
canonical ensemble, which gives the distribution of states in a fix d volume, temperature, and
number of molecules. The canonical partition function Q is calculated from the molecular partition
function using:
for distinguishable systems
( , , )={

! for indistinguishable systems

(2)
where is the volume and is the number of molecules.
A wide array of thermodynamic properties c n be calculated using the following relationships:
= 2 ( )
,

= 2
( ) +( ) (3)
, ,

= + ( ) ,
( , , )=− ( , , )
=− ( )
, , ≠
(4)
2

=2 ( )+2( )

,
2

, (5)

(6)

(7)

(8)
 Journal Pre-proof

(9)
( )

= −

)
(

where is the internal energy, is the enthalpy, is the entropy, is the Helmholtz free energy, is the
chemical potential, and and are the heat capacity at constant volume and pressure, respectively.

2.1.2 Transition state theory

Transition state theory describes the rates of activated elementary steps. It assumes that the complete
potential energy surface does not need to be known. Instead, all reactants proceed through a saddle
point, known as the transition state. By assuming quasi-equilibrium between the reactants and the
transition state, the rate constant of a reaction is calculated [14]. The pre-exp nential factor A is
related to the partition function in the following manner:

=
ℎ
(10)

where is the molecular partition function of species i, is the stoichiometry of species in a

‡
reaction, is the partition function of the transition state, and h is Planck’s constant. The factor of
ℎ

is due to the weak frequency associated with the reaction coordinate [15]. Similarly,
the activation energy can be estimated using statistical mechanics:

≈ ‡=‡−
(11)
‡
where is the activation energy, is the enthalpy of the transition state, and is the enthalpy of the initial state.

2.2 Semi-empirical/empirical methods

Ab-initio methods can become computationally prohibitive especially for large reaction networks
and/or large molecules. In order to reduce the number of calculations required for a complete
mechanism, semi-empirical and empirical re ationships are often used to enable scalability in
both molecular and network size. Properties re evaluated quickly using a few descriptors.

2.2.1 Brønsted-Evans-Polanyi (BEP) relationships

BEP relationships estimate the activation energies of a homologous series from a
thermodynamic descriptor. The simplest domi a t form of that relationship is
expressed as:

(12) =+ 0

where is the activation energy, is the slope of the BEP, 0 is the intrinsic reaction barrier, and is the change
in enthalpy of the reaction. The slope, , represents the reaction coordinate position of the transition state
where a value of 0 and 1 represent reactant-like (early) and product-like (late) transition states,
respectively. If the change in electronic energy is used as a descriptor instead of the change in enthalpy,
the activation energy typically only represents the difference in electronic energy between the transition
state and the reactants. BEP relationships for common homologous series are available in the literature
[16–18]. A homologous series defines a family of reactions undergoing the same type of chemical
transformation, e.g., C-H bond scission say in alkanes, and exists when the transition state of all members
(elementary reactions) of the family is alike. Having estimated the slope and intercept from a few
members of a family, it enables calculations of kinetic parameters of the entire family from much simpler
and less expensive thermodynamic calculations. Clearly, BEP relations allow scalability to large reaction
networks.
 Journal Pre-proof

2.2.2 Linear scaling relationships (LSRs)

Calculating the binding energy of adsorbates on different surfaces can become expensive, especially
for large adsorbates and/or mechanisms. Abild-Peterson and coworkers found that the binding energy
of heteroatoms, such as O, C, N, and S, can be used as a descriptor for partially hydrogenated
intermediates (i.e., OHx, CHx, NHx, and SHx), respectively [19]. Similar to BEPs, LSRs
assume a linear relationship:

= ( ) + (13a)
(13b)
−

( )=

where and are the binding energies of and respectively, and ( ) and are the slope and intercept. The slope, ( ), can be estimated from regression f electr nic structure
calculation data or theoretically (Equation 13b) where is the maximum number of ligands on the
central heteroatom and is the actual number of ligands on the central heter atom, as it is related to
the valency of the adsorbate on metals based on the d-band theory [19]. Typically, LSRs are applied
for adsorption across a family of catalysts, e.g., metals [19,20]. LSRs have been extended to oxides,
carbides, phosphides, and nitrides [21–24].

LSRs are particularly useful when transferring mechanisms to different surfaces as the electronic
energies of only a handful adsorbates need to be calculated. Additionally, LSRs can be extended to
multidentate species using:

new = ref +∑ , ( r f sp ci s j
n w − ref
ref species j
) (14)
=1

where is the slope connecting multidentate adso bate and reference species , , ,
, new ref

refspecies j ref species j

new , ref are the binding energies of species on the new surface, species on reference surface, reference species on the new surface, and species on the reference surface,

respectively [19,21,25]. By calculating the binding energies on a reference surface, one can estimate
all thermochemistry on a new surface from knowledge of simple heteroatom information on the
new surface.

2.2.3 NASA/Shomate polynomi ls

Calculating thermochemical properties using statistical mechanics can become
cumbersome to use for on-the-fly kinetic and CFD calculatio s. It is often more
convenient and faster to estimate thermodynamic properties usi g a poly omial that is
fitted to the thermodynamic data. This approach bypasses use of loops, natural
logarithms, and exponentials. In addition, these simplified relationships can be included
in a compiled code, further speeding a process that often requires a very large number
of iterations as part of a numerical solver. Two different forms often used in the literature
are NASA polynomials and Shomate polynomials [26]. The empirical forms are shown in
equations 15 and 16, respectively.

= + + 2
+ 3
+ 4
(15a)
1 2 3 4 5

(15b)
2 3 4
1

= + + + + +

6
1
2 2 3
3 4
4 5
5

=+ +
2

+
3

+
4

+ (15c)
1 2 3
2 4
3 5
4 7
 Journal Pre-proof

2 3 1
=++ + +
(16a)
2

2 3 4
1

(16b)
− = + + + − + −

298.15
2 3 4

2 3
1
= ( )+ +
2
+
3
−
2 2
+ (16c)

= (16d)
1000

2.3 Other
2.3.1 Equilibrium constants
The reaction equilibrium constant is the ratio of product to reactant activities when sufficient time has
elapsed such that the net reaction rate is zero. At equilibrium at constant temperature and pressure,
the system Gibbs free energy is at a minimum. The system Gibbs f ee ene gy is related to the reaction
quotient (ratio of product activities to reactant activities) by:

∆ =∆ °+ (17)

∆ is the overall system Gibbs free energy change, ∆ ° is the reaction standard Gibbs free energy, R is the molar gas constant, T is the temperature, and Q is
the r action quotient. A positive or negative system ∆ will result in driving the reaction towa d eactants or products, respectively. When the system ∆ is zero,
then there is no driving force towa d either products or reactants and the system has reached equilibrium. The reaction quotient at equili brium is now
the equilibrium constant, K, and the equation is rewritten as:

0=∆ °+
(18a)
−∆ °
= (18b)

2.3.2 Referencing
Thermodynamic data derived from DFT are often combined with published experimental data or higher-
level ab-initio data for gas-phase species. This is common for multiphase systems, e.g., when including
both gas and surface species in a kinetic model, where surface thermodynamics is difficult to determine
experimentally and DFT data for gas species is less accurate. Use of DFT calculations leads typically to
significantly incorrect predictions of overall thermodynamics (equilibrium constants, equilibrium
conversion). On the other hand, properties of gas species are estimated with chemical accuracy either
experimentally or from high-level ab-initio calculations. Experimental data is generally referenced at
standard temperature and pressure (STP) while DFT data is not. When the two are used together, the
thermodynamic properties of the surface species need to be adjusted so the reference state is the same as
that of the gas species. We describe two approaches to achieving this.

Adsorption Energy: If the adsorption energy for a gas species on a catalytic surface is well known,
then the DFT calculated values for the surface species are replaced with those well-known values. The
thermodynamic properties of surface species must be shifted in a way that does not alter the surface
reaction energies. If there are multiple gas species with well-known adsorption energies, then a shift
in properties of surface species that minimizes the overall difference between the well-known and
DFT calculated adsorption energies is used [27].
 Journal Pre-proof

Surface Energies: When adsorption energies are not well known, an alternative approach is
followed. The thermodynamic properties of a set of reference gases are compared to their DFT
calculated thermodynamic properties. The difference is then used to shift the surface species’
thermodynamic properties to align their reference states. If multiple reference gases are employed,
then a shift that minimizes the overall difference between the experimental and DFT-based adsorption
energies is used. This difference also needs to be applied in a way that does not impact surface
reaction energies [28,29].

2.3.3 Coverage effects

When multiple species are adsorbed on a surface, the adsorbates can either have attractive or repulsive
interactions compared to the limit of infinite separation. These interactions o ten have non-trivial
effects on thermodynamic and kinetic properties and have to be included to have an accurate
representation of thermodynamics and kinetics [30–32].

3 Program features
3.1 Overview
pMuTT is developed in a modular fashion to increase flexibility and encourage new additions and
features. Classes can broadly be categorized in three groups: (1) model classes, which represent the
thermodynamic contribution from some phenomenon (such as a molecule’s translation or the
repulsive effect of adsorbates in close proximity to each other on a surface); (2) species classes, which
represent a chemical species; (3) reaction classes, which represent a chemical reaction. Python’s late
dynamic binding approach allows any model class to be inserted into species classes and any species
class to be inserted into reaction classes. An exhaustive list of the classes belonging to each group is
shown in Figure 1. Below, we describe the role of the more important classes.

Figure 1. Categorization of model cl sses, species classes, and reaction classes implemented in pMuTT version
1.2.10.

3.2 StatMech
As previously mentioned, statistical mechanical models bridge the gap between atoms’ or molecules’
quantum properties (such as vibrational frequencies, electronic energy and moment of inertia) and
bulk properties (such as heat capacity, enthalpy, or entropy) using ensemble averages. pMuTT
capitalizes on the ass mption that the modes (i.e., translational, rotational, vibrational, electronic and
nuclear) are separable by c mpartmentalizing each mode, giving users the flexibility to add or remove
modes without m difying the others. The StatMech class stores each mode (represented by a
model class) and any quantity of the bulk can be calculated if its parts have similarly
defined methods:

ℎ =++++
(19)
ℎ
where , , , , , are the thermodynamic quantities of interest of the overall statistical mechanical model (translational, rotational, vibrational, electronic, and nuclear
modes, respectively).
 Journal Pre-proof

Different models can be combined to describe different systems. For example, hydrogen gas is a
diatomic molecule and therefore has translational, vibrational, rotational, electronic and nuclear
modes; helium gas is monatomic and only contains translational, electronic, and nuclear modes; and
diamond is a condensed state with vibrational, electronic, and nuclear modes. Users also have
control of which model to assign to modes. A large adsorbate may have frustrated rotations so the
user can choose the quasi-rigid rotor harmonic oscillator approximation (qRRHO) instead of the
harmonic approximation to calculate thermodynamic properties more accurately. A list of supported
statistical mechanical models is listed in Table 2.
Table 2. List of supported statistical mechanical models.

Mode Model Remarks

Translational FreeTrans Translati ns assuming no
interm lecular interactions.
The n degrees parameter
can be adjusted for 1D, 2D and
3D translational modes.
Vibrational HarmonicVib Vib ations are independent and
ha monic.
qRRHOVib [33,34] Low-frequency modes (such as
frustrated rotations) are treated
using the rigid rotor
approximation.
EinsteinVib Each atom in a crystal vibrates
as an independent 3D harmonic
oscillator.
DebyeVib Improves upon EinsteinVib by
considering simultaneous
vibrations. This estimate
improves accuracy at lower
temperatures.
Rotational RigidRotor The species can be rotated with
no change in bond properties.
Electronic GroundStateElec Electronic ground state of a
system.
LSR Linear Scaling Relationship to
estimate binding energy of
adsorbates using another
reference adsorbate.
Nuclear EmptyNucl Does not contribute to any
thermochemical properties.
Useful for chemical reactions
where the nucleus properties
do not change.
Miscellaneous EmptyMode Default mode that does not
contribute to any
thermochemical properties.
ConstantMode Allows the user to set arbitrary
values to thermodynamic
quantities.
StatMech objects can be initialized by passing the model objects for each mode and their associated
properties. Some model objects are commonly used together such as the ideal gas assumption assumes free
translations, harmonic vibrations, rigid rotations, and ground states for the electronic and nuclear
 Journal Pre-proof

modes. For these common assumptions, StatMech can be initialized using presets.
Supplementary Listing 1 shows examples using different presets.
> CH4_statmech = StatMech(req_properties, **preset[‘idealgas’])
> H_CH4 = CH4_statmech.get_H(T, P)

3.3 Empirical
NASA and Shomate [26] polynomials are supported by pMuTT. These empirical forms can be
initialized by inputting coefficients directly, fitting to a statistical mechanical model, and fitting to a
dataset of heat capacities, enthalpies and entropies. Listing 3 shows initialization of Nasa objects
using a statistical mechanical model.
> CH4_nasa = Nasa(a_low, a_high, T_low, T mid, T high)
> CH4_nasa = Nasa.from_statmech(statmech_model, T l w, T_high)
> CH4_nasa = Nasa.from_data(T, CpoR, T_ref, HoRT ref, SoR_ref)
> H_CH4 = CH4_nasa.get_H(T)

3.4 Reactions
The Reaction class is structured in a way that any species object can be assigned as a reactant,
transition state or product of a reaction. Similar to the StatMech class, any property can be
calculated if the inputted species have corresponding methods to calculate their contribution. The
methods are separated into three general groups: the property of a particular state (i.e., initial state,
transition state, or final state), the change in a property (i.e., difference between final state and initial
state), and the activation property (i.e., difference b tw n transition state and initial state).

=
∑ (20a)

=
(20b)
∑− ∑

‡
= ∑ − ∑ (20c)

where is the interested thermody amic quantity and is the stoichiometric coefficient of species in a
reaction. Reaction objects can be initialized by strings, which makes it straightforward for users
to initialize by scripting or to import from other codes such as RING [3].

> species = ...

> reaction = Reaction.from_string(reaction_string, species)
> delta_H = reaction.get delta_H(T, P)
> G_act = reaction.get G act(T, P)

A group of Reacti n bjects can be stored in a Reactions object for further analysis. For
example, the most stable bulk structure or adsorbate configuration can be predicted at a set of
conditions by minimizing the free energy of the system. In Figure 2, the most stable configuration of
CO/Pt(111) is investigated for a handful of configurations (see Supplementary Figure 1 for the
configurations considered and Supplementary Listing 1 for code used to generate the plot).
 Journal Pre-proof

Figure 2. Ab-initio phase diagrams of the CO/Pt(111) system generated by pMuTT. Left shows the 1D phase
diagram where the Gibbs energy of the select configurations is displayed as a functi n of temperature. Right
shows the 2D diagram where the color represents the most stable c nfigurati n at a given temperature and
pressure.

A Reactions object can also represent a pathway from reactants to p oducts. pMuTT has the
capability to plot the reaction coordinate diagram, as shown in Figu e 3, and calculate the energy span
[35] of the pathway.

Figure 3. Reaction coordinate diagram generated using pMuTT for the ammonia decomposition mechanism.

3.5 BEPs
As shown in Figure 1, the BEP class is effectively represented with a transition state species. As its
name suggests, it represents a BEP relationship so the activation energy can be estimated using an
associated Reaction object. It supports different descriptors, such as the change in enthalpy or
change in electronic energy, to suit the data used to derive the relationship. An arbitrary number of
model objects can also be added to increase model complexity (e.g. if the user wanted to input the
vibrational frequencies of the transition state).
 Journal Pre-proof

> reaction = ...

> bep = BEP(reaction=reaction, slope, intercept)
> Ea = reaction.get_E_act(T)

3.6 LSRs
The electronic energy of an adsorbate can be estimated using the LSR class. Although it is semi-
empirical, it is typically inputted to a StatMech object to represent the electronic mode. Similar to
the BEP class, evaluating thermodynamic properties use a Reaction object but the inputted
reaction is typically the adsorption of different species (i.e. the binding energy of A is used to predict
the binding energy, and consequently the electronic energy, of AH x).
> A_adsorption_reaction = Reaction.from_string(‘A+*=A*’, species)
> AHx_species = LSR(reaction=A_adsorption reacti n,
slope=..., intercept=...)

3.7 Referencing
For the enthalpy of DFT-calculated species to be consistent with accurate enthalpies referenced to the
standard state, the References class can add an offset:

= ,
+ ∙ℎ
(21)
,
where , are the enthalpies of species predicted by a high accuracy technique (i.e., using experimental measurement or high-level computation) and by DFT respectively, is a vector with
descriptors, and ℎ is the vector of the enthalpy offs t corr sponding to each descriptor. The offset vector can be set manually or it can be fitted using lin ar r gr ssion using a set of reference species

[36]. By default, the descriptor is the elemental composition of the reference species but any
attribute expressed as a dictionary with numbers as values could be used.

3.8 Coverage effects

The PiecewiseCovEffect object assumes interactions are pairwise and follow a piecewise
linear form:

=+
(22)
where is the species affected by species , is the enthalpic change due the coverage effect, is the
coverage of species j, and re the slope and intercept of the coverage effect at interval k. This form has
been used in several microkinetic models to model coverage effects in the literature [37–40]. The
parameters, a d , are typically regressed using only electronic energy calculations from DFT since
vibration calculations can become expensive. As a result, the change in enthalpy due to coverage
effects is not dependent on temperature and is equal to the change in electronic energy. Howeve , if
this functionality is desired, a new class can be added where the slope and intercept are also a f
nction of temperature.

3.9 Input and o tp t

To increase usability f the software, pMuTT has modules for reading and writing files.

3.9.1 Excel
The primary method to input data to pMuTT is through spreadsheets such as Excel. The pandas library
increases flexibility by converting any sheet into a list of dictionaries. The dictionaries can then be used to
initialize any object using keyword syntax. Its flexibility is shown through repeated use to initialize
different objects in Listing 1 - Listing 5. Special rules are defined for specific header names to provide
more complex operations such as reading Atoms objects from files. An example of
 Journal Pre-proof

a spreadsheet is shown in Figure 4. Headers are defined in row 1 and a description of the header
is defined in row 2. Rows 3 – 5 represent the different species.

Figure 4. Section of the ‘refs’ sheet in the Supplementary Information showing how ab-initio properties can be
imported to pMuTT via Excel.

3.9.2 JavaScript object notation (JSON)

JSON is a data format that is easily readable by both humans and machines. This f rmat allows
complex pMuTT objects to be written and read by expressing objects in simple data types such as
dictionaries and lists. We suggest using this format if users wish to save pMuTT objects for later use
or to share objects with other users. This format can also serve as a useful debugging tool as it
shows the values assigned to important attributes. An example of a H 2O molecule expressed as a
Shomate object expressed in JSON format is shown in Figure 5.

Figure 5. JSON representation of a Shomate object for a H2O molecule.

3.9.3 Ab-initio c des

As stated in the intr ducti n, a common starting point for multiscale modeling for catalysis and
materials science involves calculating quantum mechanical properties using ab-initio codes. ASE has
a wide range of connectivity with ab-initio software, so we leverage its functionality for pMuTT.
Additionally, we have some custom functions that are not natively supported by ASE for the VASP
and Gaussian software such as extracting vibrational frequencies.

3.9.4 Network generators

Several industrially relevant mechanisms, such as pyrolysis or biomass processing, involve many
reactions and species. These species and reactions can be generated using a reaction network
 Journal Pre-proof

generator. A common output format from these codes are text files containing the elementary steps
where two different delimiters separate the species and the reaction sides. Currently, pMuTT can read
RING [41] output but the function can easily work with other formats since the delimiters present can
be specified. An example of its use is shown in Listing 7.

3.9.5 Kinetic models

Calculating kinetic properties is often an important step after evaluating thermodynamic properties.
To transition between tools, pMuTT has functionality to write input files for MKM and KMC
software. Currently, we support Chemkin and Zacros with plans to support additional packages in the
future.

4 Application
Below, we demonstrate code using pMuTT version 1.2.10 to convert ab-initio data to MKM inputs.
We use Chemkin MKM software and the ammonia decomposition mechanism on a Ru(0001) catalyst
as an example. While most of the data are inputted via spreadsheet, a user can input data through
other methods (such as JSON files or initialization within the script) r create IO methods, through
pMuTT’s extensibility for any application needing data generated by pMuTT.

4.1 Read the catalytic site

Chemkin’s surf.inp file requires surface species to be associated with a catalytic site. This is handled
by the CatSite object.

Listing 1. Initializing the catalytic site using data from the spreadsheet.
1 from pmutt.io.excel import read_excel
2 from pmutt.chemkin import CatSite
3
4 excel_path = 'NH3_Input_Data.xlsx'
5
6 cat_site_data = read_excel(io=excel path, sheet_name='cat_sites')[0]
7 cat_site = CatSite(**cat_site_data)

Line 4 is the path to the spreadsheet (see supplementary document: NH3_Input_Data.xlsx)

containing the data for this system. Line 6 reads the cata ytic site data from the specified sheet.
Normally read_excel returns a list of dictionaries (corresponding to rows and columns
respectively). However, there is only one entry in this sheet, so we store that catalytic site’s data as a
dictionary by accessing the first index of the list (represented with [0]). The CatSite object can
easily be initialized from the dictionary usi g the keyword arguments syntax in Python (represented
with **) as shown in line 7.

4.2 Read references data

As discussed earlier, enthalpies predicted by DFT may not agree with more accurate techniques
referenced to the standard state. If sources with different thermodynamic references are mixed, the
differences can be acco nted for by initializing a References object to calculate the offset. Below,
we regress the offset to the elementary composition of the reference gases hydrogen, nitrogen, and
ammonia.
Listing 2. Initializing the references using data from the spreadsheet and calculating an elemental offset between
heat of formation calculated by DFT and experiments for gas-phase species.
1 from pmutt.empirical.references import Reference, References
2
3 references_data = read_excel(io=excel_path, sheet_name='refs')
4 refs_list = [Reference(**ref_data) for ref_data in references_data]
5 refs = References(references=refs_list)
6 print(refs.offset)
 Journal Pre-proof

Similar to Listing 1, line 3 reads the references data from the spreadsheet. Line 4 initializes
Reference objects corresponding to each row in the spreadsheet using the keyword argument
syntax. Line 5 initializes a References object, which will calculate the offset corresponding to
each element. The result of line 6 shown below is the offset assigned to H and N that will be applied
to the DFT-derived species.
{'H': -129.34222830159834, 'N': -320.10077207763885}

4.3 Create NASA polynomials

The catalytic site data and the references from the previous sections can be combined with the
ab-initio data to generate NASA polynomials.
Listing 3. Initializing NASA polynomials using ab-initio data, catalytic site data, and reference data stored in a
spreadsheet.
1 from pmutt.empirical.nasa import Nasa
2
3 all_ab_initio_data = read_excel(io=excel_path, sheet name='species')
4 nasa_species = []
5 for species_data in all_ab_initio_data:
6 species = Nasa.from_statmech(T_low=298., T high=800., references=refs,
7 **species_data)
8 if species.phase.lower() == 's':
9 species.cat_site = cat_site
10 species.n_sites = 1
11 nasa_species.append(species)
Similar to Listing 1 and Listing 2, line 3 shows the ab-initio data for all species being read from the
spreadsheet. Lines 5-11 iterate over the chemical sp ci s corr sponding to each row in the spreadsheet.
Lines 6-7 initialize a NASA polynomial using a statistical mechanical model, lower and upper
temperature limits, the References object initialized in Listing 2 and the spreadsheet data. Lines
8-10 assign the CatSite object initialized in Listing 1 to surface species. Finally, line 11 adds the
new NASA polynomial to the list of processed species.

4.4 Compare NASA polynomial to statistical mechanical model

While not required, validating the empirical model against the statistical mechanical model is
important to prevent propagation of error.
Listing 4. Comparing NASA polynomi l to st tistical mechanical model.
1 f1, axes1 = nasa species[0].plot_statmech_and_empirical (Cp_units='cal/mol/K',
2 H_units='kcal/mol',
3 S_units='cal/mol/K',
4 G_units='kcal/mol')
5 for plot_ax in axes1:
6 statmech line = plot ax.lines[1]
7 statmech line.set marker('o')
8 statmech line.set fillstyle('none')
9 statmech line.set linestyle(' ')

Lines 1-4 generates the pl t to compare all available quantities (i.e., heat capacity, enthalpy, entropy,
and Gibbs free energy) between the upper and lower temperatures in the appropriate units for N 2.
Lines 5-9 show the plot can be modified using standard matplotlib commands to enable further
customization. In this case, we choose to plot the statistical mechanical points as hollow circles for
easier comparison. The result is shown in Figure 6.
 Journal Pre-proof

Figure 6. Comparison between NASA polynomial and statistical mechanical m del therm dynamic properties as
a function of temperature [K] for gas-phase N2.

4.5 Create reactions

Here, we initialize the reactions to write to the Chemkin input files.
Listing 5. Initializing ChemkinReaction objects using the NASA polynomials and data from the spreadsheet.
1 from pmutt import pmutt_list_to_dict
2 from pmutt.reaction import ChemkinReaction, Reactions
3
4 nasa_species_dict = pmutt_list_to_dict(nasa_species)
5 reactions_data = read_excel(io=excel path, sheet name='reactions')
6 reactions_list = []
7 for reaction_data in reactions_data:
8 reaction = ChemkinReaction.from string(species=nasa_species_dict,
9 **reaction_data)
10 reactions_list.append(reaction)
11 reactions = Reactions(reactions=reactions_list)

Line 4 converts the list of NASA polynomials generated in Listing 3 to a dictionary to facilitate
efficient searching for reaction initialization. Line 5 shows another example of reading data from
the spreadsheet, which highlights the flexibility of the read_excel function. Lines 6-10 show
initialization of each reaction using simi ar syntax as Listing 3. Line 11 takes the individual
Reaction objects and groups them into a Reactions object for further processing.

4.6 Write files

In this section, we write three Chemkin i put files (thermdat, gas.inp and surf.inp) using the
previously defined NASA poly omials a d reactions. The files written can be found in
Supplementary Listings 2-4.
Listing 6. Writing Chemkin input files using previously defined NASA polynomials and reactions
1 from pmutt.io.chemkin import write_gas, write_surf
2 from pmutt.io.thermdat import write_thermdat
3
4 write_thermdat(filename='thermdat', nasa_species=species)
5 write_gas(filename='gas.inp', nasa_species=species,
6 reactions=reactions, act_method_name='get_GoRT_act')
7 write_surf(filename='surf.inp', reactions=reactions,
8 act method name='get_GoRT_act')

Line 4 shows how to write a thermdat file. Lines 5-6 write the gas.inp file. Similarly, lines 7-8 write the
surf.inp file. Note that pMuTT detects if the reaction belongs in gas.inp or surf.inp using the phase of the
reactants and products. Also, in this example we lump enthalpic and entropic contributions to the
activation energy column using the method get_GoRT_act whereas get_HoRT_act would
 Journal Pre-proof

include the entropic contribution in the pre-exponential column. This bookkeeping would not
affect the Chemkin output.

4.7 Plot coordinate diagram

There are also visualization tools offered by pMuTT. Below, we show the code to generate reaction
coordinate diagrams, like Figure 3.
Listing 7. Generating reaction coordinate diagrams using the previously generated NASA polynomials and
reaction written in text format.
1 from matplotlib import pyplot as plt
2 from pmutt.io.ring import read_reactions
3
4 diagram_reactions_path = 'coordinate_diagram_rxns.txt'
5 diagram_reactions = read_reactions(filename=diagram reacti ns_path,
6 species_delimiter='+',
7 reaction_delimiter='=',
8 species=nasa species dict)
9
10 f2, ax2 = diagram_reactions.plot_coordinate_diag am(method_name='get_G',
11 units='eV', T=298.)
12 f2, ax2 = diagram_reactions.plot_coordinate_diagram(method_name='get_H',
13 units='eV', T=298.,
14 figure=f2, axes=ax2)
15
16 ax.legend(['Enthalpy (H)', 'Gibbs Energy (G)'])
17 ax.set_ylabel('Energy (eV)')
18
19 plt.show()

In Line 4, we define the location of the reactions fo matted for reaction coordinate diagrams. Lines 5-
8 read the reactions from a text file. In this file, species are separated using ‘+’ and the reaction sides
are separated using ‘=’. This function also requires the species objects corresponding to each text
label so we use nasa_species_dict defined in Listing 5. Currently, reactions must be written in
a way to conserve atoms throughout the mechanism, which may require several spectator species to
be present to ensure correct results. A future release will allow the user to generate the same diagram
without the presence of spectator species in e ementary reactions. Lines 10-11 plot the reaction
coordinate diagram using Gibbs free energy in eV at 298 K. Similarly, Lines 12-14 plot the reaction
coordinate diagram using enthalpy in eV t 298 K but supplying a figure and axes superimposes the
plots on top of each other. Lines 16-17, like Listing 4, show the matplotlib commands for further
customization. Finally, line 19 displays the plot where it can be rescaled and saved.

5 Conclusions
Thermochemistry and rate constants are ubiquitous in material science and catalysis. The pMuTT
library provides a rob st and streamlined approach to estimating thermochemical and kinetic
properties for heterogeneo s catalysis. Written in Python, it is straightforward to learn, write scripts,
and expand the code for the desired application. Numerous interfaces with other software extend
the accessibility and usefulness f the library. The objective is to increase transparency for
thermochemical analysis by making the code and documentation freely available.

pMuTT will continue to growth in capability and utility. Additional statistical mechanical models and
mixing models (such as the non-random two-liquid model NRTL) expands the variety of materials
that can be modelled. Building interfaces with more software, especially ab-initio, kinetic modeling,
and mechanism generator software, give users the flexibility and freedom to input and output data in
the desired format. Richer functionality related to predicting stable structures, such as Pourbaix
diagrams or composition-based phase diagrams at finite temperatures, are also being considered.
 Journal Pre-proof

Acknowledgements
The authors acknowledge support from the Department of Energy's Office of Energy Efficient and
Renewable Energy's Advanced Manufacturing Office under Award Number DE-EE0007888-9.5. The
authors thank Sunita Chandrasekaran and Jeffrey Frey for insightful discussions.

Appendix A. Program Details

Appendix A.1. Documentation
pMuTT is a free software with the MIT license. Instructions on how to install pMuTT and its source
code can be found on the Vlachos group’s GitHub page (https://github.com/VlachosGroup/pMuTT)
and the most up-to-date documentation and examples can be found on the pMuTT webpage
(https://vlachosgroup.github.io/pMuTT). We invite interested users to participate in development.
Discussion of enhancements, bugs, and help can be found on the GitHub Issues page
(https://github.com/VlachosGroup/pMuTT/issues).

References
[1] A. Hjorth Larsen, J. Jørgen Mortensen, J. Blomqvist, I.E. Castelli, R. Christensen, M. Dułak, J.
Friis, M.N. Groves, B. Hammer, C. Hargus, E.D. Hermes, P.C. Jennings, P. Bjerre Jensen, J.
Kermode, J.R. Kitchin, E. Leonhard Kolsbjerg, J. Kubal, K. Kaasbjerg, S. Lysgaard, J.
Bergmann Maronsson, T. Maxson, T. Olsen, L. Pastewka, A. Peterson, C. Rostgaard, J.
Schiøtz, O. Schütt, M. Strange, K.S. Thyges n, T. V gge, L. Vilhelmsen, M. Walter, Z. Zeng,
K.W. Jacobsen, J. Phys. Condens. Matter 29 (2017) 273002.
[2] S.P. Ong, W.D. Richards, A. Jain, G. Hautie , M. Kocher, S. Cholia, D. Gunter, V.L. Chevrier,
K.A. Persson, G. Ceder, Comput. Mater. Sci. 68 (2013) 314–319.
[3] C.W. Gao, J.W. Allen, W.H. Green, R.H. West, Comput. Phys. Commun. 203 (2016) 212–
225.
[4] J.-O. Andersson, T. Helander, L. Höglund, P. Shi, B. Sundman, Calphad 26 (2002) 273–312.
[5] S.-L. Chen, S. Daniel, F. Zhang, Y.A. Chang, X.-Y. Yan, F.-Y. Xie, R. Fetzer-Schmid, W.A.
Oates, Calphad 26 (2002) 175–188.
[6] E. Kozeschnik, B. Buchm yr, M th. Model. Weld Phenom. 5 (2001) 349–361.
[7] S. Van Der Walt, S.C. Colbert, G. Varoquaux, Comput. Sci. Eng. 13 (2011) 22–30.
[8] W. McKinney, in: Proc. 9th Python Sci. Conf., 2010, pp. 51–56.
[9] E. Jones, T. Oliphant, P. Pete son, (2001).
[10] T.E. Oliphant, Comp t. Sci. Eng. (2007) 10–20.
[11] K.J. Millman, M. Aivazis, Comput. Sci. Eng. 13 (2011) 9–12.
[12] J.D. Hunter, C mput. Sci. Eng. 9 (2007) 99–104.
[13] S.I. Sandler, An Introduction to Applied Statistical Thermodynamics, John Wiley & Sons,
2010.
[14] K. Laidler, M. King, J. Phys Chem 87 (1983) 2657–2664.
[15] I. Chorkendorff, J.W. Niemantsverdriet, in: Concepts Mod. Catal. Kinet., John Wiley & Sons,
Ltd, 2005, pp. 79–128.
[16] J.E. Sutton, D.G. Vlachos, ACS Catal. 2 (2012) 1624–1634.
 Journal Pre-proof

[17] A. Vojvodic, A.J. Medford, F. Studt, F. Abild-Pedersen, T.S. Khan, T. Bligaard, J.K. Nørskov,
Chem. Phys. Lett. 598 (2014) 108–112.
[18] W. Guo, D.G. Vlachos, Nat. Commun. 6 (2015) 8619.
[19] F. Abild-Pedersen, J. Greeley, F. Studt, J. Rossmeisl, T.R. Munter, P.G. Moses, E. Skúlason,
T. Bligaard, J.K. Nørskov, Phys. Rev. Lett. 99 (2007) 4–7.
[20] F. Calle-Vallejo, D. Loffreda, M.T.M. Koper, P. Sautet, Nat. Chem. 7 (2015) 403–10.
[21] E.M. Fernndez, P.G. Moses, A. Toftelund, H.A. Hansen, J.I. Martínez, F. Abild-Pedersen, J.
Kleis, B. Hinnemann, J. Rossmeisl, T. Bligaard, J.K. Nørskov, Angew. Chemie - Int. Ed. 47
(2008) 4683–4686.
[22] J.X. Liu, Y. Su, I.A.W. Filot, E.J.M. Hensen, J. Am. Chem. Soc. 140 (2018) 4580–4587.
[23] M. Fields, C. Tsai, L.D. Chen, F. Abild-Pedersen, J.K. Nørskov, K. Chan, ACS Catal. 7 (2017)
2528–2534.
[24] R. Michalsky, Y.J. Zhang, A.A. Peterson, ACS Catal. 4 (2014) 1274–1278.
[25] G. Jones, T. Bligaard, F. Abild-Pedersen, J.K. Nørskov, J. Phys. Condens. Matter 20 (2008).
[26] C.H. Shomate, J. Phys. Chem. 58 (1954) 368–372.
[27] A.B. Mhadeshwar, H. Wang, D.G. Vlachos, J. Phys. Chem. B 107 (2003) 12721–12733.
[28] A. Nicolaides, A. Rauk, M.N. Glukhovtsev, L. Radom, J. Phys. Chem. 100 (1996) 17460–
17464.
[29] C.D. Wijaya, R. Sumathi, W.H. Green, J. Phys. Chem. A 107 (2003) 4908–4920.
[30] S. Wang, V. Vorotnikov, D.G. Vlachos, ACS Catal. 5 (2015) 104–112.
[31] Z. Ulissi, V. Prasad, D.G. Vlachos, J. Catal. 281 (2011) 339–344.
[32] L.C. Grabow, B. Hvolbæk, J.K. Nørskov, Top. Catal. 53 (2010) 298–310.
[33] Y. Li, J. Gomes, S.M. Sharada, A.T. Be , M. Head-gordon, (2015).
[34] S. Grimme, Chem. - A Eur. J. 18 (2012) 9955–9964.
[35] S. Kozuch, S. Shaik, Acc. Chem. Res. 44 (2011) 101–110.
[36] S.J. Mole, X. Zhou, R. Liu, J. Phys. Chem. 100 (1996) 14665–14671.
[37] R.B. Getman, W.F. Sch eider, ChemCatChem 2 (2010) 1450–1460.
[38] A.B. Mhadeshwa , D.G. Vlachos, J. Phys. Chem. B 108 (2004) 15246–15258.
[39] J.R. Kitchin, Phys. Rev. B - Condens. Matter Mater. Phys. 79 (2009) 1–6.
[40] M. Salciccioli, Y. Chen, D.G. Vlachos, Ind. Eng. Chem. Res. 50 (2011) 28–40.
[41] S. Rangarajan, A. Bhan, P. Daoutidis, Comput. Chem. Eng. 45 (2012) 114–123.