Program specific information

Use the rtype keyword in dens_ana.in to specify the respective method.

In general, TheoDORE needs two types of information: density matrices and MO coefficients. This page contains specific information about how to obtain this information from the different quantum chemistry programs.

Q-Chem

ADC

The ADCMAN module of Q-Chem is already interfaced to the wavefunction analysis library libwfa. Therefore, most analysis steps can be performed within Q-Chem. The main purpose of TheoDORE is to enable plotting of electron-hole correlation plots and other fragment-based analysis methods.

To run the libwfa analysis set in the input file:

state_analysis    true
adc_print    3

Make sure the file ctnum_mulliken.om is copied back to be used by TheoDORE.

Futhermore, specific analysis descriptors can be parsed and put into a convenient table. To do so run

theodore parse_libwfa qchem.out qcadc

TDDFT

The CIS/TDDFT module of Q-Chem is directly interfaced to the wavefunction analysis library libwfa (see JCP 143, 171101 (2015) for more details). Most analysis steps are performed within Q-Chem and the main purpose of TheoDORE is to enable plotting of electron-hole correlation plots.

To run the libwfa analysis set in the input file (and copy back ctnum_mulliken.om):

state_analysis    true

To obtain a summary of the Q-Chem/libwfa job, run

theodore parse_libwfa qchem.out [qctddft / qctda]

Alternatively, the standard output can be parsed. To do this set read_libwfa=False in dens_ana.in. In this case, the X vector is parsed and interpreted as the 1TDM while the Y vector is ignored. The following non-standard options have to be set in the input file:

cis_ampl_print      1
print_orbitals      5000
molden_format       true

The first one assures that enough amplitudes are printed for a meaningful semi-quantitative analysis. The second and third cause the print-out of all orbitals in Molden format, written to the end of the standard output file. This Molden file has to be extracted and copied to a new file qchem.mld.

Per default RPA vectors are parsed. If you are interested in TDA vectors, specify

TDA   true

in dens_ana.in.

fchk files

It is also possible to parse formatted checkpoint (fchk) files generated using the

state_analysis    true
gui               2

options. In this case, TheoDORE can read the transition density matrices and do the full analysis.

libwfa

It is also possible to parse generic libwfa output by using the libwfa keyword. This can be used for EOM-CC calculations.

Columbus

MCSCF

MCSCF transition density matrices are written by the program mcscf.x. To compute these, it is either possible to compute non-adiabatic coupling vectors or to use the shortcut of creating an mcdenin file. This file has the same structure as the transmomin file, e.g.

MCSCF
1  2  1  1
1  3  1  1
1  4  1  1
1  5  1  1
1  6  1  1

will compute all transition moments between the 1st and the 2nd through 6th states in DRT 1.

After the computation call write_den.bas`h to convert the binary files into a form that can be read by TheoDORE. For this purpose the $COLUMBUS variable has to be set.

State density matrix analysis is possible when the computation of dipole moments was requested. In this case it is possible to use the above procedure or to simply analyze the NO coefficient files in the MOLDEN directory.

MR-CI

The MR-CI transition density analysis works in the case that transition moments were requested in the job control stage. After this it is assumed that LISTINGS/trncils* files with the transition density matrices are available. Frozen core orbitals have to be specified explicitly in the input file to get correct results. To specify, for example, four frozen orbitals of a symmetry and three of b use:

ncore={'a':4, 'b':3}

In addition, the MO-coefficients of the preceeding MCSCF calculation have to be made available, typically in MOLDEN/molden_mo_mc.sp.

For a state density analysis at the MR-CI level, the NO files should be read in rather than using the colmrci functionality. Alternatively, an attachment/detachment analysis can be done with the densav.x functionality of COLUMBUS.

Molcas

The prefered way to use Molcas is through the libwfa library, which is available through OpenMolcas as described in JCTC, 13, 5343 (2017). In this way it is possible to analyze RASSCF and MS-CASPT2 computations.

First, run Molcas using the &WFA module

&RASSI
TRD1

&WFA
h5file = $Project.rassi.h5

and copy back the *.om files. In theoinp specify “y” for

Did you use &WFA? (read_libwfa):
Choice (y/n): [y]

and proceed as usual.

Molcas (old)

It is also possible to parse Molcas RASSI output but this only works for singlet states.

RASSCF

In the case of Molcas, the output of the RASSI program is parsed. This gives access to RASSCF density and transition density matrices, so far without explicit point group symmetry. Note: The output is only parsed correctly if all states in the RASSI computation derive from the same RASSCF computation and if the specified Molden file derives from this calculation.

First run a RASSCF + RASSI job with the (undocumented) TRD1 keyword:

&RASSI
    TRD1

Then copy the transition densities to a directory TRD:

mkdir TRD && cp $WorkDir/TRD2* TRD

Alternatively, a state density matrix analysis can be performed by using the natural orbitals created by Molcas. However, for an analysis of unpaired electrons the NOs have to be changed from spin-orbitals to spatial orbitals.

MS-CASPT2

For an MS-CASPT2 calculation, the following input sections can be used

&CASPT2
multistate = 4 1 2 3 4
imag = 0.3

>> SAVE $Project.JobMix JOB001

&RASSI
NROFJOBIPHS
1 4
1 2 3 4
CIPR
TRD1

This will yield density matrices mixed according to the MS-CASPT2 calculation, which can in turn be analyzed by TheoDORE.

Unfortunately, it is not possible to use the EJOB keyword in connection with this procedure. Therefore, the energies and oscillator strengths given are not consistent!

Tubomole

CC2 / ADC(2)

If you have the binary CCRE0* files, written by Turbomole, available, then choose the option

read_binary=True

in dens_ana.in. Use tm2molden without further options to create the MO file. For printing the NTOs, it is not possible to use ` jmol_orbitals` in this case, but only molden_orbitals.

Alternatively, approximate transition density matrices can be read directly from the standard output of ricc2. The MO file is again created with tm2molden. However, it is important that also the frozen orbitals are contained in the MO file. This can be achieved by running the following commands:

#!/bin/bash
sed -i "/implicit core/d" control
echo -e "\n\n"|tm2molden

TDDFT

In the TDDFT case, the sing_a or trip_a files are parsed and interpreted as 1TDMs. For CIS/TDA, the ciss or cist files are read. This analysis only works if no explicit symmetry is chosen in the initial job setup.

MO-coefficients have to be supplied by tm2molden.

Terachem - TDDFT

For a trans. dens. mat. analysis, the CI vectors are read from standard output and the MO coefficients from a Molden file produced by Terachem. To print more CI vector elements, use

cisprintthresh 0.01

A state/difference density matrix analysis is possible by using the NO files produced when using

cisnos   yes

Natural orbital files

Natural orbital (NO) files can be parsed directly using analyze_nos. Alternatively, you can use theoinp follows by analyze_sden. This analysis works on NO files, produced for example by Q-Chem/libwfa, Columbus, and OpenMolcas. Alternatively, MO files of DFT jobs may be used, for example to compare singlet and triplet states or states with different electron number.

Run theodore analyze_nos -h to see all command line options. Some care needs to be taken in order for TheoDORE to understand the data given correctly.

For analysis of NOs, it is important that one reference containing the full invertible MO-matrix is given. This file can be specified using the -r option.

ORCA

ORCA - TDDFT

Starting in TheoDORE 2.0.1, the preferred version of parsing ORCA TDDFT jobs uses a Molden format file and the orca.cis file.

  1. Run an ORCA job and copy back the orca.gbw and orca.cis files. Note: the filename orca.cis is hardcoded in TheoDORE.

  2. Create a molden file using orca_2mkl orca -molden

  3. Run theodore theoinp and select 13 at

Type of job (rtype):
...
  [12]      cclib - Use external cclib library: Gaussian, GAMESS, ...
  [13]       orca - ORCA TDDFT (using a Molden file and cclib)
...
Choice: 13

This produces the following input file dens_ana.in

rtype='orca'
rfile='orca.out'
read_binary=True
mo_file='orca.molden.input'

ORCA using cclib

Alternatively, ORCA can be parsed entirely with the cclib library. If you want to do that, set the following output options:

%output
 PrintLevel Normal
 Print[ P_MOs ] 1
 Print[ P_Overlap ] 1
end

It is recommended also in this case to read the CI-vectors from the binary file orca.cis rather than from standard output. To do this, set

read_binary=True

In the case of TDA both options work, for RPA read_binary=True has to be used.

Gaussian - TDDFT

Gaussian is parsed with the cclib library. Set the pop=full iop(9/40=3)` option to increase the number of CI vector elements printed. Use GFINPUT to print the basis functions and iop(3/33=4)` to get the overlap matrix.

Example input:

#p PBEPBE/6-31G* td=(singlets, nstates=10) pop=full iop(9/40=3) GFINPUT

For some applications, in particular in connection with ORBKIT, it is advisable to supply an externally generated molden file with orbital information. For this purpose, open the Gaussian-log file in Molden. Choose “Write - Molden Format” and save as orbs.mld. Then specify this file in dens_ana.in:

mo_file=orbs.mld

Firefly - TDDFT

Firefly has been succesfully interfaced with TheoDORE, see EXAMPLES/CCLIB/SnH4-ecp.firefly. Firefly output is parsed with the cclib library.

ADF - TDDFT

In the new ADF interface all information is read from the binary TAPE21 file. Use the rfile option to point to this file.

To run the analysis, you need to activate the ADF scripts and license, e.g.

. ~/adfrc.sh
export SCMLICENSE=/usr/license/adf/licenses/license.txt
export PYTHONPATH=$PYTHONPATH:/usr/license/adf/adf2016.101/scripting

The interface analyzes the eigenvectors of the reduced dimensional problem as printed out by ADF. Note, that these are only normalized in the case of the Tamm-Dancoff approximation.

It is not possible to visualize NTOs using the TheoDORE/ADF interface since Slater type orbitals, as employed by ADF, are not supported. It is, however, possible to compute NTOs within ADF itself.

The atom-numbering for at_lists pertains to the original ordering in the input file rather than the internal ordering used by ADF.

DFTB+ - TDDFTB

An interface to DFTB+ was written by Ljiljana Stojanovic. This interface currently reads the following files:

  • EXC.DAT (main excited state information) - specified as ‘rfile’

  • eigenvec.out (MO coefficients) - specified as ‘mo_file’

  • XplusY.DAT (response vector)

  • SPX.DAT (ordering of response vector)

  • geom.xyz (geometry information)

  • detailed.out (orbital occupations and energies)

  • wfc.3ob-3-1.hsd (DFTB parameter file)

DFT/MRCI

TheoDORE also features an interface to the DFT/MRCI program. Singlet and triplet states can be analyzed. The interface works for analyze_tden as well as analyze_sden. Example inputs/outputs are presented in EXAMPLES/STANDARD/fa2.dftmrci.

To use TheoDORE, run DFT/MRCI and generate density matrices. You can use, for example, the following workflow

mrci_serial < mrci.inp > mrci.out
cp mrci.refconf mrci2.inp
mrci_serial < mrci2.inp > mrci2.out
sed 's/orca/orca\n$dmat/' mrci2.inp > mrci2_dmat.inp
mrci_serial < mrci2_dmat.inp > mrci2_dmat.out

This will produce the mrci2.out and mrci.cidens files to be read by TheoDORE.

ONETEP - TDDFT

An interface for TDDFT computations in ONETEP is available. Currently (October 2021) this interface requires a developoment version of ONETEP. The interface can perform an analysis of CT numbers but no exporting of orbitals or densities is possible.

Analysis occurs in a mixed basis where excitations proceed from a valence basis to a joint basis. TheoDORE needs information on both types of bases to operate. The following files are required:

  • <rfile>.onetep

  • <rfile>_response_denskern_*.dkn_dens.mat

  • <rfile>.jointngwf2atoms/valngwf2atoms

  • <rfile>.jointoverlap.mat/valoverlap.mat

Here, <rfile> is a joint prefix to all the files, which is read from the input file dens_ana.in and can be specified via theoinp.

Other programs (cclib)

In principle all third party programs, which are parsed by the cclib library can be used. These are: ADF, Firefly, GAMESS, Gaussian, Jaguar, Molpro, ORCA. But not all of these have been tested by the developers and it may be necessary to set some additional program specific options. Please report, if you did so successfully.

To quickly check whether a logfile can be parsed by cclib, simply type:

cc_check.py <logfile>