Interface Data Files:   idf | wfn | bdf

Synopsis

[-]( idf | wfn | bdf)   <filename>

Description

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.

  1. AIM wavefunction files (.wfn)
  2. VALRAY binary data files (.bdf)
  3. VALRAY ascii input files (.dat)
  4. XD files
  5. Gaussian CUBE Files (.cub, .cube)
  6. Crystallographic Information Files (.cif)
  7. CRYSTAL print-output files
  8. Promolecule files

VALRAY .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.

  1. 1. - AIM wavefunction files (.wfn)

    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:

    Among 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.

  2. 2. - 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.
    ]

  3. 3. - 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.

  4. 4. - 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.[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:

    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
    ./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.

  5. 5. - Gaussian Cube Files (.cub, .cube)

    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.

  6. 6. - 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")[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
        
  7. 6. - CRYSTAL print output files

    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).

  8. 7. - Promolecule

    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
        

References

  1. “Official Atoms in Molecules Download Site”.
    https://www.chemistry.mcmaster.ca/aimpac/imagemap/imagemap.htm. Accessed 19 Nov 2018.
  2. 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.
  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. “CIF Applications. V. CIFtbx2: extended tool box for manipulating CIFs”
    Hall, S. R.; Bernstein, H. J. J. Appl. Cryst. 1996, 29, 598-603. DOI: 10.1107/S0021889896006371.
  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). Website of the AIMAll package: http://aim.tkgristmill.com/. Accessed 25 Nov 2018.
  6. “Format specification for AIM Extended Wavefunction Files (.wfx files) Version 1.0.4c.” Online resource: http://aim.tkgristmill.com/wfxformat.html. Accessed 25 Nov 2018.
  7. “Gaussian.com | Expanding the limits of computational chemistry”. Website of the GAUSSIAN package: https://www.gaussian.com. Accessed 16 April 2019.
  8. “General Atomic and Molecular Electronic Structure System”.
    M.W.Schmidt, K.K.Baldridge, J.A.Boatz, S.T.Elbert, M.S.Gordon, J.H.Jensen, S.Koseki, N.Matsunaga, K.A.Nguyen, S.Su, T.L.Windus, M.Dupuis, J.A.Montgomery J. Comput. Chem. 1993, 14, 1347-1363.
  9. “Advances in electronic structure theory: 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.
  10. GAMESS: General Atomic and Molecular Electronic Structure System”. Online resource: http://www.msg.ameslab.gov/gamess/. Accessed 25 Nov 2018.
  11. GAMESS online documentation: Input Description”. Online resource: http://www.msg.ameslab.gov/gamess/GAMESS_Manual/input.pdf. Accessed 2 Nov 2018.
  12. “Amsterdam Density Functional (ADF): powerful DFT software for modeling chemistry.” Official web site: https://www.scm.com/product/adf/. Accessed 10 Apr 2019.
  13. “Example: adf2aim: convert an ADF TAPE21 to WFN format (for Bader analysis).” Online resource: https://www.scm.com/doc/ADF/Examples/AIM_HF.html.  Accessed 10 Apr 2019.
  14. “The ORCA program system”. Neese, F. Wiley Interdiscip. Rev.: Comput. Mol. Sci. 2012, 2, 73-78.
  15. ORCA: An ab initio, DFT and semiempirical SCF-MO package”.
    Online resource: https://orcaforum.kofo.mpg.de.   Accessed 10 Apr 2019.
  16. 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.
  17. “NWChem: a comprehensive and scalable open-source solution for large scale molecular simulations”.
    M. Valiev, E.J. Bylaska, N. Govind, K. Kowalski, T.P. Straatsma, H.J.J. van Dam, D. Wang, J. Nieplocha, E. Apra, T.L. Windus, W.A. de Jong, Comput. Phys. Commun. 2010, 181, 1477-1489.
  18. “NWChem: Open Source High-Performance Computational Chemistry”. Online resource: http://www.nwchem-sw.org  Accessed 26 Nov 2018./li>
  19. “NWChem User Documentation”. Online resource: https://github.com/nwchemgit/nwchem/wiki/  Accessed 26 Nov 2018.
  20. “NWChem: Properties”. Online resource: https://github.com/nwchemgit/nwchem/wiki/Properties  Accessed 26 Nov 2018.
  21. Álvaro Vázquez-Mayagoitia “Generator of AIM Wavefunction files NWCHEM [WFN / WFX].” Online resource: https://sites.google.com/site/alvarovazquezmayagoitia/goals/codes/nwchem-notes/generator-of-aim-wavefunction-files-nwchem  Accessed 26 Nov 2018.
  22. “The Molden Format”.  Online resource: http://cheminf.cmbi.ru.nl/molden/molden_format.html. Accessed 26 Nov 2018.
  23. 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.
  24. (a) “Molden 2.0: quantum chemistry meets proteins”.
    Gijs Schaftenaar, Elias Vlieg and Gerrit Vriend  J. Comput. Aided Mol. Des. 2017, 31, 789.
    (b) “Molden: a pre- and post-processing program for molecular and electronic structures”.
    G.Schaftenaar and J.H. Noordik  J. Comput. Aided Mol. Des. 2000, 14, 123-134.
  25. Gijs Schaftenaar, “MOLDEN a pre- and post processing program of molecular and electronic structure”, CMBI, the Netherlands.
    Online resource: http://cheminf.cmbi.ru.nl/molden/. Accessed 26 Nov 2018.
  26. “cubegen.” Website of the Gaussian program package: https://gaussian.com/cubegen/. Accessed 11 Oct 2017.
  27. Volkov, A.; Macchi, P.; Farrugia, L.: Gatti, C.; Mallison, P.; Richter, T.; Koritsanszky, T.; 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). Official Web Site: http://www.chem.gla.ac.uk/~louis/xd-home/. Accessed 12 Apr 2019.
  28. (a) “Quantum‐mechanical condensed matter simulations with CRYSTAL
    Dovesi, R.; Erba, A.; Orlando, R.; Zicovich‐Wilson, C. M.; Civalleri, B.; Maschio, L.; Rérat, M.; Casassa, S.; Baima, J.; Salustro. S; Kirtman, B. Wiley Interdisciplinary Reviews: Computational Molecular Science (WIREs Comput. Mol. Sci.) 2018, 8, 4, e1360. DOI: 10.1002/wcms.1360.
    (b) “CRYSTAL17 User's Manual” R. Dovesi, V. R. Saunders, C. Roetti, R. Orlando, C. M. Zicovich-Wilson, F. Pascale, B. Civalleri, K. Doll, N. M. Harrison, I. J. Bush, P. D’Arco, M. Llunell, M. Causà, Y. Noël, L. Maschio, A. Erba, M. Rerat and S. Casassa (University of Torino, Torino, 2017).
    (c) “CRYSTAL: a computational tool for solid state chemistry and physics.” Website: http://www.crystal.unito.it/. Accessed 19 Apr 2019.