Libra-ML-Modeling

Overview

This repository contains a collection of Python scripts, Jupyter notebooks, datasets, and XYZ files that were used to train the models for the paper "A 3D, Structure-Based, Deep Learning Approach for Predicting the Regioselectivity of Transition-Metal Catalysis" by Hadler et al.

Paper DOI:

Main Libra-ML Repository/Package: https://github.com/Hartwig-Group/Libra-ML

Zenodo Archive:

Note

This repository is intended for users who wish to reproduce the model training presented in the paper. If you just want to use the trained models to predict selectivity or generate catalyst geometries, please refer to the main Libra-ML repository!

Dataset

For those who wish to use the datasets provided in this repository for their own modeling or analysis, we recommend either splitting the data using a Leave-One-Catalyst-Out (LOCO) strategy based on ligand identity (ligand_1_cas) or using a 5 x 2 repeated grouped cross-validation approach (GroupKFold with shuffle), where the grouping is done by ligand identity (ligand_1_cas). This ensures that the model is evaluated on its ability to generalize to unseen catalysts. The experimental dataset acts as an extrapolative test set, collected in house to avoid patterns and biases present in the literature data. Optimized catalysts and their conformers can be found in the data/xyz/ directory.

• Unactivated Olefin Datasets (butene, hexene, etc): data/HF-Literature.tsv and data/HF-Experimental.tsv

• Activated Olefin Datasets (allyl cyanide and styrene): data/HF-Allyl-Cyanide.tsv and data/HF-Styrene.tsv

If you use these datasets, please cite the original publication:

add citation later

Repository Structure

• data/: Contains datasets in TSV format and optimized catalyst geometries in XYZ format.
  • xyz/: Contains optimized catalyst geometries and their conformers in XYZ format.
    • allyl-cyanide/: Optimized catalyst geometries for the allyl cyanide dataset.
    • butene/: Optimized catalyst geometries for the unactivated olefin dataset.
    • styrene/: Optimized catalyst geometries for the styrene dataset.
• model-training/: Contains Jupyter notebooks and scripts used for training the models presented in the paper, including control experiments.
  • active-learning/: Notebooks and scripts related to active learning experiments used in the new ligand generation case study.
  • allyl-cyanide/: Notebooks and scripts specific to modeling hydroformylation of allyl cyanide.
  • butene/: Models and experiments related to modeling hydroformylation of unactivated olefins.
  • butene-5x2/: Models and experiments for 5x2 repeated grouped cross-validation experiments on the unactivated olefin datasets.
  • control-experiments/: Notebooks and scripts for various control experiments, including random baseline models and Y-shuffled models.
  • styrene/: Notebooks and scripts specific to modeling hydroformylation of styrene.
• README.md: This file, providing an overview of the repository and installation instructions.
• pyproject.toml and uv.toml: Configuration files for managing dependencies using uv.

Installation

This repository uses uv to manage and install the dependencies.

1. Clone the repository:

   $ git clone git@github.com:nhadler/Libra-ML-Modeling.git
   $ cd Libra-ML-Modeling

2. Install most dependencies using uv: Run the following command. This will install most project dependencies listed in pyproject.toml.

   $ uv sync

3. Manually Install CUDA-enabled PyTorch and PyTorch Geometric: Due to the variability of CUDA versions and configurations across different systems, you need to install PyTorch and PyTorch Geometric (and their dependencies like torch_scatter, torch_sparse, etc.) manually to ensure they are compatible with your specific CUDA environment (or if you need a CPU-only build).

   • Install PyTorch: Visit the official PyTorch installation page (https://pytorch.org/get-started/locally/). Select your operating system, package manager (pip), CUDA version (or CPU), and copy the generated installation command. Run this command using uv pip install, adding --force-reinstall to ensure it replaces any previous installation.

     # Example (replace with the command from the PyTorch website for your setup)
     $ uv pip install --force-reinstall torch --index-url https://download.pytorch.org/whl/cu118

   • Install PyTorch Geometric (PyG) and dependencies: Visit the PyTorch Geometric installation instructions page (https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html). Find the command corresponding to the specific versions of PyTorch and CUDA you just installed. Run this command using uv pip install, again adding --force-reinstall.

     # Example (replace with the command from the PyG website for your setup)
     $ uv pip install --force-reinstall torch_geometric torch_scatter torch_sparse torch_cluster -f https://data.pyg.org/whl/torch-2.6.0+cu118.html # Adjust URL based on PyTorch/CUDA version

4. Running Code: To run any Python script within the isolated environment created by uv:

   $ uv run python your_script.py

   To run Jupyter Lab/Notebook:

   $ uv run --with jupyter jupyter lab # or jupyter notebook

   The --with jupyter flag tells uv to include the jupyter executable, which might not be in the base environment but is necessary to launch Jupyter Lab.