Controlling Gaussian Operation
This page describes the various different mechanisms that are provided for controlling Gaussian operations, setting program defaults, specifying file locations and resource allocation, and the like. They are:
- Link 0 commands: directives placed in the Gaussian input file prior to the route section.
- Default file specifications: entries in the Gaussian defaults file Default.Route.
- Command line options: options to the operating system command to run Gaussian.
- Environment variables: values assigned to UNIX operating system environment variables (see the Equivalencies tab).
Each type is described separately on this page. See the Precedence tab for precedence rules between the various mechanisms.
This section lists all Link 0 commands, which are optional and precede the route section.
Link 0 commands may be up to 500 characters in length.
%Mem=N
Sets the amount of dynamic memory used to N 8-byte words (default). This value may also be followed by KB, MB, GB, TB, KW, MW, GW or TW (without intervening spaces) to specify units of kilo-, mega-, giga-, or tera-bytes or words. The default memory size is 800 MB. A different default value can be set in Default.Route with the -M- directive.
%Chk=file
Locates and names the checkpoint file.
%OldChk=file
The contents of the checkpoint file specified by %OldChk are copied to the checkpoint file of the current job step at the start of the job step. This allows data to be picked up from a previous calculation without destroying anything on the checkpoint file from it.
%SChk=file
Saves a copy of the checkpoint file when the job step starts. One can usually do the same thing with %OldChk and %Chk but sometimes it might be convenient to save the intermediate results this way.
%RWF=file
Locates and names a single, unified read-write file (old-style syntax).
%RWF=loc1,size1,loc2,size2, …
An alternate syntax is provided for splitting the read-write file among two or more disks (or file systems). Each location is followed by a maximum size for the file segment at that location. The size of each file segment is given in 8-byte words (default). This value may also be followed by KB, MB, GB, TB, KW, MW, GW or TW (without intervening spaces) to specify units of kilo-, mega-, giga- or tera-bytes or words. A value of -1 for any size parameter indicates that any and all available space may be used, and a value of 0 indicates that an existing segment should retain its current size. The locations may be either directory locations, or full pathnames. Note that directory specifications must include terminal slashes (on UNIX systems).
%OldRWF=file
The contents of the specified read-write file are copied to the read-write file of the current job step, allowing data from a previous calculation to be picked up without modifying the existing file.
%OldBAF=file, %OldFAF=file
Copy the data on the BAF/FAF file to the active checkpoint file at the start of the job step. With the default extension being .baf and .faf respectively (although either type file may be specified for either option if the extension is included).
%Int=spec
Locates and names the two-electron integral file(s). The spec parameter may take on either of the forms used for the read-write file.
%D2E=spec
Locates and names the two-electron integral derivative file(s). The spec parameter may take on either of the forms used for the read-write file.
%KJob LN [M]
Tells the program to stop the run after the Mth occurrence of Link N. For example, %KJob L502 2 will cause the run to terminate after Link 502 has been run for the second time. M may be omitted; it defaults to 1.
%Save
Causes Link 0 to save scratch files at the end of the run. By default, all non-specified scratch files are deleted and all named scratch files are saved when the run completes successfully.
%ErrorSave
Causes Link 0 to delete scratch files at the end of a successful run, including any files that were named explicitly preceding this directive. In other words, if a file is named before %ErrorSave is encountered, it will not be saved. However, if the directive naming the file appears after the %ErrorSave directive, the file will be retained. If the job ends abnormally, all files are saved. %NoSave is a synonym for this directive.
If both %Save and %ErrorSave are specified, then the one appearing latest in the input file takes precedence.
%Subst LN dir
Tells Link 0 to take the executable (.exe file) for a link from an alternate directory. For example %SUBST L913 /user/chem will cause /user/chem/l913.exe to be run instead of the default executable (in $g26root). The directory specification should be in the usual format for the machine involved. Only the directory can be specified; the file name must have the standard form of lnnnn.exe, where nnnn is the Link number.
Parallel Job Directives
The %CPU, %NProc, %LindaWorkers and %GPUCPU Link 0 commands from Gaussian 16 are no longer available. The equivalent command line options should be used instead.
%UseSSH
Start Linda workers using ssh rather than rsh. %UseRSH specifies the use of rsh, and it is the default. The form %SSH=command allows you to specify any program. The default value can be set in Default.Route with the -S- directive.
%DebugLinda
Report details concerning the starting and stopping of Linda workers.
Depending on the characteristics of a particular computer system, it is sometimes necessary for performance reasons to override some of the defaults built into the program. This can be done by creating a customization file. On UNIX-based systems, this file is named Default.Route, generally residing in $g26root/g26. Under Windows, the Gaussian defaults file is Default.Rou, and it is located by default in the Gaussian 26W scratch subdirectory (e.g., C:\G26W\scratch). The format of the file is the same on all computer systems.
An alternate location for the file can be used. When searching for a Default.Route file, the current directory is checked first, followed by the directories in the path for Gaussian executables, as specified in the environment variable GAUSS_EXEDIR, which normally points to $g26root/g26.
User Defaults Files
Gaussian users may set their own defaults by creating their own Default.Route file. Gaussian checks the current working directory for a file of this name when a job is initiated. Settings in the local file take precedence over those in the site-wide file, and options specified in the route section of the job take precedence over both of them.
Default.Route Limitations
Not all route section keywords are honored in the Default.Route file. In general, the rule is that options which are specific to a specific job type are ignored. Thus, Integral=SuperFine, which changes the default integration grid, will be honored, while Freq=Raman, which specifies a setting for a specific job type, will be ignored.
The following subsections describe the types of information which can be supplied in the defaults file.
Route Defaults
These parameters are introduced by -#- and have the same form as normal route section commands. For example, this line will set the default SCF algorithm to the conventional (non-direct) algorithm:
-#- SCF=Conventional
There may be more than one -#- line in the file.
Commands listed in Default.Route change only the defaults; they are overridden by anything specified in the route section of an input file. Thus, if the Default.Route contains:
-#- MP2=NoDirect
and the route section contains the MP2 keyword, then the conventional MP2 algorithm will be used. However, if the route section contains the MP2=Direct keyword, then the direct algorithm will be used.
The directive -R- is a synonym for -#-.
Maximum Disk Usage
You will usually want to specify the amount of scratch disk space available via the MaxDisk keyword in the Default.Route file. For example, the following line sets MaxDisk to 2 GB:
-#- MaxDisk=2GB
The amount of available disk space is given in 8-byte words by default. This value may also be followed by KB, MB, GB, TB, KW, MW, GW, or TW (without intervening spaces) to specify units of kilo-, mega-, giga-, or tera-bytes/words.
The scratch disk space is set unlimited by default: i.e., MaxDisk=-1. In other words, it is assumed that enough disk space is available to perform a given calculation with no redundant work. Thus, specifying the amount of available memory and disk is by far the most important way of optimizing performance for your calculations. Doing so allows the program to decide between the various available algorithms, selecting the optimal one for your particular system configuration. Keep in mind that the more disk space available, the faster the evaluation, especially for MP2.
Memory Defaults
Gaussian jobs which unwisely use excessive memory can cause severe difficulties on the system. The memory directive -M- enforces a default dynamic memory limit. For example, the following line sets default memory use to 3GB:
-M- 3GB
The amount of available memory is given in 8-byte words (default); this value may also be followed by KB, MB, GB, TB, KW, MW, GW, or TW (without intervening spaces) to specify units of kilo-, mega-, giga-, or tera-bytes or words. The default memory size is 800 MB (100 MW). Note that this limit can be overridden with the %Mem Link 0 command.
The memory directive -U- sets default memory to use in utilities such as formchk and freqchk.
Organization and Host Names
The host name may be set with -H-; the value specifies the host name to be used in archive entries generated by Gaussian. The default is the current hostname.
The organization/site name may be set with -O-; the value specifies the site name to be used in archive entries generated by Gaussian. There is no default.
Parallel Job Directives
Gaussian defaults to execution on only a single processor. If your computer system has multiple processors/cores, and parallel processing is supported in your version of Gaussian, you may the specific CPUs on which to run with the -C- directive. For example, the following directive specifies that the program should run on the first 5 cores of a hexacore system (reserving one core for other use):
-C- 0,1,2,3,4
The node list can also be specified as a range (e.g., 0-5). Ranges can also be followed by a suffix of the form /n, which says to use every nth processor in the range (e.g., /2 specifies every second processor/core).
The older -P- directive can be used to specify the total number of processors on which to execute (leaving the selection of processors to the operating system). Clearly, the number of processors requested should not exceed the number of processors available, or a substantial decrease in performance will result.
Network/Cluster Parallel Execution
You can specify the list of Linda workers in Default.Route via the -W- directive:
-W- dalton,lavoisier:2,priestley,agassiz:3,curie
This example will use the specified five nodes for parallel execution, placing 2 worker processes on lavoisier, 3 workers on agassiz, and one worker on each of the other systems. If the master node—the node where the job is started—is not one of these systems, a worker will also run on that system (making a total of six nodes).
This directive corresponds to—and can be overridden by—the Link 0 command %LindaWorkers.
The -S- directive specifies which program to use to start worker processes. It takes either rsh (the default) or ssh as its parameter.
Combining SMP and Network Parallelism
When -W- is combined with -C- or -P-, then an SMP parallel worker process is started on each node in the node list (or more than one such process when multiple workers are specified for that node). In other words, these individual worker processes run in parallel according to the SMP-related settings. If the settings are inappropriate for a listed computer, then the work will fail on that node. For example, the following directives will start workers as multiprocessors jobs on the specified systems:
-W- alpha,beta,gamma
-C- 0,1,2,3
However, if system beta is a dual-core workstation, that worker process will fail as there is no processor 2 or 3 present on that computer. This mechanism is designed primarily for cluster environments with uniform nodes.
Note that it is the Default.Route file on the master which is relevant; Default.Route files that may be present on worker systems are not used.
Parallel Execution on GPUs
The -G- directive sets the default list of GPUs to use. When using GPUs it is essential to have each GPU controlled by a specific CPU and much preferable if the CPU is physically close to the GPU it is controlling. The list uses the syntax gpu#(s)=core#(s) to indicate which GPUs to use and the core to which each is pinned. For example, the following directive tells Gaussian to execute on GPU0 through GPU3:
-G- 0,1,2,3=0,1,16,17
GPU0 and GPU1 are pinned to cores 0 and 1, while GPU2 and GPU3 are pinned to cores 16 and 17 (respectively).
Ranges of GPUs and/or cores can be used in this directive. For example, the following is equivalent to the preceding:
-G- 0-3=0-1,16-17
formchk Directives
The -F- directive sets the default options for the formchk utility. By default formchk produces a formatted checkpoint file that is backwardly compatible with all previous versions of Gaussian.
The parameter to -F- can be -3 or -2 to create a formatted checkpoint file of the corresponding version (version 3 is the default). The parameter can also contain -c, which causes the molecular mechanics atom types to appear in the formatted checkpoint file as strings rather than integers.
The memory directive -U- sets default memory to use in utilities such as formchk and freqchk.
The g26 command accepts the following options on all platforms:
| Option | Description | Example |
| -r | Route section default keyword list | -r="Int=SuperFine Freq=HPModes" |
| -m | Memory amount for Gaussian jobs | -m=200GB |
| -c | Processor/core list for multiprocessor parallel jobs. The list can include ranges and/or multiple items separated by commas. | -c="0-15,18-23" |
| -g | GPUs=Cores list for GPU parallel jobs. The list preceding the equals sign indicates the GPUs to use for the calculation. Corresponding items in the second list specify the core to which each CPU is pinned. | -g="0-8=0-6,31,32" |
| -w | List of hostnames for network parallel jobs. Hostnames can be optionally followed by a colon and an integer to indicate how many workers are to be started on that node. | -w="apple,banana:2,cherry" |
| -x | Complete route for the job (the route is not read from the input file). | -x="# b3lyp/6-31G(d) opt freq" |
| -rr | Read the route from the chk file (and hence from a %oldChk or %oldBAF file) rather than from the input. The input file is read if it exists, but it is not an error if it does not exist or is /dev/null. No %-lines are read: command line switches must be used for file names, memory etc. | |
| -y | Checkpoint file. -oc is a synonym. | -y="$HOME/project3/gfp.chk" |
| -fchk -baf -faf |
Generate the specified formatted checkpoint file as well as a binary one, and update it each time the checkpoint file is updated. If the file has extension .baf or .faf, that type of file is generated instead. The forms -baf and -faf can be used to make the file extension default to the corresponding extension. During a relaxed scan, a file with a unique name derived from the specified name is generated at each optimized point. -fck is a synonym. | -fchk=/plots/job8.fchk |
| -z | Read-write file. | -z=/scratch2/fox7.rwf |
| -zn | Specify read-write file but save only for restarting (i.e., as with %NoSave). | -zn=/scratch2/fox7.rwf |
| -ic | Existing checkpoint file from which to read input. | -ic=job6 |
| -ib -if |
BAF/FAF from which to read input. With the default extension being .baf and .faf respectively (although either type file may be specified for either option if the extension is included). The previous options –im, –im4, –im8,–ir, –ir4 and –ir8 are all equivalent to this option. | -ib=fox7.baf |
| -ob -of |
Output BAF or FAF, with the default extension being .baf and .faf respectively (although either type file may be specified for either option if the extension is included). The forms -ob4,-of4 force 4-byte integers on 64-bit computers. The previous options –om, –om4, –om8, –or, –or4 and –or8 are synonyms. | -of=job16new.faf |
| -exedir | Path of directories to search for link executables. | -exedir="/A1/gauss/bsd:/A1/gauss" |
| -scrdir | Scratch directory/directories to use. | -scrdir=/scratch |
| -kj | Equivalent to %KJob link0 command. Causes the job to stop at the requested point in the current job step (any additional job steps are ignored). | -kj="L301" |
| -l0c | Arbitrary link 0 commands to be applied to each job step in the input file, separated by semicolons. | %D2E="/scratch3/job5" |
| -lflags | Flags (options) to be passed to Linda ntsnet. | -lflags="-vv" |
| -s | Command to use for starting workers for network parallel jobs: generally ssh or rsh, but any command may be specified. | -s=ssh |
| -ssh | Use ssh to start Linda workers. | |
| -rsh | Use rsh to start Linda workers. | |
| -p | Specify the number of processors to use for the job (leaving the selection to the operating system). | -p=4 |
Note that the quotation marks are often required around option values to avoid modification by the shell.
Most options that control how Gaussian operates can be specified in any of 4 ways. From highest to lowest precedence these are:
- As Link 0 input (%-lines): This is the usual method to control a specific job and the only way to control a specific step within a multi-step input file. Example: %MEM=200GB.
- As options on the command line: Command line options are useful when you want to define aliases or other shortcuts for different common ways of running the program. Example: g26 -m=200gb …
- As environment variables: This is most useful in standard scripts, for example for generating and submitting jobs to batch queuing systems. Example: export GAUSS_MDEF=200gb
- As directives in the Default.Route file: This is most useful when one wants to change the program defaults for all jobs. Example: -M- 200GB
The following table lists the equivalences among Link 0 commands, command line options, Default.Route items and environment variables. In general, the environment variable GAUSS_QDEF provides a equivalent functionality to –Q– in the Default.Route file and the g26 command option –q (note that q may be more than one character). For example, all of the following have the equivalent effect:
-M- 4GB in Default.Route
export GAUSS_MDEF=4GB
g26 -m="4GB" …
| Default.Route | Link 0 | g26 Opt. | Env. Var. | Description |
| Gaussian execution defaults | ||||
| -R- | -r | GAUSS_RDEF | Route section keyword list. | |
| # section | -x | GAUSS_XDEF | Complete route for the job (route not read from input file). | |
| -M- | %Mem | -m | GAUSS_MDEF | Memory amount for Gaussian jobs. |
| -C- | -c | GAUSS_CDEF | Processor/core list for multiprocessor parallel jobs. | |
| -G- | -g | GAUSS_GDEF | GPUs=Cores list for GPU parallel jobs. | |
| -W- | -w | GAUSS_WDEF | List of hostnames for network parallel jobs. | |
| -S- | %SSH=command | -s | GAUSS_SDEF | Program to start workers for network parallel jobs. %UseSSH is equivalent to %SSH=ssh and %UseRSH similarly specifies rsh. |
| %DebugLinda | -lf="-vv" | GAUSS_LFDEF | Provide additional Linda debugging information. | |
| %KJob | -kj | GAUSS_KJDEF | Terminate job step at the specified link. Note that the link 0 command causes the job to go on to the next job step in a multistep job; in contrast, any subsequent steps are skipped with the command line option and the environment variable. | |
| File locations (useful for scripts and external programs) | ||||
| %Chk | -y | GAUSS_YDEF | Checkpoint file for job. | |
| %RWF | -z | GAUSS_ZDEF | Read-write file for job. | |
| %OldChk | -ic | GAUSS_ICDEF | Existing checkpoint file from which to read input. | |
| %OldBAF | -ib | GAUSS_IBDEF | BAF from which to read input (extension defaults to .baf; .faf can be specified explicitly). | |
| %OldFAF | -if | GAUSS_IFDEF | FAF from which to read input (extension defaults to .faf; .baf can be specified explicitly). | |
| -ob | GAUSS_OBDEF | Output BAF (extension defaults to .baf; .faf can be specified explicitly). | ||
| -of | GAUSS_OFDEF | Output FAF (extension defaults to .faf; .baf can be specified explicitly). | ||
| Utility program defaults | ||||
| -F- | GAUSS_FDEF | Options for the formchk utility. | ||
| -U- | GAUSS_UDEF | Memory amount for utilities. | ||
| Archive entry data | ||||
| -H- | -h | GAUSS_HDEF | Computer hostname. | |
| -O- | GAUSS_ODEF | Organization (site) name. | ||
Note that the quotation marks are normally required around the specified value for the command line and environment variables to avoid modification of the parameter string by the shell.
Link 0 Commands
These commands specify a name for the checkpoint file, and an alternate name and directory location for the read-write file, and cause only the checkpoint file to be saved at the conclusion of the Gaussian job:
%RWF=/chem/scratch2/water Files to be deleted go here. %NoSave %Chk=water Files to be saved go here.
Default.Route Entries
For a dual-core workstation with 8 GB memory and 1 TB of disk, the default algorithms and memory allocation are fine. However, MaxDisk and the default CPUs for execution need to be specified:
-C- 0,1 -#- MaxDisk=200GB
On a server with 4 octa-core processors and 256 GB of memory designed to be used for large jobs, 8 cores should be used by default: the first 8 odd numbered cores starting with core 0. Also, more memory should be given to each job (2 GB/core):
-M- 16GB -C- 0-16/2 -#- MaxDisk=500GB
On some older Intel processors (Nehalem and before), there is not enough memory bandwidth to keep all the CPUs on a chip busy, and it is often preferable to use half the CPUs, each with twice as much memory as if all were used. For example, on such a machine with 4 12-core chips and 128 GBytes of memory, with CPUs 0-11 on the first chip, 12-23 on the second, etc., it is better to run using 24 processors (6 on each chip) and give them 72/24=3GByte memory each, rather than use all 48 with only 1.5GBytes of memory each. The appropriate directive would be
-M- 72GB -C- 0-47/2
/2 says to use every other core: i.e., cores 0, 2, 4, 6, 8 and 10 on chip 0, cores 12, 14, 16, 18, 20 and 22 on chip 1, and so on.
