Input file

Octopus uses a single input file from which to read user instructions to know what to calculate and how. This page explains how to generate that file and what is the general format. The Octopus parser is a library found in the liboct_parser directory of the source, based on bison and C. You can find two (old) separate release versions of it at the bottom of the Releases page.

Input file

Input options should be in a file called inp , in the directory Octopus is run from. This is a plain ASCII text file, to create or edit it you can use any text editor like emacs, vi, jed, pico, gedit, etc. For a fairly comprehensive example, just look at the tutorial page Basic input options.

At the beginning of the program, the parser reads the input file, parses it, and generates a list of variables that will be read by Octopus (note that the input is case-independent). There are two kind of variables: scalar values (strings or numbers), and blocks (that you may view as matrices).

Scalar Variables

A scalar variable var can be defined by:

var = exp

var can contain any alphanumeric character plus _, and exp can be a quote-delimited string, a number (integer, real, or complex), a variable name, or a mathematical expression. Complex numbers are defined as {real, imag}. Real numbers can use scientific notation with e or E (no d or D, Fortran people), such as 6.02e23. Variable names are not case-sensitive, and you must not redefine a previously defined symbol – especially not the reserved variables x, y, z, r, w, t which are used in space- or time-dependent expressions, where w is the 4th space coordinate when operating in 4D. A list of predefined variables follows below

Mathematical expressions

The parser can interpret expressions in the input file, either to assign the result to a variable, or for defining functions such as a potential in the Species block or a time-dependent function in the TDFunctions block. The arguments can be numbers or other variables.

Arithmetic operators

Logical operators

Logical operation will return 0 for false or 1 for true. You can exploit this to define a piecewise expression, e.g. “2 * (x <= 0) - 3 * (x > 0)" (although the step function may also be used). The comparison operators (except ==) use only the real part of complex numbers.

Functions

These mathematical operations are all based on the GSL library and are defined in symbols.c and grammar.y.

References

Predefined variables

There are some predefined constants for your convenience:

Since version 7.0 there are also some predefined units that can be found by searching for the decimal point . in share/variables:

Blocks

Blocks are defined as a collection of values, organised in row and column format. The syntax is the following:


%var
 exp | exp | exp | ... 
 exp | exp | exp | ... 
 ...
%

Rows in a block are separated by a newline, while columns are separated by the character | or by a tab. There may be any number of lines and any number of columns in a block. Note also that each line can have a different number of columns. Values in a block don’t have to be of the same type.

Comments

Everything following the character - until the end of the line is considered a comment and is simply cast into oblivion.

Includes

With include FILENAME it is possible to include external files into the input file. To illustrate the usage of this command we can split the input file from the Methane tutorial in two.

In the input file inp we have:

 CalculationMode = gs
 UnitsOutput = eV_Angstrom

 Radius = 3.5*angstrom
 Spacing = 0.22*angstrom
 
 
 include geometry.oct

with the geometry being defined in geometry.oct

 CH = 1.2*angstrom
 %Coordinates
   "C" |           0 |          0 |           0
   "H" |  CH/sqrt(3) | CH/sqrt(3) |  CH/sqrt(3)
   "H" | -CH/sqrt(3) |-CH/sqrt(3) |  CH/sqrt(3)
   "H" |  CH/sqrt(3) |-CH/sqrt(3) | -CH/sqrt(3)
   "H" | -CH/sqrt(3) | CH/sqrt(3) | -CH/sqrt(3)
 %

Environment variables

You can also set variables using the environment, which can be helpful in scripting.

Default values

If Octopus tries to read a variable that is not defined in the input file, it automatically assigns to it a default value (there are some cases where Octopus cannot find a sensible default value and it will stop with an error). All variables read (present or not in the input file) are output to the file exec/parser.log . The variable that are not defined in the input file will have a -default comment to it. If you are not sure of what the program is reading, just take a look at it.

We recommend you to keep the variables in the input file to a minimum: ‘‘do not write a variable that will be assigned its default value’’. The default can change in newer versions of Octopus and old values might cause problems. Besides that, your input files become difficult to read and understand.

Documentation

Each input variable has (or should have) its own documentation explaining what it does and the valid values it may take. This documentation can be obtained online or it can also be accessed by the oct-help command.

Experimental features

Even in the stable releases of Octopus there are many features that are being developed and are not suitable for production runs. To protect users from inadvertly using these parts they are declared as ‘‘Experimental’’.

When you try to use one of these experimental functionalities Octopus will stop with an error. If you want to use it you need to set the variable ExperimentalFeatures to yes. Now Octopus will only emit a warning.

By setting ExperimentalFeatures to yes you will be allowed to use parts of the code that are not complete or not well tested and most likely produce wrong results. If you want to use them for production runs you should contact the Octopus developers first.

Good practices

In order to ensure compatibility with newer versions of Octopus and avoid problems, keep in mind the following rules of good practice when writing input files:

 UnitsOutput = ev_angstrom

‘‘must always’’ be used instead of

 UnitsOutput = 3
 m = 0.1
 c = 137.036
 E = m*c^2

instead of

 m = 0.1
 c = 137.036
 E = 1877.8865

In the second case, you might change the value of m (or c if you are a cosmologist) while forgetting to update E, ending up with an inconsistent file.