Metadata-Version: 2.4
Name: care-crn
Version: 0.0.0
Summary: Chemical Reaction Network generator for heterogenous catalysis
Author-email: Santiago Morandi <santiagomorandi@yahoo.it>, Oliver Loveday <oliverlovros@gmail.com>, Pol Sanz Berman <psanz@iciq.es>
Maintainer-email: Santiago Morandi <santiagomorandi@yahoo.it>, Oliver Loveday <oliverlovros@gmail.com>, Pol Sanz Berman <psanz@iciq.es>
License: MIT License
        
        Copyright (c) 2024 LopezGroup-ICIQ
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/LopezGroup-ICIQ/care
Project-URL: Bugtracker, https://github.com/LopezGroup-ICIQ/care/issues
Keywords: heterogeneous catalysis,chemical reaction networks,kinetics,machine learning
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.12
Requires-Python: ==3.12.*
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: acat==1.6.8
Requires-Dist: ase==3.24.0
Requires-Dist: matplotlib==3.8.0
Requires-Dist: networkx==3.2
Requires-Dist: numpy==1.26.4
Requires-Dist: pandas==2.2.0
Requires-Dist: prettytable==3.9.0
Requires-Dist: pydot==2.0.0
Requires-Dist: mp-api==0.45.3
Requires-Dist: pymatgen
Requires-Dist: torch==2.4.0
Requires-Dist: torch_geometric==2.5.3
Requires-Dist: rdkit==2023.9.6
Requires-Dist: scikit_learn==1.5.1
Requires-Dist: scipy==1.15.1
Requires-Dist: numba
Requires-Dist: energydiagram
Requires-Dist: rich
Requires-Dist: py-cpuinfo
Requires-Dist: psutil
Requires-Dist: dask[complete]==2025.3.0
Requires-Dist: juliacall==0.9.27
Requires-Dist: openpyxl==3.1.5
Provides-Extra: ocp
Requires-Dist: fairchem-core==1.4.0; extra == "ocp"
Provides-Extra: mace
Requires-Dist: mace-torch==0.3.12; extra == "mace"
Requires-Dist: torch-dftd==0.5.1; extra == "mace"
Provides-Extra: petmad
Requires-Dist: pet_mad==1.4.3; extra == "petmad"
Provides-Extra: orb
Requires-Dist: orb-models==0.4.2; extra == "orb"
Requires-Dist: pynanoflann==0.10.0; extra == "orb"
Provides-Extra: sevennet
Requires-Dist: sevenn==0.11.2; extra == "sevennet"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: codecov; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Dynamic: license-file

[![PyPI version](https://img.shields.io/pypi/v/care-crn.svg)](https://pypi.org/project/care-crn/)
[![DOI](https://img.shields.io/badge/DOI-10.26434%2Fchemrxiv--2024--bfv3d-blue)](https://doi.org/10.26434/chemrxiv-2024-bfv3d)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
![Python 3.11](https://img.shields.io/badge/python-3.12-blue.svg)
[![Python package](https://github.com/LopezGroup-ICIQ/care/actions/workflows/python-package.yml/badge.svg)](https://github.com/LopezGroup-ICIQ/care/actions/workflows/python-package.yml)
[![codecov](https://codecov.io/gh/LopezGroup-ICIQ/care/graph/badge.svg)](https://codecov.io/gh/LopezGroup-ICIQ/care)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/care-crn?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/care-crn)
[![Powered by RDKit](https://img.shields.io/badge/Powered%20by-RDKit-3838ff.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQBAMAAADt3eJSAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAAFVBMVEXc3NwUFP8UPP9kZP+MjP+0tP////9ZXZotAAAAAXRSTlMAQObYZgAAAAFiS0dEBmFmuH0AAAAHdElNRQfmAwsPGi+MyC9RAAAAQElEQVQI12NgQABGQUEBMENISUkRLKBsbGwEEhIyBgJFsICLC0iIUdnExcUZwnANQWfApKCK4doRBsKtQFgKAQC5Ww1JEHSEkAAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyMi0wMy0xMVQxNToyNjo0NyswMDowMDzr2J4AAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjItMDMtMTFUMTU6MjY6NDcrMDA6MDBNtmAiAAAAAElFTkSuQmCC)](https://www.rdkit.org/)

# CARE: Catalysis Automated Reaction Evaluator

<div style="display: flex; justify-content: center; align-items: center;">
    <p align="center">
     <img src="https://raw.githubusercontent.com/LopezGroup-ICIQ/care/main/care_readme_figure.png" width="80%" height="80%" />
    </p>
</div>

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](https://github.com/LopezGroup-ICIQ/gamenet_uq), [FairChem-v1](https://github.com/FAIR-Chem/fairchem), [MACE](https://github.com/ACEsuit/mace) potentials, *etc*.) and includes kinetic functionalities enabling the quantification of catalytic activity for reactions containing thousands of elementary steps.

## 🪛 Installation

### 1\. From PyPI

```bash
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](https://github.com/FAIR-Chem/fairchem) potentials:**
    Install `torch_sparse` and `torch_scatter` by following the instructions in the [PyTorch Geometric](https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html) page. Then:

    ```bash
    pip install care-crn[ocp]
    ```

2.  **For other evaluators:**
    You can install [MACE](https://github.com/ACEsuit/mace), [PET-MAD](https://github.com/lab-cosmo/pet-mad), [Orb](https://github.com/orbital-materials/orb-models), and [SevenNet](https://github.com/MDIL-SNU/SevenNet) by running:

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

    Or all at once:

    ```bash
    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](https://github.com/ACEsuit/mace/issues/555)). 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](https://julialang.org/), install it and the required packages:

```bash
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)

<!-- end list -->

1.  **Clone the repo:**

    ```bash
    git clone git@github.com:LopezGroup-ICIQ/care.git
    cd care
    ```

2.  **Create a conda environment:**

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

3.  **Install the package in "editable" mode:**

    ```bash
    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:**

    ```bash
    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.

```bash
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
```

<div style="display: flex; justify-content: center; align-items: center;">
    <p align="center">
     <img src="https://raw.githubusercontent.com/LopezGroup-ICIQ/care/main/care_bp_screenshot.png" width="70%" height="70%" />
    </p>
</div>

CRNs in CARE are stored as compressed .json files.

```python
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.

```bash
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](./src/care/scripts/input_examples/eval_crn/). 

For macOS we noticed a lower performance in the CRN generation due to Python multiprocessing (see *Contexts and start methods* in the [documentation](https://docs.python.org/3/library/multiprocessing.html))


### Microkinetic simulation

```bash
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:

```bash
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](./src/care/scripts/input_examples/care_script/).

## 📖 Tutorials

We currently provide two tutorials, available in the ``notebooks`` directory:
- [CARE tutorial](./notebooks/care_demo.ipynb) <br/>
- [Adsorbate placement](./notebooks/adsorbate_placement.ipynb).

## ✒️ License

The code is released under the [MIT](./LICENSE) 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](https://doi.org/10.26434/chemrxiv-2024-bfv3d)
