3.2.1. 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 the nextnano++ software.

• !

• //

• /* 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 the nextnanomat GUI.

String feature

Find & Replace of variables

Example: %WIDTH = 10.0

nextnano³ 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:

sqrt()	square root \(\sqrt{\text{ }}\)
exp()	exponential function \(\exp({\text{ }})\)
log()	natural logarithm \(\log\)
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{ }})\)
abs()	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 "`´ ``" or INT():

%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. or 1 or any other nonzero value, then the statement is included in the input file.

• If the value of %TemperatureDependentBandGap is either .FALSE. or 0 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.

nextnano³ 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.

&macro filename = 'macro.in' /

Here, macro.in is an ASCII file containing the following content:

&macro  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 with 0d0 10.0d0.

• Find x-nodes = 9 and replace it with x-nodes = 29.

• Find GaAs and replace it with InP.

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'
!
!---------------------------------------------------------------------------!
&macro  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

&macro  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

&macro  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.