automol

automol is a Python library for working with molecular geometries. It centers on a single Geometry model (atomic symbols, Cartesian coordinates, charge, and spin) and builds identity generation (InChI, SMILES, ...), 3D visualization, and RDKit/ASE interoperability on top of it.

See the documentation for API reference.

Installation

automol is built and distributed with Pixi. In another Pixi-managed project:

pixi add --channel avcopan automol

For local development, see Contributing.

Usage

Geometry

Every feature builds on the single Geometry model — atomic symbols, Cartesian coordinates, charge, and spin:

from automol import geom, Geometry

water = Geometry(
    symbols=["O", "H", "H"],
    coordinates=[[0.0, 0.0, 0.0], [0.0, 0.0, 0.96], [0.93, 0.0, -0.24]],
    charge=0,
    spin=0,
)

com = geom.center_of_mass(water)

Identity generation (InChI, SMILES)

from automol import Algorithm, Identity

inchi = Identity.from_geometry(water, algorithm=Algorithm.RDKIT_INCHI)
print(inchi.value)  # "InChI=1S/H2O/h1H2"

smiles = Identity.from_geometry(water, algorithm=Algorithm.RDKIT_SMILES)
print(smiles.value)  # "O"

RDKit interoperability

automol.rd brings RDKit functions to the project, without knowing anything about the core Geometry model itself:

from automol import geom, rd

mol = rd.mol.from_smiles("O")
geo = geom.from_rdkit_mol(mol)

Conversions between Geometry and other cheminformatic packages (e.g., RDKit, ASE, ...) are maintained by automol.geom and modules wrapping the external packages are agnostic to automol.

Visualization

from automol import View

# Visualization (e.g. in a Jupyter notebook)
view = View()
view.add_geometry(water, label=True)

Geometry also supports inlay rendering, providing a View() and xyz-formatted block:

water
# Shows a 3D rendering + xyz-formatted block.

See the documentation for more on geometries, identity generation, visualization, and interoperability with RDKit/ASE.

Architecture

automol is organized as a strict layer stack (ident → geom → rd → utils), enforced by import-linter, with each core data model owned by the module that defines it — external-library bridges (like the RDKit interop above) live in consuming sub-packages rather than in the core models themselves. See Contributing for the full architectural rationale.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. See Contributing for coding standards and workflow.

License

This project is licensed under the MIT License.