Libra-ML is a Python program for predicting the regioselectivity of Rh-catalyzed olefin hydroformylation with various organophosphorus ligands using 3D structure-based deep learning. Specifically, it enables the automatic generation and calculation of transition-metal complex geometries and subsequent prediction using a 3D-GNN in an easy-to-use command line interface and Python API for the rapid exploration of new metal-ligand chemical space.
The associated publication can be found via its DOI: [TODO: Insert Paper DOI here, e.g., 10.1021/acs.joc.xxxxxx].
Libra-ML is developed by the Hartwig Group at the University of California, Berkeley.
If you have any questions or issues, feel free to open an issue on GitHub.
See the full documentation here.
Libra-ML is ready out of the box to predict the regioselectivity of olefin hydroformylation with organophosphorus ligands. To get started, simply install the package and its required dependencies (see Installation below), and ensure that xTB and CREST are installed and available in your system's PATH.
Once setup, you can run the following command line program with your ligand of interest:
libra-ml predict --name "My Ligand Name" "ligand SMILES string"This single command is all you need to automatically generate and calculate the geometry of your ligand, extract the relevant descriptors, and predict the regioselectivity. To learn more about how to use Libra-ML's command line interface and Python API, see our documentation.
Libra-ML is compatible with Linux and macOS and is distributed through PyPI and Docker. Docker images are available with xTB and CREST pre-installed, making it easy to get started without needing to install these dependencies separately.
The only required external executables are xTB >=6.7.1 and CREST >=3.0.1, which must be installed and available in your system's PATH environment variable when Libra-ML is run. These can be installed via conda or by installing the binaries directly (binaries are often faster).
See below for the quickest installation instructions using pip, or refer to our detailed documentation to learn how to install Libra-ML using other methods, such as with Docker images.
Libra-ML requires Python >=3.11,<3.13, PyTorch, Torch-Scatter, and Torch-Sparse to be installed in your environment. The easiest way to install Libra-ML is via pip, which will automatically install the required dependencies.
To install PyTorch, follow the instructions on the PyTorch website to select the appropriate version for your system. For example, to install PyTorch with CUDA 11.8 support, run:
pip install torch --extra-index-url https://download.pytorch.org/whl/cu118Then install Torch-Scatter and Torch-Sparse, making sure to select the correct version for your system. For example, to install them for PyTorch 2.0.1 with CUDA 11.8, run:
pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.0.1+cu118.htmlThen, to install Libra-ML using pip, run the following command:
pip install libra-mlThen you can verify the installation by running:
libra-ml --testUpon first use, or by running libra-ml download, Libra-ML will automatically download the pre-trained model weights from the [checkpoint Zenodo repository]([TODO: Insert Zenodo Link Here]). This requires about 11GB of storage and may take a few minutes depending on your internet connection.
Beyond single predictions, Libra-ML offers several commands:
- Predict: Generate structures and predict regioselectivity for a single ligand SMILES.
# Basic prediction for butene substrate libra-ml predict --name "MyLigand" "PCCCP" # Prediction with specific reaction conditions libra-ml predict --name "AnotherLigand" "PCCP" --temp 100 --h2 10 --co 10
- Batch: Predict regioselectivity for multiple ligands defined in a CSV file.
libra-ml batch input_ligands.csv --output batch_results --processes 4
- Explain: Generate SHAP explanations for a specific conformer prediction (requires the files from a completed prediction).
libra-ml explain path/to/conformer.xyz path/to/topology.json --save-path explanation.pkl
- Download: Manually download or update the required model checkpoint files.
libra-ml download
- Test: Verify the installation and check for external dependencies (xTB, CREST).
libra-ml --test
See the CLI Documentation for detailed options and see the Usage Documentation.
Guidelines for contribution and information on setting up a development environment can be found in the CONTRIBUTING.md file.
If you encounter any problems or have questions, please file an issue on our GitHub repository. Provide a detailed description of the problem, your installation method, and relevant system information.
Libra-ML is developed by the Hartwig Group at the University of California, Berkeley. In particular, the following people have contributed significantly to developing its functionality:
Libra-ML is released under the BSD 3-clause license and is thus completely free for both academic and commercial use.
If you find this code, the models, or data useful for your research, please cite our publication.
@article{[TODO: InsertCiteKeyHere],
author = {[TODO: Hadler, Rest of Authors]},
title = {{A 3D, Structure-Based, Deep Learning Approach for Predicting the Regioselectivity of Transition-Metal Catalysis}},
journal = {[TODO: Journal Name]},
year = {[TODO: Year]},
volume = {[TODO: Volume]},
issue = {[TODO: Issue]},
pages = {[TODO: Pages]},
doi = {[TODO: Insert Paper DOI Here]},
url = {[TODO: Link to paper]}
}