DOCSEARCHbyAlgolia
Submit Docs

Auto3D

repository·main·Indexed 42 days ago

https://github.com/isayevlab/auto3d_pkg

A tool for generating low-energy 3D conformers from SMILES or SDF inputs. Auto3D automates tautomer and stereoisomer enumeration, embedding, and optimization using neural network potentials such as AIMNet2, ANI2x, and ANI2xt. Version 3.1.1 features a dataclass-based API via Auto3DOptions and provides CLI commands for geometry optimization, single-point energy calculations, and thermochemistry via ASE support.

Tokens
80.5K
Snippets
253
Records
336
Agent score
49%

What's inside Auto3D

  1. Introduction to Auto3D

    main

    Auto3D is a Python package designed to generate low-energy conformers from SMILES or SDF inputs. It automates several key molecular modeling steps:

    • Stereoisomer enumeration and duplicate filtering: Identifying and managing different stereoisomers.
    • 3D building: Constructing initial 3D structures.
    • Geometry optimization and ranking: Performing fast optimization and ranking using ANI and AIMNet neural network atomistic potentials.

    Auto3D can be used in two ways:

    1. As a Python library imported into your scripts.
    2. As a Command Line Interface (CLI) tool executed from the terminal.

  2. What is Auto3D?

    main

    Auto3D is a Python package designed to generate low-energy conformers from SMILES or SDF inputs. It automates several stages of the molecular modeling pipeline, including:

    • Stereoisomer enumeration and duplicate filtering.
    • 3D building of molecular structures.
    • Fast geometry optimization and ranking using neural network atomistic potentials (specifically ANI and AIMNet).

    Auto3D can be used either as a Python library or executed directly from the terminal.

  3. Identify transition states via imaginary mode properties

    main

    Auto3D 3.0 uses Eckart/Sayvetz projection to remove translation and rotation from the Hessian before analysis. It then identifies transition states based on the remaining vibrational spectrum.

    New SD Properties for Transition States:

    • N_imaginary_modes: Count of imaginary vibrational modes (excluding translation/rotation).
    • Max_imaginary_mode_cm-1: Magnitude of the largest imaginary mode in cm-1.
    • Is_transition_state: True if Max_imaginary_mode_cm-1 is $\ge$ 50 cm-1.

    Note: If Is_transition_state is True, the record will also have Thermo_failed = "transition_state" to prevent it from being caught by standard 'success' filters.

  4. Implement a Custom Neural Network Potential (NNP)

    main

    Auto3D allows using custom PyTorch NNP models. Your model must implement a specific interface where it returns energies only (Auto3D derives forces automatically).

    Required Interface Requirements:

    1. Attributes: The model instance must have coord_pad (float) and species_pad (int) attributes to handle padding during serialization (e.g., torch.jit.save).
    2. Forward Method Signature: forward(species: torch.Tensor, coords: torch.Tensor, charges: torch.Tensor) -> torch.Tensor
      • species: Shape (batch_size, max_atoms), atomic numbers padded with species_pad.
      • coords: Shape (batch_size, max_atoms, 3), coordinates in Angstroms.
      • charges: Shape (batch_size,), total molecular charges.
      • Returns: Tensor of shape (batch_size,) containing energies in eV.

    Usage:

    • CLI: Pass the path to the .pt file using --engine=/path/to/model.pt.
    • Python API: Pass the path to the .pt file to optimizing_engine in Auto3DOptions.
    import torch

class MyNNP(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.coord_pad = 0.0     # Fill value for unused coordinate slots
        self.species_pad = -1    # Fill value for unused species slots

    def forward(
        self, 
        species: torch.Tensor,    # Shape: (batch_size, max_atoms)
        coords: torch.Tensor,     # Shape: (batch_size, max_atoms, 3)
        charges: torch.Tensor,     # Shape: (batch_size,)
    ) -> torch.Tensor:
        # ... implementation ...
        return energies  # Shape: (batch_size,) in eV

  5. Handle R-group (*) and dummy atoms in custom NNPs

    main

    In Auto3D 3.0, the AIMNet2Adapter was updated to use an explicit atom_mask from batch_opt.padding.pad_from_mols to prevent dummy atoms (like R-group * atoms) from being treated as real species.

    Important for Custom NNP Developers: If you maintain a custom Neural Network Potential (NNP), ensure your model does not use species_pad = 0 if you use 0-based species indices. Using 0 as a padding value can cause the optimizer to zero out forces on real atoms with index 0, leading to incorrect geometries. Use -1 for species_pad to ensure it is always safe.

  6. Implement a custom Neural Network Potential (NNP)

    main

    To use a custom potential within Auto3D (e.g., for tautomer ranking or general workflows), you must implement the CustomNNP contract.

    Crucial Implementation Detail: Your model's forward method must follow the signature forward(species, coords, charges) -> energies.

    Note that the argument order is species first, followed by coords and charges, returning only energies. This is the mirror image of Auto3D's internal adapter interface, and getting this order wrong will cause confusing failures.

    # Conceptual implementation of the CustomNNP contract
class MyCustomNNP:
    def forward(self, species, coords, charges) -> energies:
        # Implementation logic
        pass

  7. Compare energies of stereoisomers

    main

    After generating 3D structures with Auto3D, you can compare the relative energies of the resulting isomers.

    Key Physical Principles:

    • Enantiomers: In a vacuum, enantiomers should have identical energies.
    • Diastereomers: These have different physical properties and different energies.
    • E/Z Isomers: Geometric isomers around double bonds typically have different energies.

    Auto3D output files (SDF format) contain energy properties such as E_hartree or E_tot. You can extract these to rank isomers by stability.

    from rdkit import Chem
import pandas as pd

def compare_stereoisomer_energies(sdf_path):
    mols = list(Chem.SDMolSupplier(sdf_path, removeHs=False))
    data = []
    for mol in mols:
        if mol is None: continue
        name = mol.GetProp("_Name")
        
        # Extract energy (handling different possible property keys)
        if mol.HasProp("E_hartree"):
            e = float(mol.GetProp("E_hartree"))
        elif mol.HasProp("E_tot"):
            e = float(mol.GetProp("E_tot"))
        else:
            continue

        # Extract stereochemistry tags
        centers = Chem.FindMolChiralCenters(mol)
        stereo = "/".join([tag for _, tag in centers])

        data.append({"Name": name, "Stereo": stereo, "E_hartree": e})

    df = pd.DataFrame(data)
    # Convert Hartree to kcal/mol relative to the lowest energy isomer
    df["E_kcal"] = (df["E_hartree"] - df["E_hartree"].min()) * 627.509
    return df.sort_values("E_kcal")

  8. Understanding AIMNet2 in Auto3D

    main

    Since version 2.2.1, AIMNet2 is the default model used by Auto3D.

    • To use AIMNet2, specify optimizing_engine="AIMNET" in your configuration.
    • The original (deprecated) AIMNet model is no longer the default.
    • You can access specialized AIMNet2 registry models (such as aimnet2-2025, aimnet2-nse, or aimnet2-pd) by using the command auto3d models list to see available options.

  9. Understand the Auto3D conda dependency strategy (v3.1.1+)

    main

    Starting from version 3.1.1, the Auto3D conda recipe uses a hybrid dependency model to ensure compatibility with conda-forge requirements while maintaining functionality:

    1. Conda-native dependencies: torchani and ase are included in requirements.run. This ensures that users get working optimization engines (ANI2x/ANI2xt) and thermochemistry APIs immediately upon conda install without extra steps.
    2. Pip-managed dependencies: aimnet is excluded from the conda recipe because its dependency nvalchemi-toolkit-ops is pip-only. To use AIMNet2 engines, users should run pip install aimnet within their conda environment after installation.
    3. Architecture: The package is marked noarch: python, meaning a single build serves all platforms. Compiled dependencies like pytorch and rdkit are resolved at install time.

  11. Understand Auto3D output files and properties

    main

    Auto3D outputs results into a timestamped directory containing:

    • molecules_out.sdf: The final optimized conformers.
    • Auto3D.log: The processing log.

    SDF File Properties

    The output SDF file includes the following properties:

    • _Name: The molecule name.
    • ID: A stable identifier.
    • E_tot or E_tot(Hartree): Total energy in Hartree.
    • E_rel(kcal/mol): Relative energy in kcal/mol.

    Note: The input SMILES string is not written to the output SDF.

    Reading output in Python (RDKit)

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

  12. Choose an Auto3D engine (Neural Network Potentials)

    main

    Auto3D supports three primary engines. Choose based on your molecule type and speed requirements.

    ModelBest ForSpeedElements
    AIMNETGeneral use, charged moleculesFast (single model)H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I
    ANI2xOrganic moleculesSlowest (8-model ensemble)H, C, N, O, F, S, Cl
    ANI2xtTautomers, screeningFast (single model)H, C, N, O, F, S, Cl

    Important Notes:

    • ANI2x is slower because it loads the full 8-model ensemble from torchani.
    • ANI2x and ANI2xt require the ani extra: pip install "Auto3D[ani]".
    • AIMNET supports specific registry models (e.g., aimnet2-2025, aimnet2-nse) which download to ~/.cache/aimnet. Use auto3d models list to view available models.