======================
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:

.. code-block:: bash

   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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**

.. code-block:: bash

   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**

.. code-block:: bash

   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**

.. code-block:: bash

   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**

.. code-block:: bash

   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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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**:

  .. code-block:: bash

     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``
  **Type**: Float (multiple values accepted, degrees)

  **Default**: [0.0, 180.0]

  **Description**: Allowed dihedral values for amide bonds. Only used if amide bonds are rotatable (via ``--include_amide_bonds``).

  **Example**:

  .. code-block:: bash

     tqchem ttconf molecule.xyz --include_amide_bonds --amide_grid 0.0 180.0

``--amino_grid``
  **Type**: Float (multiple values accepted, degrees)

  **Default**: [0, 60, 120, 180, 240, 300]

  **Description**: Allowed dihedral values for amino bonds (C-N bonds on amines).

  **Example**:

  .. code-block:: bash

     tqchem ttconf molecule.xyz --amino_grid 0 60 120 180 240 300

``--alkane_grid``
  **Type**: Float (multiple values accepted, degrees)

  **Default**: [0, 60, 120, 180, 240, 300]

  **Description**: Allowed dihedral values for alkane C-C bonds.

  **Example**:

  .. code-block:: bash

     tqchem ttconf molecule.xyz --alkane_grid 0 60 120 180 240 300

``--t_butyl_grid``
  **Type**: Float (multiple values accepted, degrees)

  **Default**: [0.0, 60.0]

  **Description**: Allowed dihedral values for tert-butyl groups (restricted rotation).

  **Example**:

  .. code-block:: bash

     tqchem ttconf molecule.xyz --t_butyl_grid 0.0 60.0 120.0

``--iso_propyl_grid``
  **Type**: Float (multiple values accepted, degrees)

  **Default**: [0.0, 60.0, 120.0]

  **Description**: Allowed dihedral values for isopropyl groups.

  **Example**:

  .. code-block:: bash

     tqchem ttconf molecule.xyz --iso_propyl_grid 0.0 60.0 120.0

``--chalcogen_grid``
  **Type**: Float (multiple values accepted, degrees)

  **Default**: [0, 60, 120, 180, 240, 300]

  **Description**: Allowed dihedral values for chalcogen bonds (S-C, O-C bonds).

  **Example**:

  .. code-block:: bash

     tqchem ttconf molecule.xyz --chalcogen_grid 0 60 120 180 240 300

``--default_grid``
  **Type**: Float (multiple values accepted, degrees)

  **Default**: [0, 30, 60, 90, 120, 150, 180, 210, 240, 270, 300, 330]

  **Description**: Allowed dihedral values for all rotatable bonds not covered by specific bond-type grids. This is the most comprehensive grid and is used as a default for unknown bond types.

  **Example**:

  .. code-block:: bash

     tqchem ttconf molecule.xyz --default_grid 0 30 60 90 120 150 180 210 240 270 300 330

``--overwrite_grids``
  **Type**: Float (multiple values accepted, degrees)

  **Default**: None

  **Required**: No

  **Description**: Overwrite all bond-specific grids with this single grid. Useful for quickly changing dihedral sampling across the entire molecule. When specified, all bonds use this grid regardless of their type.

  **Example**:

  .. code-block:: bash

     tqchem ttconf molecule.xyz --overwrite_grids 0 90 180 270

Usage Examples
--------------

**Example 1: Simple conformer search with default settings**

.. code-block:: bash

   tqchem ttconf COCCNC

This performs conformer search on the SMILES string ``COCCNC`` using GFN2-xtb method with default parameters. Results are saved with prefix ``COCCNC`` (or sanitized version).

**Example 2: Conformer search from file with multiple input conformers**

.. code-block:: bash

   tqchem ttconf molecule.xyz --name "mycompound" --n_sweeps 3

Uses the provided XYZ file as initial structure, performs 3 sweeps through the tensor train, and saves results with prefix ``mycompound``.

**Example 3: Conformer search with quantum mechanical optimization**

.. code-block:: bash

   tqchem ttconf "C1=CC=CC=C1" --method gfn1-xtb --threads 8 --rank 3

Optimizes the benzene conformer with GFN1-xtb (faster than GFN2) using 8 threads and rank-3 tensor train approximation.

**Example 4: Solvation-aware conformer search**

.. code-block:: bash

   tqchem ttconf molecule.xyz --method gfn2-xtb --solvent water --energy_difference 0.5

Performs conformer search in implicit water solvent with a wider energy window (0.5 eV), useful for identifying hydrated conformers.

**Example 5: Custom dihedral sampling with restricted rotation**

.. code-block:: bash

   tqchem ttconf molecule.xyz --default_grid 0 60 120 180 240 300 --t_butyl_grid 0.0 60.0

Uses 60-degree sampling for most bonds but restricts tert-butyl rotation to 0° and 60°.

**Example 6: Minimal computation with force field**

.. code-block:: bash

   tqchem ttconf molecule.xyz --method gfn-ff --rank 2 --n_sweeps 1 --threads 2

Fast conformer search using GFN force field with minimal computational resources.

**Example 7: Comprehensive ensemble with multiple metrics**

.. code-block:: bash

   tqchem ttconf conformer1.xyz conformer2.xyz --method gfn2-xtb --ensemble_optimization --energy_difference 1.0 --rmsd_cutoff 0.5

Initializes optimization with multiple input conformers, uses ensemble optimization, and includes conformers up to 1.0 eV above the minimum with 0.5 Å RMSD filtering.

**Example 8: Verbose output with custom settings**

.. code-block:: bash

   tqchem -v 1 ttconf molecule.xyz --method gfn2-xtb --seed 12345 --name "optimized"

Runs with full verbosity, custom random seed for reproducibility, and named output files.

**Example 9: Amide rotation exploration**

.. code-block:: bash

   tqchem ttconf peptide.xyz --include_amide_bonds --amide_grid 0.0 180.0 --default_grid 0 60 120 180 240 300

Allows rotation of amide bonds (restricted to 0° and 180°, typical for amides) while using standard sampling for other bonds.

**Example 10: High-precision exploration**

.. code-block:: bash

   tqchem ttconf molecule.xyz --method gfn2-xtb --rank 4 --n_sweeps 4 --threads 16 --seed 42 --energy_difference 0.26 --rmsd_cutoff 0.125

Comprehensive conformer search with high tensor train rank, multiple sweeps, many threads, and strict energy/RMSD filtering for high-accuracy ensemble.

Output Files
============

The TQchem CLI produces different output files depending on the subcommand used.

Generate Subcommand Output
---------------------------

The ``generate`` subcommand produces a single XYZ file per input molecule:

- From SMILES: ``{sanitized_smiles}.xyz``
- From XYZ: ``{original_filename}_generated.xyz``

Each file contains multiple frames representing different conformers.

TTconf Subcommand Output
-------------------------

The ``ttconf`` subcommand produces four output files (using the name specified or derived from input):

1. ``{name}_best_conformer.xyz``
   Single frame containing only the minimum-energy conformer found. Useful for visualization or use as a single reference structure.

2. ``{name}_ensemble.xyz``
   Multiple frames containing all conformers within the specified ``--energy_difference`` window and meeting the ``--rmsd_cutoff`` criterion. This is the main ensemble for statistical analysis.

3. ``{name}_sampled_conformers.xyz``
   All conformers sampled during optimization before energy-based filtering. Useful for understanding the complete sampling and diagnosing sampling issues.

4. ``{name}.csv``
   Comma-separated values file containing numerical data for each sampled conformer, including energies, RMSD values, and other metrics. Useful for analysis and visualization in external tools.

Getting Help
============

Display help for the main program:

.. code-block:: bash

   tqchem -h

Display help for the ``generate`` subcommand:

.. code-block:: bash

   tqchem generate -h

Display help for the ``ttconf`` subcommand:

.. code-block:: bash

   tqchem ttconf -h

Citation
========

If you use TQchem in your research, please cite:

.. code-block:: bibtex

   @misc{ttconf2024,
       title = {Tensor Train Optimization for Conformational Sampling of Organic Molecules},
       url = {http://dx.doi.org/10.26434/chemrxiv-2024-jjns1},
       doi = {10.26434/chemrxiv-2024-jjns1},
       author = {Zurek, Christopher and Mallaev, Ruslan A. and Paul, Alexander and van Staalduinen, Nils and Pracht, Philipp and Ellerbrock, Roman and Bannwarth, Christoph},
       year = {2024},
   }