Quick Start Guide

Get up and running with Auto3D in 5 minutes.

Installation

Option 1: pip (simplest)

pip install Auto3D

Option 2: uv (fastest)

uv pip install Auto3D

Option 3: conda (recommended for GPU)

conda install -c conda-forge auto3d

Verify installation:

auto3d --version

Your First Conformer

Create a file molecules.smi with SMILES strings:

CCO ethanol
c1ccccc1 benzene
CC(=O)O acetic_acid

Generate conformers:

auto3d run molecules.smi --k=1

This generates the lowest-energy conformer for each molecule.

Understanding the Output

Auto3D creates a timestamped folder with results:

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

The output SDF file contains:

  • Optimized 3D coordinates

  • Energy in Hartree (E_tot property)

  • Relative energy in kcal/mol (E_relative property)

  • Original SMILES and molecule name

View in Python:

from rdkit import Chem

mols = list(Chem.SDMolSupplier("molecules_out.sdf"))
for mol in mols:
    name = mol.GetProp("_Name")
    energy = float(mol.GetProp("E_tot"))
    print(f"{name}: {energy:.6f} Hartree")

Common Use Cases

Generate Multiple Conformers

Get top-5 lowest-energy conformers per molecule:

auto3d run molecules.smi --k=5

Energy Window Selection

Keep all conformers within 3 kcal/mol of the minimum:

auto3d run molecules.smi --window=3.0

Enable GPU Acceleration

For faster processing:

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

Python API

For programmatic access:

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}")

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

from Auto3D import Auto3DOptions, smiles2mols

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

for mol in mols:
    print(f"{mol.GetProp('_Name')}: {mol.GetProp('E_tot')} Hartree")

Choosing a Model

Auto3D supports three neural network potentials:

Model

Best For

Speed

Elements

AIMNET

General use, charged molecules

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

Tautomers, ultra-fast screening

Ultra fast

H, C, N, O, F, S, Cl

Specify with --engine:

auto3d run molecules.smi --k=1 --engine=ANI2x

Configuration Files

For reproducible workflows, use a YAML config:

# Generate template
auto3d config init -o config.yaml

# Edit config.yaml, then run
auto3d run molecules.smi -c config.yaml

Example config.yaml:

k: 5
optimizing_engine: AIMNET
use_gpu: true
enumerate_isomer: true
threshold: 0.3

Troubleshooting

“No module named ‘Auto3D’”

Ensure Auto3D is installed in your active environment:

pip show Auto3D

CUDA out of memory

Reduce batch size or use CPU:

# Use CPU
auto3d run molecules.smi --k=1 --no-gpu

# Or reduce batch size in Python
config = Auto3DOptions(path="molecules.smi", k=1, batchsize_atoms=512)

Slow processing

  1. Enable GPU: --gpu

  2. Use faster model: --engine=ANI2xt

  3. Reduce k: --k=1 for screening

Next Steps