care-crn 0.5.2

Chemical Reaction Network generator for heterogenous catalysis

CARE: Catalysis Automated Reaction Evaluator

CARE (Catalytic Automated Reaction Evaluator) is a framework for the automated generation and manipulation of chemical reaction networks (CRNs) in heterogeneous catalysis. CARE is powered by ML-based energy evaluators (GAME-Net-UQ, FairChem-v1, MACE potentials, etc.) and includes kinetic functionalities enabling the quantification of catalytic activity for reactions containing thousands of elementary steps.

🪛 Installation

1. From PyPI

pip install care-crn

2. Install External Evaluators & Runtimes

care-crn interfaces with several external ML Interatomic Potentials (MLIPs). These must be installed separately.

MLIP Evaluators

1. For FAIRChem-v1 potentials: Install torch_sparse and torch_scatter by following the instructions in the PyTorch Geometric page. Then:

   pip install care-crn[ocp]
   

2. For other evaluators: You can install MACE, PET-MAD, Orb, and SevenNet by running:

   pip install care-crn[mace]
   pip install care-crn[petmad]
   pip install care-crn[orb]
   pip install care-crn[sevennet]
   

   Or all at once:

   pip install care-crn[ocp,mace,petmad,orb,sevennet]
   

   NOTE: There is currently a dependency clash during installation of OCP and MACE evaluators related to the e3nn library (see: this issue for MACE). Installation might result in an incompatibility warning, but both evaluators should work correctly if the installation order shown above is followed.

Julia (Microkinetic modeling)

To run microkinetic simulations with Julia, install it and the required packages:

curl -fsSL https://install.julialang.org | sh -s -- --yes && ~/.juliaup/bin/juliaup add 1.11
julia -e 'import Pkg; Pkg.add("DifferentialEquations"); Pkg.add("LinearSolve");'

⏲ Julia setup time estimate: ~13min (Ubuntu), ~9min (macOS)

---

3. Developer Installation

If you want to contribute to the code or use the very latest (unstable) version, you can install from the source.

• ⏲ Total installation time estimates: ~18min (Ubuntu), ~11min (macOS).
• 💾 Required disk space: ~6.5 GB (Conda environment), ~4.3 GB (Julia+dependencies)

1. Clone the repo:

   git clone [e-mail]:LopezGroup-ICIQ/care.git
   cd care
   

2. Create a conda environment:

   conda create -n care_env python==3.12
   conda activate care_env
   

3. Install the package in "editable" mode:

   python3 -m pip install -e .
   

   NOTE: macOS users might need to launch a new shell at this point in order for the entry points to work correctly.

4. Install optional dependencies:

   python3 -m pip install -e .[ocp]
   python3 -m pip install -e .[mace]
   # etc.
   

💥 Usage

Blueprint generation

The blueprint can be constructed in two ways, by providing (i) the network carbon and oxygen cutoffs ncc and noc, or (ii) the chemical space as list of SMILES.

gen_crn_blueprint -h  # documentation
gen_crn_blueprint -ncc 2 -noc 1 -o output_name  # Example from ncc and noc
gen_crn_blueprint -cs "CCO" "C(CO)O" -o output_name # Example from user-defined chemical space

CRNs in CARE are stored as compressed .json files.

from care.io import load_network

crn = load_network("blueprint.json.gz")

Evaluation of intermediate and reaction properties

The range of catalyst materials on which CRNs can be evaluated depends on the domain of the data-driven energy evaluator employed. Currently, CARE provides interfaces to GAME-Net-UQ, FairChem-v1 potentials, MACE, Orb, PET-MAD, and SevenNet.

eval_crn -h  # documentation
eval_crn [-i INPUT] [-bp BP] [-o OUTPUT] [-ncpu NUM_CPU]

This script requires an input toml file defining the material/surface of interest, the model of choice and its settings. The output is a ReactionNetwork object stored as pickle file. You can find examples of input files here.

For macOS we noticed a lower performance in the CRN generation due to Python multiprocessing (see Contexts and start methods in the documentation)

Microkinetic simulation

run_kinetic [-i INPUT] [-crn CRN] [-o OUTPUT]

This script runs microkinetic simulation starting from the evaluated reaction network and an input toml file defining the reaction conditions, solver, inlet conditions. The results are stored as a pickle object file.

Run all together

You can run the entire pipeline (blueprint generation ➡ energy evaluation ➡ kinetic simulation) running the care_run script:

care_run -h  # documentation
care_run -i input.toml -o output_name

This will generate a output_name folder with the generated reaction network and additional results from the kinetic simulation. Examples of input .toml files can be found here.

📖 Tutorials

We currently provide two tutorials, available in the notebooks directory:

• CARE tutorial
  
• Adsorbate placement.

✒️ License

The code is released under the MIT license.

📜 Reference

• A Foundational Model for Reaction Networks on Metal Surfaces Authors: S. Morandi, O. Loveday, T. Renningholtz, S. Pablo-García, R. A. Vargas Hernáńdez, R. R. Seemakurthi, P. Sanz Berman, R. García-Muelas, A. Aspuru-Guzik, and N. López DOI: 10.26434/chemrxiv-2024-bfv3d