Command-Line Interface

Overview

The TQchem command-line interface provides a powerful toolkit for conformer search and molecular structure manipulation. TQchem offers two complementary subcommands:

generate: Quickly generate a few conformers from SMILES strings or XYZ files using RDKit
ttconf: Perform comprehensive conformer search using tensor train optimization with various electronic structure methods

Global Options

All subcommands support the following global options:

-v, --verbosity

Type: Integer (0 or 1)

Default: 1

Description: Control the verbosity of the output.

0: Silent mode (only errors reported)
1: Info mode (standard output with optimization details)

Example usage:

tqchem -v 0 ttconf molecule.xyz

The `generate` Subcommand

Purpose

The generate subcommand provides rapid conformer generation for molecular structures. It is designed for quick prototyping and initial conformer sampling using RDKit’s conformer generation algorithms. Use this when you need a fast initial set of conformers without the global optimization that ttconf provides.

Use Cases:

Convert SMILES strings to 3D molecular structures
Rapidly generate multiple conformers for quick screening
Prepare initial structures for downstream analysis
Generate conformers from existing XYZ files with proper connectivity detection

Options

Input Options

--smiles

Type: String (multiple values accepted)

Default: Empty list

Required: No (either --smiles or --xyz must be provided)

Description: SMILES string(s) to convert to XYZ file(s) and generate conformers for. Multiple SMILES strings can be specified on a single command.

Example:

tqchem generate --smiles "CCO" "CC(C)O"

--xyz

Type: String (multiple values accepted, file paths)

Default: Empty list

Required: No (either --smiles or --xyz must be provided)

Description: Path(s) to XYZ files for which conformers will be generated. Multiple files can be specified.

Example:

tqchem generate --xyz molecule1.xyz molecule2.xyz

Conformer Generation Options

--n_conformers

Type: Integer

Default: 1

Required: No

Description: Number of conformers to generate for each input molecule. The algorithm will attempt to generate this many conformers with conformations distinct above the RMSD threshold.

Constraints: Must be greater than zero. If fewer distinct conformers can be generated below the RMSD threshold than requested, a warning will be issued.

Example:

tqchem generate --smiles "CCO" --n_conformers 10

--rmsd

Type: Float

Default: 0.125 Ångströms

Required: No

Description: Root Mean Square Deviation (RMSD) threshold for atomic positions. Conformers with RMSD values below this threshold relative to existing conformers are considered identical and will be removed. A higher value produces more diverse conformers but may reduce the number generated.

Note: The RMSD calculation is based on heavy atom positions only.

Example:

tqchem generate --smiles "CCO" --rmsd 0.5

Charge Options

--charge

Type: Integer (multiple values accepted)

Default: 0 for all molecules (auto-assigned if not provided)

Required: No (Relevant only for XYZ file input)

Description: Formal charge(s) of the molecule(s). Primarily used when reading from XYZ files to assist with bond type determination. If fewer charges are specified than XYZ files provided, remaining files will default to charge 0 with a warning.

Note: This parameter is automatically handled for SMILES input based on the SMILES string chemistry.

Example:

tqchem generate --xyz mol1.xyz mol2.xyz --charge 0 +1

Output Files

The generate subcommand produces output XYZ files containing the generated conformers:

For SMILES input: {sanitized_smiles}.xyz
For XYZ input: {original_filename}_generated.xyz

Each file contains multiple frames, one for each generated conformer.

Usage Examples

Example 1: Generate 5 conformers from a SMILES string

tqchem generate --smiles "CCO" --n_conformers 5

This generates 5 diverse conformers of ethanol and saves them to CCO.xyz.

Example 2: Generate conformers from multiple SMILES strings

tqchem generate --smiles "C1=CC=CC=C1" "c1ccccc1O" --n_conformers 10

This generates 10 conformers each for benzene and phenol in separate files: C1=CC=CC=C1.xyz and c1ccccc1O.xyz.

Example 3: Generate conformers from XYZ files with custom RMSD threshold

tqchem generate --xyz molecule1.xyz molecule2.xyz --n_conformers 20 --rmsd 0.5

This generates 20 conformers for each molecule with a higher RMSD diversity threshold, producing more varied structures.

Example 4: Generate conformers from charged molecules

tqchem generate --xyz anion.xyz cation.xyz --n_conformers 5 --charge -1 +1

This generates 5 conformers for each molecule, properly handling the specified formal charges.

The `ttconf` Subcommand

Purpose

The ttconf subcommand performs global conformer search and optimization using tensor train-based sampling combined with electronic structure calculations. It is designed for high-accuracy conformer exploration and ensemble generation. Use this when you need rigorous conformer sampling with proper energy-based filtering and ensemble statistics.

Use Cases:

Find the complete conformational ensemble of a molecule
Optimize conformers using semi-empirical methods (GFN-xtb) or force fields
Generate energy-weighted conformer ensembles
Perform implicit solvation calculations
Create conformer libraries for molecular dynamics or docking studies

Positional Arguments

conformers

Type: String (multiple values accepted)

Required: Yes

Description: Paths to conformer files (XYZ format only) or a single SMILES string. Specifies the input molecular structure(s). XYZ files can contain multiple frames (conformers), and multiple XYZ files can be provided as long as they represent different conformations of the same molecule (identical connectivity and atomic composition). All provided conformers are used for initialization of the tensor train.

Valid Inputs:

A single XYZ file (with one or multiple frames)
Multiple XYZ files (each can have one or multiple frames, all representing the same molecule)
A SMILES string (will be used if path does not exist)

Example:

tqchem ttconf molecule.xyz
tqchem ttconf "CCO"
tqchem ttconf conformer1.xyz conformer2.xyz conformer3.xyz

General Options

--name

Type: String

Default: Stem of the first input file (or sanitized SMILES if string input)

Required: No

Description: Prefix for output file names. All result files will use this prefix.

Output Files Generated:

{name}_best_conformer.xyz - Single minimum energy conformer
{name}_ensemble.xyz - Energy-filtered conformer ensemble
{name}_sampled_conformers.xyz - All sampled (unrelaxed) conformers
{name}.csv - Conformer data and energies

Example:

tqchem ttconf molecule.xyz --name "my_molecule"

Objective Function Options

These options define how the energy is calculated and filtered.

Electronic Structure Method

--method

Type: String (choices only)

Default: gfn2-xtb

Required: No

Valid Options:

gfn1-xtb: GFN1 extended tight-binding method (fast, lower accuracy)
gfn2-xtb: GFN2 extended tight-binding method (recommended, good balance)
gfn-ff: GFN force field (very fast, approximate)
amber-ff: AMBER force field (classical, very fast)

Description: Electronic structure method used for energy calculations and optimization. GFN-xtb methods provide semi-empirical quantum mechanical accuracy, while force fields are faster but less accurate. GFN methods automatically enable ensemble optimization.

Example:

tqchem ttconf molecule.xyz --method gfn1-xtb

Molecular Properties

--charge

Type: Integer

Default: 0

Required: No

Description: Formal charge of the molecular system. Primarily relevant for XYZ input files where charge information is not available. This is used by the electronic structure method for proper energy calculation.

Example:

tqchem ttconf molecule.xyz --charge +1

--solvent

Type: String or None

Default: None (vacuum)

Valid Options:

None: Perform calculations in vacuum
water: Implicit solvation in water using GBSA

Required: No

Description: Solvent environment for implicit solvation calculations. When specified, the free energy in solution is calculated using the Generalized Born Surface Area (GBSA) model.

Note: Only compatible with GFN methods.

Example:

tqchem ttconf molecule.xyz --solvent water

Energy Filtering

--filter_type

Type: String (choices only)

Default: energy

Valid Options:

energy: Use absolute energy values
energy difference: Use energy relative to reference energy (ΔE)
boltzmann energy difference: Use Boltzmann-weighted energy differences

Required: No

Description: Method for filtering energies during optimization. Determines how energy values are compared and pruned during the tensor train optimization.

energy: Keeps conformers based on absolute energy (removes only severely strained structures)
energy difference: Normalizes all energies relative to a reference (useful for identifying low-energy conformers)
boltzmann energy difference: Weights pruning by Boltzmann distribution (physically motivated at finite temperature)

Example:

tqchem ttconf molecule.xyz --filter_type "energy difference"

--reference_energy

Type: Float (eV)

Default: None (calculated from initial molecule structure)

Required: No

Description: Reference energy used in energy difference and boltzmann energy difference filter types. If not provided, the energy of the initial input structure is used as the reference. This is useful for comparing multiple runs or using literature reference values.

Example:

tqchem ttconf molecule.xyz --filter_type "energy difference" --reference_energy -42.5

Ensemble Optimization

--ensemble_optimization

Type: Boolean flag (action=”store_true”)

Default: True for GFN methods, False for force fields

Required: No

Description: Enable ensemble optimization mode, which uses CREST’s efficient ensemble-based algorithm. This is automatically activated for GFN methods and provides faster optimization through simultaneous handling of multiple conformers.

Note: Only compatible with GFN-xtb methods. Force field methods ignore this flag.

Example:

tqchem ttconf molecule.xyz --method gfn1-xtb --ensemble_optimization

Optimizer Options

These options control the tensor train optimization algorithm.

--n_sweeps

Type: Integer

Default: 2

Required: No

Description: Number of sweeps through the tensor train during optimization. Each sweep performs a full pass through the tensor train dimensions. More sweeps generally lead to better optimization but increased computational cost. Typically 2-4 sweeps are sufficient.

Example:

tqchem ttconf molecule.xyz --n_sweeps 3

--rank

Type: Integer

Default: 2

Required: No

Description: Rank of the tensor train decomposition. Controls the expressiveness of the tensor train approximation. Higher ranks can represent more complex energy landscapes but increase memory and computational requirements. Typical values: 2-4.

Example:

tqchem ttconf molecule.xyz --rank 3

--threads

Type: Integer

Default: 4

Required: No

Description: Maximum number of CPU threads to use during optimization. Parallelizes conformer generation and energy evaluations. Set to the number of available CPU cores for best performance, or lower for shared systems.

Example:

tqchem ttconf molecule.xyz --threads 8

--seed

Type: Integer

Default: 42

Required: No

Description: Random seed for reproducible conformer sampling. Use the same seed to reproduce identical results. Change the seed to explore different conformer samples.

Example:

tqchem ttconf molecule.xyz --seed 123

--no_initialization

Type: Boolean flag (action=”store_true”)

Default: False (initialization enabled)

Required: No

Description: Prevent initialization of the tensor train with the provided input molecule(s). When not set, the provided conformer(s) are used as starting points for optimization, typically improving results. Use this flag only for testing or when you want purely random initialization.

Example:

tqchem ttconf molecule.xyz --no_initialization

Results Filtering Options

These options control which conformers are included in the output ensemble.

--energy_difference

Type: Float (eV)

Default: 0.26 eV

Required: No

Description: Energy range determining which conformers are included in the output ensemble. Conformers within this energy range of the lowest-energy conformer are retained. The default of 0.26 eV (≈6 kcal/mol) typically captures important conformers while filtering out unlikely high-energy states.

Example:

tqchem ttconf molecule.xyz --energy_difference 0.5

--rmsd_cutoff

Type: Float (Ångströms)

Default: 0.125 Å

Required: No

Description: RMSD threshold for identifying duplicate conformers. When filtering the ensemble, conformers with heavy-atom RMSD below this value relative to a lower-energy conformer are removed as duplicates.

Example:

tqchem ttconf molecule.xyz --rmsd_cutoff 0.25

Internal Coordinates Options

These options control how rotatable bonds are handled and allow customization of dihedral angle grids for different functional groups.

Bond Types and Dihedral Grids

--single_batframe

Type: Boolean flag (action=”store_true”)

Default: False

Description: Use a single Bond-Angle-Torsion (BAT) frame for the entire molecule instead of special coordinate systems for rings. Normally, ring systems are treated with special internal coordinates; this flag forces all atoms to use standard BAT coordinates.

Example:

tqchem ttconf molecule.xyz --single_batframe

--include_amide_bonds

Type: Boolean flag (action=”store_true”)

Default: False

Description: Include amide bonds (C-N single bonds adjacent to C=O) as rotatable bonds. By default, amide bonds are restricted due to partial double-bond character. Use this flag to allow rotation around amide bonds.

Note: Automatically enabled if --amide_grid is specified.

Example:

tqchem ttconf molecule.xyz --include_amide_bonds

Dihedral Angle Grids

The following options specify allowed dihedral angles for different functional groups. When sampling conformers, only specified angles are used. Narrower grids reduce computation time; broader grids explore more conformational space. If not specified, sensible defaults are used.

--amide_grid