Program Development Features

This section documents keywords and options useful for developers who are extending and/or interfacing to Gaussian 09. It also discusses non-standard routes and the determination of the standard orientation.

Program Development-Related Keywords

The keywords and options described here are useful for developing new methods and other debugging purposes, but are not recommended for production level calculations.

GENERAL JOB RESTART

Restart
We discuss here the general use of Restart, designed for debugging. See the Restart section for production use. This keyword restarts a calculation by reusing the read-write file. The form Restart L1 reuses the read-write file but generates a new route.

Restarts using the original route can specify the occurrence of a particular link and whether to clean up or retain overlay and link-volatile files using the following syntax:

#P Restart [Ln[(m)]] [Clean|KeepOverlay|KeepAll]

IOP SETTING KEYWORDS

IOp1=keyword
This keyword controls various details of the operating system interface. The options are standard, but not all are implemented (or even relevant!) in every version.
OPTIONS

FileIODump		Dump FileIO tables at the end of each link. FDump is a synonym for this keyword.
TimeStamp		Turn on time stamping. TStamp is a synonym for this keyword.
FileIOPrint		Turn on additional debug print in FileIO.
Synch		Currently a no-op (appears in a few test jobs).
NoDFTJ		Turn off use of the pure Coulomb term for non-hybrid DFT (seldom useful in production jobs).
AbelianOnly		Force the use of only abelian symmetry (seldom useful in production jobs).
NoPackSort		Turn off packing addresses into 32-bits during sorts, even if the address space being sorted is < 231 (seldom useful in production jobs).

IOp2
This option sets the maximum amount of memory which will be dynamically allocated. MDV and Core are synonyms for IOp2.

IOp33
This sets the standard debug print option as specified.For example, the following sets IOp(33) to 3 in all invocations of overlay 2, and IOp(33) to 1 in all invocations of overlay 7:

IOp33(2=3,7=1)

The Gaussian 09 IOps Reference also documents all internal options (IOps). They are also documented on our web site: www.gaussian.com/iops.htm.

DEBUGGING OPTIONS FOR STANDARD KEYWORDS

CPHF
The following options are used for debugging:
OPTIONS

KeepMicro		Keep all EE centers in CPHF, even for Opt=CalcFC or Opt=CalcAll with non-quadratic microiterations, where atoms that are not used in internal coordinates need not be included in the CPHF.
NoReuse		Do not reuse the electric field CPHF solution in the 2nd (nuclear) CPHF during frequency calculations. The default is ReUse.
XY		Treat real and imaginary perturbations together. The opposite is NoXY, which does them separately. The default is to treat them separately if nuclear perturbations are also being done, but to treat them together if there are only electromagnetic perturbations.
ZVector		Use the Z-Vector method [Diercksen81, Diercksen81a, Handy84] for post-SCF gradients. Allowed and the default if Hartree-Fock 2nd derivatives are not also requested. The NoZVector keyword says to use the full 3 x NAtoms CPHF for post-SCF gradients.

FMM
The following options are available for debugging:
OPTIONS

LMax=N		Specifies the maximum order multipole. The default is 25.
Levels=N		Specifies the number of levels to use in the FMM. The default is 8 for molecules and is adjusted dynamically for PBC.
Tolerance=N		Specifies the accuracy level as 10-N. The default values for N are 11 except for pass 0 of the SCF where it is 7.
JBoxLen=N		Sets the minimum box length (size) to N/1000 Bohrs when doing J. By default, N is 2.5. The maximum of JBoxLen and KBoxLen is used if J and K are done at the same time. BoxLen is a synonym for JBoxLen.
KBoxLen=N		Sets the minimum box length (size) to N/1000 Bohrs when doing K. By default, N is 0.75. The maximum of KBoxLen and JBoxLen is used if K and J are done at the same time.
AllNearField		Turn on all near-field in FMM.
NoParallelCPHF		Forbid parallel execution in FMM during the CPHF phase. NoParCPHF is a synonym for this option.

Integral
The following options are used for debugging:
OPTIONS

CNDO		Do calculation in main code using CNDO/2 integrals.
INDO		Do calculation in main code using INDO/2 integrals.
ZIndo1		Do calculation in main code using ZIndo/1 integrals.
ZIndoS		Do calculation in main code using ZIndo/S integrals.
DPRISM		Use the PRISM algorithm [Gill94] for spdf integral derivatives. This is the default.
Rys1E		Evaluate one-electron integrals using the Rys method [Dupuis76, King76, Rys83], instead of the default method. This is necessary on machines with very limited memory.
Rys2E		If writing two-electron integrals, use Rys method (L314) [Dupuis76, King76, Rys83, Schlegel84]. This is slower than the default method, but may be needed for small memory machines and is chosen by default if regular (non-Raffenetti) integrals are requested (by the NoRaff option).
DSRys		Use scalar Rys integral derivative code. Can combine with Berny for df only using Rys.
Berny		Use Berny sp integral derivative and second derivative code (L702).
Pass		Pass specifies that the integrals be stored in memory via disk, and NoPass disables this. Synonymous with SCF=[No]Pass, which is the recommended usage.
NoJEngine		Forbid use of special Coulomb code.
NoSP		Do not use the special sp integral program (L311) when writing integrals to disk.
RevDagSam		Reverse choice of diagonal sampling in Prism.
NoSchwartz		Do not use Schwartz integral estimates (only use the heuristic set). Schwartz says to use the Schwartz integral estimates in addition to the heuristic set. The default is to use both.
RevRepFock		Reverse choice of Scat20 vs. replicated Fock matrices.
NoDFTCut		Turn off extra DFT cutoffs.
SplitSP		Split AO S=P shells into separate S and P shells. NoSplitSP is the default.
SplitSPDF		Split AO S=P=D and S=P=D=F shells into S=P, D, and F. NoSplitSPDF is the default.
SplitDBFSPDF		Split density S=P=D and S=P=D=F into S=P, D, and F. NoSplitDBFSPDF is the default.
NoGather		Forbid use of gather/scatter digestion, even when processing small numbers of density matrices. Splatter is a synonym for this option.
ForceNuc		Do nuclear-electron Coulomb with electron-electron.
SepJK		Do J and K in HF/hybrid DFT separately for testing.
Seq2E		Set up for parallel 2 electron integral evaluation but then do not run in parallel (for debugging).
SeqXC		Set up for parallel 2 electron integral evaluation but then do not run in parallel (for debugging).
SeqLinda		Cause Linda workers to run sequentially. Currently just makes the Linda workers other than the master run simultaneously but before the master.
BigAtoms		Make all atom sizes large in XC quadrature.
BigShells		Make all shell sizes large in XC quadrature.
NoSymAtGrid		Do not use (Abelian) symmetry to reduce grid points on symmetry-unique atoms.
LinMIO		Convert to linear storage in FoFCou for testing.
RevDistanceMatrix		Reverse choice of whether to precompute distance matrix during numerical quadrature. The default is to precompute for molecules but not for PBC.
NoDynParallel		Turn off dynamic work allocation.

Sparse
The following options are used for debugging:
OPTIONS

Loose		Sets the cutoff to 5 * 10-5.
Medium		Sets the cutoff to 5 * 10-7. This is the default for semi-empirical methods.
Tight		Sets the cutoff to 1 * 10-10. This is the default for DFT methods.
N		Sets the cutoff to 1 * 10-N.

CHANGING LINK INVOCATION AND ORDERING

ExtraLinks
This requests that additional links be executed. They are added to all instances of their overlay after the regular links. For example, ExtraLinks=L9997 will cause each instance of overlay 99 to include links 9999 (by default) and 9997, in that order.

ExtraOverlays
This command requests that extra overlay cards be read in non-standard route format and inserted into the standard route immediately before the final (overlay 99) card.

Skip
Skip initial overlay cards in the route. Skip=OvNNN skip until first occurrence of overlay NNN. Skip=M skip first M cards.

Use=Lnnn
This specifies alternate routes through the program.
OPTIONS

L123		Use L123 instead of L115 for IRC. This is the default for IRC, except for IRCMax jobs.
L402		Use old link 402 code for semi-empirical.
L503		Use link 503 for SCF.
L506		Use link 506 for ROHF.

If a combination of options or links is required which is drastically different than a standard route, then a complete sequence of overlays and links with associated options can be read in. The job-type input section begins with the line:

# NonStd

This is followed by one line for each desired overlay, in execution order, giving the overlay number, a slash, the desired options, another slash, the list of links to be executed, and finally a semicolon:

Ov/Opt=val,Opt=val,…/Link,Link,…;

For example:

7/5=3,7=4/2,3,16;

specifies a run through the links 702, 703, and 716 (in this order), with option 5 set equal to 3 and option 7 equal to 4 in each of the links. If all options have their default value, the line would be

7//2,3,16;

A further feature of the route specification is the jump number. This is given in parentheses at the end of the link list, just before the semicolon. It indicates which overlay line is executed after completion of the current overlay. If it is omitted, the default value is +0, indicating that the program will proceed to the next line in the list (skipping no lines). If the jump number is set to -4, on the other hand, as in

7//2,3,16(-4);

then execution will continue with the overlay specified four route lines back (not counting the current line).

This feature permits loops to be built into the route and is useful for optimization runs. An argument to the program chaining routine can override the jump. This is used during geometry optimizations to loop over a sequence of overlay lines until the optimization has been completed, at which point the line following the end of the loop is executed.

Note that non-standard routes are not generally created from scratch but rather are built by printing out and modifying the sequence produced by the standard route most similar to that desired. This can be accomplished most easily with the testrt utility.

A Simple Route Example. The standard route:

# RHF/STO-3G

causes the following non-standard route to be generated:

 1/38=1/1;
 2/12=2,17=6,18=5,40=1/2;
 3/6=3,11=1,16=1,25=1,30=1,116=1/1,2,3;
 4//1;
 5/5=2,38=5/2;
 6/7=2,8=2,9=2,10=2,28=1/1;
 99/5=1,9=1/99;

The resulting sequence of programs is illustrated below:

A Simple Route Sequence

The basic sequence of program execution is identical to that found in any ab initio program, except that Link 1 (reading and interpreting the route section) precedes the actual calculation, and that Link 9999 (writing to the checkpoint file) follows it. Similarly, an MP4 single point has integral transformation (links 801 and 804) and the MP calculation (link 913) inserted before the population analysis (Link 601) and Link 9999. Link 9999 automatically terminates the job step when it completes.

A Route Involving Loops. The standard route:

# RHF/STO-3G Opt

produces the following non-standard route:

 1      1/18=20,19=15,38=1/1,3;
 2      2/9=110,12=2,17=6,18=5,40=1/2;
 3      3/6=3,11=1,16=1,25=1,30=1,71=1,116=1/1,2,3;
 4      4//1;
 5      5/5=2,38=5/2;
 6      6/7=2,8=2,9=2,10=2,28=1/1;
 7      7//1,2,3,16;
 8      1/18=20,19=15/3(2);
 9      2/9=110/2;
10      99//99;
11      2/9=110/2;
12      3/6=3,11=1,16=1,25=1,30=1,71=1,116=1/1,2,3;
13      4/5=5,16=3/1;
14      5/5=2,38=5/2;
15      7//1,2,3,16;
16      1/18=20,19=15/3(-5);
17      2/9=110/2;
18      6/7=2,8=2,9=2,10=2,19=2,28=1/1;
19      99/9=1/99;

The resulting sequence of program execution is illustrated below:

A Route Involving Loops

Several considerations complicate this route:

• The first point of the optimization must be handled separately from later steps, since several actions must be performed only once. These include reading the initial molecule specification and generating the initial orbitals.

• There must be a loop over geometries, with the optimization program (in this case the Berny optimizer, Link 103) deciding whether another geometry was required or the structure has been optimized.

• If a converged geometry is supplied, the program should calculate the gradients once, recognize that the structure is optimized, and quit.

• Population analysis and orbital printing are done by default only at the first and last points, not at the relatively uninteresting intermediate geometries.

The first point has been dealt with by having two basic sequences of integrals, guess, SCF, and integral derivatives in the route. The first sequence includes Link 101 (to read the initial geometry), Link 103 (which does its own initialization), and has options set to tell Link 401 to generate an initial guess. The second sequence uses geometries produced in Link 103 in the course of the optimization, and has options set to tell Link 401 to retrieve the wavefunction from the previous geometry as the initial guess for the next.

The forward jump on the eighth line has the effect that if Link 103 exits normally (without taking any special action), the following lines (invoking Links 202 and 9999) are skipped. Normally, in this second invocation of Link 103, the initial gradient will be examined and a new structure chosen. The next link to be executed will be Link 202, which processes the new geometry, followed by the rest of the second energy+gradient sequence, which constitutes the main optimization loop. If the second invocation of Link 103 finds that the geometry is converged, it exits with a flag which suppresses the jump, causing Links 202, 601 and 9999 to be invoked by the following lines and the job to complete.

Lines 11-16 form the main optimization loop. This evaluates the integrals, wavefunction, and gradient for the second and subsequent points in the optimization. It concludes with Link 103. If the geometry is still not converged, Link 103 chooses a new geometry and exits normally, causing the backward jump on line 16 to be executed, and the next line processed to be line 11, beginning a new cycle. If Link 103 finds that the geometry has converged, it exits and suppresses the jump, causing the concluding lines (17-19) to be processed.

The final instance of Link 601 prints the final multipole moments as well as the orbitals and population analysis if so requested. Finally, Link 9999 generates the archive entry and terminates the job step.

MP and CI optimizations have the transformation and correlation overlays (8 and 9) and the post-SCF gradient overlays (11 and 10, in that order) inserted before overlay 7. The same two-phase route structure is used for numerical differentiation to produce frequencies or polarizabilities.

The route for Opt=Restart is basically just the main loop from the original optimization, with the special lines for the first step omitted. The second invocation of Link 103 is kept and does the actual restarting.

Standard Orientation Conventions

Before a calculation is performed, a molecule can be reoriented to a different coordinate system, called the standard orientation, with the use of molecular symmetry.

This section describes the goals, factors to consider, and various rules for positioning axes for the standard orientation of molecules.

SELECTION GOALS

The goals for selecting conventions for standard orientation are:

• To simplify the 3x3 transformation matrices by reorienting the molecule.

• Two Z-matrices differing in values of internal coordinates but identical in integer quantities (such as occurs on subsequent points of a geometry optimization) should produce the same standard orientation.

• Two different Z-matrices for the same molecule should produce the same coordinates, except for a possible renumbering of atoms.

• Maximizing the number of molecular orbital coefficients which are zero by symmetry.

GENERAL CONSIDERATIONS

The factors that should be considered for standard orientation are:

• A right handed coordinate system is used throughout the calculation.

• The molecule is translated so that its center of charge is at the origin.

• Atoms are not reordered relative to their order upon input.

• The Cartesian axes are considered to increase in priority in the order X < Y < Z.

RULES FOR POSITIONING AN AXIS

Criteria for rotating and aligning an axis are listed below. If rotation is required to meet one of these criteria, it should be a 180 degree rotation about the X, Y, or Z axis, defined as follows:

An axis of rotation or a principal axis of charge can be aligned with a Cartesian axis in one of two ways—either parallel or antiparallel, depending on the successive application of the following tests until a definite result is achieved:

• The sum of the coordinates of the atoms of the highest atomic number on the axis must be positive.

• The third moment of charge must be positive.

• The sum of the projections of the atomic coordinates onto the reference axis must be positive.

• The first atom with a non-zero projection on the reference axis must have a positive projection on that axis.

RULES FOR POSITIONING PRINCIPAL AXES OF CHARGE

In the absence of any other rules, the principal axis corresponding to the largest principal moment of charge must be aligned with the highest priority Cartesian axis available. Individual point groups have specific considerations:

SPECIAL RULES FOR ASYMMETRIC TOP MOLECULES

Asymmetric top molecules are distinguished by having two of three moments of inertia equal. The third moment can thus be uniquely identified as the reference axis and the point group is analyzed by considering circular sets of atoms.

The following rules are applied for asymmetric top molecules:

• The unique axis is aligned with the Z axis.

• A circular-set of atoms is composed of atoms lying in a plane which have the same atomic number, and are equidistant from a reference axis perpendicular to the plane. Atoms on the reference axis are not included in any circular-set. A circular-set of atoms is generated by a proper rotation axis.

• The key atom in an asymmetric top molecule is the atom with the lowest number in the key circular-set. The following tests are carried out successively to find the key circular-set:

  • Which set is nearest the XY plane?
  • Which set has a positive projection on the Z axis?
  • Which set is nearest the Z axis?
  • Which set is comprised of atoms with the lowest atomic number?
    
    
• The orientation is then chosen for the specific point group:

  • C_n, C_nh, S_n: The molecule is rotated about the Z axis to maximize the number of pairs of heavy atoms parallel to the Y axis. If no such arrangement is satisfactory, then the key atom is placed in the YZ plane to give it a positive Y coordinate.

  • D_n, D_nh: One of the C₂ axes is made coincident with the Y Cartesian axis. The tests described below are used to decide which C₂ axis is so positioned.

  • D_nd, C_nv: One of the vertical planes is made coincident with the YZ Cartesian plane. The tests below are used to decide which plane is so positioned.

• The following are tests for selecting among axes for the D_n, D_nh, D_nd, and C_nv molecules:

  • Maximize the projection of the key atom on the Y axis.

  • If two orientations give the maximum projection on the Y axis, select one with the maximum projection on the X axis.

  • For molecules contained in the XY plane, the standard axis orientation rules (see above) are applied to the X axis to complete the orientation specification.

SPECIAL RULES FOR SPHERICAL TOP MOLECULES

Spherical top molecules are distinguished by having their equal moments of inertia and can be characterized by identifying spherical sets of atoms.

A spherical-set of atoms is composed of atoms which are equidistant from the origin and have the same atomic number. Spherical-sets should be ordered in terms of increasing distance from the origin and of increasing atomic number at any one distance. The key atom is the lowest numbered atom in the first spherical-set.

Although not generally the case, it is possible, with appropriate geometric constraints, to have D_2d, D_2h, or D₂ molecules that are symmetric tops. Such molecules have three perpendicular two-fold axes that are aligned with the X, Y, and Z axes in accordance with the rules given above.

RWF Numbers

The following is a list of read-write files. Those that are permanently on the checkpoint file are marked with the letter P, and those that are temporarily on the checkpoint file are marked with the letter T. T files are saved for use in restarting an optimization or numerical frequency run, but are deleted when the job step completes successfully.

Last updated on: 10 May 2009