Molecule Input Formats

CHEMSMART provides flexible molecule input capabilities, supporting multiple file formats and molecular representations. This page describes the various ways you can create molecules for use in quantum chemistry calculations.

Note

For more information about CHEMSMART’s design and capabilities, see the preprint: https://arxiv.org/abs/2508.20042

Workflow Overview

The following diagram illustrates how different input formats are processed to create molecules for quantum chemistry calculations:

┌──────────────────┐
│  Input Sources   │
└──────────────────┘
        │
        ├─── ASE Atoms
        ├─── Pymatgen Molecule
        ├─── RDKit Molecule
        ├─── File Formats (.xyz, .sdf, .pdb, .com/.log, .inp/.out, .db, .cdx/.cdxml, etc.)
        └─── PubChem queries (by name, CID, or SMILES)
        │
        ▼
┌──────────────────────────────┐
│  Input Processing            │  ──────►  Creates Molecule Object
│  (chemsmart.io)              │           (parses all supported input formats)
└──────────────────────────────┘
        │
        ▼
┌──────────────────┐
│    Molecule      │  ──────►  Central molecular representation
│     Object       │           (symbols, positions, charge, multiplicity)
└──────────────────┘
        │
        ├─────────────────────────────────┐
        ▼                                 ▼
┌──────────────────┐            ┌──────────────────┐
│ chemsmart.jobs   │            │ chemsmart.jobs   │
│ .gaussian.writer │            │   .orca.writer   │
└──────────────────┘            └──────────────────┘
        │                                 │
        ▼                                 ▼
┌──────────────────┐            ┌──────────────────┐
│  .com/.gjf files │            │    .inp files    │
│  (Gaussian, Inc.)│            │      (ORCA)      │
└──────────────────┘            └──────────────────┘

Supported File Formats

Coordinate Files

XYZ Files

Standard XYZ format for atomic coordinates:

# Single structure
chemsmart sub -s server gaussian -p project -f molecule.xyz -c 0 -m 1 opt

# Multi-structure file (select 5th structure)
chemsmart sub -s server gaussian -p project -f molecules.xyz -i 5 -c 0 -m 1 opt

Note

XYZ files do not contain charge or multiplicity information. You must specify these using -c and -m flags.

SDF Files

Structure-Data Format files with 2D or 3D coordinates:

chemsmart sub -s server gaussian -p project -f molecule.sdf -c 0 -m 1 opt

PDB Files

Protein Data Bank (PDB) coordinate files, including single-model structures and multi-model ensembles delimited by MODEL / ENDMDL records:

# Single-model PDB
chemsmart sub -s server gaussian -p project -f molecule.pdb -c 0 -m 1 opt

# Multi-model PDB (select 3rd model)
chemsmart sub -s server gaussian -p project -f ensemble.pdb -i 3 -c 0 -m 1 opt

Gaussian Files

Gaussian Input Files (.com, .gjf)

Gaussian input files contain route, charge, multiplicity, and coordinates:

chemsmart sub -s server gaussian -p project -f input.com opt

Tip

CHEMSMART reads the existing charge and multiplicity from .com files. Override with -c and -m if needed.

Gaussian Output Files (.log, .out)

Use optimized structures from Gaussian output:

# Use last structure from optimization
chemsmart sub -s server gaussian -p project -f opt.log sp

# Use specific structure (e.g., 10th structure from scan)
chemsmart sub -s server gaussian -p project -f scan.log -i 10 sp

ORCA Files

ORCA Input Files (.inp)

ORCA input files with coordinates and calculation settings:

chemsmart sub -s server gaussian -p project -f input.inp opt

ORCA Output Files (.out)

Extract structures from ORCA calculations:

chemsmart sub -s server gaussian -p project -f orca_opt.out sp

xTB Files

xTB Main Output Files (.out)

An xTB calculation writes its results to a directory (containing charges, xtbopt.log, g98.out, and so on). For geometry input you can point -f at the xTB main output file; when given a file path, CHEMSMART automatically resolves it to the parent calculation directory and reads the associated auxiliary files. Each xTB calculation directory must contain exactly one xTB main output.

chemsmart sub -s server gaussian -p project -f co2_ohess/co2_ohess.out sp

CREST Files

A CREST calculation writes its results to a directory (containing crest_conformers.xyz, crest.energies, crest_dynamics.trj, and other auxiliary files).

CREST Ensemble XYZ Files

These are standard single- or multi-frame XYZ files and can be passed directly with -f: crest_best.xyz is the lowest-energy conformer (a single structure) and the usual starting point for follow-up DFT jobs; crest_conformers.xyz is the conformer ensemble sorted by energy, for conformational sampling; and crest_rotamers.xyz is the rotamer ensemble, for cases where rotamers rather than only conformers are needed as geometry input.

# Using Gaussian via the gaussian subcommand: Optimization on CREST best conformer
chemsmart sub -s server gaussian -p project -f crest_best.xyz -c 0 -m 1 opt

# Using Gaussian via the gaussian subcommand: TS optimization on CREST conformer ensemble
chemsmart sub -s server gaussian -p project -f crest_conformers.xyz -c 0 -m 1 crest -j ts

# Using ORCA via the orca subcommand: Single-point calculation on a selected CREST rotamer
chemsmart sub -s server orca -p project -f crest_rotamers.xyz -i 3 -c 0 -m 1 opt

# Visualize an ensemble
chemsmart run mol -f crest_conformers.xyz -i ':' visualize
chemsmart run mol -f crest_rotamers.xyz -i ':' visualize

CREST Dynamics Trajectory File

CREST MD trajectories are saved as crest_dynamics.trj. The trajectory can be inspected with:

chemsmart run mol -f crest_dynamics.trj -i ':' visualize

CREST Optimization Log File

CREST geometry-optimization intermediates are written to crestopt.log. The optimization trajectory can be inspected with:

chemsmart run mol -f crestopt.log -i ':' visualize

ChemDraw Files

ChemDraw XML (.cdxml) and Binary (.cdx) Files

CHEMSMART supports reading molecular structures directly from ChemDraw files, including organometallic complexes with aromatic ligands such as Cp, Cp*, and benzene rings.

# Organic molecule
chemsmart sub -s server gaussian -p project -f molecule.cdxml -c 0 -m 1 opt

# Organometallic complex (charge and multiplicity must be specified explicitly)
chemsmart sub -s server gaussian -p project -f ferrocene.cdxml -c 0 -m 1 opt

Tip

You can submit a Gaussian optimization directly from a ChemDraw file in a single command:

chemsmart sub -s server gaussian -p project -f molecule.cdxml -c 0 -m 1 opt

This will:

Read the molecular structure from the ChemDraw file
Generate 3D coordinates using RDKit’s EmbedMolecule
Create a Gaussian input file with specified charge and multiplicity
Submit the geometry optimization job to the HPC cluster

Note

Both binary (.cdx) and XML-based (.cdxml) ChemDraw formats are supported.
RDKit is used internally to parse ChemDraw files and generate 3D coordinates.
For multi-molecule ChemDraw files, use -i to select a specific molecule when submitting jobs.
3D coordinates are automatically generated from 2D structures.
Reading binary .cdx files requires the Open Babel CLI (obabel on PATH) when RDKit cannot parse the file. This is separate from the Python openbabel / pybel bindings used for generic format conversion. If obabel is not available, save the file as .cdxml instead.
Charge and multiplicity of organometallic complexes are not inferred from the ChemDraw file – always specify -c and -m explicitly.

Example: Multi-molecule ChemDraw file

# Select the 2nd molecule from a ChemDraw file with multiple structures
chemsmart sub -s server gaussian -p project -f molecules.cdxml -i 2 -c 0 -m 1 opt

Warning

Converting multi-fragment ChemDraw files: by default, chemsmart run convert (and FileConverter) writes only the last molecule, consistent with other multi-structure formats. To emit every fragment as numbered files (basename_1.ext, basename_2.ext, …), pass -z / --include-intermediate-structures:

chemsmart run convert -i two_molecules.cdxml -o two_molecules.xyz -z

For full details on organometallic complex support and its restrictions, see ChemDraw Files.

Molecular Databases

CHEMSMART Database Files (.db)

CHEMSMART .db files are produced by the database workflow, typically with chemsmart run database assemble (see Assembling Records). When a CHEMSMART database is used as molecular input, CHEMSMART first selects the requested record, molecule, or structure, then passes the selected geometry, charge, and multiplicity to Gaussian, ORCA, or PyMOL (see Workflow Integration).

Tip

Use chemsmart run database query -f chemsmart.db to list available record indices and IDs before selecting structures from a database.

# By index of the record (last structure by default)
chemsmart sub -s server gaussian -p project -f chemsmart.db --ri 3 opt

# By record ID and structure index
chemsmart sub -s server gaussian -p project -f chemsmart.db --rid a1b2c3d4e5f6 -i 5 sp

# By structure ID
chemsmart sub -s server orca -p project -f chemsmart.db --sid c4d5e6f78a9b ts

# By molecule ID (all structures in the molecule)
chemsmart run mol -f chemsmart.db --mid ABCDEFGHIJKLMN-U visualize

PubChem Integration

Query PubChem directly by name, CID, or SMILES:

# By compound name
chemsmart sub -s server gaussian -p project -P water -c 0 -m 1 -l water opt

# By CID (Compound ID)
chemsmart sub -s server gaussian -p project -P 962 -c 0 -m 1 -l water opt

# By SMILES string
chemsmart sub -s server gaussian -p project -P "O=Cc1ccccc1" -c 0 -m 1 -l benzaldehyde opt

Note

When using -P (PubChem), the -l flag specifies the output filename.
PubChem queries support compound names, CIDs (Compound IDs), and SMILES strings.
SMILES strings are processed by PubChem to retrieve 3D structures and generate coordinates.

ASE Database and Trajectory Files (.db, .traj)

Use structures from ASE database or trajectory files:

# From ASE database
chemsmart sub -s server gaussian -p project -f molecules.db -i 5 -c 0 -m 1 opt

# From ASE trajectory
chemsmart sub -s server gaussian -p project -f md.traj -i 10 -c 0 -m 1 opt

Python Object Integration

CHEMSMART’s Molecule class provides seamless integration with popular Python chemistry libraries:

From ASE Atoms

from ase import Atoms
from chemsmart.io.molecules.structure import Molecule

# Create ASE Atoms object
atoms = Atoms('H2O', positions=[[0, 0, 0], [0, 0, 1], [0, 1, 0]])

# Convert to CHEMSMART Molecule
molecule = Molecule.from_ase_atoms(atoms)

From RDKit Mol

from rdkit import Chem
from rdkit.Chem import AllChem
from chemsmart.io.molecules.structure import Molecule

# Create RDKit molecule from SMILES
rdkit_mol = Chem.MolFromSmiles('CCO')
AllChem.EmbedMolecule(rdkit_mol)

# Convert to CHEMSMART Molecule
molecule = Molecule.from_rdkit_mol(rdkit_mol)

Aromaticity Detection (`is_aromatic`)

The is_aromatic property detects aromaticity by converting the molecule to an RDKit representation and checking whether any atom both carries the aromatic flag and belongs to a ring. This guards against false positives in acyclic molecules (e.g. H₂O, MgI₂) that can arise when the geometry-based bond-order heuristic assigns a bond order of 1.5 to short single bonds.

Note

Known limitations of aromaticity detection:

Bond orders are inferred purely from 3D geometry (interatomic distances), not from an electronic structure calculation. This means the detection is model-dependent and may not match formal aromaticity criteria in all cases.
Edge cases such as the cyclopropenyl cation (aromatic) versus the cyclopropenyl radical (non-aromatic) may not be distinguished correctly, because the outcome depends on how bond orders and electron counts are assigned from the geometry alone.
For borderline or unusual systems (strained rings, metal-organic frameworks, non-Kekulé structures, etc.) the result should be treated as a heuristic estimate rather than a definitive answer.
If precise aromaticity information is required, consider constructing the RDKit molecule directly from a SMILES string or from an output file that encodes explicit bond orders.

From Pymatgen

CHEMSMART molecules can be converted to and from Pymatgen format:

from chemsmart.io.molecules.structure import Molecule

# Convert CHEMSMART Molecule to Pymatgen
molecule = Molecule.from_filepath('input.xyz')
pymatgen_mol = molecule.to_pymatgen()

Note

For converting Pymatgen molecules to CHEMSMART, you can use the ASE Atoms adaptor as an intermediate format.

Best Practices

Charge and Multiplicity

Always specify charge and multiplicity for:

XYZ files
SDF files
PDB files
ASE database/trajectory files
PubChem queries
ChemDraw files

# Correct usage with charge and multiplicity
chemsmart sub -s server gaussian -p project -f molecule.xyz -c -1 -m 2 opt

Structure Selection

For multi-structure files, use -i to select a specific structure:

# Use 1-based indexing
chemsmart sub -s server gaussian -p project -f scan.log -i 15 sp

Warning

CHEMSMART uses 1-based indexing to match most molecular visualization software, unlike Python’s 0-based indexing.

File Format Auto-Detection

CHEMSMART automatically detects file formats based on extensions:

.xyz → XYZ format
.sdf → SDF format
.pdb → PDB format
.com, .gjf → Gaussian input
.log → Gaussian output
.inp → ORCA input
.out → Gaussian/ORCA/xTB output (auto-detected by reading file header)
.cdx, .cdxml → ChemDraw format
.db → CHEMSMART/ASE database (auto-detected by validating the database schema)
.traj → ASE trajectory

Note

For .out files, CHEMSMART automatically detects whether the file is from Gaussian, ORCA, or xTB by examining the file header. If detection fails, an error will be raised indicating the unsupported format. For xTB, the .out file is resolved to its parent calculation directory so that the associated output files can be read.

For unsupported extensions, CHEMSMART first tries Open Babel (preferred for molecular formats such as .mol2, .smi, .cml, .mol). If Open Babel cannot read the file, CHEMSMART falls back to ASE. Periodic / ASE-specific extensions (.traj, .cif, .cfg, .db, VASP/POSCAR, .gen, .castep, .xsf, .extxyz, …) skip Open Babel and go straight to ASE, because Open Babel either cannot read them or silently drops cell / PBC information.

Directory batch conversion (--directory + --filetype) still uses a fixed whitelist (log, com, gjf, out, inp, xyz, sdf, pdb, cdxml, cdx). Formats such as .mol2 / .smi are available via single-file convert (-i / -o) only. See Convert CLI Options for convert CLI options and output formats.

Note

Open Babel read limits: the Open Babel → Molecule path round-trips geometry through XYZ, so bond orders, residue metadata, and atom typing are not preserved. Non-zero formal charge and spin multiplicity are taken from Open Babel when available; neutral charge is left as None. Zero-dimensional inputs (e.g. SMILES) are expanded with Open Babel make3D() — coordinates are a force-field guess, not experimental geometry. If make3D fails, CHEMSMART logs a warning and may still return a molecule with incomplete 3D coordinates.

Molecule Input Formats

Workflow Overview

Supported File Formats

Coordinate Files

XYZ Files

SDF Files

PDB Files

Gaussian Files

Gaussian Input Files (.com, .gjf)

Gaussian Output Files (.log, .out)

ORCA Files

ORCA Input Files (.inp)

ORCA Output Files (.out)

xTB Files

xTB Main Output Files (.out)

CREST Files

CREST Ensemble XYZ Files

CREST Dynamics Trajectory File

CREST Optimization Log File

ChemDraw Files

ChemDraw XML (.cdxml) and Binary (.cdx) Files

Molecular Databases

CHEMSMART Database Files (.db)

PubChem Integration

ASE Database and Trajectory Files (.db, .traj)

Python Object Integration

From ASE Atoms

From RDKit Mol

Aromaticity Detection (is_aromatic)

From Pymatgen

Best Practices

Charge and Multiplicity

Structure Selection

File Format Auto-Detection

See Also

Aromaticity Detection (`is_aromatic`)