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.
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.
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.
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
- Specify the
BasisDefaultskey 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
- 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 (
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* 4will be interpreted as 12, but
3 *4will 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¶
- 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
- 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
- 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
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.
There are a few ways to alter the standard execution flow, which may be useful to developers or expert users.
- 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).
- 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).
- 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.
The amount of output in different stages of the program is controlled by print keys, that can be toggled with the key
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:
- 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.
- Prints overlap population of all basis functions.
- 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.
- 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.
- Print the information about the distance effects used in the numerical integrals.
- Print more details about the fitting procedure, such as the fit coefficients at each SCF cycle.
- Print the symmetry operators.
- Print the list of basis functions
- Threshold for printing Mulliken population terms. Default 1e-2. Works with print orbpop.
- 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.
The following print options only make sense when debugging the code.
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
- 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