Manual:Input file
From OctopusWiki
Octopus uses a single input file from which Octopus will read user instructions to know what to calculate and how. This page explains how to generate that file and what is the general format.
Contents |
Input file
Input options should be in a file called inp, in the directory Octopus is run from. This is a plain ACSII 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 file PREFIX/share/octopus/samples/Na2.
At the beginning of the program liboct 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.
Mathematical expressions
The parser can interpret several expressions in the input file and assign the result to the variable. The arguments can be numbers or other variables. All arithmetic operators are supported (a+b, a-b, a*b, a/b; for exponentiation the syntax a^b is used), and the following 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. 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. 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.
Predefined variables
There are some predefined constants for your convenience:
pi-
3.141592653589793. What else is there to say? e- The base of the natural logarithms.
falseorforno- False in all its flavors.
trueortoryes- The truthful companion of
false.
Blocks
Blocks are defined as a collection of values, organised in row and column format. The syntax is the following:
%varexp | 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.
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 status/out.oct. 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 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.
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
Units = ev_angstrom
must always be used instead of
Units = 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.
