Input and Output¶

When the program has been installed properly on your machine, you should be able to run it by supplying appropriate input.

In the Examples section you can find sample input files covering most basic options.

Delimiters

An input record may contain several items. The general rule is that each sequence of characters, that does not contain a delimiter, is an entity. Delimiters in this context are:

the blank or space character ‘ ‘
the comma ‘,’ and
the equal sign ‘=’.

It is assumed throughout that only characters of the Fortran character set are used.

Warning

Do not use tabs in the input file! The program may not see them as delimiters and the effects are hard to predict.

Uppercase and lowercase

Virtually all input items are case-insensitive, but take notice of the obvious exceptions: names of files and directories are case-sensitive.

Keywords¶

Input is structured by keywords, or keys. A key is a string of letters, dollar signs ($), and digits. It must not start with a digit. It must not contain any other character, in particular not any blank.

Key-controlled input occurs in two forms: either one record (which contains both the key and/or associated data) or a sequence of records, collectively denoted as a key block. The first record of the block specifies the key (and may supply additional information); the block is closed by the ‘end-key’ code: a record containing only the word ‘End’. The other records in the block provide data associated with the key.

The form to be used for a key is not optional: each admissible key corresponds to a particular form. The block form is used for keys which relate to ‘lists’ of data, such as atomic coordinates or basis functions.

As is the case in the molecular code, the ‘title’ must be specified explicitly with the key Title and may be put on any record of the input file. The input file should end with a record ‘End Input’, that is, the program reads input until such a record is encountered or until the Fortran end-of-file condition becomes true, whichever comes first.

‘End Input’ is not a key.

Summarizing, the input file must have the following format:

Format of the Input file¶

TITLE jobname
   key-controlled data
   key-controlled data
   (et cetera...)
End Input

The ordering of keys in input is free and has no consequences.

All numerical information is ‘free format’: the absolute positions of numbers and the format of reals is irrelevant.

In most cases lowercase characters and capitals can both be used and the program will not discriminate between them, except in filenames.

Setting up an Input File¶

We now give a brief guide how to set up input.

You first specify the minimally required information: the definition of the geometry and the basis sets.

Define the geometry with the key blocks Atoms and Lattice.
Specify the BasisDefaults key block. With this you can set the quality of the basis set to be used, and the size of the frozen core.
Terminate the input file by typing ‘End Input’

Atoms
   Atomnames and fractional/Cartesian coordinates
End

Lattice
   Lattice vectors of the unit cell
End

BasisDefaults
   BasisType ...
   Core      ...
End

Then you add keys for all aspects for which you don’t want to use the defaults.

Specify a title using the key Title.
Other keys: Unrestricted (if you want to do a spin-unrestricted calculation), NumericalQuality (general precision parameter), KSpace (parameter for numerical integration over the Brillouin Zone), DOS (generation of the density-of-states), and so on.
Comments: everything behind a exclamation mark ”!” is treated as comment. If you put it behind a key, leave some space between it, otherwise it will be seen as part of the key.

Consult the sample runs and description below, to see how you may use the various keys (Lattice, Atoms, BasisDefaults).

General Input Features¶

The program supports the following features to enhance user-friendliness of input:

Arithmetic expressions can be used (wherever numbers are required) involving the standard arithmetic operands in Fortran (+ - * / **), together with parentheses where necessary or convenient. Blanks are allowed in expressions and ignored, but they are interpreted as separators, i.e. as denoting the end of an expression, whenever the part before the blank can be evaluated as a correct expression. For instance 3* 4 will be interpreted as 12, but 3 *4 will be interpreted as 3, followed by a character *, followed in turn by the number 4. All numbers and results are interpreted and handled as being of type real, but whenever the result is a whole number (allowing for small round-off deviations), it will be recognized as possibly denoting an integer.
(Single) quotes can be used to designate strings, i.e. (parts of) records which are not to be parsed for expressions, but which are to be taken as they are. The quotes themselves are ignored. Double quotes inside a string are understood to denote the single quote character (as part of the string).
Empty records and starting blanks in records are allowed, and can be used to enhance clarity and readability of the input file for human readers by structuring its layout.
A double colon :: is interpreted as an end of line character, hence the double colon and anything after it is ignored

Title, Comments and Ignore¶

Title: Specifies the title of this run. The title is used for identification of the result files.

Comment (block-type), and line oriented: The content of this key is a text that will be copied to the output header. There, general program information is printed, too. The exclamation mark can also be used to add comments to you input that should not interpreted by BAND. Example:

Comment ! here are my comments
   Description of the calculation
   Some more description
End

Lattice ! FCC lattice
   0 a a
   a 0 a
   a a 0
End

! Here are my defines
Define
   a = 3.75
End

Finally it is possible to let BAND ignore parts of the input

Ignore (block-type): Suppress reading of input until the next end-key code (END).

Defining variables and functions¶

The user may define variables and functions in the input file, and apply them subsequently in expressions. The input file is read sequentially and variables and functions must be defined before they can be used. Note carefully that replacement of a variable (or function) by its value will occur wherever possible (textually), even if it leads to non-sense input. A frequently occurring mistake is that the user defines a variable ‘C’ in the input and then gets it corrupted because of subsequent isolated C characters being replaced by the defined numerical value. Therefore: avoid single-character variables and function names. Always check carefully that the identifier you introduce is not ‘used’ already in the input file. A few variables and functions are pre-defined:

variables: pi = 3.1415....
functions: sin, cos, tan, asin, acos, atan, exp, log, sqrt, nint.

The argument list of a function must be enclosed in parentheses, and the arguments (in case of more than one) must be separated by commas. Defining variables and/or functions is done with the block-type key define.

Define (block-type): Definition of user-supplied functions and variables that can subsequently be used in the input file. (see the note on auxiliary input features)

Example (part of input):

DEFINE
   ab = sin(pi/3)
   s13 = 14*sqrt(2)
   func(x,y,z) = x*ab+y**2-y*z
End
AKEY = FUNC (S13/5, S13/7, SIN(PI/6))

Here a function func and variables ab and s13 are defined, using the pre-defined functions sin and sqrt, as well as the pre-defined variable pi. These are then applied to assign a value to the (hypothetical) key AKEY.

Note 1: the variable ab is also used in the definition of func! This is allowed because ab is defined before func.

Note 2: variable- and function names must have the same form as keywords, i.e. only certain characters are allowed.

Note 3: in the definition of variables and functions blanks are ignored altogether (in the value part) and will not be interpreted as possible separators of the expression that defines the variable or function.

Execution flow¶

There are a few ways to alter the standard execution flow, which may be useful to developers or expert users.

StopAfter: Specifies that the program is stopped after execution of a specified program-part (subroutine). The specified name should be one of a pre-defined list. The most relevant ones are gemtry (all geometrical aspects are checked, symmetry analysis is carried out, and numbers of (symmetry-unique) integration points in real space and in k-space are determined; this part takes only little cpu-time) and atomic (in addition to the geometry-part all radial parts of basis- and fit functions are generated, and the spherically symmetric atoms are computed and inserted in the crystal; the initial charge density is defined and integrated (check on integration-precision), and the electrostatic interaction is computed between the unrelaxed free atoms).
SKIP: followed by any number of strings (separated by blanks or commas) tells the program to skip certain parts. Should only be used by those who know what they’re doing. Recognized are certain pre-defined strings. Useful argument may be DOS when that part of the program takes a long time (usually not), or eigenvalues (to suppress printing the eigenvalues at the (first and last) SCF cycles).

ALLOW: debugging feature to let the program continue even when intermediate results seem to be wrong or very inaccurate. Currently there are only few places in the program where this key is used. Argument to the key is what should be allowed. Possible arguments: BadIntegration, OCC, CHARGEERROR, DEPENDBASIS.

Printed Output¶

The amount of output in different stages of the program is controlled by print keys, that can be toggled with the key Print followed by a key (see description of Print key).

Print

One or more strings (separated by blanks or comma’s) from a pre-defined set may be typed after the key. This induces printing of various kinds of information, usually only used for debugging and checking. The set of recognized strings frequently changes (mainly expands) in the course of software-developments. Useful arguments may be symmetry, and fit. A list of all important arguments to this key follows:

Eigens: Prints the (complex) coefficients in the form (norm, phase factor) of the eigenvectors with respect to the valence basis. Coefficients with a norm smaller than eigthreshold will be skipped. This threshold can be set with the option eigthreshold x, default x=.01.

MullikenOverlapPopulations: Prints overlap population of all basis functions.

OrbitalLabels: Prints the labels of the orbitals. If you are interested in the labels of an old calculation and you don’t want to repeat it completely, you can add the option StopAfter gemtry to your input file.

OrbPop: Prints the Mulliken population per orbital, for all eigenstates. This is the most detailed population analysis that you can get, one for all k-points and for each band. Populations below a certain threshold are ignored. This threshold can be set with the option popthreshold x. By default x =.01.

BLCKAT: Print the information about the distance effects used in the numerical integrals.

Fit: Print more details about the fitting procedure, such as the fit coefficients at each SCF cycle.

Symmetry: Print the symmetry operators.
OrbLabels: Print the list of basis functions

Thresholds¶

POPTHRESHOLD: Threshold for printing Mulliken population terms. Default 1e-2. Works with print orbpop.

EIGTHRESHOLD: Components smaller (absolute value) than this parameter (default 1e-2) are not printed in the output of the DOS section, where the breakdown of crystal orbitals in the primitive basis is printed. Works with print eigens.

More options¶

The following print options only make sense when debugging the code.

Print

One or more strings (separated by blanks or comma’s) from a pre-defined set may be typed after the key. The following names replace the IRPNT[IPRSE] keys of the previous versions of BAND:

PrepNone, PrepMore, PrepDetail replace IPRNTP 0, 2, 5
IntNone, IntMore, IntDetail replace IPRNTI 0, 2, 5
FrmNone, FrmMore, FrmDetail replace IPRNTR 0, 2, 5
SCFNone, SCFMore, SCFDetail replace IPRNTS 0, 2, 5
EigNone, EigMore, EigDetail replace IPRNTE 0, 2, 5

Debug key¶

(programmers only)

DEBUG: The argument is usually a (list of) subroutine names that you want to debug. (The programmer can check for this in the same way as PRINT or ALLOW keys.)