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 between0
and1023
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 (usually1
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 GmbH processes
- -b i, --blas_threads i
Set number of parallel threads in BLAS, LAPACK, etc. Here,
i
threads are specified, any integer value between0
and1023
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 or0
, 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
anddatabase_syntax.txt
.Additionally, the files
keywords_nnp.xml
anddatabase_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, oldSOFT_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 definedimport{ # 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 directoryimport{ # 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 definedoutput{ # 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) pathoutput{ # 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 }