Macro features¶
The Macro feature of nextnano³ is also described here: https://github.com/nextnano/FortranInputParser. The Fortran Input Parser source code is open-source.
- Comment signs
Everything in the same line following after such a symbol is treated as a comment.
#
Note: This is the same comment sign as used in nextnano++.
!
//
/*
This is a comment.
*/
The end tag
*/
is optional.Note: No line breaks are allowed for the comments
/*
...
*/
.<
This is a comment.
>
Note
However, the following are exceptions and are treated differently.
#IF
!IF
#WHEN
!WHEN
These are special statements for conditional lines (see below).
Note
XML tags can be used in the input file, .e.g. to provide additional meta information. They are ignored by nextnano³ but could be used in e.g. nextnanomat. Everything that is between these brackets
<
...
>
is replaced with blanks. This can be used to define XML tags such as:<variables> # comment %TEMPERATURE = 300.0 # (DisplayUnit:K) %WIDTH = 10.0 # (DisplayUnit:nm) %HEIGHT = 20.0 < unit = "nm" > # (DisplayUnit:nm) </variables> <variables> %TEMPERATURE = 300.0 </variables> # (DisplayUnit:K)
Macro 1: Variables¶
The %
symbol is used to define a variable such as %VARIABLE =
that should be replaced with another string or value.
Variables are case-sensitive.
A variable is only defined and initialized if the first character in a line starts with the %
symbol.
This macro distinguishes between strings (default), i.e. simple string replacements where 1
and 1.0
are treated as a string) and
functions (i.e. arithmetic operations if %FunctionParser = yes
)
where both 1
or 1.0
are treated as a real number.
Both can be combined but it is important to understand the differences to avoid errors.
For instance, for some specifiers, the input parser expects an integer number and not a real number.
So real numbers have to be converted back to integers in some cases.
This macro is supported by nextnanomat.
String feature¶
Find & Replace of variables
Example: %WIDTH = 10.0
The nextnano³ tool supports a simple Find & Replace feature where strings in the input file can be replaced with another string.
- How to use it
Just put something like the following lines anywhere into your input file. We recommend that you put it at the beginning of the input file for better readability.
#---------------------------------------------------------------- # By default, we do not evaluate functions. # Everything is just a simple "Find & Replace String" operation. #---------------------------------------------------------------- %width = 10.0 # quantum well width (DisplayUnit:nm) %length = 10 # quantum well length (DisplayUnit:nm) %size = 10.0 # quantum well size (DisplayUnit:nm) %z_coordinates = -21.0 101.0 # from z = -21 to z = 101 (DisplayUnit:nm) %well_material = GaAs # quantum well material: GaAs %barrier_material = "AlAs" # quantum barrier material: AlAs %zmin = -10.0 # zmin = - 10 nm (DisplayUnit:nm) %zmax = 10.0 # zmax = 10 nm (DisplayUnit:nm) # derived variable: quantum_region = zmin zmax = -10.0 10.0 %quantum_region = %zmin %zmax # (DisplayUnit:nm) %hkl_z_direction = 0 1 1 # [0 1 1] growth direction # The whole string including blanks after the first '=' sign is used. %Region1 = region-number = 1 base-geometry = line region-priority = 1
The %
sign indicates that you define a variable.
When the input file is processed, all occurences of %width
, %z-coordinates
, %well_material
, … are replaced by the according strings.
A comment sign (e.g. #
, !
) is allowed in this line.
Blanks are allowed within the string which is useful for reading in arrays of numbers.
Almost everything is allowed.
- Restrictions
The variables and their definitions are case-sensitive.
A variable name must not contain a
-
sign, e.g.%cb-mass = 0.067 # (DisplayUnit:m0)
is not allowed. Use underscores
_
instead.In one line, only one variable can be initialized.
Function feature¶
Find, Evaluate & Replace
Example: %WIDTH = %LENGTH / 2.0
The statement %FunctionParser = yes
switches the function parser on (default: off).
The following operators
round arithmetic brackets |
|
power (exponentiation) |
|
arithmetic multiplication, division |
|
arithmetic plus and minus |
|
and functions are supported:
|
square root \(\sqrt{\text{ }}\) |
|
exponential function \(\exp({\text{ }})\) |
|
natural logarithm \(\log\) |
|
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{ }})\) |
|
absolute value \(|{\text{ }}|\) |
Example
#------------------------------------------------------------------------- # If '%FunctionParser = yes', then from now on we evaluate all functions. # If '%FunctionParser = no' (or not present), no functions are evaluated. # "Find & Evaluate & Replace String" operation. #------------------------------------------------------------------------- %FunctionParser = yes # This is an important line! %a = 4.0 # a = 4.0 %b = 3 # b = 3 %function1 = SQRT(%a) - %b / 2 # Evaluate: sqrt(a) - b / 2 = 2.0 - 1.5 = 0.5 ... %xalloy = %function1 # Insert evaluated value for %function1. # Strings containing blanks are also possible. # They must be in quotation marks "" or apostrophes ''. %string1 = "GaAs" %string2 = "GaAs" %string3 = "zero-potential = yes" # Logical variables that are .TRUE. or .FALSE. can be defined # and used in conditional #IF statements. %Logical1 = .TRUE. %Logical2 = .FALSE.
We have to be careful about the value of a variable.
Should it be regarded as a string (default),
or as a function (%FunctionParser = yes
)?
#---------------------------------------------------------------------------- # Treat variables as strings (default): # ------------------------------------- # e.g. %variable1 = %zmin %zmax # '%zmin %zmax' is treated as a string # %variable2 = 2.5e0 # '2.5e0' is treated as a string # %variable3 = 2.5 # '2.5' is treated as a string without exponent 'e0' #---------------------------------------------------------------------------- #%radius = 5e0 # quantum dot radius = 5 nm (DisplayUnit:nm) %grid_spacing = 0.5 # grid spacing (DisplayUnit:nm) #---------------------------------------------------------------------------- # From now on, evaluate all functions: # ------------------------------------ # e.g. %variable1 = %zmin %zmax # '%zmin %zmax' is treated as a formula # # (which will produce an error in this case) # %variable2 = 2.5 # '2.5' is converted to a real number including exponent 'e0' #---------------------------------------------------------------------------- %FunctionParser = yes # use function parser %radius = 5 # quantum dot radius = 5 nm (DisplayUnit:nm) %boundary = %radius + 1 # device_width/2 = 5 nm + 1 nm (DisplayUnit:nm)
- Special treatment of integers
The parser distinguishes between integers and real numbers. Thus we have to be careful when using functions. This means that we have to convert the real values back to integers. Integers will be rounded down up
>= .5
or rounded down if< .5
, i.e. they will be rounded to the nearest integer.Option a) (recommended)
#---------------------------------------------- # If you need an integer, then use INT(...). # %nodes contains an integer value. #---------------------------------------------- %nodes = INT( %width / %grid_spacing - 1 )
Option b) (deprecated)
#---------------------------------------------- # If you need an integer, then simply call the # variable '%INT(<name>)' # %INT(nodes) contains an integer value. #---------------------------------------------- %INT(nodes) = %width / %grid_spacing - 1
Option c) (deprecated)
#---------------------------------------------- # If you need an integer, then simply call the # variable '%INT(<name>)' # %nodes is real number. # %INT(nodes) contains an integer value. #---------------------------------------------- %nodes = %width / %grid_spacing - 1 %INT(nodes) = %nodes
Integer numbers can be defined using quotation marks
"`´ ``"
orINT()
:%NumberOfEigenvalues = "10" # 10 eigenvalues %NumberOfEigenvalues = INT(10) # 10 eigenvalues
Integer arrays can be defined using quotation marks
"`´ ``"
:%hkl_z_direction = "0 1 1" # [0 1 1] growth direction
conditional lines¶
#IF
, !IF
, #WHEN
or !WHEN
statements can also be used to define conditional lines,
i.e. variables can be used to define conditional lines.
#IF
, !IF
, #WHEN
or !WHEN
are not case-sensitive, i.e.
#if
, !if
, #when
or !when
also work.
#IF %TemperatureDependentBandGap varshni-parameters-on = yes
Such a statement has the following meaning:
If the value of
%TemperatureDependentBandGap
is either.TRUE.
or1
or any other nonzero value, then the statement is included in the input file.If the value of
%TemperatureDependentBandGap
is either.FALSE.
or0
or undefined, then the statement is simply ignored as if it were a comment.
In this example, the text is always commented out, unless %IncludeHoles
is defined with a value %IncludeHoles
/= 0
or /= .FALSE.
.
%IncludeHoles = .TRUE. # or %IncludeHoles = 1 !IF %IncludeHoles $quantum-model-holes !IF %IncludeHoles model-number = 1 !IF %IncludeHoles model-name = effective-mass !IF %IncludeHoles cluster-numbers = 1 !IF %IncludeHoles valence-band-numbers = 1 2 3 !IF %IncludeHoles number-of-eigenvalues-per-band = 10 !IF %IncludeHoles $end_quantum-model-holes
In the following, the evaluated value of %IncludeElectrons
is 0
,
therefore the three lines starting with !IF %IncludeElectrons
are treated as comments.
%IncludeHoles = 1 %IncludeElectrons = 1 - %IncludeHoles # evaluated to: 1 - 1 = 0 !IF %IncludeElectrons $quantum-model-electrons # treated as comment !IF %IncludeElectrons model-number = 1 # treated as comment !IF %IncludeElectrons ... # treated as comment
If the variable definition
%IncludeHoles = .TRUE.
appears after the line
%FunctionParser = yes
quotation marks "
or apostrophes '
must be used for the logical strings .TRUE.
/.FALSE.
to indicate that they have to be treated as strings:
%IncludeHoles = ".TRUE." # or %IncludeHoles = '.TRUE.'
Variable replacement
Once the input file has been processed, the input file (
*.in
) is copied to the output folder. Additionally, this output folder contains a file called*.in.mo_macro
which contains the input file with all variables having been replaced with their values.All variables and their values that are used in a simulation are written to the output folder into a file called
variables_input.txt
.
Macro 2: Namelist (deprecated)¶
Alternatively, namelists are supported for macros.
The input syntax for this macro is implemented as a NAMELIST
which is a standard Fortran feature.
The nextnano³ tool supports a simple Find & Replace feature where strings in the input file can be replaced with another string. The first lines of the input file can contain the following additional entries.
¯o filename = 'macro.in' /
Here, macro.in
is an ASCII file containing the following content:
¯o Find_and_Replace_1 = '$WIDTH' ,'0d0 10.0d0' Find_and_Replace_2 = 'x-nodes = 9','x-nodes = 29' Find_and_Replace_3 = 'GaAs' ,'InP' /
These three lines have the following meaning:
Find
$WIDTH
and replace it with0d0 10.0d0
.Find
x-nodes = 9
and replace it withx-nodes = 29
.Find
GaAs
and replace it withInP
.
Dowload example file: macro.in
Example 1
!***************************************************************************! ! Macro: 'Find & Replace' !***************************************************************************! ! ! A macro can be used to simply search for a specific string and to replace ! it with another string. ! ! Example: Replace the material 'GaAs' with 'InAs'. ! material-name = GaAs ! ==> material-name = InAs ! ! Replace the quantum well width '$WIDTH' with '10d0': ! x-coordinates = -$WIDTH $WIDTH ! ==> x-coordinates = -10d0 10d0 ! ! Replace the string '2*$WIDTH' with '20d0': ! (Mathematical operations are not supported yet. They are treated as strings.) ! x-coordinates = 0d0 2*$WIDTH ! ==> x-coordinates = 0d0 20d0 ! ! Replace the string '$WIDTH+$SIZE' with '30d0': ! (Mathematical operations are not supported yet. They are treated as strings.) ! x-coordinates = 0d0 $WIDTH+$SIZE ! ==> x-coordinates = 0d0 30d0 ! ! Replace the quantum well width '$WIDTH' with '0d0 10d0': ! x-coordinates = $WIDTH ! ==> x-coordinates = 0d0 10d0 ! ! Simulate along x, y or z direction: ! Find_and_Replace_1 = '$DIRECTION' ,'x' ! simulation along x direction ! Find_and_Replace_2 = '$DOMAINTYPE','1 0 0' ! simulation along x direction ! ! Find_and_Replace_1 = '$DIRECTION' ,'y' ! simulation along y direction ! Find_and_Replace_2 = '$DOMAINTYPE','0 1 0' ! simulation along y direction ! ! a) The macro can be defined in the input file: filename = '' (or) ! b) The macro can be read in from another file: filename = 'macro.in' ! !---------------------------------------------------------------------------! ¯o filename = 'macro.in' ! (optional) macro file to be read in, use '' for no macro input file Find_and_Replace_1 = '$WIDTH' ,'0d0 10.0d0' ! is ignored if macro file is read in Find_and_Replace_2 = 'x-nodes = 9','x-nodes = 29' ! is ignored if macro file is read in Find_and_Replace_3 = 'GaAs' ,'InP' ! is ignored if macro file is read in /
Example 2
¯o filename = '' ! (optional) macro file to be read in, use '' for no macro input file Find_and_Replace_1 = '$WIDTH' ,'0d0 10.0d0' ! find string, replace string Find_and_Replace_2 = 'x-nodes = 9','x-nodes = 29' ! find string, replace string Find_and_Replace_3 = 'GaAs' ,'InP' ! find string, replace string /
Example 3
¯o Find_and_Replace_1 = '$WIDTH' ,'0d0 10.0d0' ! find string, replace string Find_and_Replace_2 = 'x-nodes = 9','x-nodes = 29' ! find string, replace string Find_and_Replace_3 = 'GaAs' ,'InP' ! find string, replace string ... Find_and_Replace_40 = 'GaAs' ,'InP' ! find string, replace string /
Currently up to 40 Find & Replace definitions can be specified.