MPQC is an object-oriented program that directly allows the user to specify objects that MPQC then manipulates to obtain molecular properties such as energies, forces, etc. This makes the input very flexible, but very complex. However, most calculations should be quite similar to the one of the examples given later in this chapter. The best way to get started is to use one of the test input files located in tests/validation/reference/inputs and modify it to meet your needs.
The object-oriented input format is described in the following sections:
- Overview of the Object-Oriented Input
- A Walk-Through of an Object-Oriented Input File
- Sample Object-Oriented Input Files
- Specifying MPQC Input in XML and INFO formats
Overview of the Object-Oriented Input
MPQC starts off by creating a KeyVal object that parses the input file specified on the command line. The MPQC input associates keywords with values. The values can be scalars, arrays, or groups of keyword/value pairs. The latter feature allows to create a hierarchy of keyword/value pairs so that each keyword has an absolute path describing its location in a hierarchy. The details of MPQC input are documented in the KeyVal documentation.
MPQC input can be specified in one of two industry-standard formats, JSON and XML, as well as the non-standard INFO format developed for the Boost.PropertyTree library. In practice we recommend using JSON since it is less verbose than XML and, unlike the INFO format, can be manipulated from most programming languages. Thus the rest of this document will focus on JSON only; Specifying MPQC Input in XML and INFO formats illustrates the correspondence between JSON, XML, and INFO formats.
The keywords recognized by MPQC are located at the top prefix. That is, they must be nested between the top-level curly brakets. The primary keywords that MPQC will examine are given below. Most of these keywords specify objects, thus they will be groups of key-value pairs used to construct the objects by calling the corresponding KeyVal constructors. The KeyVal constructors are documented with the source code documentation for each class.
property- This keyword specifies the Property object that will be evaluated by calling its Property::evaluate() method. The specialization of Property that is most commonly used is Energy, which computes a Taylor expansion of the molecular energy computed with a Wavefunction object with respect to the nuclear coordinates. There is no default value for this keyword.
unitsThis keyword specifies the units system to be used. The value of this keyword is a string that matches one of the values accepted by the UnitFactory::set_default() method. The default value is "2018CODATA", i.e., the 2018 CODATA revision of the fundamental constants is used.
There are also some utility keywords that tell mpqc some technical details about how to do the calculation:
debugger- This optional keyword gives a Debugger object which can be used to help find the problem if MPQC encounters a catastrophic error.
A Walk-Through of an Object-Oriented Input File
This example input does a Hartree-Fock calculation on water. Following is the entire input, followed by a breakdown with descriptions.
First, we specify the molecular property object that MPQC will evaluate. MPQC looks for the target property object by looking up keyword property. This keyword is followed by a : and then several keyword-value pairs separated by commas and enclosed in a pair of matching curly brakets. The data between the brakets contain the information that will be given to the KeyVal constructor of the particular Property specialization. But first MPQC wants to know which Property specialization it's dealing with here: that's given by the value of keyword type, in this case it's "Energy", which means this will be an object of class Energy .
String "Energy" is known as the key that globally identifies class Energy, and every class that is constructible from a KeyVal input must have one. Note the comma after "Energy": it is used in JSON to separate syntactic elements like keyword-value pairs and keyword groups.
The rest of the keywords in this section are used by the KeyVal constructor of the Energy class; these are listed in the documentation of the Energy class. The only such keyword is wfn:
Note that the value of wfn, namely $:wfn, is actually a reference to a Wavefunction object specification elsewhere else in the input file. The leading $ indicates that this is a reference and the keyword following the $ is the actual location of the Wavefunction object specification. The : in front of the keyword means that the keyword is not relative to the current location in the input, but rather relative to the root of the tree of keywords (i.e., the top-level JSON curly brakets). (this reference could have been also written relative to the current position in the keyword hiearchy, as $..:wfn). Thus, this line grabs the Wavefuntion object that is specified later in the input file.
- Todo:
- update when WavefunctionProperty parses
wfnAn interesting point is that if you look at the documentation for Energy, you will see that it doesn't readwfnkeyword. The KeyVal constructor of a derived class will typically call the base class KeyVal constructors, hence the derived class will examine all keywords of base classes. If you follow the base classes of Energy up to the Properties class, you'll find thatwfnis indeed read by the WavefunctionProperty class.
The specification of properties object is now complete and the keyword block closes by a curly braket, followed by a comma since more keywords follow:
Next we find the "wfn" keyword. It provides the object referred by the property object specification. It is a specialization of the (abstract) Wavefunction class In this case we will do a spin-restricted Hartree-Fock calculation. That is done with an object of type RHF. Since MPQC will expect any specialization of the Wavefunction class here, we must explicitly specify the object type by giving the type keyword:
The rest of keywords in this section are examined by the base classes of RHF:
Specifically, the molecule keyword specifies the Molecule object for which to compute the RHF wave function, and the basis keyword specifies the Basis object which gives the Gaussian basis in which RHF wave function will be computed.
Once again, the values of these keywords are references to object specifications given below. Separate Molecule and Basis object specifications could have been placed here, but usually it is necessary that several objects refer to the exact same object, so that for example the changes to the Molecule object by an optimizer will be "seen" by the RHF object. This can only be done using references.
A curly braket closes the wfn object specification.
Next we find the molecule keyword that has been referred to by the wfn object. It specifies a Molecule object:
Since Molecule is a concrete class there is no need to give a type keyword here.
The atomic coordinates are specified by giving the name of a text file in the XYZ format.
Next, a basis set object is given:
Keyword name specifies the basis set name, and keyword molecule specifies the atomic centers on which to place the basis functions. There is no type keyword here since Basis is a concrete class.
There is no comma after the closing curly braket since this is the last keyword group in the input file. Now we close off the top-level JSON group with a curly braket and we are finished.
Sample Object-Oriented Input Files
The easiest way to get started with mpqc is to start with one of sample inputs that most nearly matches your problem. The src/bin/mpqc/samples contains all of the sample inputs below:
- none yet
Specifying MPQC Input in XML and INFO formats
The correspondence between JSON, XML, and INFO formats is best demonstrated by example. The following JSON input (used as the example in A Walk-Through of an Object-Oriented Input File )
is expressed in XML as
The same input is expressed in the INFO format as
