Navigation :

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

a+b: addition
a-b: subtraction
-a: unary minus
a*b: multiplication
a/b: division
a^b: exponentiation

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.

a < b: less than
a <= b: less than or equal to ($\le$)
a > b: greater than
a >= b: greater than or equal to ($\ge$)
a == b: equal to
a && b: logical and
a || b: logical or
!a: logical not

Functions

sqrt(x): The square root of x.
exp(x): The exponential of x.
log(x) or ln(x): The natural logarithm of x.
log10(x): Base 10 logarithm of x.
logb(x, b): Base b logarithm of x.
{x, y&-125;: The complex number $x + iy$.
arg(z): Argument of the complex number z, $\arg(z)$, where $-\pi < \arg(z) <= \pi$.
abs(z): Magnitude of the complex number z, $|z|$.
abs2(z): Magnitude squared of the complex number z, $|z|^2$.
logabs(z): Natural logarithm of the magnitude of the complex number z, $\log|z|$. It allows an accurate evaluation of $\log|z|$ when $|z|$ is close to one. The direct evaluation of log(abs(z)) would lead to a loss of precision in this case.
conjg(z): Complex conjugate of the complex number z, $z^* = x - i y$.
inv(z): Inverse, or reciprocal, of the complex number z, $\frac{1}{z} = \frac{x - i y}{x^2 + y^2}$.
sin(x), cos(x), tan(x), cot(x), sec(x), csc(x): The sine, cosine, tangent, cotangent, secant and cosecant of x.
asin(x), acos(x), atan(x), acot(x), asec(x), acsc(x): The inverse (arc-) sine, cosine, tangent, cotangent, secant and cosecant of x.
atan2(x,y): = $\mathrm{atan}(y/x)$.
sinh(x), cosh(x), tanh(x), coth(x), sech(x), csch(x): The hyperbolic sine, cosine, tangent, cotangent, secant and cosecant of x.
asinh(x), acosh(x), atanh(x), acoth(x), asech(x), acsch(x): The inverse hyperbolic sine, cosine, tangent, cotangent, secant and cosecant of x.
min(x, y): The minimum of x and y.
max(x, y): The maximum of x and y.
step(x): The Heaviside step function in x. This can be used for piecewise-defined functions.
erf(x): The error function $\mathrm{erf}(x) = \frac{2}{\sqrt{\pi}} \int_0^x dt e^{-t^2}$.
realpart(z): The real part of the complex number z.
imagpart(z): The imaginary part of the complex number z.
floor(x): The largest integer less than the real number x.
ceiling(x): The smallest integer greater than the real number x.

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:

pi: 3.141592653589793.
e: The base of the natural logarithms.
false or no: False.
true or yes: True.
i: The imaginary unit $i$, ‘‘i.e.’’ {0, 1}

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

angstrom: 1.8897261328856432.
pm or picometer: 0.018897261328856432.
nm or nanometer: 18.897261328856432.
ry or rydberg: 0.5.
eV or electronvolt: 0.03674932539796232.
invcm: 4.5563353e-06.
kelvin: 3.1668105e-06.
kjoule_mol: 0.00038087988.
kcal_mol: 0.0015936014.
as or attosecond: 0.0413413737896.
fs or femtosecond: 41.3413737896.
ps or picosecond: 41341.3737896.
c: 137.035999139.

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:

Although input variables that take an option as an input can also take a number, the number representation makes the input file less readable and it is likely to change in the future. So ‘‘‘avoid using numbers instead of values’'’. For example

 UnitsOutput = ev_angstrom

‘‘must always’’ be used instead of

 UnitsOutput = 3

‘‘‘Do not include variables that are not required in the input file’'’, especially declarations of values that are just a copy of the default value. This makes the input file longer, less readable and, since defaults are likely to change, it makes more probable that your input file will have problems with newer versions of Octopus. Instead rely on default values.
‘‘‘Avoid duplicating information in the input file’'’. Use your own variables and the mathematical-interpretation capabilities for that. For example, you should use:

 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.