Auto3D

PyPI PyPI - Downloads Docs Python 3.11+ PyPI - License

auto3d-white

SMILES in, low-energy 3D conformers out. Auto3D enumerates tautomers and stereoisomers, embeds and optimizes them with a neural network potential (AIMNet2, ANI2x, ANI2xt), removes duplicates, and ranks what is left by energy — in one command, or one function call.

pip install Auto3D
auto3d run molecules.smi --k=1

That writes molecules_<timestamp>/molecules_out.sdf: the lowest-energy conformer per input molecule, each carrying its energy.

Installation

pip install Auto3D                # core: AIMNet2 engines
pip install "Auto3D[ani,ase]"     # + torchani (ANI2x/ANI2xt) and ase (thermochemistry)

Requires Python ≥ 3.11 and PyTorch ≥ 2.8. For GPU acceleration, install a CUDA-enabled PyTorch build first. AIMNet2 weights download to ~/.cache/aimnet on first use, so the first run needs network access.

Using conda? Install Auto3D itself with pip, even inside a conda env.

conda install -c conda-forge auto3d installs 2.3.0, not 3.1.0. conda-forge requires every dependency to be a conda package, and aimnet — a core dependency since 3.0.0 — is not one yet, nor is its own dependency nvalchemi-toolkit-ops.

Auto3D works fine inside a conda environment; it is only the conda package that lags. installation.yml sets up the supported combination:

conda env create --file installation.yml --name auto3D
conda activate auto3D          # pip installs Auto3D[ani,ase] into it

Details and the path forward: Building the conda package.

Quick start

Command line

auto3d run molecules.smi --k=5          # top-5 conformers per molecule
auto3d run molecules.smi --window=3.0   # or everything within 3 kcal/mol
auto3d run molecules.smi --k=5 --no-gpu # CPU only

Exactly one of --k or --window is required. GPU is used by default, and requesting it with no visible CUDA device is a fatal error, not a fallback — pass --no-gpu on a CPU-only machine.

Python

from Auto3D import Auto3DOptions, main

config = Auto3DOptions(path="molecules.smi", k=1)
output_path = main(config)

main() returns a WorkflowResult, which is the output path (it subclasses str) and also carries n_molecules, n_conformers, and failures.

For batches of ≤150 molecules, skip the job directory and get RDKit molecules straight back:

from Auto3D import Auto3DOptions, smiles2mols

mols = smiles2mols(["CCO", "CCCO", "c1ccccc1"], Auto3DOptions(k=1, use_gpu=False))
for mol in mols:
    print(mol.GetProp("_Name"), mol.GetProp("E_tot"), "Hartree")

What you get

A run creates <stem>_<timestamp>/ next to the input, containing the output SDF and an Auto3D.log. Each conformer in the SDF carries:

Property Meaning
E_tot / E_tot(Hartree) Total energy, Hartree
E_rel(kcal/mol) Energy relative to the best conformer of that molecule
_Name, ID Molecule name and a stable identifier
fmax, Converged, Dropped_Oscillating Optimizer diagnostics

The input SMILES is not written to the output — join on _Name/ID against your input file.

Beyond conformer generation

Each of these wraps a Python API function and has a matching notebook in example/.

Command Does Python API
auto3d run Generate conformers from SMILES/SDF main, smiles2mols
auto3d energy Single-point energy for an SDF calc_spe
auto3d optimize Geometry-optimize an existing SDF opt_geometry
auto3d thermo Enthalpy / entropy / Gibbs (needs ase) calc_thermo
auto3d tautomers Enumerate and rank stable tautomers get_stable_tautomers
auto3d validate Check an input file without running —
auto3d config init|show|validate Manage YAML configs —
auto3d models list|info|test Inspect and smoke-test engines —

All commands except models list take -v/--verbose, the only way to get a traceback. --json is available on run, validate, and the four property commands. Exit codes: 0 success, 2 config/input error, 4 GPU requested but unavailable, 6 partial success, 130 interrupted.

Engines

Engine Networks/step Elements
AIMNET (default) 1 H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I
aimnet2-2025, aimnet2-nse, aimnet2-pd, … 1 as above (aimnet2-pd swaps As for Pd)
ANI2x 8 (ensemble) H, C, N, O, F, S, Cl
ANI2xt 1 H, C, N, O, F, S, Cl

Select with --engine or optimizing_engine. AIMNet2 models come from the aimnet package and are sha256-validated on download; auto3d models list shows what is available. optimizing_engine also accepts a path to a custom NNP.

No engine speed benchmark is maintained in this repository, so the table reports how many networks each engine evaluates per step rather than a speed ranking. Time your own workload before choosing.

Key parameters

Parameter Default Description
k — Top-k conformers per molecule
window — Energy window, kcal/mol — exactly one of k/window is required
optimizing_engine AIMNET Engine name, registry name, or path to a custom model
use_gpu True GPU acceleration; missing CUDA device is fatal, not a fallback
gpu_idx 0 CUDA index, or a list for multi-GPU
enumerate_tautomer False Enumerate tautomers
enumerate_isomer True Enumerate stereoisomers
threshold 0.3 RMSD threshold for duplicate removal, Å
opt_steps 2000 Maximum optimization steps
convergence_threshold 0.01 Force convergence threshold, eV/Å

Full list: CLI reference · API reference

Upgrading from 2.x

AIMNet2 is now served by the aimnet package rather than bundled .jpt files, and the default AIMNet2 energies differ from 2.x (the registry .pt externalizes D3 dispersion), so conformer rankings may shift slightly. The thermochemistry SDF property S_hartree is now S_hartree_per_K. Python ≥ 3.11 and PyTorch ≥ 2.8 are required. See the migration guide.

Documentation

auto3d.readthedocs.io · Installation · Quickstart · CLI · API · Custom NNPs · Troubleshooting · Notebooks

Citation

@article{liu2022auto3d,
    title={Auto3D: Automatic generation of the low-energy 3D structures with ANI neural network potentials},
    author={Liu, Zhen and Zubatiuk, Tetiana and Roitberg, Adrian and Isayev, Olexandr},
    journal={Journal of Chemical Information and Modeling},
    volume={62},
    number={22},
    pages={5373--5382},
    year={2022},
    publisher={ACS Publications},
    doi={10.1021/acs.jcim.2c00817}
}

Contributing

Issues · Discussions · CONTRIBUTING.md

License

MIT — see LICENSE.

Project links

Data verified by PyPI on Aug 21, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for ilkwonc from gravatar.com ilkwonc Avatar for LiuCMU from gravatar.com LiuCMU

Credits

Author: Zhen Liu

Maintainer: Olexandr Isayev

GitHub Statistics

Data verified by PyPI on Aug 21, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.11

Provides Extra

ani ase dev docs all

Tags

chemistry molecular-dynamics conformer-generation neural-network-potentials cheminformatics drug-discovery

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

auto3d-3.1.0.tar.gz (7.1 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

auto3d-3.1.0-py3-none-any.whl (6.8 MB view details)

Uploaded Python 3

File details

Details for the file auto3d-3.1.0.tar.gz.

File metadata

  • Download URL: auto3d-3.1.0.tar.gz
  • Upload date:
  • Size: 7.1 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for auto3d-3.1.0.tar.gz
Algorithm Hash digest
SHA256 42d9c230b284d258bfc1ba2065bd00cee3795697e03186210a5e0df4cfa733bb
MD5 2468e5125f89fa18043c8f918bd2ceeb
BLAKE2b-256 10cf5ee4bd0a6f915b489011ac53cace162b53faf4b82caaff1be5d81ceb5ee1

See more details on using hashes here.

Provenance

The following attestation bundles were made for auto3d-3.1.0.tar.gz:

Publisher: publish.yml on isayevlab/Auto3D_pkg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file auto3d-3.1.0-py3-none-any.whl.

File metadata

  • Download URL: auto3d-3.1.0-py3-none-any.whl
  • Upload date:
  • Size: 6.8 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for auto3d-3.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 054a12c945b11b9b58332b0ca8ab4352d9a05541e618fc9f906edbb55e4adeb0
MD5 472e286ea831cda31edf25cc4a639872
BLAKE2b-256 33e5a98f2eb31586ab98670f96ba457e288561adb8514a3cb5997d85d7033afc

See more details on using hashes here.

Provenance

The following attestation bundles were made for auto3d-3.1.0-py3-none-any.whl:

Publisher: publish.yml on isayevlab/Auto3D_pkg

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

3.1.0 This release

2 files

3.0.0

2 files

2.3.1

2 files

2.3.0

2 files

2.2.11

1 file

2.2.10

2 files

2.2.9

2 files

2.2.8

2 files

2.2.7

2 files

2.2.6

2 files

2.2.5

2 files

2.2.4

2 files

2.2.3

2 files

2.2.2

2 files

2.2.1

2 files

2.1.0

2 files

2.0.1

2 files

2.0

2 files

1.15

2 files

1.14

2 files

1.13

1 file

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page