Tutorial: Getting Optimized Conformers and Energies

Auto3D generates low-energy 3D molecular conformers from SMILES or SDF files.

Quick Start with CLI (Recommended)

The CLI is the simplest way to use Auto3D. Generate the lowest-energy conformer for each molecule:

auto3d run molecules.smi --k=1 --gpu

Essential CLI Commands

# Basic conformer generation
auto3d run input.smi --k=1                    # Top-1 conformer (CPU)
auto3d run input.smi --k=1 --gpu              # Top-1 conformer (GPU, faster)
auto3d run input.smi --k=5 --gpu              # Top-5 conformers
auto3d run input.smi --window=3.0 --gpu       # Within 3 kcal/mol window

# Model selection (choose one)
auto3d run input.smi --k=1 --engine=AIMNET --gpu   # Default, most versatile
auto3d run input.smi --k=1 --engine=ANI2x --gpu    # Fast, organic molecules
auto3d run input.smi --k=1 --engine=ANI2xt --gpu   # Ultra-fast screening

# Multi-GPU for large datasets
auto3d run input.smi --k=1 --gpu --gpu-idx="0,1,2,3"

# Configuration presets
auto3d config init -p quick -o quick.yaml      # Fast screening
auto3d config init -p balanced -o balanced.yaml # Balanced (default)
auto3d config init -p thorough -o thorough.yaml # High accuracy
auto3d run input.smi --k=1 -c quick.yaml --gpu

The source jupyter notebook can be downloaded here

[ ]:

import os, sys
root = os.path.dirname(os.path.dirname(os.path.abspath("__file__")))

import Auto3D
# Auto3DOptions is a dataclass for configuring Auto3D parameters
# main function takes the configuration and runs the Auto3D pipeline
from Auto3D import Auto3DOptions, main

[2]:

#Always ensure that you have the latest version
print(Auto3D.__version__)

2.2.6

CLI Reference

Basic Commands

# Generate conformers
auto3d run input.smi --k=1 --gpu              # Top-1 conformer
auto3d run input.smi --k=5 --gpu              # Top-5 conformers
auto3d run input.smi --window=3.0 --gpu       # Energy window selection

# GPU options
auto3d run input.smi --k=1 --gpu              # Enable GPU
auto3d run input.smi --k=1 --gpu --gpu-idx=1  # Use specific GPU
auto3d run input.smi --k=1 --gpu --gpu-idx="0,1,2"  # Multi-GPU

# Model selection
auto3d run input.smi --k=1 --engine=AIMNET --gpu   # Default (most elements)
auto3d run input.smi --k=1 --engine=ANI2x --gpu    # Fast (organic)
auto3d run input.smi --k=1 --engine=ANI2xt --gpu   # Ultra-fast

# Isomer/tautomer control
auto3d run input.smi --k=1 --enumerate-tautomer --gpu
auto3d run input.smi --k=1 --no-enumerate-isomer --gpu

# Output control
auto3d run input.smi --k=1 -v --gpu           # Verbose output
auto3d run input.smi --k=1 --json --gpu       # JSON output

Configuration Management

# Generate config templates
auto3d config init                            # Default template
auto3d config init -p quick -o quick.yaml     # Fast screening preset
auto3d config init -p balanced -o balanced.yaml  # Balanced preset
auto3d config init -p thorough -o thorough.yaml  # High accuracy preset

# Validate and view config
auto3d config validate config.yaml
auto3d config show config.yaml

# Run with config file
auto3d run input.smi -c config.yaml --gpu

Utility Commands

# Model information
auto3d models list                            # List available models
auto3d models info AIMNET                     # Model details

# Input validation
auto3d validate input.smi                     # Check for issues

# Help
auto3d --help
auto3d run --help

Python API (for Programmatic Access)

For integration into scripts and workflows, Auto3D provides a Python API:

[ ]:

if __name__ == "__main__":
    path = os.path.join(root, "example/files/smiles.smi")  # You can specify the path to your file here
    config = Auto3DOptions(path=path, k=1, use_gpu=False)  # Configure Auto3D parameters
    out = main(config)  # Run Auto3D and get output path
    print(out)

Model Selection Guide

Model	Elements Covered	Charge Support	Speed	Best For
AIMNET (default)	H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I	Neutral + charged	Fast	General use, charged molecules
ANI2x	H, C, N, O, F, S, Cl	Neutral only	Very fast	Organic molecules
ANI2xt	H, C, N, O, F, S, Cl	Neutral only	Ultra-fast	Fast screening, tautomers

CLI Examples:

auto3d run input.smi --k=1 --engine=AIMNET --gpu   # Default, most versatile
auto3d run input.smi --k=1 --engine=ANI2x --gpu    # Fast organic screening
auto3d run input.smi --k=1 --engine=ANI2xt --gpu   # Ultra-fast screening

Understanding the `k` Parameter

The 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.

You 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.

CLI Examples:

auto3d run input.smi --k=1 --gpu      # Keep only lowest-energy conformer
auto3d run input.smi --k=5 --gpu      # Keep top 5 conformers
auto3d run input.smi --window=3.0 --gpu  # Keep all within 3 kcal/mol

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.

Configuration Files

For complex or reproducible workflows, use YAML configuration files:

# Generate a config template
auto3d config init -o config.yaml

# Use a preset
auto3d config init -p quick -o quick.yaml      # Fast screening
auto3d config init -p balanced -o balanced.yaml  # Balanced settings
auto3d config init -p thorough -o thorough.yaml  # High accuracy

# Run with configuration
auto3d run input.smi -c config.yaml --gpu

Example config.yaml:

k: 5                          # Top-5 conformers per molecule
optimizing_engine: AIMNET     # Neural network model
use_gpu: true                 # Enable GPU acceleration
gpu_idx: 0                    # GPU index
enumerate_isomer: true        # Enumerate unspecified stereocenters
threshold: 0.3                # RMSD threshold for duplicate removal

For backwards compatibility, the legacy YAML-only syntax still works:

auto3d parameters.yaml

You can find an example parameters.yaml at here