QMay

Introduction

Installation

Installation from source code.

Prerequisites

For Cygwin see Installing on Cygwin for the prerequisites.

Compulsory Prerequisites

• C++ compiler
• libxml2 library and header files
• BLAS library
• LAPACK library

On openSUSE these requirements can be satisfied with:

zypper in gcc-c++ libxml2 libxml2-devel blas-devel lapack-devel

Optional Prerequisites

• libcint library and header files

Configuration

Run

./configure

The choice of C++ compiler and flags can be modified in the normal autoconf way, eg.:

./configure CXX=g++ CXXFLAGS=-Ofast

One can specify non-default location of libraries etc. via the command line in the usual autoconf way, eg. for using MKL:

export LD_LIBRARY_PATH="/opt/intel/mkl/lib/intel64:${LD_LIBRARY_PATH}"
./configure CXX=icpc LDFLAGS="-L/opt/intel/mkl/lib/intel64" \
            LIBS="-lmkl_intel_lp64 -lmkl_core -lmkl_sequential -lpthread"

Building

Run

make [-j n]

Testing the build

To test the build simply run:

make [-j n] check

or to run only a given set of tests the TESTS variable can be set, eg:

make [-j n] check TESTS="he2_s.xml h2o_zmat.xml"

Note: for cross-compilation systems you will need to execute this on the target architecture.

Installing on Cygwin

When installing Cygwin the following packages need to be installed in addition to those installed by default:

Package	Package Group	Reason
gcc-core	Devel	compiling C files
gcc-g++	Devel	compiling C++ files
make	Devel	building packages
libxml2	Libs	libxml2 library
libxml2-devel	Libs	libxml2 headers
liblapack-devel	Libs	BLAS/LAPACK library
ncurses	Utils	tput for pretty make check

and the libcint library should also be built and installed. QMay can then be configured and built in the normal way.

Notes about input files

QMay input files are well formerd XML files which are read and processed sequentially, thus the order in which things appear matters. eg. geometry declaration should come before basis declaration.

Why XML?

XML files are easy to verify which makes it easy to detect some common input mistakes. There are also standard tools for reading XML files.

Case sensitivity

XML is case sensitive, so case does matter for the XML parts of the file. For convenience we made the decision that all XML node and attribute names in QMay input files are lowercase. Additionally, most attribute strings should be lowercase except where it makes no sense, eg. in the case of giving a filename. The text data for nodes is case insensitive, so don't worry, you can copy a geometry or basis section from your favourite other program.

Geometry

A geometry block should simply contain the geometry in Z-matrix format. Example:

<geometry>
He
He,He,1.0
</geometry>

or in XYZ format. Example:

<geometry type="xyz">
2
Helium dimer
He   0.0  0.0  0.0
He1  0.0  0.0  1.0
</geometry>

By default the units are assumed to be angstrom, but this can be changed to bohr with the units attribute if required:

<geometry units="bohr">
...
</geometry>

Options

• debug [0 | 1] Switch on debugging or not.
• type [xyz | zmat] Format of the geometry
  • xyz - XYZ format
  • zmat - Z-matrix format
• units [angstrom | bohr] Units of geometry
  • angstrom - Angstroms
  • bohr - Bohr

Basis

The available basis sets in the library can be printed with:

qmay --print-basis-library

Explicit basis specification

Rather than create yet another basis specification, the QMay basis block accepts a subset of the Molpro basis specifications. All specifications start with ang,label, where ang is the angular momentum, eg. s or df, and label must match a corresponding entry in the geometry block.

• Basis library:
  
  ang,label,name
  
  where name is an entry from the basis library.
• Explicit exponents:
  
  ang,label,exponent1,exponent2,...
  
  where the exponents of the basis can be explicitly given.
• Even tempered exponents:
  
  ang,label,even,nexp,ratio,centre
  
  where instead of explicit exponents, nexp exponents are generated based on the ratio and centre.
• 3-term tempered exponents:
  
  ang,label,even3,nexp,$\alpha$,$\beta$,$\gamma$
  
  where instead of explicit exponents, $n=\mathrm{nexp}$ exponents are generated according to:
  
  $e_0=\alpha ;e_{\mathrm{i}}=e_{\mathrm{i}-1}\beta /\left(1+\frac{\gamma i^2}{{\left(n+1\right)}^2}\right),i=\mathrm{1,}...n-1$
• Even tempered basis set with confined progression:
  
  ang,label,evenp,nexp,$\alpha$,$\beta$,$\gamma$
  
  where instead of explicit exponents, $n=\mathrm{nexp}$ exponents are generated, where $\alpha$ is the first and largest exponent. The ratio between the first and second exponent is given by $p\left(\beta \right)$, and the ratio between the penultimate and last exponent is given by $p\left(\gamma \right)$. The ratios inbetween are determined by 'switching' linearly from a $\beta$ to $\gamma$ based ratio. The expression for the exponents is:
  
  $e_0=\alpha ;e_{\mathrm{i}}=e_{\mathrm{i}-1}/\left(\frac{\left(n-i-1\right)p\left(\beta \right)+\left(i-1\right)p\left(\gamma \right)}{n-2}\right),i=\mathrm{1,}...n-1$
  
  where:
  
  $p\left(\beta \right)=\frac{5}{\pi }\left(\arctan \left(\beta -2.5\right)+\frac{\pi }{2}\right)+\sqrt{2}$

Options

• debug [0 | 1 | 2] level of debugging output
• type [orbital] type of basis set
• contractions [general | segmented] type of contractions
  • general - Use general contractions
  • segmented - Use segmented contractions
• form [cartesian | spherical] form of basis functions
  • cartesian - Use cartesian basis functions
  • spherical - Use spherical basis functions
• print [0 | 1 | 2] level of basis output
  • 0 - show only summary information
  • 1 - additionally show exponents and contraction coefficients
  • 2 - additionally show normalization constants

Restricted Hartree-Fock Program

The Restricted Hartree-Fock program. The eigenvectors of the core Hamiltonian (h0) are used for the initial starting guess.

Options

• diis [0 | 1] whether to use DIIS or not
• print [0 | 1 | 2]
• scheme [default | os | libcint | libcintno] integral evaluation scheme
  • default - Depends on how the program was built; libcint if available, os otherwise
  • os - QMay Obara-Saika [1] routines
  • libcint - libcint routines
  • libcintno - libcint routines with optimizer disabled
• mode [direct | disk | memory] 2-electron integral evaluation mode
  • direct - Recompute integrals each time needed
  • disk - Compute integrals once and store on disk
  • memory - Compute integrals once and store in memory
• energy [1.0e-9] specify energy threshold to consider SCF iterations converged
• thresh [1.0e-6] specify eigenvalue threshold to consider SCF iterations converged
• minseig [1.0e-8] specify smallest allowed eigenvalue of the overlap matrix
• maxit [50] maximum number of SCF iterations in the case of non-convergence

CODATA

The codata directive can be used to specify the CODATA values. Since QMay files are processed sequentially it is generally a good idea that this directive, if required, should be one of the first directives, unless it is intended to modify the CODATA values during the job. With no options specified the codata directive will simply print the current values.

Options

• revision specify which set of values to use, can take the following values
  • 2010 - use 2010 values, see [8], [9]
  • 2006 - use 2006 values, see [6], [7]
  • 2002 - use 2002 values, see [5]
  • 1998 - use 1998 values, see [4]
  • 1986 - use 1986 values, see [3]
  • 1973 - use 1973 values, see [2]
  • 1969 - use 1969 values, see [10]
• bohr_to_ang specify explicitly the value of the Bohr radius

Orient

The orient directive can be used to reorientate the system.

Options

• translate [charge | mass | none] Translate the Molecule
  • charge - re-centre the system so the origin is the centre of charge
  • mass - re-centre the system so the origin is the centre of mass
  • none - do not translate
• rotate [none] Rotate the system
  • none - do not rotate

Mass

The mass directive can be used to change the masses of the current geometry.

Options

• value New mass value
• element Change mass for all centres that contain this element
• label Change mass for all centres with this label

Conditions for running a job

This top level attribute allows one to specify whether a job should run. It is primarily implemented for test inputs to be skipped when a feature is missing, but it might be used to see earlier whether a job will definitely fail. The syntax is a comma separated list, eg.:

<qmay conditions="octave"> <!-- require octave to be found in PATH -->

The current list of conditions is:

• libcint - whether the libcint integrals are available
• octave - whether octave is found in PATH

Bibliography

[1] S. Obara and A. Saika. Efficient recursive computation of molecular integrals over cartesian gaussian functions. J. Chem. Phys., 84(7):3963–3974, 1986.

[2] E. R. Cohen and B. N. Taylor. The 1973 least‐squares adjustment of the fundamental constants. J. Phys. Chem. Ref. Data, 2(4):663–734, 1973.

[3] E. R. Cohen and B. N. Taylor. The 1986 adjustment of the fundamental physical constants. Rev. Mod. Phys., 59(4):1121–1148, 1986.

[4] P. J. Mohr and B. N. Taylor. Codata recommended values of the fundamental physical constants: 1998. Rev. Mod. Phys., 72(2):351–495, 2000.

[5] P. J. Mohr and B. N. Taylor. Codata recommended values of the fundamental physical constants: 2002. Rev. Mod. Phys., 77(1):1–107, 2005.

[6] P. J. Mohr, B. N. Taylor, and D. B. Newell. Codata recommended values of the fundamental physical constants: 2006. Rev. Mod. Phys., 80(2):633–730, 2008.

[7] P. J. Mohr, B. N. Taylor, and D. B. Newell. Codata recommended values of the fundamental physical constants: 2006. J. Phys. Chem. Ref. Data, 37(3):1187–1284, 2012.

[8] P. J. Mohr, B. N. Taylor, and D. B. Newell. Codata recommended values of the fundamental physical constants: 2010. Rev. Mod. Phys., 84(4):1527–1605, 2012.

[9] P. J. Mohr, B. N. Taylor, and D. B. Newell. Codata recommended values of the fundamental physical constants: 2010. J. Phys. Chem. Ref. Data, 41(4):043109, 2012.

[10] B. N. Taylor, W. H. Parker, and D. N. Langenberg. Determination of e/h, using macroscopic quantum phase coherence in superconductors: Implications for quantum electrodynamics and the fundamental physical constants. Rev. Mod. Phys., 41(3):375–496, 1969.