2.8. Command Line¶

Command line usage:

A general form is nextnano++_Intel_64bit.exe [runmode] [options] filename1 [filename2 ...], where filename1 is the input file you want to simulate.

An example:
"nextnano++_Intel_64bit.exe" --license "C:\My Documents\nextnano\License\License_nnp.lic" --database "C:\Program Files\nextnano\2023_02_19\nextnano++\Syntax\database_nnp.in" --threads 4 --outputdirectory "C:\My Documents\nextnano\Output\HEMT_1D_nnp" --noautooutdir "C:\Program Files\nextnano\2023_02_19\Sample files\nextnano++ sample files\HEMT_1D_nnp.in"

Available optional runmodes are:

-v, --version: Show version number only.
-h, --help: Show command line usage only.
-p, --parse: Parse input file(s) and quit.
-s, --structure: Parse input file(s), generate structure(s), and quit.

Available options are:

-d database_file, --database database_file

Use database file <database_file>.

-l license_file, --license license_file

Use license file <license_file>.

Example: --license "C:\My Documents\nextnano\License\License_nnp.lic"

-i input_directory, --inputdirectory input_directory

Specify input directory <input_directory>.

-o output_directory, --outputdirectory output_directory

Specify output directory <output_directory>.

-n, --noautooutdir

Do not create output directory(ies) with same name(s) as input file(s).

(= no automatic output directory)

-q, --quick

Enable quick updates of convergence log files.

Multi-threading

-t i, --threads i

Set number of parallel threads. Here, i threads are specified, any integer value between 0 and 1023 is allowed.

Not displayed and effective in serial executables. Currently we do not provide serial executables any more.

Using --threads 0 is equivalent to not specifying --threads at all, i.e. the code does not attempt to change the number of threads used.

Maximum value for --threads is the number of CPU cores, or possibly twice that number if Hyper-threading is enabled.

For default value of 0, OpenMP system supplied maximal value is used.

If set (e.g. using nextnanomat Expert Settings), the number of parallel OpenMP threads is set to the supplied value. If the desired value is too large for the CPU, the maximum value available for the CPU is set. If not set or set to 0, the default value as specified by the environment is used (usually 1 or all available). The actually used value is output near the beginning of the log file.

For example, on an i7-8700 CPU (6 cores and 12 threads with Hyper-threading on), the optimal number for best performance is 4. Using the extra threads from Hyper-threading rather hurts performance, and issues like memory speed seem to require a further reduction to less than 6 threads. With 4 threads, CPU load is about 45-50% on the tested CPU. This feature may also be useful for HTCondor to reduce background load, or to limit individual load for multiple parallel nextnano processes

-b i, --blas_threads i

Set number of parallel threads in BLAS, LAPACK, etc. Here, i threads are specified, any integer value between 0 and 1023 is allowed.

Allows to separately set the number of BLAS (MKL) threads (MKL = Intel Math Kernel Library).

Maximum value for --blas_threads is typically the number of CPU cores.

Default value is 0 (Then uses the same number as the global number of threads which can be set by -t or --threads.)

For default value of 0, and if --threads is not specified or 0, the MKL library supplied maximal value is used.

Note

Additional notes on multi-threading

When only running one job at a time, setting --threads and --blas_threads to the number of CPU cores typically gives best performance. To force serial execution of each job, set both --threads and --blas_threads to 1.

Note that (the number of threads times the number of parallel jobs) and also (the number of BLAS threads times the number of parallel jobs) should not exceed the number of cores in order to avoid performance penalties from oversubscribing the CPU. Limited memory bandwidth may even impose lower limits on notebooks and lower grade desktop PCs.

Values for --threads and --blas_threads larger than the system supplied maximal values are automatically adjusted downwards. If unexpected values are automatically set (see log file for output), please also check your environment variables such as OMP_NUM_THREADS or MKL_NUM_THREADS.

-g, --generate

Generate additional debug information.

Also outputs syntax definition files input_syntax.txt and database_syntax.txt.

Additionally, the files keywords_nnp.xml and database_nnp.xml are created, which are used by nextnanomat for its auto completion feature.

Example: nextnano --license License_nnp.lic --outputdirectory "H:\nextnano\Output\" QuantumDot.in

Soft kill

If the user places or creates a file called SOFT_KILL (without file extension) into the root output folder of the currently running simulation, a softkill will be performed, i.e. the program exits the iteration cycle and writes the output.

The concrete effects are the following:

As soon as the SOFT_KILL file is detected (may take a while), any running classical or quantum iteration will be terminated early, but all (incomplete) results will be written into files. Note that the detection is only performed at the beginning of each iteration step.
If the SOFT_KILL file is detected in the classical current-poisson equation, no quantum or optical calculations will be performed afterwards, i.e. only classical (incomplete) results will be written into files.
After any detection, subsequent sweeps will still be executed but their data will be incomplete in the same way. (We also could prevent further sweeps if this is the preferred approach.)
The SOFT_KILL file is not being removed at the end of the simulation. However, old SOFT_KILL files are automatically removed at the beginning of the simulation and thus will not cause any trouble.
If there are multiple simulations running in parallel (or being scheduled sequentially), separate SOFT_KILL files need to be placed in the respective root output folders.

Further remarks

Priorities in descending order

Full (absolute) paths with file names have the highest priority, e.g. H:\nextnano\...
Input and output directories (both relative and absolute), defined in command line, have priority over absolute directory paths (not file paths) defined in input file.

Rules: Default input directory is the directory, where the input file is located (not the current working directory). It can be redefined in command line (--inputdirectory) or in the input file (import{ }). By default the output of the simulation is written into an automatically generated directory with the same name as the input file. This default behavior can be suppressed using the command line flag --noautooutdir. If no output directory is defined in the command line or input file, the output of the simulation is written into the current working directory (including the automatically generated directory unless it is not suppressed). Relative input and output directory paths defined in the command line are relative to the current working directory. Relative paths to directories, defined in the command line and in the input file are always concatenated. Command line definitions have priority over definitions in the input file. If in the command line a relative or absolute path (--inputdirectory / --outputdirectory) is defined, the corresponding absolute directory path in the input file is ignored.

Examples

--inputdirectory in command line is not defined

import{ # if no directory is specified,
        # the directory where the input file is located
        # is taken as the input directory
   directory   = "D:\import_files\"     # absolute path
               =   "\import_files\"     # root path
               =    "import_files\"     # relative path with respect
                                        # to current working directory

   file{
      ...
      filename = "D:\any_filename.fld"  # absolute path. The above specified directory is ignored.
               =   "\any_filename.fld"  # root path. The above specified directory is ignored.
               = "any_directory\any_filename.fld" # relative path concatenated with path specified by directory.
               =    "any_filename.fld"  # file is searched in directory
   }
}

--inputdirectory in command line is defined, e.g.

--inputdirectory D:\inputdir # absolute path

--inputdirectory \inputdir # root path

--inputdirectory inputdir # path relative to current directory

import{ # if no directory is specified,
        # the directory specified in the command line
        # is taken as the input directory
   directory   = "D:\import_files\"    # absolute path is ignored because of definition in command line
               =   "\import_files\"    # root path is ignored because of definition in command line
               =    "import_files\"    # relative path concatenated with path specified in command line

   file{
      ...
      filename = "D:\any_filename.fld"            # absolute path. The above specified directory and the path specified in the command line are ignored.
               =   "\any_filename.fld"            # root path. The above specified directory and the path from the command line are ignored.
               = "any_directory\any_filename.fld" # relative path concatenated with path specified by command line and/or path specified by directory.
               =    "any_filename.fld"            # file is searched in directory defined by the command line and directory
   }
}

The whole output of a simulation is written out in a directory named as the input file. This can be suppressed by command line flag --noautooutdir.

--outputdirectory in command line is not defined

output{  # if no directory specified,
         # the current directory is taken as output directory
   directory = "D:\simulation_output\"   # absolute path
             =   "\simulation_output\"   # root path
             =    "simulation_output\"   # relative (to current directory) path
}

--outputdirectory in command line is defined, e.g.

--outputdirectory D:\outputdir # absolute path

--outputdirectory \outputdir # root path

--outputdirectory outputdir # relative (to current directory) path

output{  # if no directory specified,
         # the directory specified in command line
         # is taken as output directory
   directory = "D:\simulation_output\"   # absolute path is ignored due to definition in command line
             =   "\simulation_output\"   # root path is ignored due to definition in command line
             =    "simulation_output\"   # relative path concatenated with path specified in command line
}