Q-Chem 4.3 User’s Manual

10.6 Visualizing and Plotting Orbitals and Densities

The free, open-source visualization program IQmol (www.iqmol.org) provides a graphical user interface for Q-Chem that can be used as a molecular structure builder, as a tool for local or remote submission of Q-Chem jobs, and as a visualization tool for densities and molecular orbitals. Alternatively, Q-Chem can generate orbital and density data in formats suitable for plotting with various third-party visualization programs.

10.6.1 Visualizing Orbitals Using MolDen and MacMolPlt

Upon request, Q-Chem will generate an input file for MolDen, a freely-available molecular visualization program [482, 483]. MolDen can be used to view ball-and-stick molecular models (including stepwise visualization of a geometry optimization), molecular orbitals, vibrational normal modes, and vibrational spectra. MolDen also contains a powerful Z-matrix editor. In conjunction with Q-Chem, orbital visualization via MolDen is currently supported for $s$, $p$, and $d$ functions (pure or Cartesian), as well as pure $f$ functions. Upon setting MOLDEN_FORMAT to TRUE, Q-Chem will append a MolDen-formatted input file to the end of the Q-Chem log file. As some versions of MolDen have difficulty parsing the Q-Chem log file itself, we recommend that the user cut and paste the MolDen-formatted part of the Q-Chem log file into a separate file to be read by MolDen.

MOLDEN_FORMAT

Requests a MolDen-formatted input file containing information from a Q-Chem job.


TYPE:

LOGICAL


DEFAULT:

False


OPTIONS:

True

Append MolDen input file at the end of the Q-Chem output file.


RECOMMENDATION:

None.


MolDen-formatted files can also be read by MacMolPlt, another freely-available visualization program [484, 485]. MacMolPlt generates orbital iso-contour surfaces much more rapidly than MolDen, however, within MacMolPlt these surfaces are only available for Cartesian Gaussian basis functions, i.e., PURECART = 2222, which may not be the default.

Example 10.212  Generating a MolDen file for molecular orbital visualization.

$molecule
   0 1
   O
   H  1  0.95
   H  1  0.95  2  104.5
$end

$rem
   METHOD           hf
   BASIS            cc-pvtz
   PRINT_ORBITALS   true (default is to print 5 virtual orbitals)
   MOLDEN_FORMAT    true 
$end 

For geometry optimizations and vibrational frequency calculations, one need only set MOLDEN_FORMAT to TRUE, and the relevant geometry or normal mode information will automatically appear in the MolDen section of the Q-Chem log file.

Example 10.213  Generating a MolDen file to step through a geometry optimization.

$molecule
   0  1
   O
   H  1  0.95
   H  1  0.95  2  104.5
$end

$rem
   JOBTYPE         opt
   METHOD          hf
   BASIS           6-31G*
   MOLDEN_FORMAT   true 
$end

10.6.2 Visualization of Natural Transition Orbitals

For excited states calculated using the CIS, RPA, or TDDFT methods, construction of Natural Transition Orbitals (NTOs), as described in Section 6.11.2, is requested using the $rem variable NTO_PAIRS. This variable also determines the number of hole/particle NTO pairs that are output for each excited state. Although the total number of hole/particle pairs is equal to the number of occupied MOs, typically only a very small number of these pairs (often just one pair) have significant amplitudes. (Additional large-amplitude NTOs may be encountered in cases of strong electronic coupling between multiple chromophores [110].)

NTO_PAIRS

Controls the writing of hole/particle NTO pairs for excited state.


TYPE:

INTEGER


DEFAULT:

0


OPTIONS:

$N$

Write $N$ NTO pairs per excited state.


RECOMMENDATION:

If activated ($N > 0$), a minimum of two NTO pairs will be printed for each state. Increase the value of $N$ if additional NTOs are desired.


When NTO_PAIRS $> 0$, Q-Chem will generate the NTOs in MolDen format. The NTOs are state-specific, in the sense that each excited state has its own NTOs, and therefore a separate MolDen file is required for each excited state. These files are written to the job’s scratch directory, in a sub-directory called NTOs, so to obtain the NTOs the scratch directory must be saved using the –save option that is described in Section 2.7. The output files in the NTOs directory have an obvious file-naming convention. The “hole” NTOs (which are linear combinations of the occupied MOs) are printed to the MolDen files in order of increasing importance, with the corresponding excitation amplitudes replacing the canonical MO eigenvalues. (This is a formatting convention only; the excitation amplitudes are unrelated to the MO eigenvalues.) Following the holes are the “particle” NTOs, which represent the excited electron and are linear combinations of the virtual MOs. These are written in order of decreasing amplitude. To aid in distinguishing the two sets within the MolDen files, the amplitudes of the holes are listed with negative signs, while the corresponding NTO for the excited electron has the same amplitude with a positive sign.

Due to the manner in which the NTOs are constructed (see Section 6.11.2), NTO analysis is available only when the number of virtual orbitals exceeds the number of occupied orbitals, which may not be the case for minimal basis sets.

Example 10.214  Generating MolDen-formatted natural transition orbitals for several excited states of uracil.

$molecule
0 1   
 N    -2.181263     0.068208     0.000000
 C    -2.927088    -1.059037     0.000000
 N    -4.320029    -0.911094     0.000000
 C    -4.926706     0.301204     0.000000
 C    -4.185901     1.435062     0.000000
 C    -2.754591     1.274555     0.000000
 N    -1.954845     2.338369     0.000000
 H    -0.923072     2.224557     0.000000
 H    -2.343008     3.268581     0.000000
 H    -4.649401     2.414197     0.000000
 H    -6.012020     0.301371     0.000000
 H    -4.855603    -1.768832     0.000000
 O    -2.458932    -2.200499     0.000000
$end

$rem  
  METHOD          B3LYP
  BASIS           6-31+G*
  CIS_N_ROOTS     3   
  NTO_PAIRS       2
$end

10.6.3 Generation of Volumetric Data Using $plots

The simplest way to visualize the charge densities and molecular orbitals that Q-Chem evaluates is via a graphical user interface, such as those described in the preceding section. An alternative procedure, which is often useful for generating high-quality images for publication, is to evaluate certain densities and orbitals on a user-specified grid of points. This is accomplished by invoking the $plots option, which is itself enabled by requesting IANLTY = 200.

The format of the $plots input is documented below. It permits plotting of molecular orbitals, the SCF ground-state density, and excited-state densities obtained from CIS, RPA or TDDFT/TDA, or TDDFT calculations. Also in connection with excited states, either transition densities, attachment/detachment densities, or natural transition orbitals (at the same levels of theory given above) can be plotted as well.

By default, the output from the $plots command is one (or several) ASCII files in the working directory, named plot.mo, etc.. The results then must be visualized with a third-party program capable of making 3-D plots. (Some suggestions are given in Section 10.6.4.)

An example of the use of the $plots option is the following input deck:

Example 10.215  A job that evaluates the H$_{2}$ HOMO and LUMO on a $1\times 1\times 15$ grid, along the bond axis. The plotting output is in an ASCII file called plot.mo, which lists for each grid point, $x$, $y$, $z$, and the value of each requested MO.

$molecule
   0  1
   H   0.0   0.0   0.35
   H   0.0   0.0  -0.35
$end

$rem
   METHOD     hf
   BASIS      6-31g**
   IANLTY     200
$end

$plots
   Plot the HOMO and the LUMO on a line
   1   0.0   0.0
   1   0.0   0.0
  15  -3.0   3.0
   2   0   0   0
   1   2
$end

General format for the $plots section of the Q-Chem input deck.

$plots
One comment line
Specification of the 3-D mesh of points on 3 lines:
$N_ x\quad x_{\ensuremath{\mathrm{min}}}\quad x_{\ensuremath{\mathrm{max}}}$
$N_ y\quad y_{\ensuremath{\mathrm{min}}}\quad y_{\ensuremath{\mathrm{max}}}$
$N_ z\quad z_{\ensuremath{\mathrm{min}}}\quad z_{\ensuremath{\mathrm{max}}}$
A line with 4 integers indicating how many things to plot:
$N_{\ensuremath{\mathrm{MO}}}\quad N_{\ensuremath{\mathrm{Rho}}}\quad N_{\ensuremath{\mathrm{Trans}}}\quad N_{\ensuremath{\mathrm{DA}}}$
An optional line with the integer list of MO’s to evaluate (only if $N_{\ensuremath{\mathrm{MO}}} > 0$)
MO(1)  MO(2) $\ldots $ MO($N_{\ensuremath{\mathrm{MO}}}$)
An optional line with the integer list of densities to evaluate (only if $N_{\ensuremath{\mathrm{Rho}}} > 0$)
Rho(1)  Rho(2) $\ldots $ Rho($N_{\ensuremath{\mathrm{Rho}}}$)
An optional line with the integer list of transition densities (only if $N_{\ensuremath{\mathrm{Trans}}}> 0$)
Trans(1)  Trans(2) $\ldots $ Trans($N_{\ensuremath{\mathrm{Trans}}}$)
An optional line with states for detachment/attachment densities (if $N_{\ensuremath{\mathrm{DA}}} > 0$)
DA(1)  DA(2) $\ldots $ DA($N_{\ensuremath{\mathrm{DA}}}$)
$end

Line 1 of the $plots keyword section is reserved for comments. Lines 2–4 list the number of one dimension points and the range of the grid (note that coordinate ranges are in Angstroms, while all output is in atomic units). Line 5 must contain 4 non-negative integers indicating the number of: molecular orbitals ($N_{\ensuremath{\mathrm{MO}}}$), electron densities ($N_{\ensuremath{\mathrm{Rho}}}$), transition densities and attach/detach densities ($N_{\ensuremath{\mathrm{DA}}}$), to have mesh values calculated.

The final lines specify which MOs, electron densities, transition densities and CIS attach/detach states are to be plotted (the line can be left blank, or removed, if the number of items to plot is zero). Molecular orbitals are numbered $1\ldots N_{\alpha },N_{\alpha }+1 \ldots N_{\alpha }+N_{\beta }$; electron densities numbered where 0= ground state, 1 = first excited state, 2 = second excited state, etc.; and attach/detach specified from state $1\to N_{\ensuremath{\mathrm{DA}}}$.

By default, all output data are printed to files in the working directory, overwriting any existing file of the same name.

Output is printed in atomic units, with coordinates first followed by item value, as shown below:

x1   y1   z1      a1   a2  ...  aN
x2   y1   z1      b1   b2  ...  bN
...

Instead of a standard one-, two-, or three-dimensional Cartesian grid, a user may wish to plot orbitals or densities on a set of grid points of his or her choosing. Such points are specified using a $grid input section whose format is simply the Cartesian coordinates of all user-specified grid points:

x1   y1   z1   
x2   y2   z2 
...

The $plots section must still be specified as described above, but if the $grid input section is present, then these user-specified grid points will override the ones specified in the $plots section.

The Q-Chem $plots utility allows the user to plot transition densities and detachment/attachment densities directly from amplitudes saved from a previous calculation, without having to solve the post-SCF (CIS, RPA, TDA, or TDDFT) equations again. To take advantage of this feature, the same Q-Chem scratch directory must be used, and the SKIP_CIS_RPA $rem variable must be set to TRUE. To further reduce computational time, the SCF_GUESS $rem can be set to READ.

SKIP_CIS_RPA

Skips the solution of the CIS, RPA, TDA or TDDFT equations for wavefunction analysis.


TYPE:

LOGICAL


DEFAULT:

FALSE


OPTIONS:

TRUE / FALSE


RECOMMENDATION:

Set to true to speed up the generation of plot data if the same calculation has been run previously with the scratch files saved.


10.6.4 Direct Generation of “Cube” Files

As an alternative to the output format discussed above, all of the $plots data may be output directly to a sub-directory named plots in the job’s scratch directory, which must therefore be saved using the –save option described in Section 2.7. The plotting data in this sub-directory are not written in the plot.* format described above, but rather in the form of so-called “cube” file, one for each orbital or density that is requested. The “cube” format is a standard one for volumetric data and consists of a small header followed by the orbital or density values at each grid point, in ASCII format. (Consult Ref. Herbert:2015a for the complete format specification.) Because the grid coordinates themselves are not printed (their locations are implicit from information contained in the header), each individual cube file is much smaller than the corresponding plot.* file would be. Cube files can be read by many standard (and freely-available) graphics programs, including MacMolPlt [484, 485] and VMD [487, 488]. VMD, in particular, is recommended for generation of high-quality images for publication. Cube files for the MOs and densities requested in the $plots section are requested by setting MAKE_CUBE_FILES to TRUE, with the $plots section specified as described in Section 10.6.3.

MAKE_CUBE_FILES

Requests generation of cube files for MOs, NTOs, or NBOs.


TYPE:

LOGICAL


DEFAULT:

FALSE


OPTIONS:

FALSE

Do not generate cube files.

TRUE

Generate cube files for MOs and densities.

NTOS

Generate cube files for NTOs.

NBOS

Generate cube files for NBOs.


RECOMMENDATION:

None


PLOT_SPIN_DENSITY

Requests the generation of spin densities, $\rho _\alpha $ and $\rho _\beta $.


TYPE:

LOGICAL


DEFAULT:

FALSE


OPTIONS:

FALSE

Do not generate spin density cube files.

TRUE

Generate spin density cube files.


RECOMMENDATION:

Set to TRUE if spin densities are desired in addition to total densities. Requires that MAKE_CUBE_FILES be set to TRUE as well, and that one or more total densities is requested in the $plots input section. The corresponding spin densities will then be generated also.


The following example illustrates the generation of cube files for a ground and an excited-state density, including the corresponding spin densities. In this example, the plots sub-directory of the job’s scratch directory should contain files named dens.N.cube (total density for state $N$, where $N=0$ or 1 represents the ground and first excited state, respectively), dens_alpha.N.cube and dens_beta.N.cube ($\rho _\alpha $ and $\rho _\beta $ for each state), and dens_spin.N.cube ($\rho _\alpha - \rho _\beta $ for each state.)

Example 10.216  Generating density and spin-density cube files for the ground and first excited state of the HOO radical.

$molecule
0 2
   H           1.004123   -0.180454    0.000000
   O          -0.246002    0.596152    0.000000
   O          -1.312366   -0.230256    0.000000
$end

$rem
plot_spin_density true
make_cube_files   true
scf_convergence   8
method            b3lyp
basis             6-31+G*
cis_n_roots       1
$end

$plots
grid information and request to plot 2 densities
20 -5.0 5.0
20 -5.0 5.0
20 -5.0 5.0
0 2 0 0
0 1 
$end

Cube files are also available for natural transition orbitals (Sections 6.11.2 and 10.6.2) by setting MAKE_CUBE_FILES to NTOS, although in this case the procedure is somewhat more complicated, due to the state-specific nature of these quantities. Cube files for the NTOs are generated only for a single excited state, whose identity is specified using CUBEFILE_STATE. Cube files for additional states are readily obtained using a sequence of Q-Chem jobs, in which the second (and subsequent) jobs read in the converged ground- and excited-state information using SCF_GUESS and SKIP_CIS_RPA.

CUBEFILE_STATE

Determines which excited state is used to generate cube files


TYPE:

INTEGER


DEFAULT:

None


OPTIONS:

$n$

Generate cube files for the $n$th excited state


RECOMMENDATION:

None


An additional complication is the manner in which to specify which NTOs will be output as cube files. When MAKE_CUBE_FILES is set to TRUE, this is specified in the $plots section, in the same way that MOs would be specified for plotting. However, one must understand the order in which the NTOs are stored. For a system with $N_\alpha $ $\alpha $-spin MOs, the occupied NTOs $1,2,\ldots ,N_\alpha $ are stored in order of increasing amplitudes, so that the $N_\alpha $’th occupied NTO is the most important. The virtual NTOs are stored next, in order of decreasing importance. According to this convention, the highest occupied NTO (HONTO) $\rightarrow $ lowest unoccupied NTO (LUNTO) excitation amplitude is always the most significant, for any particular excited state. Thus, orbitals $N_\alpha $ and $N_\alpha +1$ represent the most important NTO pair, while orbitals $N_\alpha -1$ and $N_\alpha +2$ represent the second most important NTO pair, etc..

Example 10.217  Generating cube files for the HONTO-to-LUNTO excitation of the second singlet excited state of uracil. Note that $N_\alpha = 29$ for uracil.

$molecule
0 1   
 N    -2.181263     0.068208     0.000000
 C    -2.927088    -1.059037     0.000000
 N    -4.320029    -0.911094     0.000000
 C    -4.926706     0.301204     0.000000
 C    -4.185901     1.435062     0.000000
 C    -2.754591     1.274555     0.000000
 N    -1.954845     2.338369     0.000000
 H    -0.923072     2.224557     0.000000
 H    -2.343008     3.268581     0.000000
 H    -4.649401     2.414197     0.000000
 H    -6.012020     0.301371     0.000000
 H    -4.855603    -1.768832     0.000000
 O    -2.458932    -2.200499     0.000000
$end

$plots
Plot the dominant NTO pair, N --> N+1
25 -5.0 5.0
25 -5.0 5.0
25 -5.0 5.0
2 0 0 0
29 30
$end

$rem  
  METHOD          B3LYP
  BASIS           6-31+G*
  CIS_N_ROOTS     2 
  CIS_TRIPLETS    FALSE 
  NTO_PAIRS       TRUE    ! calculate the NTOs
  MAKE_CUBE_FILES NTOS    ! generate NTO cube files... 
  CUBEFILE_STATE  2       ! ...for the 2nd excited state  
$end

Cube files for Natural Bond Orbitals (for either the ground state or any CIS, RPA, of TDDFT excited states) can be generated in much the same way, by setting MAKE_CUBE_FILES equal to NBOS, and using CUBEFILE_STATE to select the desired electronic state. CUBEFILE_STATE = 0 selects ground-state NBOs. The particular NBOs to be plotted are selected using the $plots section, recognizing that Q-Chem stores the NBOs in order of decreasing occupancies, with all $\alpha $-spin NBOs preceding any $\beta $-spin NBOs, in the case of an unrestricted SCF calculation. (For ground states, there is typically one strongly-occupied NBO for each electron.) NBO cube files are saved to the plots sub-directory of the job’s scratch directory. One final caveat: to get NBO cube files, the user must specify the AONBO option in the $nbo section, as shown in the following example.

Example 10.218  Generating cube files for the NBOs of the first excited state of $\rm H_2O$.

$rem
  METHOD          CIS
  BASIS           CC-PVTZ
  CIS_N_ROOTS     1
  CIS_TRIPLETS    FALSE
  NBO             2      ! ground- and excited-state NBO
  MAKE_CUBE_FILES NBOS   ! generate NBO cube files...
  CUBEFILE_STATE  1      ! ...for the first excited state
$end

$nbo
  AONBO  
$end

$molecule
0 1
O
H 1 0.95
H 1 0.95 2 104.5
$end

$plots
Plot the 5 high-occupancy NBOs, one for each alpha electron
40 -8.0 8.0
40 -8.0 8.0
40 -8.0 8.0
5 0 0 0 
1 2 3 4 5
$end

10.6.5 NCI Plots

We have implemented the non-covalent interaction (NCI) plots from Weitao Yang’s group [489, 490]. To generate these plots, one can set the PLOT_REDUCED_DENSITY_GRAD $rem variable to TRUE (see the nci-c8h14.in input example in $QC/samples directory).