2.6.6. grid{ }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • items: \(\mathrm{exactly\;1}\)

Specifications of the non-uniform rectangular grid lines.

Important

The following general conditions must be satisfied when defining grid{ }

Maintained Keywords

The keywords below are available in at least one of currently published releases and are not planned to change in the nearest future.

xgrid{ }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • items: \(\mathrm{maximum\;1}\)

This group is used to define simulation space grid along the \(x\)-axis.

xgrid{ min_pos }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • type: \(\mathrm{real\;number}\)

  • values: \(\mathrm{no\;constraints}\)

  • unit: \(\mathrm{nm}\)

Definition of the smallest, possible \(x\)-coordinate of the simulation domain. Grid lines specified with smaller x-coordinates are ignored.

xgrid{ max_pos }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • type: \(\mathrm{real\;number}\)

  • values: \(\mathrm{no\;constraints}\)

  • unit: \(\mathrm{nm}\)

Definition of the largest, possible x-coordinate of the simulation domain. Grid lines specified with larger \(x\)-coordinates are ignored.

xgrid{ allow_spacing_jumps }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • type: \(\mathrm{choice}\)

  • values: \(\mathrm{yes\;/\;no}\)

  • default: \(\mathrm{no}\)

If set to yes, then it is possible to assign two different grid spacing values to the same grid line, which creates a jump in the grid spacing.

xgrid{ line{ } }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • items: \(\mathrm{minimum\;2}\)

Group defining a grid lines. As the lines define the total size of the device, at least two of them have to be present for each simulation direction.

Important

The following general conditions must be satisfied when defining xgrid{ line{ } }

xgrid{ line{ pos } }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • type: \(\mathrm{real\;number}\)

  • values: \(\mathrm{no\;constraints}\)

  • unit: \(\mathrm{nm}\)

Position of the line.

Hint

A good practice is to define lines on all interfaces in the device to provide the geometry definition possibly independent to the choice of the spacing.

xgrid{ line{ spacing } }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • type: \(\mathrm{real\;number}\)

  • values: \([10^{-3}, \ldots)\)

  • unit: \(\mathrm{nm}\)

A grid spacing in the vicinity of the position of the line.

xgrid{ line{ repeat{ } } }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • items: \(\mathrm{maximum\;1}\)

This group is used to repeat a single grid line multiple times at equidistant positions. The grid lines are placed according to the following equation:

\(x_m=\) pos \(+\) shift \(\times m\),

where \(\;m=-\) minus_num , …, num-1

xgrid{ line{ repeat{ shift } } }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • type: \(\mathrm{real\;number}\)

  • values: \(\mathrm{no\;constraints}\)

  • unit: \(\mathrm{nm}\)

The distance between repeated grid lines.

xgrid{ line{ repeat{ minus_num } } }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • type: \(\mathrm{integer}\)

  • values: \(\{0,1,2,3,\ldots\}\)

  • unit: \(\mathrm{-}\)

  • default: \(0\)

Number of repeated grid lines in negative \(x\)-direction, without counting the original grid line.

xgrid{ line{ repeat{ num } } }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • type: \(\mathrm{integer}\)

  • values: \(\{1,2,3,4,\ldots\}\)

  • unit: \(\mathrm{-}\)

Number of repeated grid lines in positive \(x\)-direction, also counting the original grid line.

xgrid{ line{ repeat2{ } } }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • items: \(\mathrm{maximum\;1}\)

This group is intended to be used in conjunction with the group xgrid{ line{ repeat{ } } }. It allows to repeat the array of grid lines generated by xgrid{ line{ repeat{ } } } multiple times at equidistant positions.

xgrid{ line{ repeat2{ shift } } }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • type: \(\mathrm{real\;number}\)

  • values: \(\mathrm{no\;constraints}\)

  • unit: \(\mathrm{nm}\)

The distance between the repeated arrays of grid lines.

xgrid{ line{ repeat2{ minus_num } } }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • type: \(\mathrm{integer}\)

  • values: \(\{0,1,2,3,\ldots\}\)

  • unit: \(\mathrm{-}\)

  • default: \(0\)

Number of repetitions in negative \(x\)-direction, without counting the original array of grid lines.

xgrid{ line{ repeat2{ num } } }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • type: \(\mathrm{integer}\)

  • values: \(\{1,2,3,4,\ldots\}\)

  • unit: \(\mathrm{-}\)

Number of repetitions in positive \(x\)-direction, also counting the original array of grid lines.

xgrid{ line{ array{ } } }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • items: \(\mathrm{maximum\;1}\)

Repeating a single grid line multiple times at equidistant positions. The grid lines are placed according to the following equation:

\(x_n=\) pos \(+\) shift \(\times n\),

where \(\;n=\) min , … , max

xgrid{ line{ array{ shift } } }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • type: \(\mathrm{real\;number}\)

  • values: \(\mathrm{no\;constraints}\)

  • unit: \(\mathrm{nm}\)

The distance between repeated grid lines.

xgrid{ line{ array{ min } } }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • type: \(\mathrm{integer}\)

  • values: \(\{\ldots,-3,-2,-1,0\}\)

  • unit: \(\mathrm{-}\)

  • default: \(0\)

Number of repeated grid lines in negative \(x\)-direction, without counting the original grid line.

xgrid{ line{ array{ max } } }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • type: \(\mathrm{integer}\)

  • values: \(\{0,1,2,3,\ldots\}\)

  • unit: \(\mathrm{-}\)

Number of repeated grid lines in positive \(x\)-direction, without counting the original grid line.

xgrid{ line{ array2{ } } }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • items: \(\mathrm{maximum\;1}\)

This group is intended to be used in conjunction with the group xgrid{ line{ array{ } } }. It allows to repeat the pattern of grid lines generated by xgrid{ line{ array{ } } } multiple times at equidistant positions.

xgrid{ line{ array2{ shift } } }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • type: \(\mathrm{real\;number}\)

  • values: \(\mathrm{no\;constraints}\)

  • unit: \(\mathrm{nm}\)

The distance between repeated grid lines.

xgrid{ line{ array2{ min } } }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • type: \(\mathrm{integer}\)

  • values: \(\{\ldots,-3,-2,-1,0\}\)

  • unit: \(\mathrm{-}\)

  • default: \(0\)

Number of repetitions in negative \(x\)-direction, without counting the original array of grid lines.

xgrid{ line{ array2{ max } } }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • type: \(\mathrm{integer}\)

  • values: \(\{0,1,2,3,\ldots\}\)

  • unit: \(\mathrm{-}\)

Number of repetitions in positive \(x\)-direction, without counting the original array of grid lines.

ygrid{ }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • items: \(\mathrm{maximum\;1}\)

This group is used to define simulation space grid along the \(y\)-axis. This group has the same properties and allowed keywords as xgrid{ }.

zgrid{ }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • items: \(\mathrm{maximum\;1}\)

This group is used to define simulation space grid along the \(z\)-axis. This group has the same properties and allowed keywords as xgrid{ }.

energy_grid{ }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • items: \(\mathrm{maximum\;1}\)

Specifying the discretization of energy.

energy_grid{ min_energy }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • type: \(\mathrm{real\;number}\)

  • values: \(\mathrm{no\;constraints}\)

  • unit: \(\mathrm{eV}\)

Low-energy boundary of the energy grid.

energy_grid{ max_energy }

  • \(\mathrm{\textcolor{WildStrawberry}{required}}\)

  • type: \(\mathrm{real\;number}\)

  • values: \(\mathrm{no\;constraints}\)

  • unit: \(\mathrm{eV}\)

High-energy boundary of the energy grid.

energy_grid{ energy_resolution }

  • \(\mathrm{\textcolor{Aquamarine}{optional}}\)

  • type: \(\mathrm{real\;number}\)

  • values: \([10^{-6}, \ldots)\)

  • unit: \(\mathrm{eV}\)

  • default: \(10^{-2}\)

Spacing between subsequent energy grid points.

Examples

Basics of defining grids

grid{
    xgrid{ ... }
    ygrid{ ... }  # only 2D/3D
    zgrid{ ... }  # only 3D

grid{
    xgrid{   # x position of line and adjacent grid spacing
        line{ pos = 0       spacing = 0.5 }         # 0.5 nm spacing at position   0 nm
        line{ pos = 50      spacing = 0.1 }         # 0.1 nm spacing at position  50 nm
        line{ pos = 100     spacing = 0.5 }         # 0.5 nm spacing at position 100 nm
    }

grid{
    xgrid{ ... }

    ygrid{   # y position of line and adjacent grid spacing (2D or 3D only)
        line{ pos = 0       spacing = 0.5 }         # 0.5 nm spacing at position   0 nm
        line{ pos = 50      spacing = 0.1 }         # 0.1 nm spacing at position  50 nm

            # Here, two grid spacings are defined for y=75 nm, i.e. for y<75 nm a grid spacing of 0.1 nm
            # - and for y>75 nm a grid spacing of 0.5 nm is used.
        line{ pos = 75      spacing = 0.1 }  # <==  # 0.1 nm spacing at position  75 nm
        line{ pos = 75      spacing = 0.5 }  # <==  # 0.5 nm spacing at position  75 nm

        line{ pos = 100     spacing = 0.5 }         # 0.5 nm spacing at position 100 nm
}

Note: This example where at 75 nm an abrupt change in grid spacing is enforced is a bit dangerous. This can have impacts on numerical stability and numerical accurateness as discretized equations are only approximations to the continuous equations being solved. For nonuniform grids, higher order terms for the first or second derivates might get too large compared to slightly nonuniform grids. Abrupt changes in grid spacing rather should be avoided if possible. A corresponding warning message is written to the log file for duplicate grid points and jumps in grid points.

zgrid{   #  (3D only)
    line{ pos = 0       spacing = 0.5 }   # 0.5 nm spacing at position   0 nm
    line{ pos = 50      spacing = 0.1 }   # 0.1 nm spacing at position  50 nm
    line{ pos = 100     spacing = 0.5 }   # 0.5 nm spacing at position 100 nm
}

Note: The program generates a grid that has the specified spacing adjacent to the specified grid lines. If the grid is not equidistant, an exponential grid is generated. In this case, the calculated spacing corresponds only approximately to the specified spacing. The grid spacing used might have influence on the numerical convergence of the equations.

The actually generated grids are also written into files grid_x.dat, grid_y.dat, and grid_z.dat. Especially for more complicate grid definitions or grid definitions employing variables, it is recommended to review these files to make sure that the results match your expectations. You can also use nextnanomat \(\rightarrow\) Output \(\rightarrow\) Show grid to visualize the grid lines.

Repeating grid lines

In the same way as regions (structure{ region{} } - shape objects) can be repeated, also grid lines can be repeated which might be useful for multi-quantum wells, superlattices, Quantum Cascade Lasers, Bragg reflectors, etc. Also, it is possible to make the number of repetitions a variable in a corresponding template.

array{} copies the line object located at pos a few times, namely min times into the negative direction and max times into the positive direction, i.e. the loop runs from -shift*min to shift*max.

xgrid{
line{ pos = 11.0  spacing = 0.5  # 0.5 nm spacing at position 11.0 nm
    array{ # (optional)
            shift = 10.0    # repeat grid line in x direction by shifting it 10.0 nm (in units of [nm])
            max   = 3       # repeat grid line in x direction by applying the shift 3 (=max) times (Here, 4 lines will be set: The original one specified at pos, and 3 shifted ones.)
                            # max = 0 does not set a repeated (=shifted) grid line; negative values are not allowed.
            min   = 2    }  # (optional, default is 0) repeat grid line in negative x direction 2 times
                            # min = 0 does not set a repeated (=shifted) grid line; negative values are not allowed.
                            # In this example, the grid line at 11.0 nm is repeated 2 (=min) times into the negative direction and 3 (=max) times into the positive direction,
                            # i.e. additional grid lines at 1.0 nm, -9.0 nm and 21.0 nm, 31.0 nm, 41.0 nm will be set.
    array2{ *same as array{}* }  # (optional)

For meaning of array, see array_x{} in structure{ region{} } - Repeating regions.

For meaning of array2, see array2_x{} in structure{ region{} } - Repeating regions.

The grid line definitions line{} are processed in the order of their occurrence in order to obtain a list of default grid lines. Here, within each line{} definition, duplicate grid lines created by array{} and array2{} are ignored. After all line{} definitions have been processed, the list of default grid lines is ordered in ascending position (but the order of doubled lines remains unchanged), and intermediate grid lines are added as suggested by the respective grid spacings. Note that array{} and array2{} may accidentally cause doubled grid lines between different line{} definitions. In this case, resulting jumps in grid spacings may be nonobvious and should be checked in the output.

xgrid{
    min_pos = 100.0       # (optional) nm
    max_pos = 200.0       # (optional) nm
    line{ ... }
}

Using the optional variables min_pos and max_pos (defaults are -Infinity and +Infinity), a (half-)range can be defined for each coordinate direction within which all grid lines to be used are located. Grid lines located outside (e.g. due to a position defined by a formula or by a repetition) will be ignored. Please note that specifying a (half-)range in itself does not specify a grid line for the respective range limit(s). Similarly, there is no automatic insertion of grid lines as controlled by the respective spacings between a grid line defined inside of a (half-)range and an adjacent grid line defined outside of the (half-)range.

Per default, all defined grid lines are used for the computation, with the boundaries of the simulation region being defined by the smallest and largest coordinate positions of all grid lines defined for a respective coordinate direction. However, there are circumstances where structural features are partially or completely outside of the simulation region, and thus no grid lines are allowed for these structural features. Here, in order to facilitate reuse of coordinate calculations between region definitions and grid definitions, it is helpful to set min_pos and max_pos to the desired extent of the simulation region in order to prevent unwanted grid lines from being generated. All grid line definitions from line{} which fall outside of the interval [min_pos, max_pos] are ignored. Thus, if the such defined interval is [100, 200], an individual line with pos = 250 would be ignored. Similarly, when a line is repeated using array{} and/or array2{} multiple times, the line repetitions falling outside of the interval would be ignored.

Jumps in grid spacing

By default, jumps in grid spacings are not allowed. Optionally, they can be switched on.

xgrid{
  ...
  allow_spacing_jumps = yes
  line{ pos = 0       spacing = 0.5 }   # 0.5 nm spacing at position   0 nm
  line{ pos = 50      spacing = 0.5 }   # 0.5 nm spacing at position  50 nm
  line{ pos = 50      spacing = 0.1 }   # 0.1 nm spacing at position  50 nm
  line{ pos = 100     spacing = 0.1 }   # 0.5 nm spacing at position 100 nm
}

Here, left of the point at x=50 nm, a grid spacing of 0.5 nm is used, and right of the point at x=50 nm, a grid spacing of 0.1 nm is used which is a jump in grid spacing. allow_spacings_jumps = yes is not recommended due to a loss in numerical accuracy and numerical stability. The only purpose of this feature is to generate input files that are compatible to input files of the nextnano³ software which supports jumps by default.