{ "cells": [ { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "# Tutorial: Getting optimized conformers and energies\n", "\n", "The most basic usage of Auto3D is to get the optimized low-energy conformers. The input is just a `smi` or `SDF` file, the output is an `SDF` file containing the conformers and its energies. `Auto3D` provides flexibility in choosing isomer engine, optimization engine and other properties, but the whole process could be done with as little as 5 lines of code.\n", "\n", "The source jupyter notebook can be downloaded [here](https://github.com/isayevlab/Auto3D_pkg/blob/main/example/tutorial.ipynb)" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "import os, sys\n", "root = os.path.dirname(os.path.dirname(os.path.abspath(\"__file__\")))\n", "\n", "import Auto3D\n", "#options is a function that takes in all user-specified parameters, then return arguments for the main function\n", "#main function takes in the arguments from the options function, then actually runs the Auto3D modules\n", "from Auto3D.auto3D import options, main" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "2.2.6\n" ] } ], "source": [ "#Always ensure that you have the latest version\n", "print(Auto3D.__version__)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Generate low-energy 3D structures with Auto3D" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Checking input file...\n", "\tThere are 4 SMILES in the input file /Users/liu5/Documents/Auto3D_pkg/example/files/smiles.smi. \n", "\tAll SMILES and IDs are valid.\n", "Suggestions for choosing isomer_engine and optimizing_engine: \n", "\tIsomer engine options: RDKit and Omega.\n", "\tOptimizing engine options: ANI2x, ANI2xt and AIMNET.\n", "The available memory is 16 GB.\n", "The task will be divided into 1 jobs.\n", "Job1, number of inputs: 4\n", "\n", "\n", "Isomer generation for job1\n", "Enumerating cis/tran isomers for unspecified double bonds...\n", "Enumerating R/S isomers for unspecified atomic centers...\n", "Removing enantiomers...\n", "Enumerating conformers/rotamers, removing duplicates...\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "100%|██████████| 4/4 [00:00<00:00, 19.43it/s]\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "\n", "\n", "Optimizing on job1\n", "Preparing for parallel optimizing... (Max optimization steps: 5000)\n", "Total 3D conformers: 39\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ " 10%|▉ | 499/5000 [03:35<21:02, 3.57it/s]" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Total 3D structures: 39 Converged: 23 Dropped(Oscillating): 0 Active: 16\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ " 20%|██ | 1000/5000 [05:01<07:39, 8.70it/s]" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Total 3D structures: 39 Converged: 35 Dropped(Oscillating): 0 Active: 4\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ " 28%|██▊ | 1407/5000 [05:38<14:25, 4.15it/s]\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Optimization finished at step 1408: Total 3D structures: 39 Converged: 39 Dropped(Oscillating): 0 Active: 0\n", "Begin to select structures that satisfy the requirements...\n", "Energy unit: Hartree if implicit.\n", "Program running time: 6 minute(s)\n", "Output path: /Users/liu5/Documents/Auto3D_pkg/example/files/20231220-112847-937903_smiles/smiles_out.sdf\n", "/Users/liu5/Documents/Auto3D_pkg/example/files/20231220-112847-937903_smiles/smiles_out.sdf\n" ] } ], "source": [ "if __name__ == \"__main__\":\n", " path = os.path.join(root, \"example/files/smiles.smi\") # You can specify the path to your file here\n", " args = options(path, k=1, use_gpu=False) #specify the parameters for Auto3D \n", " out = main(args) #main acceps the parameters and run Auto3D\n", " print(out)" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "In the above example, Auto3D searches and optimizes 39 conformers, then returns the low-energy conformers using 6 minutes on a Intel MacBook. This time can be reduced to ~2 minutes if the job is run on a Nvidia RTX3090 GPU. The total running time also depends on the choice of different `optimizing_engine`:\n", "\n", "\n", "| Optimizing_engine | Elements Covered | Charge | Training Dataset Size | Target DFT | Empirical accuracy and speed |\n", "|----------|------------------------------------------------------------|---------------------------------------|-----------------------|------------------|----------------------------------------|\n", "| ANI2x | H, C, N, O, F, S, Cl | only neutral molecules | ~ 4.5M | ωB97X/6-31G* | accurate, very fast |\n", "| ANI2xt | H, C, N, O, F, S, Cl | only neutral molecules, with enhancement for tautomers | ~ 13M | B97-3c | accurate, ultra fast |\n", "| AIMNET (default) | H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I | both neutral and charged molecules | ~ 20 M | wB97M/Def2-TZVPP | very accurate, fast |\n", "\n", "For the above example, `ANI2xt` is about 8 times faster than `AIMNet`, using 16 seconds on a RTX3090 GPU. `ANI2x` is about 2 times faster than `AIMNET`, using about 1 minute on a RTX3090 GPU. The speed difference is more abvious on larger jobs. As for accuracy, all models are accurate. The difference is only obvious when we do edge examples.\n", "\n", "Note the `k=1` argument specifies that only the lowest energy conformer for each molecule will be kepted int the final output. If `k=3`, the each molecule will have at most 3 conformers, and their relative energies will be stored in the SDF file, too. Here is a diagram demonstrate the argument `k`.\n", "\n", "\n", "
\n", " \"illustraction\n", "
" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "Note that you can also use `window=x` instead of setting `k=1`. The argument `window` tells Auto3D to keep all conforers whose energies are at most `x kcal/mol` higher than the lowest-energy of that molecule. `window` and `k` are mutual exclusive, so you can only set either `window` or `k`. " ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "## Running the job in CLI\n", "\n", "You can also run the above job with CLI:\n", "\n", "```\n", "auto3d \"example/files/smiles.smi\" --k=1\n", "```\n", "\n", "## Running the job in CLI with a yaml file\n", "The parameter can be provided via a yaml file. So the above example is equivalent to\n", "```\n", "auto3d parameters.yaml\n", "```\n", "You can find an example `parameters.yaml` at [here](https://github.com/isayevlab/Auto3D_pkg/blob/main/parameters.yaml)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [] } ], "metadata": { "kernelspec": { "display_name": "py39", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.17" }, "vscode": { "interpreter": { "hash": "1b614daab3e5f7b6a193b72cc0b083bb669e7ee1c6a77737086e3d4b842fe95b" } } }, "nbformat": 4, "nbformat_minor": 2 }