2.6.1. Syntax definition¶
Documentation of input file syntax, use of variables and parser validation syntax.
Syntax validation¶
How to use validation and validation files
The syntax is listed in the files input.val
and database.val
that are located in the Syntax/
folder.
In fact, this is obsolete. These files are no longer distributed to the customer. The contents of these files are now contained inside the source code.
If one starts nextnano++ with the argument p
, i.e. nextnano++.exe p
, then the syntax definition files input_syntax.txt
and database_syntax.txt
are written out.
They are not needed. They have just informative character to display available input file syntax to the user.
As we have seen, the syntax of input files and validation files is except for some details mostly identical. As in content format languages such as XML or HTML, an almost unlimited hierarchy of objects is possible, as long as the resulting file is wellformed (means conforms with the syntax). But of course we would like now to impose constraints on what can be in an input file. This is easily done with a validation file. If desired, every input file can validated with respect to the constraints of any validation file. In this section, we describe the format used to define such constraints.
We start out with the definition of attributes. Here are some examples:
x1{ TYPE=real } x2{ TYPE=real MIN=0 } x3{ TYPE=real MIN=0 MAX=1.2 OPT="" } x4{ TYPE=real NOTZERO="" }
Thus, x1
, x2
, x3
, and x4
are attributes of the type real number.
x2
has also a mandatory minimum value defined, x3
has also a mandatory minimum value, and x4
must not be zero.
Furthermore, x3
is an optional attribute that may be omitted, while x1
, x2
, and x4
are mandatory.
Also note that as usual the order of the modifiers in the curly brackets {}
is ignored.
Similary, we have for integers:
i1{ TYPE=int } i2{ TYPE=int MIN=0 } i3{ TYPE=int MIN=0 MAX=2 OPT="" }
Vectors of real numbers can be defined as:
v1{ TYPE=vector } v2{ TYPE=vector DIM=3 } v3{ TYPE=vector MINDIM=2 MAXDIM=3 } v4{ TYPE=vector MINDIM=2 MODDIM=3 OPT="" }
Here, the modifier DIM
states an explicit dimensionality of the vector,
MINDIM
and MAXDIM
an explicit minimum and maximum dimensionality,
and MODDIM=3
requires that the dimension of the vector can be divided by 3
.
Similarly, the correponding definition for integer vectors are:
iv1{ TYPE=intvector } iv2{ TYPE=intvector DIM=3 } iv3{ TYPE=intvector MINDIM=2 MAXDIM=3 } iv4{ TYPE=intvector MINDIM=2 MODDIM=3 OPT="" }
Note that MIN
and MAX
can also applied to check the elements of vectors.
In this case, the same bounds apply to all elements of a vector.
When validating vectors or intvectors, numerical variable values are automatically
converted, therefore no extra brackets as [123]
are needed for onedimensional objects.
Next, strings are defined as
path{ TYPE=string } name{ TYPE=name_string } function{ TYPE=function_string }
and choices as
enable{ TYPE=choice VAL="yes no"} boundary{ TYPE=choice VAL="dirichlet neumann periodic" OPT=""}
Finally, enumerations are defined as
color{ TYPE=enum VAL="white black red green blue"}
When validating strings, choices, or enums, numerical variable values are automatically converted into strings,
therefore no extra quotes as "123"
are needed.
Note that string
, name_string
, and function_string
are essentially identical, execpt that
string
and name_string
forbid some characters such as >
which could conflict with file I/O,
and that name_string
further requires some of the characters azAZ_
.
Each attribute definition must be defined inside of a group definition as
shape_cuboid{ TYPE=group OPT="" x{ TYPE=vector DIM=2} y{ TYPE=vector DIM=2} z{ TYPE=vector DIM=2} }
An empty group is defined using a group definition that does not contain any attribute definitions, while a group definition inside another group definition indicates that the one group is supposed to contain the other group.
Of course, there are special modifiers for group definitions as well. Here we have available
groupname1{ TYPE=group ITEMS=3 ... } groupname1{ TYPE=group MINITEMS=5 MODITEMS=4 ... } groupname{ TYPE=group MAXITEMS=3 OPT="" ... }
Here, ITEMS=3
means that the group needs to be defined 3 times in the current scope,
while MINITEMS=5
, MODITEMS=4
, and MAXITEMS=3
have the expected meanings.
Note that the use of MINITEMS
or ITEMS
together with OPT
may lead to constraints that cannot be fullfilled.
In addition, it also possible to specify dependencies between groups. Here is an example:
groupname{ TYPE=group ?ONE{ TARGETS="x1 x2 x3" } ... x1{TYPE=group OPT="" MAXITEMS=3 } x2{TYPE=group OPT="" MAXITEMS=3 } x3{TYPE=group OPT="" MAXITEMS=5 } ... }
This means, that in the group groupname
exactly one of the three children groups x1
, x2
, and x3
must be present.
At the same time, if x3
is present, it may occur up to 5
times.
Similary,
groupname{ TYPE=group ?SOME{ TARGETS="x1 x2 x3" } ... x1{TYPE=group OPT="" MAXITEMS=3 } x2{TYPE=group OPT="" MAXITEMS=3 } x3{TYPE=group OPT="" MAXITEMS=5 } ... }
means, that at least some (even all but not none) of the children groups x1
, x2
, x3
must be present in the current scope.
Finally, by writing
groupname{ TYPE=group ?MAXONE{ TARGETS="x1 x2 x3" } ... x1{TYPE=group OPT="" MAXITEMS=3 } x2{TYPE=group OPT="" MAXITEMS=3 } x3{TYPE=group OPT="" MAXITEMS=5 } ... }
we can guarantee that atmost one of the children groups x1
, x2
, x3
is present in the current scope.
Finally, using
groupname{ TYPE=group ?NONE{ TARGETS="x1 x2 x3" } ... x1{TYPE=group OPT="" MAXITEMS=3 } x2{TYPE=group OPT="" MAXITEMS=3 } x3{TYPE=group OPT="" MAXITEMS=5 } ... }
we can enforce that none of the children groups x1
, x2
, x3
are present.
This feature is only useful for inherited groups.
Similarly, the conditions ?TWO
, ?THREE
, ?MAXTWO
, ?MAXTHREE
, ?COND_TWO
, ?COND_THREE
,
?COND_MAXTWO
, ?COND_MAXTHREE
can be used to check for 2
or 3
occurences.
In addition, it is also possible to define conditional dependencies as
groupname{ TYPE=group ?COND_SOME{ COND="n" TARGETS="x1 x2 x3" } ... n{TYPE=group OPT="" MAXITEMS=5 } ... x1{TYPE=group OPT="" MAXITEMS=3 } x2{TYPE=group OPT="" MAXITEMS=3 } x3{TYPE=group OPT="" MAXITEMS=5 } ... }
which that if group n
is present in the current scope, then at least some of the children groups x1
, x2
, x3
must also be present in the current scope.
Similarly,
?COND_NONE{ COND="n" TARGETS="x1 x2 x3" } ?COND_ONE{ COND="n" TARGETS="x1 x2 x3" } ?COND_MAXONE{ COND="n" TARGETS="x1 x2 x3" } ?COND_SOME{ COND="n" TARGETS="x1 x2 x3" } ?COND_ALL{ COND="n" TARGETS="x1 x2 x3" }
have the expected meaning as well.
Finally we also have the following tests
?EXISTS{ TARGET="global/parameters/simulate3D" } ?EXISTS_NOT{ TARGET="global/parameters/simulate3D" }
for the presence or absence of an object.
As the last examples show, both the TARGET
attribute as well as the COND
attribute
may also contain a path to the element in question, as for example:
?COND_ALL{ COND="/global/parameters/simulate3D" TARGETS="x1 x2 x3" }
Here, a path beginning with a slash /
is an absolute path that is searched from the root level.
Warning
Paths in COND
and TARGET
do not result into an exhaustive search of the symbol table yet!
Variables: Operators and functions¶
For the use with number variables, the following operators (sorted with decreasing precedence) and functions are available in the parser:
Operators
The following operators (sorted with decreasing precedence) are supported.
round arithmetic brackets 


power (exponentiation) 

right associative 
unary minus and unary plus 

right associative 
arithmetic multiplication, division, remainder 

remainder = modulo 
arithmetic plus and minus 


arithmetic comparisons 

less than, less than or equal, … 
arithmetic comparisons 

equal, not equal 
Note that you have to define a separate variable beforehand if you want to use these operators in conditional statements. For instance, arithmetic comparison works as
$a = 3 $b = 1 $greater = $a > $b #IF $greater ...
Functions
Following functions (sorted with decreasing precedence) are supported:

square root \(\sqrt{\text{ }}\) 

cubic root \(\sqrt[3]{\text{ }}\) 

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

natural logarithm \(\log\) 

natural logarithm \(\ln\) 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

absolute value \({\text{ }}\) 

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

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

rounds the number to the nearest integer 

sign function 

Heaviside step function (corresponds to 

check if value is positive 

check if value is negative 

check if value is zero 

check if value is not positive 

check if value is not negative (corresponds to 

check if value is not zero 

converts the argument into a string 
Here, the results of the comparison operators and of the comparison functions ispositive()
, …, isnotzero()
are either 1
for TRUE
or 0
for FALSE
.
Please be careful when comparing the results of floating point computations und use round()
if necessary, since e.g. (1/3)*3
has the value 0.99999999...
and not 1.0
.
Also please note that while conditional comments and conditional blocks consider any nonzero number as true,
the use of positive numbers for TRUE
is preferred, since then the arithmetic operators +
and *
can be used in conjunction with the comparison functions to implement logical expressions.
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.
Array variables
Array variables can be subscripted using round brackets as (base 1):
$element7 = $vector(7)
If the array subscript is out of range, a runtime error will occur.
In addition, for the use with array variables, the following function is available:
dim()
All variables are removed from the final symbol table.
 Further remarks
Except within comments, input files are strictly 7bit 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/Windows1252) 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.
Advanced syntax documentation for validation files¶
only for developers
Validation files also offer the feature of parserlevel group inheritance. Suppose, we have defined a group structure:
something{ TYPE=group section_base{ TYPE=group ITEMS=0 OPT=1 x{ TYPE=real OPT=1 } y{ TYPE=real OPT=1 } z{ TYPE=real OPT=1 } another_group{ TYPE=group # more stuff in here } section : section_base{ TYPE=group OPT=1 w{ TYPE=real OPT=1} } }
In this case, the group section
is inherited from the group section_base
.
Inheritance means here the following procedure:
Since the file is parsed once from the top to the bottom, first the group
section_base
is generated in the symboltable of the validation file. Note that whilesection_base
is abstract here (it may not occur), there is no need for a base group to abstract.Once the group
section
is encountered, it is constructed by deep copying all (parserlevel) subgroups ofsection_base
(thusx
,y
,z
,another_group
with all their content) and calling itsection
.Only afterwards the content of section itself (in this case is
w
) will be added.
Obviously, the following rules and restrictions to inheritence then apply:
Base group and derived group must both reside in the same group or both at root level.
Inheritance occurs in the parser, not in the validator. Thus, from a purely technical point it is also possible to inherit off group
x{}
in the example above, with the derived group having a differentTYPE
(evenTYPE=GROUP
). But since all parseritems of the base group likeTYPE
orITEMS
are not copied, any such operation is useless for constructing a validation file and not recommended.For the same reason, deriving from a
TYPE=GROUP
into a differentTYPE
is not useful either.Next, since derivation does not copy
ITEMS
,OPT
,MINVAL
,… definitions of the base group, they must be defined in all derived groups as well.Finally, any derived group may as well be base group for other inherited groups. However, selfinheritance or inheritance from a group not encountered yet during parsing is not possible.