Description
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).
%OldMatrix=matfile
Copy the data on the unformatted binary matrix element file matfile to the active checkpoint file at the start of the job step. This directive is similar %OldChk but takes the data from the specified file. In Rev. B.01 and later, the file name may be followed by the keyword i4lab or i8lab to specify that the file uses 4-byte or 8-byte integers (respectively): e.g., %OldMatrix=(myfile,i4lab).
%OldRawMatrix=matfile
Copy the data on the raw binary matrix element file matfile to the active checkpoint file at the start of the job step. This directive is similar %OldChk but takes the data from the specified file. In Rev. B.01 and later, the file name may be followed by the keyword i4lab or i8lab to specify that the fileuses 4-byte or 8-byte integers (respectively): e.g., %OldRaw=(myfile,i4lab).
%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 $g16root). 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
%CPU=proc-list
This directive contains a list of processor/core numbers for shared memory parallel processing, with multiple items are separated by commas. This directive is designed to replace the earlier %NProcShared and %NProc directives.
A default value can be set in Default.Route with the -C- directive.
%NProcShared=N
Requests that the job use up to N processors/cores on shared memory parallel execution on SMP multiprocessor computers. For most purposes, this directive is superceded by %CPU. The value of %NProcShared overrides the -P- directive in the Default.Route file.
%GPUCPU=gpu-list=core-list
This 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 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. For example, the following directive tells Gaussian to execute on GPU0 through GPU3:
%GPUCPU=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:
%GPUCPU=0-3=0-1,16-17
A default value for %GPUCPUcan be set in Default.Route with the -G- directive.
%LindaWorkers=node1[:n1] [,node2[:n2]] …
This lists the TCP node name for each node to use. By default, one Linda worker is started on each node, but the optional value allows this to be varied. A worker is always started on the node where the job is started (the master node) whether or not it appears in the node list. A default value can be set in Default.Route with the -W- directive.
%LindaWorkers may be combined with %NProcShared. In this case, one or more parallel worker processes will be run on each node (the number still determined by the values in %LindaWorkers). The value to %NProcShared specifies the number of SMP processors/cores to use on each system in the worker node list.
Do not use the obsolete %NProcLinda directive. Gaussian will compute the total number of Linda workers based on the %LindaWorkers input.
%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.
Most options that control how Gaussian 16 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: g16 -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 16 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 16 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.
Examples
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.
The following directive causes a network parallel job to be run across the specified 5 nodes. Nodes hamlet and ophelia will each run two worker processes.
%LindaWorkers=hamlet:2,ophelia:2,laertes,horatio,lear
The following directives specify that a parallel job will be executed on hosts norway, italy and spain. Nodes norway and italy will each run one 4-way SMP parallel worker, and spain will run two such workers:
NProcShared=4 Specifies four-way SMP parallelism.
%LindaWorkers=norway,italy,spain:2
These directives make sense when norway and italy are 4 processor/core computers, and spain is an 8 processor/core computer.
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).
%OldMatrix=matfile
Copy the data on the unformatted binary matrix element file matfile to the active checkpoint file at the start of the job step. This directive is similar %OldChk but takes the data from the specified file. In Rev. B.01 and later, the file name may be followed by the keyword i4lab or i8lab to specify that the file uses 4-byte or 8-byte integers (respectively): e.g., %OldMatrix=(myfile,i4lab).
%OldRawMatrix=matfile
Copy the data on the raw binary matrix element file matfile to the active checkpoint file at the start of the job step. This directive is similar %OldChk but takes the data from the specified file. In Rev. B.01 and later, the file name may be followed by the keyword i4lab or i8lab to specify that the fileuses 4-byte or 8-byte integers (respectively): e.g., %OldRaw=(myfile,i4lab).
%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 $g16root). 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.
%CPU=proc-list
This directive contains a list of processor/core numbers for shared memory parallel processing, with multiple items are separated by commas. This directive is designed to replace the earlier %NProcShared and %NProc directives.
A default value can be set in Default.Route with the -C- directive.
%NProcShared=N
Requests that the job use up to N processors/cores on shared memory parallel execution on SMP multiprocessor computers. For most purposes, this directive is superceded by %CPU. The value of %NProcShared overrides the -P- directive in the Default.Route file.
%GPUCPU=gpu-list=core-list
This 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 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. For example, the following directive tells Gaussian to execute on GPU0 through GPU3:
%GPUCPU=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:
%GPUCPU=0-3=0-1,16-17
A default value for %GPUCPUcan be set in Default.Route with the -G- directive.
%LindaWorkers=node1[:n1] [,node2[:n2]] …
This lists the TCP node name for each node to use. By default, one Linda worker is started on each node, but the optional value allows this to be varied. A worker is always started on the node where the job is started (the master node) whether or not it appears in the node list. A default value can be set in Default.Route with the -W- directive.
%LindaWorkers may be combined with %NProcShared. In this case, one or more parallel worker processes will be run on each node (the number still determined by the values in %LindaWorkers). The value to %NProcShared specifies the number of SMP processors/cores to use on each system in the worker node list.
Do not use the obsolete %NProcLinda directive. Gaussian will compute the total number of Linda workers based on the %LindaWorkers input.
%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.
Most options that control how Gaussian 16 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: g16 -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 16 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 16 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.
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.
The following directive causes a network parallel job to be run across the specified 5 nodes. Nodes hamlet and ophelia will each run two worker processes.
%LindaWorkers=hamlet:2,ophelia:2,laertes,horatio,lear
The following directives specify that a parallel job will be executed on hosts norway, italy and spain. Nodes norway and italy will each run one 4-way SMP parallel worker, and spain will run two such workers:
NProcShared=4 Specifies four-way SMP parallelism.
%LindaWorkers=norway,italy,spain:2
These directives make sense when norway and italy are 4 processor/core computers, and spain is an 8 processor/core computer.
Last updated on: 23 July 2019. [G16 Rev. C.01]