2.6. Input Syntax

Note

this site is under reconstruction

Syntax if input files for nextnano++, nextnano.MSB (incl. in nextnano++), and nextnano.NEGF are 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.