This repository provides scripts to generate vibrational displacement modes for DIMER transition state (TS) searches in crystalline structures.
This code has been tested after docking pose generation with VOID, specifically with the cation-anion Monte Carlo algorithm developed for this work.
The code automates the generation of vibrational displacement modes for catalytic reactions, focusing on hydrocarbon reactions in acidic zeolites. The default output format is a MODECAR file for VASP, with atomic types in POSCAR and POTCAR files sorted alphabetically to ensure compatibility.
It identifies oxygen atoms in gas-phase molecules docked into the crystal and distinguishes them from those in the catalyst framework (e.g., zeolites or oxides). Hydrogens at catalyst acid sites are also recognized and excluded from reactant mode calculations. For more details and examples, see the examples folder or the end of this document.
The code is tailored for reactions in zeolites, primarily hydrocarbon conversions and some involving light heteroatoms. To handle a broader range of atom types or catalyst compositions, modify the CATALYST_FRAMEWORK_ELEMENTS and CATALYST_NON_FRAMEWORK_ELEMENTS variables in (scripts/chemistry_composition.py), where additional reaction examples are also available.
Verbose output is enabled by default to aid users in understanding execution and debugging.
The code can also generate mode input files for other computational chemistry software, such as CP2K, GULP, ASE, and LAMMPS if indicated to do so, see Optional Command-line Arguments.
To install this repository, follow these steps:
git clone https://github.com/learningmatter-mit/PoTS
pip install numpy
pip install pymatgen
This software has been tested to work with numpy 1.26.4 and pymatgen 2023.3.10
To run the mode generation script, navigate to the directory containing the structure files.
Make sure the following input files are available:
-
A crystal structure file, either
POSCARor.cif. If both are available, the script prioritizes parsing thePOSCAR. -
Gas molecule coordinates in an
.xyzfile. -
A
vibdispsfile containing imaginary-frequency TS vibrational displacements. -
Optional (but recommended): A
POTCARfile forVASPruns, which will be sorted alphabetically alongside thePOSCAR.
For convenience, a template INCAR is provided in every example folder. This file can be used as a starting point for DFT calculations after mode generation and adapted as needed for specific systems.
Note: POTCAR files are not distributed with this repository due to VASP licensing restrictions. Users should generate or provide their own POTCAR when preparing inputs for VASP calculations. The PoTS code automatically triggers the atom-sorting check against the POSCAR file as soon as a file named POTCAR is present in the working directory.
Then execute:
python ../../scripts/run.py
--cp2k: Generates the &MODE_VECS section for the CP2K dimer input file CP2KMODEVECS
--gulp: Generates the vector section for the GULP dimer input file GULPvector
--ase: Generates the mode vector section for the ASE dimer input file ASE_INPUT
--lammps: Generates the displace_atoms section for the LAMMPS dimer input file LAMMPS_INPUT
To generate initial guess modes for a DIMER TS search in formats other than VASP, add the appropriate arguments to the script. The script will write the required files to the folder, allowing you to request one or multiple formats simultaneously.
python ../../scripts/run.py --cp2k --gulp --ase --lammps
If no argument is provided, the script defaults to VASP format, with atomic types in POSCAR and POTCAR files sorted alphabetically.
This section provides demonstrations of script usage across various scenarios and file types. The execution of the code should not take more than 5-10 seconds per structure.
This example uses a crystal structure in POSCAR format. The script automatically sorts atomic types alphabetically in POSCAR and POTCAR files, calculates the vibrational displacements, and generates a MODECAR file for VASP.
Analogous example to the POSCAR_test but using a .cif file for the crystal structure.
In this example, the docked gas-phase molecule contains oxygen atoms, which the script autonomously identifies and distinguishes from those in the catalyst framework. Vibrational displacements are then generated specifically for the gas-phase molecule.
This example demonstrates the automatic detection and exclusion of hydrogen atoms from acidic catalyst sites during vibrational mode calculations, particularly for zeolite systems.
A combined example featuring a gas-phase molecule with oxygen atoms and a catalyst with acidic hydrogen atoms. The script detects and processes both the docked gas-phase oxygen atoms and the acid-site hydrogen atoms during vibrational mode calculations.
An example for generating vibrational displacement modes in metal-containing systems. For systems with a broader range of atom types or different catalyst compositions, adjust the variables in the chemistry_composition.py file to include the specific metal elements. Refer to the example_run.sh script in examples/Modes_for_Metals for a detailed demonstration of the procedure.
This example demonstrates how to request output formats for DIMER TS searches in software other than VASP, such as CP2K, ASE, GULP, and LAMMPS. Use the appropriate arguments (e.g., --cp2k, --gulp, --ase, --lammps) to generate the required input files for these software packages.
The utils/ directory contains the main PoTS pipeline driver and all auxiliary scripts required to run a full transition-state search workflow starting from molecular SMILES/SMARTS. This pipeline automates tasks from conformer generation to semiempirical and DFT calculations, docking, and VASP periodic inputs.
Running the Pipeline
From the utils/ directory:
cd /path/to/PoTS/utils
python PoTS.py --smiles-file smiles.txt --smarts-file smarts.txt
A complete step by step guide can be found on the utils/README.md file.
The publication describing the algorithm and the software is the following: https://arxiv.org/abs/2504.08986
If you use this software, please cite the paper above.