Usage

Auto3D generates low-energy 3D molecular conformers from SMILES or SDF files. The command-line interface (CLI) is the primary way to use Auto3D, with a Python API available for programmatic access.

Command Line Interface (CLI)

The CLI is the recommended way to use Auto3D. It’s simple, powerful, and doesn’t require writing any code.

Basic Usage

Generate the lowest-energy conformer for each molecule:

auto3d run molecules.smi --k=1

Generate multiple conformers per molecule:

auto3d run molecules.smi --k=5

Keep all conformers within an energy window:

auto3d run molecules.smi --window=3.0

GPU Acceleration

Enable GPU for faster processing (highly recommended):

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

Use a specific GPU:

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

Use multiple GPUs for large datasets:

auto3d run molecules.smi --k=1 --gpu --gpu-idx="0,1,2,3"

Model Selection

Auto3D supports three neural network potentials:

Model	Use Case	Speed	Supported Elements
`AIMNET`	General use, charged molecules (default)	Fast	H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I
`ANI2x`	Organic molecules	Very fast	H, C, N, O, F, S, Cl
`ANI2xt`	Ultra-fast screening, tautomers	Ultra fast	H, C, N, O, F, S, Cl

Select a model with --engine:

# Default: AIMNET (most versatile)
auto3d run molecules.smi --k=1 --gpu

# ANI2x: Fast, good for organic molecules
auto3d run molecules.smi --k=1 --engine=ANI2x --gpu

# ANI2xt: Ultra-fast screening
auto3d run molecules.smi --k=1 --engine=ANI2xt --gpu

Note

AIMNet2 clarification: The default model is AIMNet2 since version 2.2.1. Specifying --engine=AIMNET uses AIMNet2.

Isomer and Tautomer Enumeration

By default, Auto3D enumerates stereoisomers for unspecified stereocenters:

# Default: enumerate stereoisomers
auto3d run molecules.smi --k=1 --gpu

# Disable stereoisomer enumeration (keep input stereochemistry)
auto3d run molecules.smi --k=1 --no-enumerate-isomer --gpu

# Enable tautomer enumeration
auto3d run molecules.smi --k=1 --enumerate-tautomer --gpu

# Use OpenEye Omega for isomer generation (requires license)
auto3d run molecules.smi --k=1 --isomer-engine=omega --gpu

Configuration Files

For complex or reproducible workflows, use a YAML configuration file:

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

# Generate with a preset
auto3d config init -p quick -o quick.yaml      # Fast screening
auto3d config init -p balanced -o balanced.yaml  # Default settings
auto3d config init -p thorough -o thorough.yaml  # High accuracy

# Run with configuration file
auto3d run molecules.smi -c config.yaml

# Configuration file overrides command-line defaults
auto3d run molecules.smi --k=1 -c config.yaml

Example config.yaml:

# Output settings
k: 5                        # Top-5 conformers per molecule
# window: 3.0               # Alternative: energy window in kcal/mol

# Neural network model
optimizing_engine: AIMNET   # AIMNET, ANI2x, or ANI2xt

# GPU settings
use_gpu: true
gpu_idx: 0                  # Or [0, 1, 2, 3] for multi-GPU

# Isomer enumeration
enumerate_isomer: true
enumerate_tautomer: false
isomer_engine: rdkit        # rdkit or omega

# Optimization
opt_steps: 2000
convergence_threshold: 0.01
patience: 250

# Duplicate removal
threshold: 0.3              # RMSD threshold in Angstroms

CLI Subcommands

# Main workflow: generate conformers
auto3d run input.smi --k=1 --gpu

# Configuration management
auto3d config init                    # Create template config
auto3d config init -p quick           # Quick preset
auto3d config show config.yaml        # Display config
auto3d config validate config.yaml    # Validate config

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

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

# Help and version
auto3d --help                         # Show all commands
auto3d run --help                     # Show run options
auto3d --version                      # Show version

Shell Completion

Enable tab completion for your shell:

auto3d --install-completion bash      # For bash
auto3d --install-completion zsh       # For zsh
auto3d --install-completion fish      # For fish

Restart your shell or source the config file after installation.

Output Control

# Verbose output (show progress details)
auto3d run molecules.smi --k=1 -v

# Quiet mode (minimal output)
auto3d run molecules.smi --k=1 -q

# JSON output (for scripting)
auto3d run molecules.smi --k=1 --json

# Custom output directory
auto3d run molecules.smi --k=1 --job-name=my_results

Legacy YAML Mode

For backwards compatibility, the old syntax still works:

auto3d parameters.yaml

CLI Quick Reference

# Basic usage
auto3d run input.smi --k=1                     # Top-1 conformer
auto3d run input.smi --k=5                     # Top-5 conformers
auto3d run input.smi --window=3.0              # Energy window

# GPU acceleration
auto3d run input.smi --k=1 --gpu               # Enable GPU
auto3d run input.smi --k=1 --gpu --gpu-idx=0   # Specific GPU
auto3d run input.smi --k=1 --gpu --gpu-idx="0,1,2,3"  # Multi-GPU

# Model selection
auto3d run input.smi --k=1 --engine=AIMNET    # Default
auto3d run input.smi --k=1 --engine=ANI2x     # Fast
auto3d run input.smi --k=1 --engine=ANI2xt    # Ultra-fast

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

# Configuration files
auto3d config init -o config.yaml
auto3d run input.smi -c config.yaml

# Validation and help
auto3d validate input.smi
auto3d --help

Python API

For programmatic access, Auto3D provides a Python API. Use this when you need to integrate conformer generation into scripts or workflows.

Large Datasets: `main()` Function

For large datasets (150+ molecules), use the main function with file I/O:

from Auto3D import Auto3DOptions, main

if __name__ == "__main__":
    config = Auto3DOptions(
        path="molecules.smi",
        k=1,
        use_gpu=True,
    )
    output_path = main(config)
    print(f"Results saved to: {output_path}")

CLI equivalent:

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

Small Batches: `smiles2mols()` Function

For small batches (< 150 molecules), use smiles2mols for convenience:

from rdkit import Chem
from Auto3D import Auto3DOptions, smiles2mols

smiles = ['CCO', 'c1ccccc1', 'CC(=O)O']
config = Auto3DOptions(k=1, use_gpu=True)
mols = smiles2mols(smiles, config)

# Access results directly
for mol in mols:
    name = mol.GetProp('_Name')
    energy = float(mol.GetProp('E_tot'))  # Hartree
    print(f"{name}: {energy:.6f} Hartree")

    # Get atomic coordinates
    conf = mol.GetConformer()
    for i in range(conf.GetNumAtoms()):
        atom = mol.GetAtomWithIdx(i)
        pos = conf.GetAtomPosition(i)
        print(f"  {atom.GetSymbol()} {pos.x:.3f} {pos.y:.3f} {pos.z:.3f}")

Configuration Options

Auto3DOptions accepts all the same parameters as the CLI:

from Auto3D import Auto3DOptions, main

if __name__ == "__main__":
    config = Auto3DOptions(
        path="molecules.smi",

        # Ranking (choose one)
        k=5,                          # Top-k conformers
        # window=3.0,                 # Or energy window (kcal/mol)

        # Neural network model
        optimizing_engine="AIMNET",   # AIMNET, ANI2x, ANI2xt

        # GPU settings
        use_gpu=True,
        gpu_idx=0,                    # Or [0, 1, 2, 3] for multi-GPU

        # Isomer enumeration
        enumerate_isomer=True,
        enumerate_tautomer=False,
        isomer_engine="rdkit",        # rdkit or omega

        # Optimization
        opt_steps=2000,
        convergence_threshold=0.01,
        patience=250,

        # Duplicate removal
        threshold=0.3,                # RMSD in Angstroms

        # Output
        verbose=True,
        job_name="my_results",
    )
    output_path = main(config)

Wrapper Functions

Auto3D provides additional wrapper functions for common tasks:

# Single-point energy calculation
from Auto3D.SPE import calc_spe

# Geometry optimization
from Auto3D.ASE.geometry import opt_geometry

# Thermodynamic calculations
from Auto3D.ASE.thermo import calc_thermo

See the examples folder for detailed usage.

Parameter Reference

All parameters work identically in CLI and Python. CLI uses --param-name syntax, Python uses param_name in Auto3DOptions.

Parameter	Default	Description
`path`	(required)	Input `.smi` or `.sdf` file path
`k`	(required*)	Number of top conformers to output per molecule
`window`	(required*)	Energy window in kcal/mol (*use `k` OR `window`)
`optimizing_engine`	AIMNET	Neural network: `AIMNET`, `ANI2x`, `ANI2xt`, or path to custom model
`use_gpu`	True	Enable GPU acceleration
`gpu_idx`	0	GPU index or list of indices for multi-GPU
`enumerate_isomer`	True	Enumerate unspecified stereocenters
`enumerate_tautomer`	False	Enumerate tautomers
`isomer_engine`	rdkit	Isomer generation: `rdkit` or `omega`
`tauto_engine`	rdkit	Tautomer enumeration: `rdkit` or `oechem`
`max_confs`	(auto)	Maximum initial conformers per molecule
`opt_steps`	2000	Maximum optimization steps
`convergence_threshold`	0.01	Force convergence threshold (eV/A)
`patience`	250	Steps before dropping non-converging structures
`batchsize_atoms`	1024	Atoms per optimization batch per GB memory
`allow_tf32`	False	Enable TF32 on Ampere+ GPUs
`threshold`	0.3	RMSD threshold for duplicate removal (A)
`memory`	(auto)	RAM allocation in GB
`capacity`	42	Molecules per GB memory
`verbose`	False	Save detailed metadata
`job_name`	(timestamp)	Output folder name

Output Files

Auto3D creates a timestamped folder with results:

20260102-143052-123456_molecules/
├── molecules_out.sdf      # Final optimized conformers
└── auto3d.log             # Processing log

The output SDF contains:

Optimized 3D coordinates for each conformer
E_tot: Total energy in Hartree
E_rel or E_relative: Relative energy in kcal/mol
_Name: Molecule identifier
Original SMILES (if input was SMILES file)