Convert CLI Options

This page documents the CLI options for converting molecular structure files between formats. Use chemsmart run convert --help for the complete list.

Basic Command Structure

chemsmart run convert [CONVERT_OPTIONS]

Convert Options

Option

Type

Description

-i, --input

string

Input molecular structure file for single-file conversion

-o, --output

string

Output file path (format is inferred from the extension). Optional for single-file conversion; may be an extension only (e.g. .xyz or xyz) to keep the input basename. When omitted with --input, writes {input_stem}.xyz by default

-d, --directory

string

Directory containing files to convert in batch mode

-t, --filetype

string

Input file type for batch directory conversion (e.g. log, com, gjf, out, inp, xyz, sdf, pdb, cdxml, cdx)

-p, --program

string

Computational program (gaussian or orca). Required when --filetype is out, because both Gaussian and ORCA use this extension

--output-filetype

string

Output file type when --output is not specified (default: xyz). Used for single-file and batch conversion

-z/--no-z, --include-intermediate-structures/--no-include-intermediate-structures

bool

Include all intermediate structures from multi-structure files (default: disabled)

Note

Provide either --input (single-file) or --directory / --filetype (batch), not both.

Single-File Conversion

When --output is omitted, the output path defaults to {input_stem}.xyz in the same directory as the input. Use --output-filetype to change the default extension (e.g. com). You may also pass only an extension to --output (e.g. .mol2 or mol2) to keep the input basename.

Single-file conversion infers the output format from the resolved output path extension:

chemsmart run convert -i molecule.pdb
chemsmart run convert -i molecule.pdb -o .mol2
chemsmart run convert -i molecule.pdb -o molecule.xyz
chemsmart run convert -i molecule.log -o molecule.mol2

Batch Directory Conversion

Convert all matching files in a directory:

chemsmart run convert --directory /path/to/dir --filetype log --output-filetype xyz
chemsmart run convert -d . -t pdb --output-filetype xyz

Directory batch conversion 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.

Output Formats and Conversion

Native writers (Molecule.write) support xyz, extxyz, com, pdb, and cosmorsxyz.

For any other output format, CHEMSMART falls back to Open Babel (via a temporary XYZ intermediate). This is used automatically by the convert CLI when the output extension is not a native writer format:

chemsmart run convert -i water.xyz -o water.mol2
chemsmart run convert -i water.pdb -o water.cml

Note

Because the write fallback uses a temporary XYZ file, charge, multiplicity, and bond connectivity are not carried into Open Babel output formats. Connectivity in the written file is regenerated by Open Babel from geometry.

Open Babel is included in the CHEMSMART conda environment. If you install CHEMSMART via pip and request a non-native output format, install Open Babel separately:

conda install -c conda-forge openbabel

If Open Babel is not installed, CHEMSMART raises an ImportError with installation instructions. Formats that Open Babel itself cannot write raise a ValueError.

Multi-structure conversion with -z / --include-intermediate-structures writes numbered files (basename_1.ext, basename_2.ext, …) rather than overwriting a single output path. This also applies to multi-fragment ChemDraw (.cdx / .cdxml) files; without -z, only the last molecule is written:

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

Note

Read vs write fallbacks: unsupported input extensions try Open Babel first, then ASE (periodic / ASE-only extensions skip Open Babel; see Molecule Input Formats). Unsupported output formats fall back to Open Babel.

Next Steps

For supported input formats and file reading details, see: