Manual: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.
Contents
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 Tutorial:Nitrogen_atom.
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 caseindependent). 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 quotedelimited 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 casesensitive, 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 timedependent expressions, where w is the 4th space coordinate when operating in 4D.
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 timedependent function in the TDFunctions
block. The arguments can be numbers or other variables.
Arithmetic operators

a+b
 addition

ab
 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 ()

a > b
 greater than
 a >= b
 greater than or equal to ()
 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)
orln(x)
 The natural logarithm of
x
. log10(x)
 Base 10 logarithm of
x
. logb(x, b)
 Base
b
logarithm ofx
.
{x, y}
 The complex number .
arg(z)
 Argument of the complex number
z
, , where . abs(z)
 Magnitude of the complex number
z
, . abs2(z)
 Magnitude squared of the complex number
z
, . logabs(z)
 Natural logarithm of the magnitude of the complex number
z
, . It allows an accurate evaluation of when is close to one. The direct evaluation oflog(abs(z))
would lead to a loss of precision in this case. conjg(z)
 Complex conjugate of the complex number
z
, . inv(z)
 Inverse, or reciprocal, of the complex number
z
, .
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)
 = .
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
andy
. max(x, y)
 The maximum of
x
andy
. step(x)
 The Heaviside step function in
x
. This can be used for piecewisedefined functions. erf(x)
 The error function .
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
 https://www.gnu.org/software/gsl/manual/html_node/Propertiesofcomplexnumbers.html
 https://www.gnu.org/software/gsl/manual/html_node/Complexarithmeticoperators.html
 https://www.gnu.org/software/gsl/manual/html_node/ErrorFunction.html
 https://www.gnu.org/software/libc/manual/html_node/RoundingFunctions.html
 https://www.gnu.org/software/gsl/manual/html_node/Representationofcomplexnumbers.html
Predefined variables
There are some predefined constants for your convenience:
pi

3.141592653589793
. e
 The base of the natural logarithms.
false
orno
 False.
true
oryes
 True.
i
 The imaginary unit , 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
.
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.
inp  geometry.oct 


CH = 1.2*angstrom
%

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 octhelp 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 mathematicalinterpretation 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.