CARE (Catalysis Automated Reaction Evaluator) is a tool for generating and manipulating chemical reaction networks (CRNs) on catalytic surfaces. CARE is powered by data-driven models such as GAME-Net-UQ, Open Catalyst models, MACE, etc.
Installing CARE requires Conda and Git locally installed. The following instructions are optimized to install CARE on Linux and macOS machines. Installation time estimates are provided for each step on an Ubuntu 24.04.01 (x86_64, 16 GB RAM, internet speed 170 Mbps) and macOS 15.3.1 (arm64, 8 GB RAM, Internet speed 40 Mbps).
⏲ Total installation time estimates: ~18min (Ubuntu), ~11min (macOS).
💾 Required disk space: ~6.5 GB (Conda environment), ~4.3 GB (Julia+dependencies)
- Clone the repo:
git clone git@github.com:LopezGroup-ICIQ/care.git⏲ 4s (Ubuntu), 26s (macOS)
- Create a conda environment with Python 3.12 and activate it:
conda create -n care_env python==3.12
conda activate care_env⏲ 8s (Ubuntu), 9s (macOS)
- Enter the repo and install the package with pip:
cd care
python3 -m pip install .⏲ 4min20s (Ubuntu), 1min50s (macOS)
NOTE: macOS users might need to launch a new shell at this point in order for the entry points to work correctly.
- (optional) To interface to energy evaluators from Open Catalyst Project, first install
torch_sparseandtorch_scatterfollowing the instructions in the PyTorch Geometric page depending on your device settings. Then, just run:
python3 -m pip install .[ocp]⏲ 17s (Ubuntu), 19s (macOS)
python3 -m pip install .[mace]
python3 -m pip install .[petmad]
python3 -m pip install .[orb]
python3 -m pip install .[sevennet]⏲ 20s (Ubuntu), 8s (macOS)
NOTE: There currently is 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.
- (optional) Install Julia and the ODE packages required to perform kinetic simulations. As alternative, simulations can run with the implemented SciPy solver.
curl -fsSL https://install.julialang.org | sh
python3 -m pip install juliacall # Python-Julia bridge
julia -e 'import Pkg; Pkg.add("DifferentialEquations"); Pkg.add("DiffEqGPU"); Pkg.add("CUDA");'⏲ 13min (Ubuntu), 9min (macOS)
NOTE: For some systems Julia may present some error while using sh. If that is the case, please install Julia by running instead:
curl -fsSL https://install.julialang.org | sh -s -- -yThe 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
The CRN blueprint is stored as pickle file. To access the blueprint, do:
from pickle import load
with open('path_to_blueprint_file', 'rb') as f:
intermediates, reactions = load(f)The range of catalyst materials on which CRNs can be constructed depends on the domain of the data-driven energy evaluator employed to derive the reaction properties. Currently, CARE provides interfaces to GAME-Net-UQ, OCP models, and MACE-MP potentials.
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)
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.
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_nameThis will generate a directory output_name containing a crn.pkl with the generated reaction network.
Examples of input .toml files can be found here.
We currently provide three tutorials, available in the notebooks directory:
The code is released under the MIT license.
- 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