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 TEXTthere 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 = 5is 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 = ; 5is 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 $_5cwhich 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_ksAttention
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 = helloWhile
$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 care 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 + 5As 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.
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 to0.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 and0
otherwise
isnegative()
returns
1
if value is negative and0
otherwise
iszero()
returns
1
if value is zero and0
otherwise
isnotpositive()
returns
1
if value is not positive and0
otherwise
isnotnegative()
returns
1
if value is not negative and0
otherwise (corresponds toheaviside()
)
isnotzero()
returns
1
if value is not zero and0
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
equals1
.- Example 2
$a = 3 $c = $a > 5 !WHEN $c ...The conditional line will not be executed as
$c
equals0
.- Example 3
$a = 1 $c = $a && 0 !WHEN $c ...The conditional line will not be executed as
$c
equals0
.Attention
While the results of all comparison operators and logical operators are
1
and0
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 value0.99999999...
not1.0 ``, therefore, ``$c
equals0
.
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
equals3
- 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
equals4
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.
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
andsimulation_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.
Comments¶
One-line comment¶
One-line comments can be started with
#
. They always run until the end of the line.Multi-line comment¶
Mult-line comments can be defined using text blocks
!TEXT
!ENDTEXT
.