This repository contains utilities to perturb the molecular orbitals produced by different quantum chemical software. Restarting calculations from perturbed molecular orbitals may steer the self-consistent field convergence toward other SCF solutions of lower energy.
The actual perturbation of the orbitals is implemented in C++. For this, different executables exist for the different quantum chemical programs, and they modify the corresponding checkpoint files or molecular orbital files. These executables can either be compiled from the source code in this repository, or downloaded directly here (Linux only).
Python scripts are provided to automatize the use of the C++ programs. An example with the methane molecule is illustrated here.
Specific information to the supported quantum chemical software can be read below.
It can happen that self-consistent field calculations converge to a non-global energy minimum. In such cases, it is helpful to perturb the molecular orbitals following a randomized scheme, as a different guess for the electronic density may lead to another SCF solution. Doing this can be especially important in interactive explorations of chemical reactivity or in ab initio molecular dynamics. The perturbation scheme is a vital component of our real-time quantum chemistry software (http://www.reiher.ethz.ch/research/haptic-quantum-chemistry).
A more detailed discussion of the topic, algorithm and applications can be found in Algorithm and applications described in doi:10.1021/acs.jctc.7b00011.
Note that binaries can be downloaded for Linux. If you want to use them it is not necessary to build the C++ executables.
- CMake (Version >= 3.3)
- C++ compiler with c++11 support
- Eigen library
The two executables can easily be compiled with the help of CMake, for instance in the terminal:
mkdir -p cpp/build
cd cpp/build
cmake -DCMAKE_BUILD_TYPE=Release ..
makeThis will create the executables turbomole_perturbation and gaussian_perturbation.
To be able to execute the Python scripts, you must first install them as a Python package, which will be called orbitalperturbation.
Follow these instructions:
cd python
pip install .This will place the executables perturb_gaussian_orbitals and perturb_turbomole_orbitals into your PATH and you will be able to execute them from the terminal.
Turbomole website: http://www.turbomole-gmbh.com/
The C++ executable perturbing the Gaussian molecular orbitals acts on orbital files produced by Turbomole (normally, alpha and beta).
It can be used in the following manner:
# turbomole_perturbation <alpha_filename> <beta_filename> <number_orbitals> <number_alpha_electrons> <number_beta_electrons>
turbomole_perturbation alpha beta 88 19 16and will directly replace the orbitals in the files alpha and beta by perturbed orbitals.
The python script turbomole_perturb automatically calls this executable in the correct fashion.
With
turbomole_perturb <turbomole_calculation_directory>the control file will be parsed to get the filenames for the alpha and beta orbitals, the number of electrons and the number of orbitals.
Then you can directly start another Turbomole calculation in this directory.
Hint: Make sure that your Turbomole calculation is unrestricted (keyword $uhf).
Gaussian website: http://gaussian.com/
The C++ executable perturbing the Gaussian molecular orbitals acts on formatted Gaussian checkpoint files. It reads the number of orbitals, alpha and beta electrons from this file, and creates a copy where the orbitals have been perturbed. It can be used in the following manner:
gaussian_perturbation original_checkpoint.fchk perturbed_checkpoint.fchkThis will create the file perturbed_checkpoint.fchk if it does not already exist.
To convert between the binary checkpoint files generated by Gaussian and their formatted counterparts, one can use the utilities formchk and unfchk provided by Gaussian.
This process as well as the execution of perturbed_checkpoint.fchk can be automatized with the Python helper script:
With
gaussian_perturb binary_checkpoint_file.chkthe orbitals in the checkpoint file binary_checkpoint_file.chk files are perturbed and you can directly start another Gaussian calculation.
Hint: Make sure that your Gaussian calculation is unrestricted (keywords UHF or UKS).
If reproducibility is required, it is possible to specify the seed of the random number generator.
To do so, you can enter an additional argument when calling the executables turbomole_perturbation and gaussian_perturbation, representing a file containing your random seed (integer number).
After the perturbation of the orbitals, this file is updated and contains the new random seed, so that you do not need to enter a different seed manually every time.
When the programs are called without this argument, the random number generator is initialized from the current time. This is the case when using the provided python scripts.