{ "cells": [ { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": "# Tutorial: Getting Optimized Conformers and Energies\n\nAuto3D generates low-energy 3D molecular conformers from SMILES or SDF files.\n\n## Quick Start with CLI (Recommended)\n\nThe CLI is the simplest way to use Auto3D. Generate the lowest-energy conformer for each molecule:\n\n```bash\nauto3d run molecules.smi --k=1 --gpu\n```\n\n### Essential CLI Commands\n\n```bash\n# Basic conformer generation\nauto3d run input.smi --k=1 # Top-1 conformer (CPU)\nauto3d run input.smi --k=1 --gpu # Top-1 conformer (GPU, faster)\nauto3d run input.smi --k=5 --gpu # Top-5 conformers\nauto3d run input.smi --window=3.0 --gpu # Within 3 kcal/mol window\n\n# Model selection (choose one)\nauto3d run input.smi --k=1 --engine=AIMNET --gpu # Default, most versatile\nauto3d run input.smi --k=1 --engine=ANI2x --gpu # Fast, organic molecules \nauto3d run input.smi --k=1 --engine=ANI2xt --gpu # Ultra-fast screening\n\n# Multi-GPU for large datasets\nauto3d run input.smi --k=1 --gpu --gpu-idx=\"0,1,2,3\"\n\n# Configuration presets\nauto3d config init -p quick -o quick.yaml # Fast screening\nauto3d config init -p balanced -o balanced.yaml # Balanced (default)\nauto3d config init -p thorough -o thorough.yaml # High accuracy\nauto3d run input.smi --k=1 -c quick.yaml --gpu\n```\n\nThe source jupyter notebook can be downloaded [here](https://github.com/isayevlab/Auto3D_pkg/blob/main/example/tutorial.ipynb)" }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": "import os, sys\nroot = os.path.dirname(os.path.dirname(os.path.abspath(\"__file__\")))\n\nimport Auto3D\n# Auto3DOptions is a dataclass for configuring Auto3D parameters\n# main function takes the configuration and runs the Auto3D pipeline\nfrom Auto3D import Auto3DOptions, 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": "## CLI Reference\n\n### Basic Commands\n\n```bash\n# Generate conformers\nauto3d run input.smi --k=1 --gpu # Top-1 conformer\nauto3d run input.smi --k=5 --gpu # Top-5 conformers \nauto3d run input.smi --window=3.0 --gpu # Energy window selection\n\n# GPU options\nauto3d run input.smi --k=1 --gpu # Enable GPU\nauto3d run input.smi --k=1 --gpu --gpu-idx=1 # Use specific GPU\nauto3d run input.smi --k=1 --gpu --gpu-idx=\"0,1,2\" # Multi-GPU\n\n# Model selection\nauto3d run input.smi --k=1 --engine=AIMNET --gpu # Default (most elements)\nauto3d run input.smi --k=1 --engine=ANI2x --gpu # Fast (organic)\nauto3d run input.smi --k=1 --engine=ANI2xt --gpu # Ultra-fast\n\n# Isomer/tautomer control\nauto3d run input.smi --k=1 --enumerate-tautomer --gpu\nauto3d run input.smi --k=1 --no-enumerate-isomer --gpu\n\n# Output control\nauto3d run input.smi --k=1 -v --gpu # Verbose output\nauto3d run input.smi --k=1 --json --gpu # JSON output\n```\n\n### Configuration Management\n\n```bash\n# Generate config templates\nauto3d config init # Default template\nauto3d config init -p quick -o quick.yaml # Fast screening preset\nauto3d config init -p balanced -o balanced.yaml # Balanced preset\nauto3d config init -p thorough -o thorough.yaml # High accuracy preset\n\n# Validate and view config\nauto3d config validate config.yaml\nauto3d config show config.yaml\n\n# Run with config file\nauto3d run input.smi -c config.yaml --gpu\n```\n\n### Utility Commands\n\n```bash\n# Model information\nauto3d models list # List available models\nauto3d models info AIMNET # Model details\n\n# Input validation\nauto3d validate input.smi # Check for issues\n\n# Help\nauto3d --help\nauto3d run --help\n```\n\n## Python API (for Programmatic Access)\n\nFor integration into scripts and workflows, Auto3D provides a Python API:" }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": "if __name__ == \"__main__\":\n path = os.path.join(root, \"example/files/smiles.smi\") # You can specify the path to your file here\n config = Auto3DOptions(path=path, k=1, use_gpu=False) # Configure Auto3D parameters\n out = main(config) # Run Auto3D and get output path\n print(out)" }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": "### Model Selection Guide\n\n| Model | Elements Covered | Charge Support | Speed | Best For |\n|-------|-----------------|----------------|-------|----------|\n| **AIMNET** (default) | H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I | Neutral + charged | Fast | General use, charged molecules |\n| **ANI2x** | H, C, N, O, F, S, Cl | Neutral only | Very fast | Organic molecules |\n| **ANI2xt** | H, C, N, O, F, S, Cl | Neutral only | Ultra-fast | Fast screening, tautomers |\n\n**CLI Examples:**\n```bash\nauto3d run input.smi --k=1 --engine=AIMNET --gpu # Default, most versatile\nauto3d run input.smi --k=1 --engine=ANI2x --gpu # Fast organic screening\nauto3d run input.smi --k=1 --engine=ANI2xt --gpu # Ultra-fast screening\n```\n\n### Understanding the `k` Parameter\n\nThe `k=1` argument specifies that only the lowest energy conformer for each molecule will be kept. With `k=3`, each molecule will have at most 3 conformers with their relative energies stored in the output SDF.\n\nYou can also use `window=x` instead of `k` to keep all conformers within `x kcal/mol` of the lowest-energy conformer. These options are mutually exclusive.\n\n**CLI Examples:**\n```bash\nauto3d run input.smi --k=1 --gpu # Keep only lowest-energy conformer\nauto3d run input.smi --k=5 --gpu # Keep top 5 conformers\nauto3d run input.smi --window=3.0 --gpu # Keep all within 3 kcal/mol\n```\n\n
\n \"illustration\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": "## Configuration Files\n\nFor complex or reproducible workflows, use YAML configuration files:\n\n```bash\n# Generate a config template\nauto3d config init -o config.yaml\n\n# Use a preset\nauto3d config init -p quick -o quick.yaml # Fast screening\nauto3d config init -p balanced -o balanced.yaml # Balanced settings \nauto3d config init -p thorough -o thorough.yaml # High accuracy\n\n# Run with configuration\nauto3d run input.smi -c config.yaml --gpu\n```\n\nExample `config.yaml`:\n\n```yaml\nk: 5 # Top-5 conformers per molecule\noptimizing_engine: AIMNET # Neural network model\nuse_gpu: true # Enable GPU acceleration\ngpu_idx: 0 # GPU index\nenumerate_isomer: true # Enumerate unspecified stereocenters\nthreshold: 0.3 # RMSD threshold for duplicate removal\n```\n\nFor backwards compatibility, the legacy YAML-only syntax still works:\n```bash\nauto3d parameters.yaml\n```\n\nYou 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 }