Command options

This page gives a description of the “command options” input section, which controls the global operation and actions of the code. This section begins an input file. It tells the code what it will do (scf, forces, relaxation, etc), how it will do it (with or without blas/3 libraries, eigensolver or linear scaling solver, etc.), and what kind of output (level of output detail, or whether to generate certain files for post-processing). The entire section is optional — by default, the code will do a SCF calculation and stop — with the only required input being the “setup data” which signals the beginning of the setup data input section.

Input options

The command options input section appears at the beginning of the input file. All data in this section is optional, with the exception of the “setup data” statement, which ends the command options section, and begins the setup data input section.

The following are the common input keywords in this section. All the keywords are optional, and can appear in any order within this section. The keywords must be left-justified. Most keywords require no data.

Defaults, if the input file includes no commands, are:

  • “do iters” – run only to scf and stop, no forces or beyond.
  • “no spinopt” – do calculation with fixed polarization.
  • “no test ” – continue to job completion, do not stop after input tests
  • “do blas3” – use BLAS/3 libraries (best if vendor-optimized, else turn off)
  • “no post ” – do not generate a file for post-processing code
  • “do split” – split the atomic basis shells into segmented form
  • “no bands” – no band structure calculation
  • “keepsym ” – trigger error if detect symmetry failure in input
  • output level = 2
     ...
output level - set the amount of outputlevel_output (int, [0=least:5=most, 2=default,3=fine-timing])
     ...
do setup|iters|force - pick one for extent of calculation
     ...
do/no tests - stop execution after checking input file/executable
     ...
do/no dynamics - molecular dynamics, or no...do/no relax - relax atomic positions, or no
     ...
do/no cell - perform cell optimization, or no
     ...
do/no neb - perform NEB transition state finding calculation, or no
     ...
do/no spinopt - optimize spin polarization (2.61) (activated only if spin on).
     ...
do/no bands - do band structure calculation (2.64)
     ...
keepsym/redusym - enforce (strict-check) symmetry, or allow reduced symmetry
     ...
... and development-only options (expert-only)
set record_length - max length (r*8) for single I/O record in binary filesmaxreclen (int)
     ...
do|no dmrho|efrho - compel/forbid a density-matrix or eigenvector based grid-density constructure
     ...
do/no blas3 - use BLAS/3 routines, or bypass them
     ...
do|no kparallel - compel/forbid the k-parallel scf (if possible)
     ...
do|no psolver - compel/forbid using a parallel eigensolver (if possible, cf. serial solves)
     ...
do|no kppsolve - permit/forbid using k-parallel-parallel eigensolvers
     ...
... and then the (required) end of the options phase input 
     ...
setup data - begin setup phase data

Details

output level

The output level is an integer value that ranges from 0 (least) to 5 (most) output. The default is 2. Setting the level to 3 causes all the timing diagnostics to be turned on – useful for debugging crashes (there is a flush print buffers embedded in the timing statement) and for performance tuning. Level 4 adds some more output for the code, and level 5 should only be invoked for small problems, or those with a lot of disk space.

relax and cell

The “do relax” is sometimes meaningless for a cell optimization. For the cell optimization, there are crystals (e.g., bcc, Td) where there are no internal degrees of freedom, i.e., the atoms are fixed by symmetry, and an atomic relaxation is moot. Also, even for those crystals with internal atomic degrees of freedom (e.g. wurtzite), it can be useful to relax the cell shape some before doing any atomic relaxation. The cell optimization is done after a geometry relaxation (i.e. the cell parameters are not minimized simultaneously with the atomic positions). Experience has shown it to be critical for good convergence that the cell minimization be done using stresses computed in cells with fully minimized atomic positions. Also, good forces and good stresses are necessary, frequently beyond the default cutoffs set in the code. Adjusting the force integrals cutoffs (cutfrc=0.010-0.001 in the run phase input data) is frequently necessary for high-quality results.

relax, neb, and cell

The “do relax” is mandatory for a NEB calculation, and the geometry relaxation method chosen in the geometry section is the method used to relax the NEB images. Note that one can either do cell or do NEB, but not both, i.e., one cannot look at a structural phase transformation that takes one crystal unit cell shape to another unit cell shape.

blas3

The code has multiple paths for some expensive computational kernels. With a vendor-optimized library, the BLAS/3 paths can be much more efficient than the explicitly coded path (especially for real, i.e., gamma-point; the results with complex arithmetic are mixed). Note: without vendor (or ATLAS-)optimized BLAS/3 libraries (i.e., self-compiled LAPACK), the BLAS/3 path can be up to 3 times slower than the explicitly coded paths, and the BLAS/3 path should be bypassed for better performance. If the code is linked to vendor-optimized libraries, the coded default to use blas3 should be unchanged. However, if vendor-optimized libraries are unavailable and the code was linked to compiled LAPACK routines that are included in the package, the blas3 routines should be bypassed using “no blas3”.

do post

The “do post” instruction causes the code to generate additional output for use in separate post-processing codes. For example, output in the file “lcao.post” records data in ASCII that can be used to drive a program to do Mulliken analyses, density-of-states, etc.

set record_length

On some platforms (Alphas), it had been the case that the length of single I/O record was limited. The code could write any record, but a read would intermittently and irreproducibly fail on records above a certain length. The code wraps all its big I/O such so as to break up a long write/read into multiple write/reads that are no longer than a fixed length maxreclen. This command tells the code to change the max record length to the specified value. An input of ‘0’ tells the code to use its internal default. Input less than 0 turns off this module (i.e. sets the limit to infinity). The code, in the output file, echoes what it is using as a max record length for a given job. This command is *optional*, and its use is discouraged. The better way to deal with this is to alter the configuration (utl) file for the compile, to guarantee that *all* runs have the same file record lengths (mixing files of different record length limits will fail).

keepsym/redusym

By default, the code triggers a failure if the input atomic configuration does not conform to the symmetry specified in the input file. When “redusym” is invoked, the code will reduce the symmetry from the input file to those symmetries respected by the atomic/cell coordinates. This is dangerous – because the symmetry is a basic check of whether you have assembled your input correctly, and allowing the code to reduce the symmetry means that an unintentionally flawed input file may run to completion, giving nonsensical results. Caveat user.