{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "# Auto3D Quick Start\n\nGet up and running with Auto3D in 5 minutes. The **CLI is the primary interface** for Auto3D, with Python API available for programmatic access.\n\n## CLI Quick Start (Recommended)\n\nThe simplest way to use Auto3D is via the command line:\n\n```bash\n# Generate lowest-energy conformer\nauto3d run molecules.smi --k=1 --gpu\n\n# Generate multiple conformers\nauto3d run molecules.smi --k=5 --gpu\n\n# Energy window selection\nauto3d run molecules.smi --window=3.0 --gpu\n\n# Model selection\nauto3d run molecules.smi --k=1 --engine=ANI2xt --gpu  # Ultra-fast\nauto3d run molecules.smi --k=1 --engine=ANI2x --gpu   # Fast\nauto3d run molecules.smi --k=1 --engine=AIMNET --gpu  # Default (charged molecules)\n\n# Multi-GPU for large datasets\nauto3d run molecules.smi --k=1 --gpu --gpu-idx=\"0,1,2,3\"\n\n# Configuration presets\nauto3d config init -p quick -o quick.yaml\nauto3d run molecules.smi --k=1 -c quick.yaml --gpu\n```\n\n## CLI Commands Reference\n\n```bash\n# Main workflow\nauto3d run input.smi --k=1 --gpu              # Generate conformers\n\n# Configuration\nauto3d config init -o config.yaml             # Create template\nauto3d config init -p quick -o quick.yaml     # Fast preset\nauto3d config init -p thorough -o thorough.yaml  # High accuracy\n\n# Utilities\nauto3d validate input.smi                     # Check input file\nauto3d models list                            # List available models\nauto3d --help                                 # Help\n```\n\n---\n\n## Python API (for Programmatic Access)\n\nFor integration into scripts and Jupyter notebooks:"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import Auto3D\n",
    "print(f\"Auto3D version: {Auto3D.__version__}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "### 1. Generate Conformers from SMILES (Python)\n\nFor small batches in notebooks, use `smiles2mols`:\n\n**CLI Equivalent:**\n```bash\necho \"CCO ethanol\nc1ccccc1 benzene\nCC(=O)O acetic_acid\" > molecules.smi\nauto3d run molecules.smi --k=1 --gpu\n```"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from Auto3D import Auto3DOptions, smiles2mols\n",
    "\n",
    "# Define some molecules\n",
    "smiles_list = [\n",
    "    \"CCO\",           # ethanol\n",
    "    \"c1ccccc1\",      # benzene\n",
    "    \"CC(=O)O\",       # acetic acid\n",
    "]\n",
    "\n",
    "# Configure Auto3D\n",
    "config = Auto3DOptions(\n",
    "    k=1,              # Get top-1 conformer per molecule\n",
    "    use_gpu=False,    # Use CPU (set True for GPU)\n",
    ")\n",
    "\n",
    "# Generate conformers\n",
    "mols = smiles2mols(smiles_list, config)\n",
    "print(f\"Generated {len(mols)} conformers\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Inspect the Results\n",
    "\n",
    "Each molecule has optimized coordinates and energy information:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for mol in mols:\n",
    "    name = mol.GetProp(\"_Name\")\n",
    "    energy = float(mol.GetProp(\"E_tot\"))  # Energy in Hartree\n",
    "    energy_kcal = energy * 627.509        # Convert to kcal/mol\n",
    "    \n",
    "    print(f\"{name}:\")\n",
    "    print(f\"  Energy: {energy:.6f} Hartree ({energy_kcal:.2f} kcal/mol)\")\n",
    "    print(f\"  Atoms: {mol.GetNumAtoms()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Visualize the Conformers\n",
    "\n",
    "View the 3D structures:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from rdkit.Chem import Draw\n",
    "\n",
    "# 2D view\n",
    "Draw.MolsToGridImage(mols, molsPerRow=3, subImgSize=(250, 200))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "### 4. Processing Larger Datasets\n\nFor larger datasets (>150 molecules), use file I/O.\n\n**CLI (Recommended):**\n```bash\nauto3d run large_dataset.smi --k=1 --gpu\n\n# Multi-GPU for maximum throughput\nauto3d run large_dataset.smi --k=1 --gpu --gpu-idx=\"0,1,2,3\"\n```\n\n**Python API:**"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "from Auto3D import Auto3DOptions, main\n",
    "\n",
    "# Get path to example file\n",
    "root = os.path.dirname(os.path.dirname(os.path.abspath(\"__file__\")))\n",
    "input_path = os.path.join(root, \"example/files/smiles.smi\")\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    config = Auto3DOptions(\n",
    "        path=input_path,\n",
    "        k=1,\n",
    "        use_gpu=False,\n",
    "    )\n",
    "    output_path = main(config)\n",
    "    print(f\"Results saved to: {output_path}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "### 5. Multiple Conformers\n\nGenerate multiple conformers per molecule:\n\n**CLI:**\n```bash\nauto3d run molecules.smi --k=5 --gpu    # Top 5 conformers per molecule\n```\n\n**Python API:**"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get top-3 conformers per molecule\n",
    "config = Auto3DOptions(k=3, use_gpu=False)\n",
    "mols = smiles2mols([\"CCCCC\"], config)  # pentane\n",
    "\n",
    "print(f\"Generated {len(mols)} conformers for pentane\")\n",
    "for mol in mols:\n",
    "    energy = float(mol.GetProp(\"E_tot\")) * 627.509\n",
    "    rel_e = float(mol.GetProp(\"E_rel(kcal/mol)\"))\n",
    "    print(f\"  Relative energy: {rel_e:.2f} kcal/mol\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "### 6. Using Energy Window\n\nKeep all conformers within an energy window:\n\n**CLI:**\n```bash\nauto3d run molecules.smi --window=3.0 --gpu    # Keep all within 3 kcal/mol\n```\n\n**Python API:**"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Keep conformers within 3 kcal/mol of minimum\n",
    "config = Auto3DOptions(window=3.0, use_gpu=False)\n",
    "mols = smiles2mols([\"CCCCCC\"], config)  # hexane\n",
    "\n",
    "print(f\"Found {len(mols)} conformers within 3 kcal/mol window\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "### 7. Choosing a Model\n\nAuto3D supports multiple neural network potentials:\n\n**CLI:**\n```bash\n# AIMNET (default) - most versatile, supports charged molecules\nauto3d run molecules.smi --k=1 --engine=AIMNET --gpu\n\n# ANI2x - fast, well-validated for organic molecules\nauto3d run molecules.smi --k=1 --engine=ANI2x --gpu\n\n# ANI2xt - ultra-fast, good for screening and tautomers\nauto3d run molecules.smi --k=1 --engine=ANI2xt --gpu\n\n# List available models\nauto3d models list\n```\n\n**Python API:**"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# AIMNET (default) - most versatile, supports charged molecules\n",
    "config = Auto3DOptions(k=1, optimizing_engine=\"AIMNET\", use_gpu=False)\n",
    "\n",
    "# ANI2x - fast, well-validated\n",
    "config = Auto3DOptions(k=1, optimizing_engine=\"ANI2x\", use_gpu=False)\n",
    "\n",
    "# ANI2xt - ultra-fast, good for tautomers\n",
    "config = Auto3DOptions(k=1, optimizing_engine=\"ANI2xt\", use_gpu=False)\n",
    "\n",
    "print(\"Available engines: AIMNET, ANI2x, ANI2xt\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next Steps\n",
    "\n",
    "- See `tutorial.ipynb` for more detailed examples\n",
    "- See `single_point_energy.ipynb` for energy calculations\n",
    "- See `tautomer.ipynb` for tautomer enumeration\n",
    "- Read the [documentation](https://auto3d.readthedocs.io/) for full details"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.10.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}