qctddft

qctddft is a command-line toolkit for post-processing Time-Dependent Density Functional Theory (TDDFT) calculations from Q-Chem. It is designed to take a workflow from raw output files to interpretable spectral regions and representative geometries, helping connect computed excited-state features to underlying molecular structure.

What it does

qctddft provides an end-to-end analysis workflow for TDDFT datasets:

1. Extract excitation energies and oscillator strengths from Q-Chem output files
2. Generate broadened absorption spectra from extracted states
3. Identify spectral regions such as peaks and shoulders
4. Assign excited states to those spectral regions
5. Cluster structures associated with a selected region to recover representative geometries

Core features

• Parsing of TDDFT output files from Q-Chem
• Spectrum generation using Gaussian broadening
• Region detection using second-derivative analysis
• Hard and fractional assignment of states to spectral regions
• Structural clustering using K-means or hierarchical clustering
• Command-line workflow suitable for batch and HPC environments

Installation

Clone the repository and install it locally:

git clone https://github.com/fr-0zt/qctddft.git
cd qctddft
pip install .

For development or test work:

pip install .[dev]

Requirements

• Python 3.9+
• Q-Chem TDDFT output files
• For structural clustering: corresponding PDB files for the analyzed snapshots

Workflow overview

A typical workflow starts from a directory of Q-Chem output files and ends with representative structures for a selected spectral region.

1. Extract TDDFT data

qctddft extract "path/to/outputs/*.out" --out extracted_data.csv

2. Build a broadened spectrum

qctddft spectrum extracted_data.csv --out spectrum.csv --save-plot

3. Identify spectral regions

qctddft regions spectrum.csv --n_regions 3 --out-csv regions.csv --save

4. Assign states to regions

qctddft assign extracted_data.csv regions.csv --out-prefix assignment_results --fractional

This produces assignment and summary tables for the detected spectral regions.

5. Cluster structures within a region

qctddft cluster assignment_results_state_assignment.csv "path/to/pdbs/*.pdb" --region 1 --n-clusters 5 --select "resname UNK" --out-dir representative_structures

To evaluate the number of clusters before selecting a final value:

qctddft cluster assignment_results_state_assignment.csv "path/to/pdbs/*.pdb" --region 1 --analyze-k

Typical inputs and outputs

Inputs

• Q-Chem output files containing TDDFT results
• CSV files generated by earlier qctddft steps
• PDB structures corresponding to analyzed configurations

Outputs

• Extracted state tables
• Broadened spectrum CSV files and optional plots
• Region definition tables
• Region assignment summaries
• Representative clustered structures for selected spectral regions

Scope and intended use

qctddft is intended for research workflows that analyze ensembles of TDDFT calculations and relate spectral behavior to structural heterogeneity. It is especially useful when many snapshots or configurations must be processed consistently through a single command-line pipeline.

Citation

If this repository contributes to published work, please cite the repository and the version used. A formal software citation can be added here in the future if the package is archived or associated with a manuscript.

Contributing

Contributions, bug reports, and suggestions are welcome through issues or pull requests.

License

This project is released under the MIT License. See LICENSE for details.