Usage

An smi or SDF file that stores the molecules is needed as the input for the package. You can find example input files in the example/files folder. You can import Auto3D as a library in any Python script, or run Auto3D through the command line interface (CLI). They are equivalent in finding the low-energy 3D conformers.

Using Auto3D as a Python library

If you just have a handful of SMILES, it’s easy to use the smiles2mols function. It is a handy tool for finding the low-energy conformers for a list of SMILES. Compared with the main function, it sacrifices efficiency for convenience because smiles2mols uses only 1 process. Both the input and output are returned as variables within Python. It’s recommended only when the number of SMILES is less than 150; otherwise using Auto3DOptions with main will be faster.

from rdkit import Chem
from Auto3D import Auto3DOptions, smiles2mols

smiles = ['CCNCC', 'O=C(C1=CC=CO1)N2CCNCC2']
config = Auto3DOptions(k=1, use_gpu=False)
mols = smiles2mols(smiles, config)

# Get the energy and atomic positions from the mol objects
for mol in mols:
   print(mol.GetProp('_Name'))
   print('Energy: ', mol.GetProp('E_tot'))  # unit: Hartree
   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}')

If you have a large number of molecules, using Auto3DOptions with the main function is recommended. It’s suitable for large inputs and stores the 3D structures in a file with the name <input_file_name>_3d.sdf, of which the path will be printed when auto3d finishes running. Note that the smi file can be replaced with an SDF file, which means Auto3D will search for low-energy conformers starting from a given geometry. Because the main function uses multiprocessing, it has to be called in a if __name__ == "__main__": block.

from Auto3D import Auto3DOptions, main

if __name__ == "__main__":
    input_path = "example/files/smiles.smi"  # This can also be an SDF file
    config = Auto3DOptions(path=input_path, k=1)  # Configure Auto3D parameters
    out = main(config)  # Run Auto3D and get output path

Using Auto3D in a terminal command line

Auto3D provides a modern CLI with subcommands. The main command is run:

auto3d run smiles.smi --k=1

You can also use a YAML configuration file:

auto3d run smiles.smi -c config.yaml

CLI Subcommands

The CLI provides several subcommands for different tasks:

# Generate conformers (main workflow)
auto3d run input.smi --k=1
auto3d run input.smi --window=5.0 --engine AIMNET

# Configuration management
auto3d config init                    # Create a template config file
auto3d config init -o my_config.yaml  # Custom output path
auto3d config show config.yaml        # Display config with syntax highlighting

# Model information
auto3d models list                    # List available NNP models
auto3d models info AIMNET             # Show details about a specific model

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

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

Shell Completion

Enable tab completion for bash, zsh, or fish:

# Bash (add to ~/.bashrc for persistence)
auto3d --install-completion bash

# Zsh (add to ~/.zshrc for persistence)
auto3d --install-completion zsh

# Fish
auto3d --install-completion fish

After installation, restart your shell or source the config file. Then you can use tab completion for commands, options, and file paths.

Legacy YAML Mode

For backwards compatibility, the old YAML-only invocation still works:

auto3d parameters.yaml

There are example files present at example/files

The above examples will do the same thing: run Auto3D and keep 1 lowest-energy structure for each SMILES in the input file. It uses RDKit as the isomer engine and AIMNET as the optimizing engine by default. If you want to keep n structures for each SMILES, simply set k=n or --k=n. You can also keep structures that are within x kcal/mol from the lowest-energy structure for each SMILES if you replace k=1 with window=x.

Note

AIMNet2 clarification: The default model in Auto3D is AIMNet2 since version 2.2.1. If you specify optimizing_engine="AIMNET", it uses AIMNet2. The old AIMNet model has been deprecated since Auto3D 2.2.1.

When the running process finishes, there will be a folder with the name of year-date-time. In the folder, you can find an SDF file containing the optimized low-energy 3D structures for the input SMILES. There is also a log file that records the input parameters and running metadata.

Wrapper functions

Auto3D provides wrapper functions for single point energy calculation, geometry optimization and thermodynamic analysis. Please see the example folder for details.

Parameters in Auto3D

For Auto3D, the Python package and CLI share the same set of parameters. Please note that -- is only required for CLI. For example, to use ANI2x as the optimizing engine, you need the following block if you are writing a custom Python script:

from Auto3D import Auto3DOptions, main

if __name__ == "__main__":
    input_path = "example/files/smiles.smi"
    config = Auto3DOptions(path=input_path, k=1, optimizing_engine="ANI2x")
    out = main(config)

You need the following block if you use the CLI:

auto3D "example/files/smiles.smi" --k=1 --optimizing_engine="ANI2x"

Category	Type	Name	Explanation
	required argument	path	A path of `.smi` or `.SDF` file to store all molecules and IDs.
ranking	required argument	–k	Outputs the top-k structures for each molecule. Only one of `--k` and `--window` need to be specified.
ranking	required argument	–window	Outputs the structures whose energies are within a window (kcal/mol) from the lowest energy. Only one of `--k` and `--window` need to be specified.
job segmentation	optional argument	–memory	The RAM size assigned to Auto3D (unit GB). By default `None`, and Auto3D can automatically detect the RAM size in the system.
job segmentation	optional argument	–capacity	By default, 42. This is the number of molecules that each 1 GB of memory can handle.
isomer enumeration	optional argument	–enumerate_tautomer	By default, False. When True, enumerate tautomers for the input.
isomer enumeration	optional argument	–tauto_engine	By default, rdkit. Programs to enumerate tautomers, either ‘rdkit’ or ‘oechem’. This argument only works when `--enumerate_tautomer=True`.
isomer enumeration	optional argument	–isomer_engine	By default, rdkit. The program for generating 3D conformers for each molecule. This parameter is either rdkit or omega. RDKit is free for everyone, while Omega requires a license.
isomer enumeration	optional argument	–max_confs	Maximum number of conformers for each configuration of the molecule. The default number depends on the isomer engine: up to 1000 conformers will be generated for each molecule if isomer engine is omega; for rdkit, it’s calculated as 8.481*(num_rotatable_bonds^1.642).
isomer enumeration	optional argument	–enumerate_isomer	By default, True. When True, unspecified cis/trans and R/S centers are enumerated.
isomer enumeration	optional argument	–mode_oe	By default, classic. The mode that omega program will take. It can be either ‘classic’ or ‘macrocycle’. Only works when `--isomer_engine=omega`.
isomer enumeration	optional argument	–mpi_np	By default, 4. The number of CPU cores for the isomer generation step.
optimization	optional argument	–optimizing_engine	By default, AIMNET. Choose either ‘ANI2x’, ‘ANI2xt’, or ‘AIMNET’ for energy calculation and geometry optimization. Can also be a path to a custom NNP model.
optimization	optional argument	–use_gpu	By default, True. If True, the program will use GPU.
optimization	optional argument	–gpu_idx	By default, 0. If you want to use multiple GPUs, specify the list of GPU indexes. For example, `[0, 1]`. Only works when `--use_gpu=True`.
optimization	optional argument	–opt_steps	By default, 2000. Maximum optimization steps for each structure.
optimization	optional argument	–convergence_threshold	By default, 0.01 eV/A. Optimization is considered as converged if maximum force is below this threshold.
optimization	optional argument	–patience	If the force does not decrease for a continuous patience steps, the conformer will drop out of the optimization loop. By default, 250.
optimization	optional argument	–batchsize_atoms	The number of atoms in 1 optimization batch per 1GB memory, default=1024.
optimization	optional argument	–allow_tf32	By default, False. Enable TF32 for faster computation on Ampere+ GPUs (slightly less precise).
duplicate removing	optional argument	–threshold	By default, 0.3. If the RMSD between two conformers is within the threshold, they are considered as duplicates. One of them will be removed. Duplicate removal is executed after conformer enumeration and geometry optimization.
housekeeping	optional argument	–verbose	By default, False. When True, save all metadata while running.
housekeeping	optional argument	–job_name	A folder that stores all the results. By default, the name is the current date and time.