ThermoScreening

ThermoScreening calculates thermochemical properties for molecular systems and provides a foundation for screening molecule sets. It currently supports thermochemistry workflows from DFTB+ inputs and exposes Python APIs for reading coordinates, parsing vibrational data, and running thermodynamic post-processing.

Documentation

The documentation is published at https://molarverse.github.io/ThermoScreening/.

It (installation, usage, configuration, and the API reference) is built with Sphinx from the docs/ directory, and you can also build it locally:

python -m pip install -e ".[docs]"
python -m sphinx -b html docs docs/_build/html   # open docs/_build/html/index.html

Features

• Thermochemistry calculations for molecular systems
• DFTB+ geometry optimization, Hessian, and normal-mode integration
• Stepwise and overall reference-calibrated reduction potentials
• Readers for DFTB+ .gen, XYZ, and vibrational frequency files
• Runtime type checking for public API calls
• Test coverage for parsing, thermochemistry, and optional DFTB+ execution paths

Installation

Install the released package:

python -m pip install thermoscreening

For a complete environment with DFTB+, native xTB, and tblite:

conda create -n thermoscreening -c conda-forge \
    python=3.12 dftbplus xtb tblite-python pip
conda activate thermoscreening
python -m pip install thermoscreening

From a source checkout, the equivalent development environment is:

conda env create -f environment.yml
conda activate thermoscreening

Run thermo doctor to report the usable engines, or check one explicitly with thermo doctor --engine dftb+.

DFTB+ Setup

DFTB+ calculations require two external pieces:

1. The dftb+ and modes executables on PATH.
2. Slater-Koster parameter files downloaded separately from DFTB.org.

Install DFTB+ with Conda if it is not already available:

conda install -c conda-forge dftbplus

Download the default 3ob-3-1 Slater-Koster files into the automatically discovered user-local directory:

thermo setup-dftb

Verify the setup with:

thermo doctor

ThermoScreening does not vendor Slater-Koster files. For custom installations, override the discovered directory with DFTB_PREFIX or pass slako_dir explicitly:

from ThermoScreening.thermo.api import dftbplus_thermo

thermo = dftbplus_thermo(
    atoms,
    slako_dir="/path/to/3ob-3-1/",
)

The bundled DFTB+ parameters were removed from the repository because they are large, independently licensed scientific data. Keeping them external makes the package smaller and keeps parameter-set licensing explicit.

Usage

Run thermochemistry from an input file with the command-line entry point:

thermo run path/to/thermo.in

The historic thermo path/to/thermo.in form remains supported.

Run a complete reference-calibrated redox screen locally or as a Slurm array:

thermo redox molecules.csv --engine xtb-cli --solvent acetonitrile -o redox
thermo slurm --tasks 32 --submit -- redox molecules.csv -o redox

Use the Python API when integrating ThermoScreening into another workflow:

from ThermoScreening.thermo.api import run_thermo

thermo = run_thermo(
    vibrational_frequencies,
    coord_file="geo_opt.xyz",
    temperature=298.15,
    pressure=101325,
    energy=electronic_energy,
    engine="dftb+",
)

print(thermo.total_gibbs_free_energy())

Testing

Run the full test suite:

python -m pytest -q

Reproduce the published DFTB/3ob/COSMO anthraquinone potentials from the raw Zenodo data:

python scripts/validate_anthraquinone_zenodo.py

Validate ideal-gas thermochemistry against a deterministic 1,000-molecule sample from QM9:

python scripts/validate_qm9.py

Validate transition-state thermochemistry against a deterministic sample from the PSI4 VQM24 dataset:

python scripts/validate_vqm24.py

Run a zero-point-energy regression across 255 model chemistries:

python scripts/validate_model_chemistry_zpe.py

Compare complete DFTB+ and GFN2-xTB entropy workflows with an experimental gas-phase compilation:

python scripts/validate_experimental_entropy.py --engine both

These commands verify their downloaded archives and keep the external data out of the repository. See the anthraquinone reference benchmark and the thermochemistry benchmarks for QM9 and VQM24 transition states, plus the experimental entropy and model-chemistry ZPE comparisons, for their scope and interpretation.

Run linting:

python -m pylint ThermoScreening

DFTB+ integration tests run only when the executables are available and DFTB_PREFIX points to a valid Slater-Koster directory. Otherwise they are skipped so the pure-Python test suite remains portable.

Citing

If you use ThermoScreening in research, cite the archived software release. Machine-readable citation metadata is available in CITATION.cff, which also powers GitHub's Cite this repository feature. Each GitHub release is archived by Zenodo and receives a version-specific DOI.

Roadmap

Planned work is tracked in GitHub issues rather than in this README. The tool supports the DFTB+, GFN-xTB (tblite) and native-xtb engines, implicit solvation, quasi-RRHO, batch screening with resume, and RDKit conformer generation; see the issue tracker for further enhancements.

License

ThermoScreening source code is licensed under the GNU Lesser General Public License v2.1 or later. See LICENSE.