micki 2.0.0__tar.gz

micki-2.0.0/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

micki-2.0.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: micki
+Version: 2.0.0
+Summary: A modular, extensible, object-oriented microkinetic modeling package
+Author: Eric D. Hermes, Aurora N. Janes, J.R. Schmidt
+License-Expression: LGPL-3.0-only
+Project-URL: Repository, https://github.com/jrschmidt2/micki
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ase
+Requires-Dist: numpy>=2.0
+Requires-Dist: sundials4py<8,>=7.9
+Requires-Dist: sympy
+Dynamic: license-file
+
+### micki
+
+A modular, extensible, robust object-oriented microkinetic modeling package
+written in Python.
+
+### DEPENDENCIES (installed automatically, see below):
+ * Python >= 3.12
+ * sundials4py (the official SUNDIALS Python interface; >= 7.9, beta)
+ * numpy >= 2.0
+ * sympy
+ * ase
+
+No compiler, SUNDIALS build or LAPACK library is needed: sundials4py ships
+prebuilt wheels that include SUNDIALS.
+
+Earlier versions that generate Fortran and compile it with f2py are kept on
+branches: `fortran-sundials7` (SUNDIALS 7 Fortran 2003 interface) and
+`sundials4` (SUNDIALS 4.X FCMIX interface).
+
+### Installation with conda (recommended):
+#fetch Micki and create a conda environment with all dependencies<br>
+git clone https://github.com/jrschmidt2/micki.git<br>
+cd micki<br>
+conda env create -f environment.yml<br>
+conda activate micki<br>
+
+Python, numpy, sympy and ase come from conda-forge. sundials4py and Micki
+itself are not on conda-forge, so `environment.yml` installs them with pip
+inside the environment (Micki in editable mode, so changes in the clone take
+effect immediately).
+
+### Installation with pip:
+#in an environment with Python >= 3.12<br>
+pip install micki<br>
+
+### Testing:
+Run the test suite (about 15 seconds; includes a water-gas shift regression test) from the repository root:<br>
+python -m unittest discover -s tests -v
+
+### Releasing:
+Releases are published to PyPI automatically by GitHub Actions
+(`.github/workflows/publish.yml`, PyPI trusted publishing):
+
+1. Set the new version in `pyproject.toml` and commit it.
+2. Create a GitHub release with tag `v<version>` (e.g. `v2.0.0`).
+
+Publishing the release runs the tests, builds the package and uploads it to
+PyPI. The workflow refuses to publish if the tag does not match the version.

micki-2.0.0/README.md

@@ -0,0 +1,48 @@
+### micki
+
+A modular, extensible, robust object-oriented microkinetic modeling package
+written in Python.
+
+### DEPENDENCIES (installed automatically, see below):
+ * Python >= 3.12
+ * sundials4py (the official SUNDIALS Python interface; >= 7.9, beta)
+ * numpy >= 2.0
+ * sympy
+ * ase
+
+No compiler, SUNDIALS build or LAPACK library is needed: sundials4py ships
+prebuilt wheels that include SUNDIALS.
+
+Earlier versions that generate Fortran and compile it with f2py are kept on
+branches: `fortran-sundials7` (SUNDIALS 7 Fortran 2003 interface) and
+`sundials4` (SUNDIALS 4.X FCMIX interface).
+
+### Installation with conda (recommended):
+#fetch Micki and create a conda environment with all dependencies<br>
+git clone https://github.com/jrschmidt2/micki.git<br>
+cd micki<br>
+conda env create -f environment.yml<br>
+conda activate micki<br>
+
+Python, numpy, sympy and ase come from conda-forge. sundials4py and Micki
+itself are not on conda-forge, so `environment.yml` installs them with pip
+inside the environment (Micki in editable mode, so changes in the clone take
+effect immediately).
+
+### Installation with pip:
+#in an environment with Python >= 3.12<br>
+pip install micki<br>
+
+### Testing:
+Run the test suite (about 15 seconds; includes a water-gas shift regression test) from the repository root:<br>
+python -m unittest discover -s tests -v
+
+### Releasing:
+Releases are published to PyPI automatically by GitHub Actions
+(`.github/workflows/publish.yml`, PyPI trusted publishing):
+
+1. Set the new version in `pyproject.toml` and commit it.
+2. Create a GitHub release with tag `v<version>` (e.g. `v2.0.0`).
+
+Publishing the release runs the tests, builds the package and uploads it to
+PyPI. The workflow refuses to publish if the tag does not match the version.

micki-2.0.0/micki/__init__.py

@@ -0,0 +1,8 @@
+from micki.reactants import Liquid, Gas, Adsorbate, Electron
+from micki.model import Reaction, Model
+from micki.eref import EnergyReference
+from micki.analysis import ModelAnalysis
+from micki.lattice import Lattice
+
+__all__ = ['Liquid', 'Gas', 'Adsorbate', 'Electron', 'Reaction', 'Model',
+           'EnergyReference', 'ModelAnalysis', 'Lattice']

micki-2.0.0/micki/analysis.py

@@ -0,0 +1,287 @@
+"""Module for doing sensitivity analysis of microkinetic model"""
+
+import collections.abc
+
+import numpy as np
+import sympy as sym
+
+from ase.units import kB
+
+from micki.reactants import Adsorbate, _Fluid
+
+
+class ModelAnalysis:
+    def __init__(self, model, product_reaction, Uequil, tol=1e-3, dt=3600):
+        self.model = model
+        self.reaction_name = product_reaction
+        self.product_reaction = model.reactions[product_reaction]
+        self.Uequil = Uequil
+        self.tol = tol
+        self.dt = dt
+
+        self.model.set_initial_conditions(self.Uequil)
+
+        t, self.U, self.r = self.model.find_steady_state()
+        model.finalize()
+
+        self.species_symbols = []
+        for species in self.model._species:
+            if species.symbol is not None:
+                self.species_symbols.append(species)
+        self.rmid = self.r[self.reaction_name]
+
+    def campbell_rate_control(self, rxn_name, scale=0.001):
+        reaction = self.model.reactions[rxn_name]
+
+        subs = {}
+        for species in self.species_symbols:
+            subs[species.symbol] = self.U[species.label]
+
+        kmid = reaction.get_kfor(self.model.T,
+                                 self.model.Asite,
+                                 self.model.z)
+
+        if isinstance(kmid, sym.Basic):
+            kmid = kmid.subs(subs)
+
+        reaction.set_scale('kfor', 1.0 - scale)
+        reaction.set_scale('krev', 1.0 - scale)
+        reaction.update(self.model.T,
+                        self.model.Asite,
+                        self.model.z,
+                        force=True)
+        klow = reaction.get_kfor()
+        model = self.model.copy()
+
+        try:
+            t1, U1, r1 = model.find_steady_state()
+        finally:
+            reaction.set_scale('kfor', 1.0)
+            reaction.set_scale('krev', 1.0)
+
+        model.finalize()
+        rlow = r1[self.reaction_name]
+        if isinstance(klow, sym.Basic):
+            subs = {}
+            for species in self.species_symbols:
+                subs[species.symbol] = U1[species.label]
+            klow = klow.subs(subs)
+
+        reaction.set_scale('kfor', 1.0 + scale)
+        reaction.set_scale('krev', 1.0 + scale)
+        reaction.update(self.model.T,
+                        self.model.Asite,
+                        self.model.z,
+                        force=True)
+        khigh = reaction.get_kfor()
+        model = self.model.copy()
+
+        try:
+            t2, U2, r2 = model.find_steady_state()
+        finally:
+            reaction.set_scale('kfor', 1.0)
+            reaction.set_scale('krev', 1.0)
+
+        model.finalize()
+        rhigh = r2[self.reaction_name]
+        if isinstance(khigh, sym.Basic):
+            subs = {}
+            for species in self.species_symbols:
+                subs[species.symbol] = U2[species.label]
+            khigh = khigh.subs(subs)
+        reaction.set_scale('kfor', 1.0)
+        reaction.set_scale('krev', 1.0)
+
+        return kmid * (rhigh - rlow) / (self.rmid * (khigh - klow))
+
+    def thermodynamic_rate_control(self, names, dg=None):
+        """Degree of thermodynamic rate control, -(kT/r) dr/dG.
+
+        The free energies of all species in `names` are shifted together
+        by -dg and +dg (default 0.001 kT) and the derivative is taken by
+        central differences.
+        """
+        T = self.model.T
+        if dg is None:
+            dg = 0.001 * kB * T
+
+        if not isinstance(names, (list, tuple)):
+            species = [self.model.species[names]]
+        else:
+            species = [self.model.species[name] for name in names]
+
+        for sp in species:
+            sp.dE -= dg
+
+        for reaction in self.model._reactions:
+            reaction.update(T=self.model.T,
+                            Asite=self.model.Asite,
+                            L=self.model.z,
+                            force=True)
+
+        model = self.model.copy(initialize=False)
+        model.set_initial_conditions(self.U)
+
+        try:
+            t1, U1, r1 = model.find_steady_state()
+        finally:
+            for sp in species:
+                sp.dE += dg
+
+        model.finalize()
+        rlow = r1[self.reaction_name]
+
+        for sp in species:
+            sp.dE += dg
+
+        for reaction in self.model._reactions:
+            reaction.update(T=self.model.T,
+                            Asite=self.model.Asite,
+                            L=self.model.z,
+                            force=True)
+
+        model = self.model.copy(initialize=False)
+        model.set_initial_conditions(self.U)
+
+        try:
+            t2, U2, r2 = model.find_steady_state()
+        finally:
+            for sp in species:
+                sp.dE -= dg
+
+        for reaction in self.model._reactions:
+            reaction.update(T=self.model.T,
+                            Asite=self.model.Asite,
+                            L=self.model.z,
+                            force=True)
+
+        model.finalize()
+        rhigh = r2[self.reaction_name]
+
+        # central difference: the two rates are 2 * dg apart in free energy
+        return (rlow - rhigh) * kB * T / (self.rmid * 2 * dg)
+
+    def activation_barrier(self, dT=0.01):
+        T = self.model.T
+
+        model = self.model.copy(initialize=False)
+        model.T = T - dT
+        model.set_initial_conditions(self.Uequil)
+        t1, U1, r1 = model.find_steady_state()
+        model.finalize()
+
+        rlow = r1[self.reaction_name]
+
+        model = self.model.copy(initialize=False)
+        model.T = T + dT
+        model.set_initial_conditions(self.Uequil)
+        t2, U2, r2 = model.find_steady_state()
+        model.finalize()
+
+        rhigh = r2[self.reaction_name]
+
+        return kB * T**2 * (rhigh - rlow) / (self.rmid * 2 * dT)
+
+    def rate_order(self, name, drho=0.05):
+        species = self.model.species[name]
+
+        rhomid = self.Uequil[species.label]
+        if not rhomid > 0:
+            raise ValueError('{} has no positive concentration'.format(name))
+
+        U0 = self.Uequil.copy()
+        rholow = rhomid * (1.0 - drho)
+        U0[species.label] = rholow
+        model = self.model.copy(initialize=False)
+        model.set_initial_conditions(U0)
+        t1, U1, r1 = model.find_steady_state()
+        model.finalize()
+        rlow = r1[self.reaction_name]
+
+        rhohigh = rhomid * (1.0 + drho)
+        U0[species.label] = rhohigh
+        model.set_initial_conditions(U0)
+        t2, U2, r2 = model.find_steady_state()
+        model.finalize()
+        rhigh = r2[self.reaction_name]
+
+        return (rhomid / self.rmid) * (rhigh - rlow) / (rhohigh - rholow)
+
+    def drate_order_dg(self, fluid, adsorbates, rho_scale=0.01, g_scale=0.01):
+        """(rho/r) d^2 r / (d rho dG): the change of the rate order in
+        `fluid` with the free energy of `adsorbates` (shifted together).
+
+        Central differences in the concentration of `fluid` (+-drho) and in
+        the free energies of `adsorbates` (+-dg).
+        """
+        if not isinstance(fluid, _Fluid):
+            raise TypeError('fluid must be a Gas or Liquid species')
+
+        if not isinstance(adsorbates, collections.abc.Iterable):
+            adsorbates = [adsorbates]
+
+        if not isinstance(adsorbates[0], Adsorbate):
+            raise TypeError('adsorbates must be Adsorbate species')
+
+        rhomid = self.U[fluid.label]
+        if not rhomid > 0:
+            raise ValueError('{} has no positive concentration'
+                             ''.format(fluid.label))
+        rmid = self.r[self.reaction_name]
+        gmid = adsorbates[0].get_G(self.model.T)
+        if isinstance(gmid, sym.Basic):
+            trans = {}
+            for species in self.model._species:
+                if isinstance(species, Adsorbate) \
+                        and species.symbol is not None:
+                    trans[species.symbol] = self.U[species.label]
+            gmid = gmid.subs(trans)
+        dg = np.abs(gmid * g_scale * 2)
+        drho = rhomid * rho_scale * 2
+
+        dr = 0
+
+        def set_dg(species, dg):
+            species.dE += dg
+
+        for i in [-1, 1]:
+            for adsorbate in adsorbates:
+                set_dg(adsorbate, i * dg)
+
+            for reaction in self.model._reactions:
+                reaction.update(T=self.model.T,
+                                Asite=self.model.Asite,
+                                L=self.model.z,
+                                force=True)
+
+            for j in [-1, 1]:
+                U0 = self.Uequil.copy()
+                U0[fluid.label] = rhomid + j * drho
+
+                model = self.model.copy(initialize=False)
+                model.set_initial_conditions(U0)
+
+                ti, Ui, ri = model.find_steady_state()
+                dr += i * j * ri[self.reaction_name]
+
+            for adsorbate in adsorbates:
+                set_dg(adsorbate, -i * dg)
+
+        for reaction in self.model._reactions:
+            reaction.update(T=self.model.T,
+                            Asite=self.model.Asite,
+                            L=self.model.z,
+                            force=True)
+
+        # the four rates are 2 * dg and 2 * drho apart
+        return (rhomid / rmid) * dr / (4 * dg * drho)
+
+    def check_converged(self, *vals):
+        for val in vals:
+            for i, key in enumerate(val[0]):
+                if np.abs(val[-1][key] - val[-2][key]) > self.tol:
+                    raise ValueError("Calculation not converged ({}: {}, "
+                                     "change {})! Increase dt or use better "
+                                     "initial guess.".format(
+                                         key, val[-1][key],
+                                         val[-1][key] - val[-2][key]))

micki-2.0.0/micki/db.py

@@ -0,0 +1,80 @@
+import warnings
+
+from ase.db import connect
+from ase.db.core import Database
+
+from micki.reactants import Adsorbate, Gas, Liquid
+from micki.eref import EnergyReference
+
+class MickiDBReadError(ValueError):
+    pass
+
+# Attempts to parse attribute 'name' from dictionary 'data' and raises a
+# parse error if it cannot be found.
+def get_data(row, param):
+    if param not in row.data:
+        raise MickiDBReadError("DB row named {} does not have '{}' entry!"
+                               "".format(row.name, param))
+    return row.data[param]
+
+# Converts a single ASE DB row to a Micki Thermo object.
+def row_to_thermo(row):
+    name = row.name
+    freqs = get_data(row, 'freqs')
+    thermo = get_data(row, 'thermo')
+    sites = get_data(row, 'sites')
+    rhoref = get_data(row, 'rhoref')
+    dE = get_data(row, 'dE')
+    symm = get_data(row, 'symm')
+    ts = get_data(row, 'ts')
+    spin = get_data(row, 'spin')
+    D = get_data(row, 'D')
+    S = get_data(row, 'S')
+
+    if thermo == 'Adsorbate':
+        return Adsorbate(row.toatoms(), name, freqs,
+                         ts=ts, sites=sites, dE=dE, symm=symm)
+    elif thermo == 'Gas':
+        return Gas(row.toatoms(), name, freqs,
+                   symm=symm, spin=spin, rhoref=rhoref, dE=dE)
+    elif thermo == 'Liquid':
+        return Liquid(row.toatoms(), name, freqs,
+                      symm=symm, spin=spin, D=D, S=S, rhoref=rhoref, dE=dE)
+    else:
+        raise ValueError('Unknown Thermo type {}!'.format(thermo))
+
+# Creates a dictionary of Thermo objects from a properly-formatted ASE DB file.
+def read_from_db(db, names=None, eref=None):
+    if isinstance(db, str):
+        db = connect(db)
+    elif not isinstance(db, Database):
+        raise ValueError("Must pass active ASE DB connection, "
+                         "or name of ASE DB file!")
+
+    species = {}
+
+    for row in db.select():
+        name = row.name
+        try:
+            species[name] = row_to_thermo(row)
+        except MickiDBReadError:
+            warnings.warn("Could not parse row {}, skipping.".format(name),
+                          RuntimeWarning, stacklevel=2)
+
+    for name, sp in species.items():
+        newsites = []
+        for site in sp.sites:
+            if site in species:
+                newsites.append(species[site])
+            else:
+                raise ValueError("Unknown site named {}!".format(site))
+        sp.sites = newsites
+
+    if eref is not None:
+        reference = EnergyReference([species[name] for name in eref])
+        for name, sp in species.items():
+            sp.eref = reference
+
+    if names is not None:
+        return {name: species[name] for name in names}
+    return species