EzReson: An efficient program for chemical resonance analysis

The program provides a general and efficient tool to perform a resonance analysis of molecules. It translates the wave function obtained from a standard DFT or Hartree-Fock calculation to the chemically more intepretable Lewis structures.

Download link for the latest v3.0 version: https://github.com/yangwangmadrid/EzReson/releases/download/v3.0/EzReson_v3.0_release.zip

NOTE: For a tutorial in Chinese, a series of articles with examples are available at the WeChat public account, "Quantum Chemistry", following the link:

https://mp.weixin.qq.com/mp/appmsgalbum?__biz=MzU5NjMxNjkzMw==&action=getalbum&album_id=1709622916134338560

This WeChat page (in Chinese as well) at "KouShare" provides an overview of the applications of EzReson to diverse chemical problems:

https://mp.weixin.qq.com/s/2JKLrs0UF92Tk-tst9zWIg

What's new in the latest 3.0 version?

Perform open-shell WFRT and PROJ jobs for pi-conjugated monoradicals and biradicals
Output overlap, Hamiltonian and interaction-energy matrices between Clar resonators or specified Lewis structures
Use the ProjDiv keyword to divide the complete set of Kekule structures into many parts, for each of which the WF and DM projections are calculations separately, thus requiring much less memory. This is useful for a huge number of Kekule structures, which would otherwise encounter out of memory problem.
Use the SciForm option for Kekule-WFRT jobs for both closed- and open-shell cases
Show elapsed time at the end of output of the program
Fixed a bug for parsing the input file: The colon symbol used for LPs in Lewis structures conflicts with that used in the MATLAB-style specification of atoms or LMOs

How to cite

If you have used EzReson in your research papers or presentations, it is obligatory to cite the following works:

Yang Wang. A Reliable and Efficient Resonance Theory Based on Analysis of DFT Wave Functions. Phys. Chem. Chem. Phys. 2021, 23, 2331-2348.
Yang Wang. Superposition of Waves or Densities: Which is the Nature of Chemical Resonance? J. Comput. Chem. 2021, 42, 412-417.
Yang Wang. Response to comment on “Superposition of waves or densities: Which is the nature of chemical resonance?” J. Comput. Chem. 2021, 42, 1341-1343.
Yang Wang. The EzReson program. 2023, https://github.com/yangwangmadrid/EzReson.

If you have used EzReson to generate or analyze Kekulé structures of pi conjugated compounds, it is required to cite the following paper:

Yang Wang. Extension and Quantification of Fries Rule and Its Connection to Aromaticity: Large-Scale Validation by Wave-Function-Based Resonance Analysis. J. Chem. Inf. Model. 2022, 62, 5136–5148.

If you have used EzReson to generate or analyze Clar structures/resonators of pi conjugated compounds, it is required to cite the following paper:

Yang Wang. Quantitative Resonance Theory Based on the Clar Sextet Model. J. Phys. Chem. A 2022, 126, 1, 164–176.

Copyright and license

The Author of the EzReson software is Yang Wang (yangwang@yzu.edu.cn; orcid.org/0000-0003-2540-2199). The EzReson program is released under GNU General Public License v3 (GPLv3).

Disclaimer

The EzReson software is provided as it is, with no warranties. The Author shall not be liable for any use derived from it. Feedbacks and bug reports are always welcome (yangwang@yzu.edu.cn). However, it is kindly reminded that the Author does not take on the responsibility of providing technical support.

How to install

Requirements

python >= 3.6
numpy >= 1.18.0
scipy >= 1.5.1

Installation

Place the folder of the EzReson package to any location as you like, which is referred to as the source directory hereafter.
Open with a text editor the script file "ezreson" in the source directory and set the EZRESON_DIR variable as the path of the source directory.
Add the source directory to the global environment variable PATH in e.g., ".bash_profile" or ".bashrc" under your HOME directory.

Then, you are ready to go.

How to use

Gaussian calculations

In the Gaussian input file (e.g., abc.gjf), add in the route section the keywords fchk=All Pop=NBO6Read, and at the end of the file add $NBO NOBOND AONAO=W $END. In this way, the checkpoint file "Test.FChk" and the NBO matrix file "abc.33" will be generated. Then, rename "Test.FChk" to "abc.fchk". The Gaussian output file should have the extension name of ".out" (If necessary, "abc.log" ought to be renamed as "abc.out").

NOTES:

It is strongly recommended to use the NBO program later than version 5.0. The free version of NBO 3.1 implemented in Gaussian package would be problematic and give unreliable results.
Do not use fchk=All to generate the checkpoint file if there are two such jobs running at the same working directory at the same time. Otherwise, the two jobs will write the same "Test.FChk" file. Instead, add the %chk=abc.chk line to obtain the checkpoint file "abc.chk". Then, use Gaussian's formchk utility to convert "abc.chk" to "abc.fchk".

Make sure that the following four files, as the inputs for EzReson, are in the same working directory:

abc.gjf
abc.out
abc.fchk
abc.33

Change to the working directory and prepare the input file for EzReson (vide infra), say, "abc_wfrt.in"
Simply execute the following command: ezreson abc_wfrt.in > abc_wfrt.out

As you see, you will find the result of resonance analysis by EzReson in file "abc_wfrt.out".

NOTE: If the analysis is conducted within the framework of the simple Hückel molecular orbital (HMO) theory, only an xyz or gjf file is required to feed EzReson.

A typical wave-function-based resonance theory (WFRT) analysis

Let us take benzene as an example. Suppose that after the DFT calculations of benzene you have obtained the four output files, Ph.gjf, Ph.out, Ph.fchk and Ph.33.

1. Perform an LMO calculation to obtain Pipek--Mezey localized MOs

Prepare an input file, named "benzene_lmo.in" as:

File = Ph
Job = LMO

NOTE: The letters in EzReon's input file are case-insensitive.

Then, use the following command to run the LMO job:

ezreson benzene_lmo.in > benzene_lmo.out

After finishing the LMO calculation correctly, the following output files will be generated:

Ph_CNAOLMO.dat
Ph_ELMO.dat
Ph_LMO.fchk

2. Identify the LMOs associated with the resonance subsystem

In this particular case of benezene, we are to find the occupied LMOs corresponding to the pi conjugated system. To this end, open file "Ph_LMO.fchk" with visualization software like JMol or Gabedit. For JMol, after opening Ph_LMO.fchk, type in the script console: isosurface mo 21 and the LMO-#21 (which is the HOMO) will be displayed. You will see that this LMO belongs to the pi-resonance system and is thus selected. Then, keep on inspecting lower LMOs, #20, #19, ..., until all LMOs belonging to the resonance subsystem have been chosen. Since in this particular case there are 6 electrons in the resonance subsystem, you only need to identify 3 LMOs.

As for benzene, the resonating LMOs are identified as 19, 20 and 21.

NOTE: Other visualization softwares may not support reading *.fchk for visualization of orbitals. But you can always convert *.fchk file to *.cube file by the cubegen utility in the Gaussian suite. Then, a great variety of visualization tools are able to read the *.cube file for visualization of molecular orbitals.

3. Perform the WRFT analysis

We have determined that the LMOs for the resonance subsystem of benzene are #19, 20 and 21. We also see that the involved atoms are the carbon atoms, whose indices are 1, 2, 3, 4, 5 and 6 as indicated in "Ph.gjf".

Accordingly, we prepare an input file, named "benzene_wfrt.in" as:

File = Ph
Job = WFRT
LMOs = 19 20 21
Atoms = 1 2 3 4 5 6

Then, use the following command to run the WFRT job:

ezreson benzene_wfrt.in > benzene_wfrt.out

NOTE: i) For the indices of atoms, the order matters in order to apply Rumer's rule for determination of linearly independent set of Lewis structures. For monocyclic systems, the ordered atoms should form a circle. For other systems, the choice is somewhat arbitrary, but it is recommended that the atoms be disposed to form a circle as much as possible.

ii) For versions 1.1.4+, the LMOs and Atoms can be defined in a more compact way by using the MATLAB colon syntax:

LMOs = 19:21
Atoms = 1:6

iii) In this case of benzene (and pi conjugated systems in general), the pi LMOs can be automatically chosen by EzReson with the PI keyword (case-insensitive):

LMOs = PI

Note that this is only valid for all-carbon conjugated systems, and not for heteroatomic systems yet.

Fragment of the output:

Performing Wave Function based Resonance Theory (WFRT) calculations ...
 
Reading LEWIS_6c_6e.dat for Lewis structures ...
215 Lewis structures in total to be considered
... ...
... ...
Solving linear equation for WFRT coefficients ...
40 Lewis structures violating Rumer's rule excluded
0 Lewis structures of small projections ( < 0.00E+00 ) excluded
Using totally 175 Lewis structures to expand the actual wave function
Normalizing the wave function by a factor of 0.9951914286 ...
---------------------------------------------------------------------------------------------------------
  No. Projection Coefficient      RE  Mulli. Bickel. Ros-Sc.  Lowdin    PWSO  Lewis structure
---------------------------------------------------------------------------------------------------------
    1   0.559795   0.3333335  175.96  18.75%  22.85%   9.60%  14.59%  19.80%  1-2 3-4 5-6
    2   0.559795   0.3333335  175.96  18.75%  22.85%   9.60%  14.59%  19.80%  2-3 4-5 1-6
   15   0.221154   0.2222227  347.79   4.94%   2.70%   4.27%   2.77%   2.44%  4: 2-3 5-6

EzReson

Install / Use

README