Exckel

Exckel generates documents to summarise and visualise the results of excited state calculations in quantum chemistry. It automates the following task

• parse the output file of the quantum chemistry software
• select/filter excited states by their $<S^2>$ and/or their minimum oscillator strength
• plot the spectrum (with conversion to absorption coefficient and wavelength)
• calculate orbital and charge difference density cubes
• render images of the cubes
• write a summary document, which tabulates excitations and images of orbitals involved and the CDDs of the excited states

Exckel is completely written in Haskell, but basically it glues together existing solutions for the individual tasks.

• Quantum chemistry software supported:
  • Gaussian TDDFT/CIS (requires #p)
  • NWChem TDDFT/RPA
  • MRCC ADC(2)
  • ORCA TDDFT
• Cube calculator:
  • Multiwfn (tested with 3.5, gMultiwfn 3.4.1)
  • [REPA] (http://hackage.haskell.org/package/repa) (only CDDs from existing orbital cubes)
• Cube renderer:
  • VMD (tested with 1.9.3) & Tachyon

Usage

Exckel is a command line program and can be easily called from a bash script or simply directly from the command line. The minimum input you will need is the output file from your quantum chemistry code and a wavefunction file (molden or fchk).

By calling exckel exckel --help, a quick explanation of all possible keywords is provided.

The exckelargs program

exckelargs exckel [OPTIONS]

Flags:
   --nocalcorbs                Do not calculate cubes for orbitals.
   --nocalccdds                Do not calculate charge density difference
                               cubes.
   --norenderimages            Do not render images from cubes.
-o --outdir=DIR                Destination for all output files and
                               existing cubes.
   --vmd=FILE                  VMD executable. Default is first vmd
                               executable found on system.
   --vmdstate=FILE             VMD visualisation state file. Used to
                               determine perspective.
   --vmdstartup=FILE           VMD script to set up general look. If none
                               is specified, it will default to your vmdrc.
   --vmdtemplate=FILE          VMD template script for plotting.
-m --multiwfn=FILE             Multiwfn executable. Default is first
                               Multiwfn executable found on system
   --cddcalculator=STRING      Program to use to calculate charge density
                               differnces. [multiwfn | repa]
-t --tachyon=FILE              Tachyon executable. Default is first tachyon
                               executable found on system
   --panformat=STRING          Format of the summary to write with Pandoc.
                               Any of [docx | odt | latex]
   --panref=FILE               Reference docx with formatting hints.
   --wf=FILE                   Wavefunction file (molden or fchk).
   --exc=FILE                  Quantum chemistry software output file with
                               excited state informations.
-i --imgres=INT,INT            Image width x heigth for plotting of cubes.
   --s2filter=FLOAT            Filter excited states by contributions of
                               next higher spin state (applies to plotting
                               and summary).
   --foscfilter=FLOAT          Filter excited states by minimum oscillator
                               strength (applies only to summary document).
   --fwhm=FLOAT                Full width at half maximum of the gaussian
                               function used to convolute the stick spectrum
                               in electron volt.
   --weightfilter=FLOAT        Minimum weight of an excitation to write to
                               the summary. (default 0.01)
   --energyfilter=FLOAT,FLOAT  Energy range (eV) of the excited states of
                               interest and plot range for spectrum.
   --states=[INT]              Plot specific states and ignore all other
                               criteria in the summary. Give as "[a,b,c]"
   --calcsoftware=STRING       Calculation software, that produced the
                               output file. [gaussian | nwchem | mrcc | orca]
   --calctype=STRING           Calculation type. [tddft | rc-adc2 (reduced
                               cost ADC(2))]
   --spectrum=STRING           Program to plot the spectrum. [gnuplot |
                               spectrify]
-r --renumberstates            Renumber the states (energy order), after
                             high spin multiplicities have been removed by
                             "--s2filter".
Common flags:
-? --help                      Display help message
-V --version                   Print version information      Print version information

At least --wf and --exc must be set and point to your wavefunction file respective your quantum chemistry output file (with excited state information).

The destination of the output (and intermediate files) is determined by --outdir, which points to the path, where output shall be written. Next to writing all files to this directory, Exckel will look for potentially already existing files (such as images and cubes) in this directory. If not set, it defaults to the current directory.

An explanation of the workflow and the effects of the parameters follows.

Note: There is an alternative to calling exckel exckel, namely exckel tabulate, which provides other parameters but is only meant for creating table documents of many images but has nothing to do with excited state analysis.

Parsing, Plotting and Filtering

Relevant arguments:

• --s2filter
• --foscfilter
• --weightfilter
• --energyfilter
• --fwhm
• --states

Exckel starts by parsing the quantum chemistry log file and looks for the informations regarding excitations, multiplicity, number of basis functions and so on.

From the $<S^2>$ value of an excited state, one can calculate the contribution of the next higher spin state as a fractional amount. The excited states can be filtered by their spin state purity. As an example lets assume the multiplicity of your reference wavefunction was a triplet ($S = 1$). The $<S^2>$ value of a pure spin state should be $<S^2> = S * (S + 1) = 2$. From the true $<S^2>$ value of the excited state, the contributions of the quintetts to the state can be calculated. If the fractional contribution of the quintett is higher than the value specified with --s2filter, the state will be discarded completely and not used to plot the spectrum, nor will it appear in the summary table, nor will cubes and images for it be calculated.

Excited states can also be filtered by a minimum oscillator strength with --foscfilter. States discarded by this filter will still contribute to the spectrum, but will not appear in the summary table and CDDs and orbitals will not be calculate for this state.

If you use a very verbose output (small coefficients printed), you can restrict the number of CI determinants printed in the summary with --weightfilter. This will influence the summary table and the orbital cubes, that need to be calculated.

Gnuplot is then used to plot the spectrum (remaining states after --s2filter and within --energyfilter (in eV)) and save it to Spectrum.png in the output directory. A convolution of the stick spectrum is done by gaussian functions, for which the full width at half maximum can be specified with --fwhm (in electron Volt).

If you want to plot specific states, which can not be accessed otherwise (because they are dark for example), you can use the --states option. It will select only the states specified for cube generation and in the table summary but not touch the other filtering options, which are now only applied for plotting of the spectrum.

Calculating Cubes

Relevant arguments:

• --outdir
• --multiwfn
• --nocalcorbs
• --nocalccdds
• --energyfilter
• --cddcalculator

Charge difference densities and and orbitals are stored in cube files. If they are already present, you can use them (give --nocalcorbs and/or --nocalccdds). You will need to make sure, that they are available in the output directoy and named properly. Orbital cubes must be called orb${NORB}.cube, where $NORB is the number of the orbital (start counting from 1) and has no leading zeros. Alpha and beta orbitals of unrestricted wavefunctions are distinguished solely by this number, where the alpha orbitals have numbers from 1 to (number of basis functions) and the beta orbitals have numbers from (number of basis functions + 1) to (number of basis functions * 2). Charge difference density cube need to be labeled as CDD${NSTATE}.cube, the corresponding holes as hole${NSTATE}.cube and the electrons as electron${NSTATE}.cube. If cubes exist (from a previous calculation or calculated on a fast computer or something) and you want to use them, specify --nocalccubes. Otherwise existing cubes will be overwritten.

If cubes are not available yet, Exckel will call an external program to calculate orbitals from the log file and the wavefunction.

The CDDs can be calculated by Multiwfn or, if you use a QC code not supported by Multiwfn, such as NWChem, by Exckel internal functions, which neglect cross terms of the CDD. The REPA based internal calculation of CDDs is quite fast and deals with arbitrary high excitations but neglects the cross terms and needs cube for the orbitals, which can be calculated beforehand by Exckel or already be present. Be aware, that the precision here is limited by the accuracy of the log file. Also be aware that for REPA based CDDs all orbital cubes needs to be stored in RAM, so you might maybe need a few GiB.

Currently only Multiwfn is supported to calculate orbital cubes. By default the first Multiwfn executable found, will be used, but this can be changed by pointing --multiwfn to a Multiwfn executable.

Plotting cubes

Relevant arguments:

• --outdir
• --norenderimages
• --vmd
• --vmdstate
• --vmdstartup
• --vmdtemplate
• --tachyon
• --imgres

All cubes found in the output directory, which follow the correct naming scheme, will be plotted, if --norenderimages is not specified.

The only visualisation programm currently supported is the combination of VMD with Tachyon. To customise the appearance of the images, a variety of options is available. Most intreresting one is propably the file specified by --vmdstartup. This is a VMD Tcl script, which is executed by VMD before doing anything else. Here you can make general settings like colours, camera settings, ... . If this is not specified, Exckel will try going for your .vmdrc in the home directory and use this one. Therefore, if your happy with your defaults when opening VMD, you don't need to specify --vmdstartup.

The second option to customise the appearance of your images is --vmdstate. This argument should point to a VMD visualisation state file. Nothing except the camera perspective is taken from this file, but if it is not specified, you will need to live with the default perspective.

Last, a VMD Tcl template script is specified, which is the working horse here. This specifies everything that is necessary to get actual input files for Tachyon for every cube. The script used by Exckel is available in data/VMD.tcl of this repository and uses the ginger template engine to replace {{ orbs }} by a list of file base names of orbital cubes and {{ cdddens }} by a list of file base names of CDDs, electrons and holes. If you want to use your own Tcl script provide it via --vmdtemplate. Make sure it quits VMD properly, otherwise it will stay open forever.

VMD is called, writes input files for Tachyon (*.dat) and Tachyon (executable can be specified by --tachyon, defaults to first tachyon found) is called to render images in the resolution given by --imgres (defaults to 2000 x 1200 pixel). Make sure your Tachyon supports png output.

Writing the Summary Document

Relevant arguments:

• --outdir
• --pdformat
• --panref

From everything that is available up to now, the summary document will be created by Pandoc. You can choose to get the output as Microsoft Word docx (--pdformat=docx), as a LibreOffice/OpenOffice compatible Open Document Text odt (pdformat=odt) or as LaTeX source code (pdformat=latex).

The exact formatting of the output document depends on reference documents (--panref) in the case of ODT and DOCX files. If --panref is specified and points to a .docx or .odt document with formatting hints, these will be used. Otherwise a default is provided (and included in the executable, thanks TemplateHaskell) and automatically used.

The finaly summary is written to the output directoy as summary.*.

Example

For a Gaussian calculation of benzene, where you have Benzen.fchk as the wavefunction and Benzen.log as the log file of the calculation and want to write a summary for all excited states with an oscillator strength > 0.1 as a docx.

exckel exckel --wf=Benzen.fchk --exc=Benzen.log --outdir=exckel-out --foscfilter=0.1 --panformat=docx

Installation

Exckel needs serveral components to do all its work. Many of them are Haskell libraries and you don't need to take care of them, but calculators for the orbitals, visualisation software and the raytracing engine are system calls to standard quantum chemistry applications. Furthermore ImageMagick and Gnuplot are needed.

If you want to build from source, you will also need Haskell's stack tool, which takes care of building.

Dependencies

Installation of the external programs is up to you. Installation of them is quite easy.

• Multiwfn
• VMD
  • I highly recommended to customise VMD with the .vmdrc to fit your needs. This requires the least complex setup from VMD startup scripts, state files and template scripts.
• Tachyon
  • Can be compiled from source, but is also available in many linux distributions. The version bundled with VMD does not support PNG images.
• Gnuplot
  • On Linux is basically always included in the distributions, easy to install on Windows.
• ImageMagick
  • On Linux is basically always included in the distributions, easy to install on Windows.
• If you want to use ODT or LaTeX output Pandoc
• If building from source Haskell's Stack
  • Can be easily installed as a binary without any knowledge of Haskell

Building from Source

Clone the repository from git, use stack to install everything.

git clone https://github.com/sheepforce/Exckel.git
cd Exckel
stack install

Likely this will take some time, as especially Pandoc is a very large library, that takes some time to build.

Make sure the installation directory shown by stack is in your PATH.

Installing the Binary

For Linux a partially statically linked binary is available, which only requires most fundamental C libraries to be available on your system. Simply copy the binary to a directory of your choice and make sure it is in your PATH.