2.6. Input Syntax¶

Note

this site is under reconstruction

The syntax of input files for nextnano++, nextnano.MSB (included in nextnano++), and nextnano.NEGF has been unified. The syntax features described below are, therefore, valid for all abovementioned tools. For tool-specific elements of syntax, such as the meaning, use, and allowed combinations of various keywords, please see the respective documentations: nextnano++, nextnano.MSB, and nextnano.NEGF.

General¶

Case Sensitivity¶

Input files are always CASE-SENSITIVE, which means that uppercase and lowercase are distinguished in the input files.

Example
In the script
text
Text
TeXt
teXt
TEXT
there are 5 different entries.

White-Spaces¶

The input files are almost white-space independent.

Example 1
The two scripts
x=5 $y=6 z=[1,2]
and
x = 5
$y = 6
z = [1,
    2]
have the same effect.
Example 2
Elements of syntax
band{
and
band   {
are considered the same.

However, there are exceptions, when breaking line is not allowed.

Example 3
Adding a line breaks like
band
{
x
= 5
is not allowed.

Semicolons¶

For better readability, optional semicolons may be used to separate or terminate assignments.

Example 1

x=5; $y=6 ; z=[1,2];

However, placing semicolons at inappropriate places will result in a syntax error.

Example 2
Using a semicolon like
x = ; 5
is not allowed.

Variables¶

One can define variables and use them either to set some parameters or to evaluate other quantities for further use. Variable name always starts with a dollar sign ($) and is followed by a letter or underscore (_), and then by an arbitrary number of characters, numbers, or underscores.

Example 1
Script below contains 3 variable names
$a_43
$_BT
$_5c
which are a_43, _BT, and _5c.

Numbers and arrays¶

Variables can be defined to contain a number of an array of numbers. The numbers are of a double-precision floating-point format by default. If no rounding is needed then they get automatically converted to integers.

Example 1
In the script below
$x = 123
$y = 123.3
$z = 123.0
$zzz_ks = [12.3, 4]
$x, $z, and the last element of $zzz_ks are converted to integers. $y and the first element of $zzz_ks remain as doubles.

Variables always have a global scope. Therefore, they can be used everywhere after definition. The variables can be used for mathematical operations.

Example 2
Using variables for mathematical operation can look like
$y = sqrt($y)*$x
a = $zzz_ks
Attention

Element-wise mathematical operations between vectors or between scalars and vectors are not supported.

Strings¶

It is possible to define string variables, either by assigning a quoted string constant or unquoted string constant.

Example 1
Two string variables are defined in the script below.
$name = "some text"
$id = hello
While $name is defined with a quoted string constant, $id is defined with an unquoted string constant.
Attention

Similarly to variable names, unquoted string constants have to begin with a letter or an underscore. Also, they cannot contain white spaces. Quoted string constants does not have such limitations.

Note

While carriage returns are not allowed inside of string constants, they (and also comments) are allowed between quoted string constants to be concatenated.

Leading and trailing blanks are trimmed. Multiple string constants are automatically concatenated with blanks inserted in between them.

Example 2
Two quoted string constants
"aa b" "c"
and three unquoted string constants
aa b c
are automatically concatenated as
"aa b c"

To concatenate strings without inserted blanks, one can use + operator. All: string constants, string variables, double constants, and double variables can be concatenated with some string variable into a string.

Example 3
Concatenating multiple types of data into one string variable.
$id = hello
$id2 = "world"
$num = 3
$concat = $id + "_" + $id2 + $num + 5
As a result $concat contains "hello_world35".

Attention

Limitation: Quoted string constants can only be added using + from the right. Therefore, in an expression like for $concat, the leftmost term in a concatenation (here $id) have to be a variable.

Double values are rounded into the nearest integer first, before being concatenated to a string variable.

Hint

Use conversion function string(), if no such rounding is wanted.

Comments¶

One-line comment¶

One-line comments can be started with #. They always run until the end of the line.

Example 1
Line comments can begin anywhere in the line.
# This is a comment line.
x = 3.0   # This is a comment, too.

Multi-line comment¶

Mult-line comments can be defined using text blocks !TEXT !ENDTEXT.

Example 2
!TEXT
almost arbitrary content can come here
!ENDTEXT
Attention

Nesting text blocks is not allowed.

Conditional Statements¶

Conditional lines¶

Conditional lines allow enabling and disabling individual lines.

Example 1
If $x=0 then all three lines are ignored.
!WHEN $x    schottky{
!WHEN $x        name = air
!WHEN $x    }
The $x must be defined as a number, otherwise an error message will occur.

Note

In this example, the text is always commented out, unless $x is defined with value $x != 0.

Attention

No rounding or truncation is being performed here on $x so it has to be equivalent to 0.0 if defined as a double.
Warning

Conditional #IF and #if have been deprecated and are in the process of being removed. They should not be used for conditional lines.

Conditional blocks¶

Conditional blocks can be defined using !IF, !ELIF, ELSE, and ENDIF. They allow enabling and disabling entire blocks.

Note

Use of !ELSE and !ELIF is optional

Example 2

   !IF($x)
       name = air
       note = "Some text"
       !WHEN $y  note2 = "This is a nested conditional line."
   !ELIF($y)
       name = GaAs
   !ELIF($z)
       name = InAs
   !ELSE
       name = InGaAs
   !ENDIF

Here, variables also needs to be defined with non-zero values to be considered ``TRUE``.

Attention

Nesting conditional blocks is not allowed.

Data section¶

A data section can be defined using !DATA statement. As everything below the !DATA statement will be ignored by the parser, it is available only at the end of the input file.

The data section can be, however, used by some simulators (currently nextnano++) to define and/or run post-processing scripts of generated data.

Example 1
One can write anything in the data section like it is a comment.
!DATA

An arbitrary text starting from here
until the end of the file.
However, it is not advised to use it for making comments in the input files.

Operators and functions¶

Tables for number variables¶

The following functions and operators (sorted with decreasing precedence) are available for the use with number variables.

functions

description

sqrt()

square root $\sqrt{\text{ }}$

cbrt()

cubic root $\sqrt[3]{\text{ }}$

exp()

exponential function $\exp({\text{ }})$

log()

natural logarithm $\log$

ln()

natural logarithm $\ln$

log2()

decadic logarithm (base 2) $\log_{2}$

log10()

decadic logarithm (base 10) $\log_{10}$

sin()

sine $\sin({\text{ }})$

cos()

cosine $\cos({\text{ }})$

tan()

tangent $\tan({\text{ }})$

asin()

acrsine $\sin^{-1}({\text{ }})$

acos()

arccosine $\cos^{-1}({\text{ }})$

atan()

arctangent $\tan^{-1}({\text{ }})$

sinh()

hyperbolic sine $\sinh({\text{ }})$

cosh()

hyperbolic cosine $\cosh({\text{ }})$

tanh()

hyperbolic tangent $\tanh({\text{ }})$

asinh()

inverse hyperbolic sine $\sinh^{-1}({\text{ }})$

acosh()

inverse hyperbolic cosine $\cosh^{-1}({\text{ }})$

atanh()

inverse hyperbolic tangent $\tanh^{-1}({\text{ }})$

erf()

error function $\text{erf}({\text{ }})$

erfc()

complementary error function $\text{erfc}({\text{ }})$

gamma()

Gamma function $\Gamma({\text{ }})$

fdm3half()

complete Fermi–Dirac integral $F_{-3/2}({ })$ of order -3/2 (includes the $1/\Gamma(-1/2)$ prefactor)

fdmhalf()

complete Fermi–Dirac integral $F_{-1/2}({ })$ of order -1/2 (includes the $1/\Gamma(1/2)$ prefactor)

fdzero()

complete Fermi–Dirac integral $F_{0}({ })$ of order 0 (includes the $1/\Gamma(1)=1$ prefactor)

fdphalf()

complete Fermi–Dirac integral $F_{1/2}({ })$ of order 1/2 (includes the $1/\Gamma(3/2)$ prefactor)

fdp3half()

complete Fermi–Dirac integral $F_{3/2}({ })$ of order 3/2 (includes the $1/\Gamma(5/2)$ prefactor)

abs()

absolute value $|{\text{ }}|$

floor()

floor function floor(x): largest integer $\le x$

ceil()

ceiling function ceil(x): smallest integer $\ge x$

round()

rounds the number to the nearest integer

sign()

sign function

heaviside()

Heaviside step function (corresponds to isnotnegative())

ispositive()

returns 1 if value is positive and 0 otherwise

isnegative()

returns 1 if value is negative and 0 otherwise

iszero()

returns 1 if value is zero and 0 otherwise

isnotpositive()

returns 1 if value is not positive and 0 otherwise

isnotnegative()

returns 1 if value is not negative and 0 otherwise (corresponds to heaviside())

isnotzero()

returns 1 if value is not zero and 0 otherwise

string()

converts the argument into a string

operators

symbol

comment

round arithmetic brackets

( )

power (exponentiation)

^

right associative

unary minus and unary plus

- +

right associative

arithmetic multiplication, division, remainder

* / %

remainder is modulo

arithmetic plus and minus

+ -

arithmetic comparisons

< <= >= >

less than, less than or equal, …

arithmetic comparisons

== !=

equal, not equal

logical NOT

~

right associative

logical AND

&&

logical OR

||

Arithmetic comparisons and logical operators¶

You have to define separate variable beforehand if you want to use any for conditional statements. The logical operators, conditional blocks, and conditional comments consider any nonzero number as true, and zero as false.

Example 1
$a = 3
$b = 1
$c = $a > $b
!WHEN $c ...
The conditional line will be executed as $c equals 1.
Example 2
$a = 3
$c = $a > 5
!WHEN $c ...
The conditional line will not be executed as $c equals 0.
Example 3
$a = 1
$c = $a && 0
!WHEN $c ...
The conditional line will not be executed as $c equals 0.
Attention

While the results of all comparison operators and logical operators are 1 and 0 as well, this may change in the future releases.

Attention

One should be careful when comparing the results of floating point computations, e.g., (1/3)*3 has the value 0.99999999… not 1.0, and use round() if necessary.

Dealing with floating-point numbers¶

Use round() if necessary when calling operators of arithmetic comparison on floating-point numbers to avoid errors.

Example 1
$a = (1/3)*3
$c = $a && 1
!WHEN $c ...
The conditional line will not be executed as $a has the value 0.99999999... not 1.0 ``, therefore, ``$c equals 0.

The function string() converts the argument into a string, which can be used to obtain a string representation of a floating point variable. This string representation may differ for different computer architectures, operating systems, and software releases.

Functions for array variables¶

Array variables can be subscripted using round brackets (). If the array subscript is out of range, a run-time error will occur.

Example 1

$vector = [1, 3, 5, 7]
$element = $vector(2)

$element equals 3

Example 2

$vector = [1, 3, 5, 7]
$element = $vector(5)

Run-time error occurs.

In addition, for the use with array variables, the following function is available:

Dimension of an array variable can be obtained using function dim().

Example 3

$vector = [1, 3, 5, 7]
$size = dim($vector)

$size equals 4

Debug statements¶

Next, there are also a couple of debug statements available, that can be used at any (reasonable) point inside an input file or validation file:

!VARS    # prints all variables with their values into the standard output
!TABLE   # prints the entire symbol table into the standard output

Example:

--- Variables at line 14 -------------
$QW_WIDTH = 6
$QW_SEPERATION = 4
$QW_min = 20
$QW_max = 26
--------------------------------------

But note that result of these debug statements obviously depends on their location in the file. Additionally, all variables and their values that are used in a simulation are written to the output folder into a file called

variables_input.txt (for variables used in the input file)
variables_database.txt (for variables used in the database file)

Groups and attributes¶

Next, we define groups and attributes. Their name follows (except for the leading dollar symbol $) the same convention as variable names. Validation files may also contain groupnames starting with a question mark ?. We have here the following syntax:

groupname{
   attribute1 = value1
   group2{
      attribute1 = value2  # Each group has its own scope !!
      ....
   }
   group2{                 # groups with the same name and content may repeat
      ....
   }
   attribute2 = value2     # but attributes are unique.
}                          # the group groupname ends here

Note that the order of groups is relevant in some cases, but the order of the attributes in a group is always ignored. Also note that groups may be empty as:

emptygroup{}

The curly brackets {} belonging to each group are checked for correctness.

There exist different types of attributes. Allowed are

real numbers
x = 12.121
integers
i = 12
vectors of real numbers
xV = [12.3e-4, 2, 3, sqrt(54.12)+2.1]
vectors of integers
iV = [1, 2]

strings

c="ohohi-oh ./opij "  # But many exotic characters are not allowed!

choices and

color = red           # Pick one from a set of tokens

enumerations

food = "juice bread dessert"  # Pick subset from a set of tokens

Attributes may also (like variables) be initialized with values of variables or the results of computations. But note that unlike variables, attributes may neither be redefined nor be used in mathematical expressions.

XML Tags¶

In addition, it is possible to add tags to explicitly check the current scope. For example,

groupname{
   ...
   <groupname>
   ...
}

or

groupname{
   ...
<groupname>}

will have no effect, while

groupname{
   ...
<differentgroupname> }

will cause an error message, since the assumed scope and the actual scope do not match.

Input files may also be decorated at the root level (i.e. outside of any group) with XML tags such as

<id>
</id>

or also:

<id/>

Here, id follows (except for the leading dollar symbol) the same convention as variable names. For backwards compatibility, in addition, also the empty (non-XML) tag <> is still available to e.g. check root level group closure. Please note that, whereas the simulator completely ignores the content of XML tags, they may have special meaning for calling programs such as nextnanomat and thus should not be altered without understanding their use. Practically, this means that, outside of groups, you may decorate input files/templates or also databases with XML tags in any way you wish. Just make sure to comment out stuff to be ignored by nextnano++ with double comments ## (to avoid possible collisions with conditional ifs) in order to add things such as:

<description>
##
## any stuff you want, e.g. rich text, nextnano++ will happily ignore it
##
</description>
<variables> $mass = 0.067 <unit># m_0</unit> </variables>

At the root level, one can use the empty tag

<>

to check for the root scope. This is optional and not required. Tags with these brackets <...> are ignored by the parser and can be used to provide additional meta data. That is, everything right (or left) of such symbols is executed normally, as if there was just a ; (optional separator) instead of each tag.

Example:

<tag/>

It might look like an XML tag but it is much simpler. Nesting and matching tags are not checked. No blanks or special characters except underscores _ may be used within tags <...>.

Additional Examples and Remarks¶

E.g. you can define:

$pi = 4 * atan(1)

This will give 3.1415926535897932384626433832795029. You can also specify:

$pi = 3.1415926535897932384626433832795029

Variable evaluation occurs already during parsing of the input/database file and thus before the beginning of the actual simulation. The input file after variable evaluation and the database file after the variable evaluation and possible modification by database{ } in the input file (which are the real inputs of the simulation) are written into files

simulation_input.txt and
simulation_database.txt.

In case of problems, or when many variables are used, it is highly recommended to review the file simulation_input.txt for possible mistakes. Similarly, simulation_database.txt will tell you (and our customer support) which values of material parameters were actually used for the simulation.

Further remarks: Except within comments, input files are strictly 7-bit ASCII. That is, no umlauts, diacritics, etc. in strings, names, etc. This is an inherent limitation of the parser. Command line parameters, file paths, and file names may contain all characters except \ / ? * ^ & ' ` < > : " and control characters (e.g. newlines). Unfortunately, e.g. on (US localized) windows, file names or file paths containing characters outside of code page 1252 (https://en.wikipedia.org/wiki/Windows-1252) may not be found or properly processed. Similar issues also may arise for other Windows localizations or for other operating systems. In order to avoid such problems, please make to sure to avoid characters outside of code page 1252 for all file names and file paths.