- Description
- Script Invocation
- File Formats
- Options
- Related Info
- Examples
Description
Requests a calculation using an external program. This mechanism was originally primarily intended to facilitate the use of external programs to provide the low-level calculations in ONIOM calculations. However, it has been made very general. For example, it 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:
- Convert the text file—referred to as the “input file”—into input for another program.
- Run that program.
- Convert the results into a standard text form for recovery by Gaussian. The converted file for use by Gaussian is referred to as the “output file.”
You may specify a different script by including its name as the option to the External keyword: e.g., External=MyScript.
Script Invocation
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 Fortran unformatted file designed to export data such as the overlap and Core Hamiltonian matrix and two-electron integrals in an extensible format. The structure is documented in GauOpen: Interfacing to Gaussian 16. |
All of these files are deleted by Gaussian once the results have been recovered.
Additional arguments to the script may also be included:
External=”RunTink Amber”
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.
File Formats
Input File Format
The input file has the following format:
| #atoms derivatives-requested charge spin | |
| atomic# x y z MM-charge | 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 (format 4I10). The remaining lines specify the atomic number, coordinates, and molecular mechanics charge for each atom (format I10, 4F20.12).
Output File Format
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.
Options
It is 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 g16/doc subdirectory (doc folder on Windows). Options must follow the name of the script. Test job 769 serves as an example of some of these options. Note that the formats of some files are controlled by options to the Output keyword. See also GauOpen: Interfacing to Gaussian 16.
InUnf
A unformatted matrix element file will be provided to the external program containing coordinates and one-electron matrix elements (overlap, core Hamiltonian, etc.). Refer to g16/doc/unfdat.txt for details on the contents of the file and to g16/doc/rdmat.F for a sample program which reads the file and prints its contents. 1Elintegrals is a synonym for this option.
2ElIntegrals
The unformatted matrix element file should also contain two-electron integrals. This option implies SCF=Conventional.
Raw
Read or write a raw binary matrix element file rather than an unformatted file.
InputFchk
A formatted checkpoint file should be generated and provided to the external program. InFChk is a synonym for this option.
OutputUnf
A unformatted file will be provided to the external program and an updated or replaced file with the same structure will be read by G16 for the results, in lieu of the default text output file expected from the external program/script. OutUnf is a synonym for this option.
IOFchk
A formatted checkpoint file will be generated and provided to the external program, and a new .fchk file will be read to import results afterwards. OutputFChk is a synonym for this option.
ReadInputSection
This option can be used to alter the content of the external text input file that Gaussian 16 automatically generates for the external script. When the data transfer between Gaussian 16 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 16 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.
PostSCF
Run the external program after the SCF calculation in Gaussian but before the population analysis and molecular property links.
PostPop
Run the external program after the SCF calculation and the population analysis and molecular property links.
MO2ElIntegrals
Request MO integral transformation and storage in the unf file. Implies PostSCF.
ActiveAtoms
AllAtoms
Specifies which atoms are included in the text input and matrix element files for ONIOM calculations. The default is AllAtoms. ActiveAtoms includes only the atoms in the model system (high layer).
NoDelete
Retain the intermediate files used.
Guess
Force Gaussian to generating/reading an initial guess for orbitals. NoGuess prevents Gaussian from doing so. The default is NoGuess unless initial guess options are set, so NoGuess is useful during ONIOM calculations with Guess=Input or Guess=Read for the other models.
AO2ElDerivatives
Generate the AO 1-electron and 2-electron integral derivatives and include them in the matrix element file.
AO2PDM
Save the post-SCF contribution to the 2-particle density matrix on the matrix element file.
Files
Include the contents of the specified internal Gaussian file within the generated matrix element file. For example, the following option:
External=Files=(123,(456,offset=1,integer=27))
will cause the contents of internal file 123 (assumed by default to be real values) to be included in the matrix element file (labeled as “File 123”). The second item in the file list specifies the 27 integers in internal file 456 starting after the first (8-byte) word (labeled as “File 456 integers section 001”), as well as any real values following the integers (labeled “File 456 reals section 002”).
Related Keywords
External scripts may also be specified as one of the models for the ONIOM keyword (see the examples).
The Gaussian stand-alone mm utility program can be run with the -external switch, which causes it to read and write data in the formats used by the External interface.
See GauOpen: Interfacing to Gaussian 16 for information about exchanging data with other programs.
Examples
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=NoMicro
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=NoMicro
- Description
- Script Innovation
- File Formats
- Options
- Related Info
- Examples
Requests a calculation using an external program. This mechanism was originally primarily intended to facilitate the use of external programs to provide the low-level calculations in ONIOM calculations. However, it has been made very general. For example, it 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:
- Convert the text file—referred to as the “input file”—into input for another program.
- Run that program.
- Convert the results into a standard text form for recovery by Gaussian. The converted file for use by Gaussian is referred to as the “output file.”
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 Fortran unformatted file designed to export data such as the overlap and Core Hamiltonian matrix and two-electron integrals in an extensible format. The structure is documented in GauOpen: Interfacing to Gaussian 16. |
All of these files are deleted by Gaussian once the results have been recovered.
Additional arguments to the script may also be included:
External="RunTink Amber"
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 | 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 (format 4I10). The remaining lines specify the atomic number, coordinates, and molecular mechanics charge for each atom (format I10, 4F20.12).
Output File Format
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 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 g16/doc subdirectory (doc folder on Windows). Options must follow the name of the script. Test job 769 serves as an example of some of these options. Note that the formats of some files are controlled by options to the Output keyword. See also GauOpen: Interfacing to Gaussian 16.
InUnf
A unformatted matrix element file will be provided to the external program containing coordinates and one-electron matrix elements (overlap, core Hamiltonian, etc.). Refer to g16/doc/unfdat.txt for details on the contents of the file and to g16/doc/rdmat.F for a sample program which reads the file and prints its contents. 1Elintegrals is a synonym for this option.
2ElIntegrals
The unformatted matrix element file should also contain two-electron integrals. This option implies SCF=Conventional.
Raw
Read or write a raw binary matrix element file rather than an unformatted file.
InputFchk
A formatted checkpoint file should be generated and provided to the external program. InFChk is a synonym for this option.
OutputUnf
A unformatted file will be provided to the external program and an updated or replaced file with the same structure will be read by G16 for the results, in lieu of the default text output file expected from the external program/script. OutUnf is a synonym for this option.
IOFchk
A formatted checkpoint file will be generated and provided to the external program, and a new .fchk file will be read to import results afterwards. OutputFChk is a synonym for this option.
ReadInputSection
This option can be used to alter the content of the external text input file that Gaussian 16 automatically generates for the external script. When the data transfer between Gaussian 16 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 16 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.
PostSCF
Run the external program after the SCF calculation in Gaussian but before the population analysis and molecular property links.
PostPop
Run the external program after the SCF calculation and the population analysis and molecular property links.
MO2ElIntegrals
Request MO integral transformation and storage in the unf file. Implies PostSCF.
ActiveAtoms
AllAtoms
Specifies which atoms are included in the text input and matrix element files for ONIOM calculations. The default is AllAtoms. ActiveAtoms includes only the atoms in the model system (high layer).
NoDelete
Retain the intermediate files used.
Guess
Force Gaussian to generating/reading an initial guess for orbitals. NoGuess prevents Gaussian from doing so. The default is NoGuess unless initial guess options are set, so NoGuess is useful during ONIOM calculations with Guess=Input or Guess=Read for the other models.
AO2ElDerivatives
Generate the AO 1-electron and 2-electron integral derivatives and include them in the matrix element file.
AO2PDM
Save the post-SCF contribution to the 2-particle density matrix on the matrix element file.
Files
Include the contents of the specified internal Gaussian file within the generated matrix element file. For example, the following option:
External=Files=(123,(456,offset=1,integer=27))will cause the contents of internal file 123 (assumed by default to be real values) to be included in the matrix element file (labeled as “File 123”). The second item in the file list specifies the 27 integers in internal file 456 starting after the first (8-byte) word (labeled as “File 456 integers section 001”), as well as any real values following the integers (labeled “File 456 reals section 002”).
External scripts may also be specified as one of the models for the ONIOM keyword (see the examples).
The Gaussian stand-alone mm utility program can be run with the -external switch, which causes it to read and write data in the formats used by the External interface.
See GauOpen: Interfacing to Gaussian 16 for information about exchanging data with other programs.
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=NoMicro
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=NoMicro
Last updated on: 30 August 2022. [G16 Rev. C.01]
