Requests a calculation using an external program. This mechanism is primarily intended to facilitate the use of external programs to provide the low-level calculations in ONIOM calculations, but can also be used to conduct geometry optimizations using Gaussian’s optimizer with external programs providing the function values and derivatives.
Gaussian uses a standardized interface to run an external program to produce an energy (and optionally a dipole moment or forces) at each geometry. A text file is produced with the current structure, and a script named Gau_External is run by default (see below for information on specifying an alternate script). This script, which is provided by the user, is expected to:
You may specify a different script by including its name as the option to the External keyword: e.g., External=MyScript.
By default, the Gau_External script is passed six parameters:
$ Gau_External layer InputFile OutputFile MsgFile FChkFile MatElFile
The parameters are defined as follows:
layer | A key letter indicating whether the computation is being performed on the real system (R), the model system of a 2-layer ONIOM or the middle layer of a 3-layer ONIOM (M), or the model system of a 3-layer ONIOM (S). | |
InputFile | The name of the file Gaussian has prepared as input for the external program. | |
OutputFile | The name of the file which should be read in after the external program completes. | |
MsgFile | The name of a file for messages; if the script creates this file, then its contents are copied to the Gaussian output file. | |
FChkFile | A formatted checkpoint file. If the appropriate options are set to link 402, then this file is created from the read-write file before starting the external script, and may be read to import results after the script finishes instead of Gaussian input being provided via OutputFile. The output formatted checkpoint file can contain an initial two blank lines plus the data to be updated in the usual format; it does not need to contain any information which is to remain unchanged. | |
MatElFile | Matrix element file. This is a simple Fortran unformated file designed to export data such as the overlap and Core Hamiltonian matrix and two-electron integrals in an extensible format. The structured is documented in a separate section following the examples. |
All of these files are deleted by Gaussian once the results have been recovered.
Additional arguments to the script may also be included:
In this example, the actual command would be:
$ RunTink Amber layer InputFile OutputFile MsgFile FChkFile MatElFile
The specified script is always passed the parameters mentioned above as its final six arguments.
The input file has the following format:
#atoms derivatives-requested charge spin atomic# x y z MM-charge MM-atom_type Repeated for each atom.
The first line specifies the number of atoms in the molecule, what derivatives are to be computed (0=energy only, 1=first derivatives, 2=second derivatives), and the molecule’s charge and spin multiplicity. The remaining lines specify the atomic number, coordinates and molecular mechanics charge for each atom.
The output file is in fixed format, and has the following data (all in atomic units):
| Items | Pseudo Code | Line Format | ||
| energy, dipole-moment (xyz) | E, Dip(I), I=1,3 | 4D20.12 | ||
| gradient on atom (xyz) | FX(J,I), J=1,3; I=1,NAtoms | 3D20.12 | ||
| polarizability | Polar(I), I=1,6 | 3D20.12 | ||
| dipole derivatives | DDip(I), I=1,9*NAtoms | 3D20.12 | ||
| force constants | FFX(I), I=1,(3*NAtoms*(3*NAtoms+1))/2 | 3D20.12 |
The second section is present only if first derivatives or frequencies were requested, and the final section is present only if frequencies were requested. In the latter case, the Hessian is given in lower triangular form: αij, i=1 to N, j=1 to i. The dipole moment, polarizability and dipole derivatives can be zero if none are available.
It is also possible to provide one-electron or one- and two-electron integrals and other matrix elements to an external program and to recover results such as MOs or densities from the other program. Full details and examples are in the g09/doc subdirectory (doc folder on Windows). Options must follow the name of the script.
InUnf
A Fortran unformatted file will be provided to the external program containing coordinates and one-electron matrix elements (overlap, core Hamiltonian, etc.). Refer to g09/doc/unfdat.txt for details on the contents of the file and to g09/doc/rdmat.F for a sample program which reads the file and prints its contents. 1Elintegrals is a synonym for this option.
2ElIntegtrals
The Fortran unformatted file should also contain two electron integrals. This option implies SCF=Conventional.
InputFchk
A formatted checkpoint file should be generated and provided to the external program.
OutputUnf
A Fortran unformatted file will be provided to the external program and an updated or replaced file with the same structure will be read by G09 for the results, in lieu of the default text output file expected from the external program/script.
IOFchk
A formatted checkpoint file will be generated and provided to the external program, and an new .fchk file will be read to import results afterwards.
ReadInputSection
This option can be used to alter the content of the external text input file that Gaussian 09 automatically generates for the external script. When the data transfer between Gaussian 09 and the external script is handled using one of the options above (e.g. IOFchk), the default external text input file is not needed. With this option, a section (delimited by the usual blank lines) will be read from the Gaussian 09 input file. The text in this section will be placed in the external text input file instead of the usual content of such file. This provides additional flexibility to provide extra instructions to the external script.
Test job 769 serves as an example of these options.
External scripts may also be specified as one of the models for the ONIOM keyword (see examples below).
The Gaussian stand-alone MM program can be run with the -external switch, which causes it to read and write data in the formats used by the External interface.
The following route section specifies an external script for the low layer of a 3 layer ONIOM calculation:
# ONIOM(B3LYP/6-31G(d):AM1:External="RunTink Amber") Opt
The following route section specifies an external script for the high accuracy layer of a 2 layer ONIOM job:
# ONIOM(External="RunCC SDT":B3LYP/6-31G(d)) Opt
The structure of the optional unformatted matrix element is as follows. The initial section contains records relating to the molecular structure and other general job characteristics:
| Record | Format and Description | |
| 1 | Character*64 LabFil, Integer IVers, Integer NLab, Character*64 GVers A label for the file type, version number for the file format, number on general data records which follow and preceed the matrix elements, and the version of Gaussian which wrote the file. |
|
| 2 | Character*64 Title, Integer NAtoms, Integer NBasis, NBsUse,ICharg, Multip, NE, Len12L, Len4L, IOpCl The first 64 characters of the title section from the run which created the file and the number of atoms and basis functions. NBsUse is the number of linearly independent basis functions. ICharg is the molecular charge, Multip the spin multiplicity (1=singlet, etc.) and NE the number of electrons. Len12L is the number of bytes used for the integer labels for sparse 1D and 2D matrices, and Len4L is the number of bytes used for 4D matrices (2e integrals). IOpCl is the closed/open-shell flag if the file is written after an initial guess or SCF has been done; otherwise it is -1, meaning unspecified. |
|
| 3 | Integer IAn(NAtoms) Atomic numbers |
|
| 4 | Integer IAtTyp(NAtoms) Atom type information. The main aspect of interest to other programs is that negative values indicate inactive atoms during an ONIOM model system calculation. By default, the file is written with inactive atoms omitted from all arrays and NAtoms set to the number of active atoms, but all atoms can optionally be included. |
|
| 5 | Real*8 AtmChg(NAtoms) Nuclear charges, may be different from atomic numbers if ECPs were used. |
|
| 6 | Real*8 C(3,NAtoms) Cartesian nuclear coordinates in Bohr. |
|
| 7 | Integer IBfAtm(NBasis), IBfTyp(NBasis) IBfAtm is the map from basis functions to atoms. IBfTyp is a type flag for each basis function. Each is of the form LLLMMM, where LLL is the angular momentum and MMM is the component number. Negative values are for pure functions and positive for Cartesian. So cartesian Ds are numbered 2001 through 2006 and pure Ds are -2001 through -2005. |
|
| 8 to NLab | Other scalar data about the calculation. Currently NLab is 7 and so there are no such records, but programs should skip records 8 to NLab to ensure that they ignore data which is added here later. |
These NLab records are followed by zero or more matrix sections, each of which has an initial record
containing a label, the number of integers and number of reals for each element, the total number of
elements and number of elements per record. NI can be zero for dense matrices (stored with zeros
included):
Character*64 Label, Integer NI, NR, NTot, NPerRec, N1, N2, N3, N4, N5
N1 through N5 are dimensions for the object as a matrix, with 0 for unused dimensions and negative values for ones which are lower triangular, e.g. if NBasis=50 and NBsUse=49 then N1 ... N5 would be –50 50 0 0 0 for the overlap matrix and 50 49 0 0 0 for the transformation to an orthogonal basis.
This is followed by (NTot+NPerRec-1)/NPerRec records each of the form:
Integer ID(NI,NPerRec), Real*8 DX(NR,NPerRec)
or just
Real*8 DX(NR,NPerRec)
if NI=0, with the labels if any in ID and values in DX. All matrix elements are over pure or Cartesian basis functions in accord with that specified in the Gaussian route or defaulted for the particular basis set.
Currently, the following sections are always written with the following labels:
OVERLAP
CORE HAMILTONIAN ALPHA
CORE HAMILTONIAN BETA
KINETIC ENERGY
Each is a lower triangular matrix stored dense (all N*(N+1)/2 elements with no labels). The two core Hamiltonians are identical unless a Fermi contact perturbation has been applied.
ORTHOGONAL BASIS
If present, this is a (NBasis,NBsUse) matrix giving the transformation from AOs to a linearly independent orthonormal set.
DIPOLE INTEGRALS
If present, this is 3 lower-triangular matrices holding the X, Y, and Z dipole matrix elements.
GIAO D2H/DBDM
If present, this is 9 × NAtoms lower triangular matrices holding the GIAO core Hamiltonian 2nd derivatives with respect to external field and nuclear magnetic moments (the matrix elements required for the diamagnetic shielding term).
GIAO L/R3
If present, this is 3 × NAtoms lower triangular matrices holding the GIAO magnetic perturbations (the matrices required for the paramagnetic shielding term).
ALPHA ORBITAL ENERGIES
If present, this an NBsUse vector of initial guess or converged orbital energies.
ALPHA MO COEFFICIENTS
If present, this an NBasis × NBsUse matrix of initial guess or converged orbitals.
BETA ORBITAL ENERGIES
If present, this an NBsUse vector of initial guess or converged orbital energies.
BETA MO COEFFICIENTS
If present, this an NBasis × NBsUse matrix of initial guess or converged orbitals.
ALPHA DENSITY MATRIX
If present, this is a lower-triangular matrix containing the alpha spin part of the density matrix selected by the options for population analysis, etc. If read back into Gaussian, it is stored in place of the SCF density.
BETA DENSITY MATRIX
If present, this is a lower-triangular matrix containing the beta spin part of the density matrix selected by the options for population analysis, etc. If read back into Gaussian, it is stored in place of the SCF density.
ALPHA SCF DENSITY MATRIX
If present, this is a lower-triangular matrix containing an initial guess or converged SCF density.
BETA SCF DENSITY MATRIX
If present, this is a lower-triangular matrix containing an initial guess or converged SCF density.
[ALPHA,BETA] [MP2,MP3,MP4,CI,QCI/CC] DENSITY MATRIX
If present, these are the alpha and beta densities including the indicated type of correlation.
GAUSSIAN SCALARS
This a vector of labelled reals. Labels between 1 and 1000 refer to elements of the Gaussian /Gen/ file
(for a table, see below). Labels higher than 1000 are reserved for specific scalar to or from the external
program.
If 2e integrals are available (i.e., if SCF=Conventional was specified on the route) then there will be one
of the following sections:
ALPHA DENSITY DERIVATIVES
BETA DENSITY DERIVATIVES
If present, these have lower triangular AO density derivatives with respect to whatever perturbations were applied during CPHF. The number of matrices is the number of perturbations, and varies.
ALPHA MO DERIVATIVES
BETA MO DERIVATIVES
If present, these are the (NBasis,NAE,3) and (NBasis,NBE,3) MO coefficient derivatives with respect to a magnetic field.
REGULAR 2E INTEGRALS
or
RAFFENETTI 2E INTEGRALS
Only non-zero integrals are stored with 4 indices I≥J, I≥K, K≥L, J≥L if I=K. NR is 1 for regular integrals and 1, 2, or 3 for Raffenetti integral combinations:
R1(I,J,K,L) = (IJ|KL) - 1/4[(IK|JL)+(IL|JK)]
R2(I,J,K,L) = (IK|JL) + (IL|JK)
R3(I,J,K,L) = (IK|JL) - (IL|JK)
The default is R1 only for closed-shell systems, R1 and R2 for UHF. The NoRaff keyword forces regular integrals, and IOp(3/11=N) can be used for force a particular set of Raffenetti integrals.
The sample program rdmat.F in the doc subdirectory of the main Gaussian installation directory is a simple Fortran program which reads this file an prints the contents. It does not require any routines from Gaussian and can be used as a template for processing the file. On x86-64/Linux machines, it can be compiled with any of g77, gfortran, pgf77, pgf90, or ifort and will read the file generated by Gaussian (which uses pgf77). On other systems it may be necessary to use the same compiler as was used for Gaussian. The program should be compiled with a default integer size of 8 bytes to read a file built by a 64-bit version of Gaussian.
The Gaussian scalars are:
| 1 | Virial ratio | |
| 2-4 | Components of applied electric field, if any | |
| 5 | 2e SCF energy | |
| 6 | SCRF g-factor | |
| 7 | SCRF a0 | |
| 8 | Thermal Energy | |
| 9 | E(CI/CC/QCI/BD) | |
| 10 | E(CCD+ST4(CCD)/QCISD(T)/BD(T)/CI+Davidson) | |
| 11 | E(VAR1) | |
| 12 | Zero-point energy | |
| 13 | Multi-step (G1, G2, etc.) energy | |
| 14 | Number of imaginary frequencies | |
| 15 | D(PUHF) | |
| 16 | EPUHF | |
| 17 | ECBS2 | |
| 18 | ECBSI | |
| 19 | EPMP2-0 | |
| 20 | EPMP3-0 | |
| 21 | Root-mean-squared force of optimized parameters | |
| 22 | E(CIS-MP2) | |
| 23 | RMS error in density matrix | |
| 24 | S**2 after annihilation of first contaminant | |
| 25 | CIS energy | |
| 26 | UMP4D (=UMP4DQ - E4(R+Q)) | |
| 27 | Reference energy for BD | |
| 28 | MP5 | |
| 29 | S4SD (computed in ANNIL in L502, used by PSCF spin projection routines) | |
| 30 | Frozen-core part of total energy | |
| 31 | 'TAU' from SCFDM | |
| 32 | SCF ENERGY | |
| 33 | UMP2 energy | |
| 34 | UMP3 energy | |
| 35 | UMP4(SDTQ) energy | |
| 36 | CBS OIii | |
| 37 | Total energy with RF from L116 | |
| 38 | MP4DQ energy | |
| 39 | MP4SDQ energy | |
| 40 | Used by L116 | |
| 41 | Nuclear repulsion energy | |
| 42 | T (length of correction of reference determinant) | |
| 43 | Updated energy for optimizations | |
| 44 | <S**2> of SCF wave function | |
| 45 | <S**2> corrected to first order (after DOUBAR) | |
| 47 | A0 | |
| 48 | Used to accumulate energy during Opt=Simult | |
| 49 | Temperature for thermochemistry | |
| 50 | Pressure for thermochemistry | |
| 51 | Scale factor for frequencies in thermochemistry | |
| 52 | Nuclear repulsion contribution from inactive atom pairs | |
| 53 | Singles contribution to E2 in ROMP2 | |
| 54 | E(2) with current orbitals for extrapolation | |
| 55 | Nuclear term in the reaction field energy | |
| 56 | Electronic term in the reaction field energy | |
| 57 | Curvature from projected frequency jobs | |
| 58 | Reaction coordinate for single-points along IRCs |
Last update: 22 May 2014