The keyword IDF is
an acronym for Interface Data File and defines a
pathname to a disk file which has been generated by other computer packages
and contains all the experimental or theoretical data needed for evaluating
the electron density of an isolated molecule or molecular crystal.
The WFN alias refers to the wave function file generated by different
quantum-mechanical programs according to the format required by the
AIMPAC code.[1Official Atoms in Molecules Download Site]
Similarly the BDF alias remembers the binary data file produced by the
VALRAY code.[2Stewart, R. F.;
Spackman, M. A.; Flensburg, C.VALRAY User's Manual
(Version 2.1), Carnegie-Mellon University, Pittsburg, and University of
Copenhagen, Copenhagen, 2000.]
Currently the two aliases can be used indifferently, next to IDF, to indicate
any interface data file.
PAMoC is interfaced to two main classes of
software codes, namely ab initio electronic structure packages and
computer programs for multipole refinement of experimental and theoretical
structure factors. Eventually, PAMoC accepts other types of
IDF (like CIFs[3Mallison, P. R.; Brown,
I. D.
Classification and use of electron density data
in
International Tables for Crystallography, Volume G, Definition and exchange
of crystallographic data.
Hall, S.; McMahon, B. (Eds.); Section 3.5,
pp. 141-143. Dordrecht: Springer, 2005, ISBN: 978-0-470-68910-3.
IUCr
online edition, 2006, ISBN: 978-1-4020-3138-0, DOI:
10.1107/97809553602060000107.,
4Hall, S. R.; Bernstein, H. J.
J. Appl. Cryst. 1996, 29, 598-603.] and
CRYSTAL print-output files), but in these cases the actions that
PAMoC can take, are limited by the type and content of the IDF
itself, and additional data input may be required.
A list of the IDFs recognized by PAMoC is
reported below. Each item in the list is a link to a subsequent paragraph that
provides the necessary details. If needed, a full description of the
structure and use of the interface data file will be given in a separate
page of the manual.
VALRAY binary data files (.bdf)VALRAY ascii input files (.dat)XD filesGaussian CUBE Files (.cub, .cube)CRYSTAL print-output filesVALRAY .bdf is the only binary data file recognized by
PAMoC. The remaining IDFs are all ascii files.
PAMoC distinguishes one from the other because of a specific
character string in the first line of each file.
In the absence of such a string, the IDF is assumed to be an AIM wavefunction
file.
Many popular ab initio quantum chemistry programs can create
a traditional AIM wavefunction file (extension .wfn) and, eventually, an
extended AIM wave function file (extension .wfx). The extended AIM wavefunction
file is a new wavefunction file format originally defined for
AIMAll.[5“Computational Chemistry Using the Quantum
Theory of Atoms in Molecules (QTAIM)”
AIMAll (Version 17.11.14),
Todd A. Keith, TK Gristmill Software, Overland Park KS, USA, 2017
(aim.tkgristmill.com)]
The .wfx
file format[6Format specification for AIM
Extended Wavefunction Files (.wfx files) Version 1.0.4c]
is not supported by PAMoC.
Here we mention a few general purpose ab initio electronic structure packages which are capable of producing .wfn files:
GAUSSIAN-XX.[7Gaussian.com | Expanding the limits of
computational chemistry]
In this package the Output=Option keyword is
most often used to create input file for various external programs, and
must be included in the route section of the GAUSSIAN input
file, together with some other useful keywords:
GAUSSIAN to write
an AIM wavefunction file. The wavefunction-file-name must be
entered on a separate line at the end of the GAUSSIAN
input file. Alternatively, Output=WFX
writes a wavefunction file used by the newer versions of
AIMPAC (.wfx files).PAMoC expects that the basis set contains 6d and 10f
cartesian functions (rather than the standard pure 5d and 7d).GAMESS.
[8M.W.Schmidt, K.K.Baldridge, J.A.Boatz,
S.T.Elbert, M.S.Gordon, J.H.Jensen,GAMESS: General Atomic and
Molecular Electronic Structure System]
In order to produce the AIM wavefunction data, the input file should
include:[11“GAMESS
online documentation: Input Description”.]
The AIM wavefunction data are written to file .dat at the end of the job.
ADF.[12Amsterdam Density Functional (ADF):
powerful DFT software for modeling chemistry.] The
ADF package contains the utility adf2aim
which converts an ADF TAPE21 to WFN format (for Bader
analysis).[13Example: adf2aim: convert
an ADF TAPE21 to WFN format (for Bader analysis).]ADF uses Slater Type Orbitals, STOs, as
basis functions, but currently the use of STOs by PAMoC
requires some fixes.)
1s, 2s, 3s, 4s, 5s, 6s, 7s
2p, 3p, 4p, 5p, 6p, 7p
3d, 4d, 5d, 6d
4f, 5f
ORCA
.[14Neese, F. Wiley
Interdiscip. Rev.: Comput. Mol. Sci. 2012, 2,
73-78.,
15ORCA: An ab initio, DFT
and semiempirical SCF-MO package.] The package contains
the utility program orca_2aim which reads a .gbw
file and creates a .wfn file.
Currently this works only for closed-shell wave functions. The usage is
very simple – just type AIM in the simple input line of your
input file, or use the shell command “ orca_2aim
BaseName ” (will produce
BaseName.wfn from BaseName.gbw).[16ORCA manual - Version
4.0.1]NWChem.[17M. Valiev, E.J. Bylaska, N. Govind, K. Kowalski, T.P.
Straatsma, H.J.J. van Dam,NWChem: Properties.] with the keyword
AIMFILE.
The properties module is started when the task directive
“TASK property” is defined in the user
input file. More details are given in reference[21Álvaro Vázquez-MayagoitiaAmong the ab initio packages mentioned above, only
GAMESS, ORCA, and NWCHEM are distributed
at "no cost", at least for academics.
An alternative route to generate a .wfn file is to first
generate a Molden File[22The
Molden Format] and then to convert the Molden File
into a .wfn file by using the Molden2AIM utility
program.[23Molden2AIM: a utility
program to create AIM-WFN, AIM-WFX, and NBO-47 files from a Molden
file.]
The Molden File is a sort of wavefunction file originally defined
for MOLDEN to support a number of other programs.[24(a) Schaftenaar, G.; Vlieg, E.; Vriend, G.
J. Comput. Aided Mol. Des. 2017, 31, 789.
(b) Schaftenaar, G.; Noordik, J.H. J. Comput. Aided Mol.
Des. 2000, 14, 123-134.,
25Gijs Schaftenaar, “MOLDEN a pre-
and post processing program of molecular and electronic structure”,
CMBI, the Netherlands.]
Many quantum mechanical codes can generate Molden files,
including ORCA and NWChem. NWChem
recommends to generate a Molden file with the
MOLDENFILE option in the property module, and then to convert the
Molden File into a .wfn file by using the
Molden2AIM utility program, instead of using the AIMFILE
option directly.[20NWChem:
Properties.]
Although it is not necessary for the PAMoC user to know the structure of the wave function file, the interested reader can find an accurate description of it on a separate page of this manual.
VALRAY binary data files (bdf)VALRAY is a program package for multipole
refinement and analysis of electron densities from X-ray diffraction data
based on Stewart multipole formalism. It stores and retrieves much of its
data on a binary data file (bdf), that PAMoC is able
to read. The structure of the VALRAY binary data file is
described in the VALRAY Users's Manual[2Stewart, R. F.; Spackman, M. A.; Flensburg, C.
VALRAY User's Manual (Version 2.1), Carnegie-Mellon University,
Pittsburg, and University of Copenhagen, Copenhagen, 2000.]
VALRAY ascii data input files (.dat)PAMoC can also read a VALRAY
ascii data input file, that has to be prepared by the user, following the
instructions in the VALRAY Users's Manual[2Stewart, R. F.; Spackman, M. A.; Flensburg, C.
VALRAY User's Manual (Version 2.1), Carnegie-Mellon University,
Pittsburg, and University of Copenhagen, Copenhagen, 2000.].
However, it is mandatory that the first line of the VALRAY
input file is REMARK VALRAY, in order to let
PAMoC know which type of IDF it is going to read.
XD is a computer program
package for multipole refinement and analysis of electron densities from
X-ray diffraction data based on Hansen-Coppens multipole formalism.[27 Koritsanszky, T.; Mallison, P.; Macchi,
P.; Volkov, A.; Gatti, C.; Richter, T.; Farrugia, L.:
XD2016.
A Computer Program Package for Multipole Refinement, Topological Analysis
of Charge Densities and Evaluation of Intermolecular Enerigies from
Experimental or Theoretical Structure Factors (2016).]
The XD interface data file must contain the identifier
XD as the first two characters, in order to let
PAMoC recognize the type of interface. Then the names of
the Master, Parameter and Databank files follow in this order, unless
they are introduced by a keyword. The recognized keyword are:
File-names must not contain any keyword-name as a substring. Any line
in the interface data file which begins with either '!' or '#' is a comment
line and therefore it is ignored by PAMoC.
An example of XD-interface-data-file (xd.idf) follows:
XD
!the sequence order of the next three lines
!is mandatory
./pathname/xd.mas
./pathname/xd.res
./pathname/xd.bnk_RHF_CR
The same IDF of the previous example can be written in the following way:
XD
!since keywords are being used, the sequence
!order of the next three lines is irrelevant
xdres ./pathname/xd.res
xdbnk ./pathname/xd.bnk_RHF_CR
xdmas ./pathname/xd.mas
The interface generates a disk file 'valray.dat' which
contains atomic scattering factors (FCORE,
FVAL, FLSHEL,
FDIPOL, FQUAD,
FOCTAP, FHEXAD) and atomic
populations (POPVAL) in VALRAY format,
available for merging into an input data deck for VALRAY
code.
WARNING: the interface between XD and
PAMoC is still in preparation. It has been tested for
calculation of outer moments (Stewart pseudoatom), intermolecular
interactions and lattice energies (Spackman model). Any application which
implies a direct evaluation of the electron density is likely to
fail.
The CUBE file is a common format for storing
molecular geometric and volumetric field data from quantum/computational
chemical calculations. It originates from the Gaussian software package.[7Gaussian.com | Expanding the limits of
computational chemistry] The official specification
of the CUBE file format, sanctioned by Gaussian, Inc., is
described on the Gaussian webpage[7Gaussian.com | Expanding the limits of computational
chemistry] as part of the document on the
“cubegen” utility.[26Gaussian utility
“cubegen”]
The interested user can find an accurate description of the CUBE
file format on a separate page of the PAMoC manual.
At the Sagamore XIII conference held at Stare Jablonski, Poland, in 2000, the IUCr Commission on Charge, Spin and Momentum Densities decided to prepare a CIF dictionary ("rhoCIF")[3Mallison, P. R.; Brown, I. D. “Classification and use of electron density data” in “International Tables for Crystallography, Volume G, Definition and exchange of crystallographic data.” Hall, S.; McMahon, B. (Eds.); Section 3.5, pp. 141-143. Dordrecht: Springer, 2005.] for reporting electron densities in crystals.
The XD program packege [27
Koritsanszky, T.; Mallison, P.; Macchi, P.; Volkov, A.; Gatti, C.;
Richter, T.; Farrugia, L.:
XD2016. A Computer Program Package
for Multipole Refinement, Topological Analysis of Charge Densities and
Evaluation of Intermolecular Enerigies from Experimental or Theoretical
Structure Factors (2016).] (starting from its 2003 version)
can read and write CIF's which include data items described in the "rhoCIF"
dictionary, as well as items in the "coreCIF" dictionary.
PAMoC actually uses a limited implementation of the
"rhoCIF" and "coreCIF" dictionaries, based on the CIFtbx library of
Fortran functions for programming CIF applications.[4Hall, S. R.; Bernstein, H. J. J. Appl. Cryst.
1996, 29, 598-603.]
The CIF-IDF must contain the identifier CIF
as the first three characters.
Then, the name of a standard CIF file follows, not necessarily on the
same line.
Optionally, an XD-type data-bank file-name (introduced by keywords
XDBNK or DBNK)
and a set of semicolon-separated dictionary file-names (introduced by
keyword DICT) can be provided on separate lines.
CIF dictionaries can be defined also through the environment variable
CIF_DIC (set externally to PAMoC).
Dictionaries defined in the IDF file override those defined externally.
If an XD-type data-bank file (atom wave-function) has been made
available, the interface generates a disk file, 'valray.dat', which
contains atomic scattering factors (FCORE,
FVAL, FLSHEL,
FDIPOL, FQUAD,
FOCTAP, FHEXAD) and atomic
populations (POPVAL) in VALRAY format,
suitable for merging into an input data deck for VALRAY
code.
Any line in the interface data file which begins with either '!' or '#' is a comment line and therefore it is ignored by PAMoC.
An example of CIF-interface-data-file (cif.idf) follows:
CIF ./pathname/lala.cif
dict ./pathname/cif_core.dic:./pathname/cif_rho.dic
xdbnk ./pathname/xd.bnk_RHF_CR
!uncomment next line to select a data-set among two or more data-sets in the CIF file
!data data-set-name
The CRYSTAL package[28CRYSTAL: a computational tool for solid
state chemistry and physics.] provides a
nuclear-centered multipole expansion of the periodic wave function,
based on Mulliken partitioning scheme. Mulliken moments can be used
to estimate molecule-molecule electrostatic interaction energies as
well as the electrostatic contribution to the crystal lattice
energy. The interface-data-file to PAMoC is the union of the
output files produced by the CRYSTAL programs
crystal (which calculates a periodic
wave-function) and properties
(which calculates spherical harmonics multipole moments, using the keyword
POLI).
The following shell-script illustrates the procedure:
#!/bin/csh # set EXEDIR = $HOME/bin/CRYSTAL98 date >& glycine-crystal98.ext hostname >>& glycine-crystal98.ext $EXEDIR/scfdir < glycine-crystal98.inp >>& glycine-crystal98.ext $EXEDIR/properties << ENDINPUT >>& glycine-crystal98.ext POLI 4 0 -4 END ENDINPUT date >>& glycine-crystal98.ext
Only a limited number of tests has been made, using versions 1998, 2003
and 2006 of the CRYSTAL package.
CRYSTAL print output files are also recognized by PAMoC as
an external-dma file (see keyword ext).
This type of IDF sets up a promolecule or a procrystal calculationA promolecule is defined to be a model of a molecule where the electron density distributions of each of its atoms have been spherically averaged and placed at their minimum energy positions. A similar definition holds for a procrystal. The independent-atom-model (IAM) alias promolecule or procrystal arrangement of neutral atoms.. The first line of the promolecule IDF must specify the identifier PROM as the first four characters. The remaining characters on the line may define a title for the job. All data in the promolecule IDF follow the syntax outlined in the Data Input Section of this manual. For a promolecule calculation only the coord block data is needed, unless fractional coordinates are given, in which case (i.e. the procrystal case) also the crystal block data (cell, latt, sym, space) are required.
An example of promolecule-interface-data-file (h2o.idf) follows:
PROM h2o
COORD BOHR
O 0.00000000 2.29990442 1.53036069
H 0.00000000 3.74285016 2.60003072
H 0.00000000 0.85696057 2.60003072
END
GAUSSIAN package:
https://www.gaussian.com. Accessed 16 April 2019.GAMESS
a decade later”. M.S.Gordon, M.W.Schmidt in “Theory and
Applications of Computational Chemistry: the first forty
years”, pp. 1167-1189, Elsevier, Amsterdam, 2005.GAMESS: General Atomic and Molecular Electronic
Structure System”. Online resource: http://www.msg.ameslab.gov/gamess/.
Accessed 25 Nov 2018.GAMESS online documentation: Input
Description”. Online resource:
http://www.msg.ameslab.gov/gamess/GAMESS_Manual/input.pdf.
Accessed 2 Nov 2018.ORCA program system”.
Neese, F. Wiley Interdiscip. Rev.: Comput. Mol. Sci.
2012, 2, 73-78.ORCA: An ab initio, DFT and semiempirical
SCF-MO package”.ORCA manual - Version 4.0.1”; § 9.33.9,
p. 744. Online resource:
https://cec.mpg.de/fileadmin/media/Forschung/ORCA/orca_manual_4_0_1.pdf
Accessed 25 Nov 2018.Molden2AIM: a utility program to create
AIM-WFN, AIM-WFX, and NBO-47 files from a Molden file.”. Online
resource:
https://github.com/zorkzou/Molden2AIM.
Accessed 26 Nov 2018.CRYSTAL”