The Default.Route File

Description

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, residing in $g25root/g25. Under Windows, the Gaussian defaults file is Default.Rou, and it is located in the Gaussian 25W scratch subdirectory (e.g., C:\G25W\scratch). The format of the file is the same on all computer systems.

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.

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.

Command Line Options & Environment Variable Equivalents

All of these directives can also be set via environment variables or UNIX/Linux command line arguments. The environment variable GAUSS_xDEF provides a command line equivalent to -X- in the Default.Route file. Similarly, the command line argument to g25 –x=”value” specifies the same setting. For example, all of the following have the equivalent effect:

  -M- 4GB in Default.Route
  export GAUSS_MDEF=4GB
  g25 -m="4GB" …

Order of Priority

The order of priority is:

command line argument
environment variable
Default.Route setting
internal program default

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.

Parallel Job Directives

Parallel Execution on Shared Memory Multiprocessors

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.

Examples

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.

Directive List

Default.Route	Link 0	Option	Env. Var.	Description
-#-		-r	GAUSS_RDEF	Route section keyword list.
-C-	%CPU	-c	GAUSS_CDEF	Processor/core list for multiprocessor parallel jobs.
-F-			GAUSS_FDEF	Options for the formchk utility.
-G-	%GPUCPU	-g	GAUSS_GDEF	GPUs=Cores list for GPU parallel jobs.
-H-			GAUSS_HDEF	Computer hostname.
-M-	%Mem	-m	GAUSS_MDEF	Memory amount for Gaussian jobs.
-O-			GAUSS_ODEF	Organization (site) name.
-P-	%NProcShared	-p	GAUSS_PDEF	Number of processors/cores for multiprocessor parallel jobs. Superseded in most cases by -C-.
-R-		-r	GAUSS_RDEF	Route section keyword list.
-S-	%UseSSH	-s	GAUSS_SDEF	Program to start workers for network parallel jobs: rsh or ssh.
-U-			GAUSS_UDEF	Memory amount for utilities.
-W-	%LindaWorkers	-w	GAUSS_WDEF	List of hostnames for network parallel jobs.

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: %CPU=1,2,3,4. For full documentation on Link 0 command, see Link 0 Commands
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: g25 -c="1,2,3,4" …
As environment variables: This is most useful in standard scripts, for example for generating and submitting jobs to batch queuing systems. Example: export GAUSS_CDEF="1,2,3,4"
As directives in the Default.Route file: This is most useful when one wants to change the program defaults for all jobs. Example: -C- 1,2,3,4

When searching for a Default.Route file the current default directory is checked first, followed by the directories in the path for Gaussian executables: environment variable GAUSS_EXEDIR, which normally points to $g16root/g16.

The following table lists the equivalences among Link 0 commands, command line options, Default.Route items and environment variables. The -h, -o options and the -i and -o option classes were introduced in [REV B], as were their corresponding environment variables.

Default.Route	Link 0	Option	Env. Var.	Description
Gaussian execution defaults
-R-		-r	GAUSS_RDEF	Route section keyword list.
-M-	%Mem	-m	GAUSS_MDEF	Memory amount for Gaussian jobs.
-C-	%CPU	-c	GAUSS_CDEF	Processor/core list for multiprocessor parallel jobs.
-G-	%GPUCPU	-g	GAUSS_GDEF	GPUs=Cores list for GPU 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.
-W-	%LindaWorkers	-w	GAUSS_WDEF	List of hostnames for network parallel jobs.
-P-	%NProcShared	-p	GAUSS_PDEF	#processors/cores for multiprocessor parallel jobs. Deprecated; use -C-.
-L-	%NProcLinda	-l	GAUSS_LDEF	#nodes for network parallel jobs. Deprecated; use -W-.
Archive entry data
-H-		-h	GAUSS_HDEF	Computer hostname.
-O-		-o	GAUSS_ODEF	Organization (site) name.
Utility program defaults
-F-			GAUSS_FDEF	Options for the formchk utility.
-U-			GAUSS_UDEF	Memory amount for utilities.
Parameters for scripts and external programs
	# section	-x	GAUSS_XDEF	Complete route for the job (route not read from input file).
	%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.
	%OldMatrix	-im	GAUSS_IMDEF	Matrix element file from which to read input.
	%OldMatrix=(file,i4lab)	-im4	GAUSS_IM4DEF	Matrix element file using 4-byte integers from which to read input.
	%OldMatrix=(file,i8lab)	-im8	GAUSS_IM8DEF	Matrix element file using 8-byte integers from which to read input.
	%OldRaw	-ir	GAUSS_IRDEF	Raw matrix element file from which to read input.
	%OldRaw=(file,i4lab)	-ir4	GAUSS_IR4DEF	Raw matrix element file using 4-byte integers from which to read input.
	%OldRaw=(file,i8lab)	-ir8	GAUSS_IR8DEF	Raw matrix element file using 8-byte integers from which to read input.
		-oc	GAUSS_OCDEF	Output checkpoint file. Generally redundant with -y/GAUSS_YDEF.
		-om	GAUSS_OMDEF	Output matrix element file.
		-om4	GAUSS_OM4DEF	Output matrix element file using 4-byte integers.
		-om8	GAUSS_OM8DEF	Output matrix element file using 8-byte integers.
		-or	GAUSS_ORDEF	Output raw matrix element file.
		-or4	GAUSS_OR4DEF	Output raw matrix element file using 4-byte integers.
		-or8	GAUSS_OR8DEF	Output raw matrix element file using 8-byte integers.

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.

Last updated on: 15 July 2019.