IDF|BDF|WFN

[-]idf|bdf|wfn  filename

This keyword enters the pathname to a valid interface data file (IDF) on disk.

The IDF provides a link between PAMoC and other computer packages, which are able to produce a representation of the electron density distribution of an isolated molecule or molecular crystal.

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 CIF's and CRYSTAL-XX 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.

Here is the list of recognized interfaces:

• AIM wavefunction files (.wfn files)
• VALRAY ascii data input files and binary data files (bdf)
• XD files
• 3D grid data files
• Crystallographic Information File (CIF)
• CRYSTAL-XX print output files
• promolecule

VALRAY bdf is the only binary data files recognized by PAMoC. The remaining IDF's 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.

AIM wavefunction files (.wfn files)

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. The .wfx file format is not yet supported by PAMoC.

Here we mention a few general purpose ab initio electronic structure packages which are capable of producing .wfn files that have been submitted to PAMoC successfully:

• GAUSSIAN-XX. The following keywords should be included in the route section of the Gaussian input file:
  1. OUTPUT=WFN, which tells 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.
  2. 6d 10f, because PAMoC expects that the basis set contains 6d and 10f functions (rather than the standard 5 and 7).
  3. DENSITY=CURRENT, which generates the desired wavefunction. This is vital when running correlated jobs. Otherwise the SCF (HF) density is stored in the wavefunction file. In addition, the FULL option for variational post-HF methods should be included, as the default is "frozen core".
  4. NOSYM, which causes both the geometry and basis set to be stored in the same reference system.
• GAMESS. AIM wavefunction decks are written to file PUNCH at the end of the job. The input file should include:
  1. AIMPAC=.TRUE. in the $CTRL section of the input file (this generates the desired wavefunction file). AIMPAC requires at least RUNTYP=PROP.
  2. MP2PRP=.TRUE. in the $MP2 section (this ensures that an MP2 wavefunction is generated).
• ADF. The interface between ADF and PAMoC still requires some fixes.

Among the three ab initio packages mentioned above, only GAMESS is distributed under a "site license at no cost". However there are other ab initio packages that are capable of producing .wfn files and are distributed at no cost, like ORCA (available under a research group license to academic users) and NWCHEM (distributed as open-source under the terms of the Educational Community License version 2.0, ECL 2.0). ORCA has a built-in procedure, instead NWCHEM needs a third-party patch.

VALRAY ascii data input files and 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.

Alternatively, PAMoC can read a VALRAY ascii data input file, that has to be prepared by the user, following the instructions in the VALRAY Users's Manual[1 Stewart, 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 files

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.[2 Koritsanszky, T.; Mallison, P.; Macchi, P.; Volkov, A.; Gatti, C.; Richter, T.; Farrugia, L.:
XD2006. A Computer Program Package for Multipole Refinement, Topological Analysis of Charge Densities and Evaluation of Intermolecular Enerigies from Experimental or Theoretical Structure Factors (2007).]

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:

1. XDMAS for the Master file;
2. XDPAR, XDINP, XDRES for the Parameter file;
3. XDBNK, DBNK for the Data-Bank file.

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
/home/username/src/pamoc/tests/lala/interfaces/xd.mas
/home/username/src/pamoc/tests/lala/interfaces/xd.res
/home/username/src/pamoc/tests/lala/interfaces/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 /home/username/src/pamoc/tests/lala/interfaces/xd.res
xdbnk /home/username/src/pamoc/tests/lala/interfaces/xd.bnk_RHF_CR 
xdmas /home/username/src/pamoc/tests/lala/interfaces/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.

The interface between XD and PAMoC is still in preparation. It has been tested for calculation of outer moments (Stewart pseudoatom) and of intermolecular interactions and lattice energies (Spackman model). Any application which implies a direct evaluation of the electron density is likely to fail.

3D grid data files

Gaussian Cube File Format

The cube file, originated by the Gaussian software package, is an ascii text file that consists of a header followed by volumetric data. All values in the cube file are in atomic units.

The Header. The first two lines of the header are comments (generally ignored by parsing packages or used as two default labels). PAMoC can recognize a 3d-grid or cube file if the first line of the header has CUBE as its first four characters.
The third line contains a) the number of atoms, followed by b) the x, y, z coordinates of the origin of the reference system, c) factor used to convert working units of lengths to atomic units (lengths are multiplied by factor on writing, and divided by factor on reading) and d) factor used to convert working units of volumetric values to atomic units (volumetric values are multiplied by factor on writing, and divided by factor on reading). The last two fields are not present in the original Gaussian Cube Files, but they are required by PAMoC.
The next three lines give the number of points along each axis, followed by the axis vector, which allows for non-cubic volumes.
The last section in the header consists of one line for each atom, with 5 numeric entries: a) the atom number, b) the atomic charge, and c) the three x, y, z coordinates of the atom.
The original Gaussian format arranged numerical integer values in a 5-digit wide fields (format I5) and floating point values in a 12-character wide field with 6 decimal places (format F12.6).

The Volumetric Data. This section consists of one floating point number for each volumetric element (format 6E13.9). The grid is arranged with the x axis as the outer loop and the z axis as the inner loop. It is written as (N_x*N_y) records, each of length N_z, with a separate write for each record and format 6E13.5 so that if N_z is not a multiple of six, there may be blank space in some lines.
A code like the following Fortran loop:

      Do Ix = 1, Nx                                      ! outer loop
         Do Iy = 1, Ny                                   ! middle loop
            Write(*,'(6E13.5)') (G(Ix,Iy,Iz),Iz=1,Nz)    ! inner loop
            end Do
         end Do
    

An Example. For a Gaussian density cube, the output file looks like this:

NAtoms, X0, Y0, Z0                      number of atoms and coordinates of the origin
Nx, Xx, Yx, Zx                          number of increments in the slowest running direction
Ny, Xy, Yy, Zy
Nz, Xz, Yz, Zz                          number of increments in the fastest running direction
IA1, Chg1, X1,  Y1,  Z1                 atomic number, charge, and coordinates of the first atom
...  ...  ...  ...  ...
IAn, Chgn, Xn,  Yn,  Zn                 atomic number, charge, and coordinates of the last atom
(Nx*Ny) records, each of length Nz      values of the density at each point in the grid
    

The coordinates (X,Y,Z) of a point (I_x, I_y, I_z) are calculated as:

X = X0 + (Ix - 1)*Xx + (Iy - 1)*Xy + (Iz - 1)*Xz
Y = Y0 + (Ix - 1)*Yx + (Iy - 1)*Yy + (Iz - 1)*Yz
Z = Z0 + (Ix - 1)*Zx + (Iy - 1)*Zy + (Iz - 1)*Zz
    

PAMoC Cube File Format

The cube file, originated by PAMoC, has the same structure of the cube file generated by the Gaussian software package. However it differs by the way that the volumetric data are printed out. Indeed, PAMoC uses the following Fortran loop:

      Do Iz = 1, Nz                                      ! outer loop
         Do Iy = 1, Ny                                   ! middle loop
            Write(*,'(6E13.5)') (G(Ix,Iy,Iz),Ix=1,Nx)    ! inner loop
            end Do
         end Do
    

      Do Iyz = 1, Ny*Nz                                  ! outer loop 
         Write(*,'(6E13.5)') (F(Ix,Iyz),Ix=1,Nx)         ! inner loop
         end Do
    

An example of 3d-interface-data-file (h2o.g3d), generated by PAMoC, follows:

Cube Generator is PAMoC: http://www.istm.cnr.it/˜barz/pamoc
 h2o at crystal (ice VIII) geometry: PBE0/DZP
    3   -5.698326   -4.069602   -4.167965    1.889726    1.000000
   64    0.180899    0.000000    0.000000
   71    0.000000    0.180899    0.000000
   66    0.000000    0.000000    0.180899
    8    8.000000    0.000000    2.299904    1.530361
    1    1.000000    0.000000    3.742850    2.600031
    1    1.000000    0.000000    0.856961    2.600031
  0.00000E+00  0.00000E+00  0.00000E+00  0.00000E+00  0.00000E+00  0.00000E+00
  0.00000E+00  0.00000E+00  6.98429E-17  1.18504E-16  1.96498E-16  3.18421E-16
  5.04269E-16  7.80440E-16  9.77505E-16  2.01124E-15  3.02443E-15  4.30273E-15
  5.98009E-15  8.11922E-15  1.07683E-14  1.39507E-14  1.76541E-14  2.18217E-14
  2.63461E-14  3.10688E-14  3.57855E-14  4.02589E-14  4.42372E-14  4.74136E-14
  4.97434E-14  5.09512E-14  5.09512E-14  4.97434E-14  4.74136E-14  4.42372E-14
  4.02589E-14  3.57855E-14  3.10688E-14  2.63461E-14  2.18217E-14  1.76541E-14
  1.39507E-14  1.07683E-14  8.11922E-15  5.98009E-15  4.30273E-15  3.02443E-15
  2.01124E-15  9.77505E-16  7.80440E-16  5.04269E-16  3.18421E-16  1.96498E-16
  1.18504E-16  6.98429E-17  0.00000E+00  0.00000E+00  0.00000E+00  0.00000E+00
  0.00000E+00  0.00000E+00  0.00000E+00  0.00000E+00
  0.00000E+00  0.00000E+00  0.00000E+00  0.00000E+00  0.00000E+00  0.00000E+00
  0.00000E+00  7.43726E-17  1.29124E-16  2.19086E-16  3.63280E-16  5.88688E-16
  7.64478E-16  1.68462E-15  2.70087E-15  4.03434E-15  5.88711E-15  8.39201E-15
! ............................................................................
! .............................. omitted lines ...............................
! ....... in this case there will be 64 x 71 x 66 floating point values ......
! ............................................................................
  3.49351E-12  2.36347E-12  1.56263E-12  1.00967E-12  6.37556E-13  3.93437E-13
  2.37273E-13  1.39842E-13  8.05464E-14  4.53389E-14  2.49409E-14  1.34082E-14
  7.04443E-15  3.61691E-15  1.81488E-15  8.89967E-16
    

Crystallographic Information File (CIF)

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")[3 Mallison, 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. ] for reporting electron densities in crystals.

The XD program package (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.[4 Hall, 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, available 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 /home/username/src/pamoc/tests/lala/interfaces/lala.cif
dict /home/username/src/pamoc/tests/lala/interfaces/cif_core.dic:/home/username/src/pamoc/tests/lala/interfaces/cif_rho.dic
xdbnk /home/username/src/pamoc/tests/lala/interfaces/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
    

CRYSTAL-XX print output files

The CRYSTAL package 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. PAMoC users are kindly invited to report bugs and problems to the author.

CRYSTAL print output files are also recognized by PAMoC as an external-dma file (see keyword ext).

promolecule

This type of IDF sets up a promolecule or a procrystal calculation A 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. For a promolecule calculation only the coord block data is needed, unless fractional coordinates are given, in which case also the crystal block data (cell, latt, sym, space) are required. For a procrystal calculation both the coord and the crystal (cell, latt, sym, space) block data are needed. Any line in the IDF beginning with either ! or # is a comment line. Data are provided in the form of a keyword followed by arguments, as shown in the following Table:

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
    

1. Stewart, R. F.; Spackman, M. A.; Flensburg, C. VALRAY User's Manual (Version 2.1), Carnegie-Mellon University, Pittsburg, and University of Copenhagen, Copenhagen, 2000.
2. Koritsanszky, T.; Mallison, P.; Macchi, P.; Volkov, A.; Gatti, C.; Richter, T.; Farrugia, L.: XD2006. A Computer Program Package for Multipole Refinement, Topological Analysis of Charge Densities and Evaluation of Intermolecular Enerigies from Experimental or Theoretical Structure Factors (2007).
3. Mallison, 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.
4. Hall, S. R.; Bernstein, H. J. J. Appl. Cryst. 1996, 29, 598-603.