InputFileTemplate#

class nextnanopy.inputs.InputFileTemplate(fullpath=None, configpath=None, parse=False, text=None)#

This class stores and manipulates any kind of nextnano input files.

For each nextnano product, the syntax is different but the core information is very similar like the variables that can be changed. This class contains useful methods such as to get a preview of the file or execute a simulation.

The initialization of the class will execute the load method and setup the config file.

Parameters:

fullpathstr or pathlib.Path, default=None: Path to the file. If given, the file is loaded, unless text is given as well: then fullpath only names the file and nothing is read from disk.
configpathstr or pathlib.Path, default=None: Path to the config file. If omitted, a copy of the process-wide configuration (nextnanopy.config) is taken instead of reading a file; see Notes.
parsebool, default=False: Experimental feature to parse the input file into a structured object. Please refrain from using it.
textstr, default=None: Contents of the input file. If given, the file content is read from this string instead of from disk at fullpath.

Attributes:

fullpathstr or pathlib.Path: Path to the file.
configpathstr or pathlib.Path: Path of the configuration file behind config. Read-only; assign config to point this file at a different configuration.
variablesDictList of InputVariable: Input variables defined in the file, keyed by name.
raw_lineslist of str: Each line of the file as it was loaded.
raw_textstr: The raw_lines as one string, without the current input variable values applied. Read-only.
textstr: Text of the file with the current variable values applied. Assigning replaces raw_lines and reloads variables, but does not re-detect product.
lineslist of str: The raw_lines updated with the current input variable parameters.
filenamestr: File name with the extension. Assigning changes fullpath to the same folder with the new name.
filename_onlystr: File name without the extension. Assigning changes fullpath to the new name, keeping the folder and the extension.
folder_inputstr: Folder containing the input file. Assigning changes fullpath to the new folder, keeping the file name.
productstr: Detected nextnano product when the file is loaded. Defaults to ‘not valid’ if the product is not recognised.
configNNConfig: The configuration this file runs on, bound at construction (see Notes).
execute_infodict: Information about the last execution. Empty until execute() has run.

See also

InputFile: For the documentation of the methods, see this class.

Notes

The configuration is bound at construction and never re-read afterwards. With no configpath, the file takes a copy of the process-wide configuration (nextnanopy.config) as it stands at that moment. Two things follow, both intended:

nextnanopy.config.set(...) reaches every input file built after it, and no save() is needed for that – saving only matters for other processes. It reaches no file that already exists.
The copy is this file’s own. Editing .config here changes neither nextnanopy.config nor any other input file, and later edits to nextnanopy.config do not reach this file.

So configure first, then build the input files. To point a file that already exists at a different configuration, assign .config; to build one on a config file of its own, pass configpath.

property folder_output#

Folder where the simulated data is stored. Read-only.

Returns:

pathlib.Path: Output directory of the last execution, as chosen by execute() from overwrite and create_subdirectory.

Raises:

KeyError: If the input file has not been executed yet.

preview(nums=True)#

Print the text of the file.

Parameters:

numsbool, default=True: If True, prefix each line with its index, starting at 0.

load(fullpath, text=None)#

Load the input file.

The steps are the following:

Clear the raw_lines, variables and fullpath attributes.
Load the raw text (updates the fullpath and raw_lines attributes).
Find the nextnano product (updates product).
Validate the input file.
Load the input variables (updates variables).
Load the content, when applicable.

Parameters:

fullpathstr or pathlib.Path: Path to the file to be loaded.
textstr, default=None: Contents of fullpath, if the caller has already read them. Saves re-reading the file from disk. If omitted, the file is read here.

Raises:

FileNotFoundError: If fullpath does not exist and text is not given.

save(fullpath=None, overwrite=False, automkdir=True, temp=False, content=False)#

Save the current information into a file.

The fullpath attribute is updated to the path that was written.

Parameters:

fullpathstr or pathlib.Path, default=None: Path including the file name where it will be saved. If None, the fullpath attribute is used.
overwritebool, default=False: If False, an index is appended to the file name when it is already taken (example.nnp, then example_0.nnp, example_1.nnp, …), so an existing file is never overwritten. If True, the file is written even if it exists and no index is appended.
automkdirbool, default=True: If True, create the parent folder if it does not exist.
tempbool, default=False: If True, save into a temporary folder that is removed when the process exits, keeping the current filename. Ignored with a warning when fullpath is given.
contentbool, default=False: Experimental feature, refrain from using it. If True, save the parsed content attribute instead of text. Comments are not preserved. It requires the file to be loaded with parse=True.

Returns:

str: Path of the file that was written. Not necessarily fullpath: with overwrite=False an index may have been appended.

Raises:

ValueError: If neither the fullpath argument nor the fullpath attribute is set, or if content is True and the file was not loaded with parse=True.
FileNotFoundError: If automkdir is False and the parent folder does not exist.

execute(show_log=True, convergenceCheck=False, convergence_check_mode='pause', overwrite=False, create_subdirectory=True, **kwargs)#

Execute the input file located at fullpath.

Individual kwargs can be passed like license or database; anything not given comes from config.

Parameters:

show_logbool, default=True

If False, do not print the simulation log to the console. The log file is written either way.

convergenceCheckbool, default=False

If True, check the log for convergence once the simulation has finished. Ignored when the file is executed in parallel, as a sweep or an execution queue does.

convergence_check_mode{‘pause’, ‘terminate’, ‘continue’}

What to do when the simulation did not converge. Only used when convergenceCheck is True.

‘pause’: ask the user how to proceed. If no interactive terminal is attached (e.g. CI, cluster jobs), behaves like ‘terminate’ instead of blocking on input.
‘terminate’: terminate the script.
‘continue’: notify the user but continue the script. This is also the only mode that tolerates a missing log file.

overwritebool, default=False

If False, the output directory is created under an unused name: an index is appended (example_0, example_1, …) when the name is already taken, so a run never writes into an earlier run’s output. If True, an existing directory is used as it is - which means writing next to whatever the earlier run left there; nothing is deleted. Has no effect when create_subdirectory is False.

create_subdirectorybool, default=True

If True, the simulation writes into <outputdirectory>/<input file name>/. If False, it writes into the outputdirectory itself.

**kwargsdict

The nextnano product’s own command line arguments, passed on as they are. Anything not given here comes from config. kwargs may contain:

exestr, optional: Path to the executable.
licensestr, optional: Path to the license file.
databasestr, optional: Path to the database file.
outputdirectorystr, optional: Path where to save the simulated data.

and other parameters depending on the nextnano product. For example, ‘threads’ is accepted by nextnano++. See the documentation of the command line arguments of each nextnano product on the online Manual (https://www.nextnano.com/docu/).

Returns:

dict: Information about the started simulation, also stored in execute_info. Keys: ‘process’, ‘outputdirectory’, ‘filename’, ‘logfile’, ‘cmd’, ‘wdir’, ‘queue’, ‘tout’, ‘terr’.

Raises:

ValueError: If fullpath is empty or is not an existing file, or if convergence_check_mode is not one of the values listed above.
FileNotFoundError: If the executable path in config is empty or invalid.
RuntimeError: If convergenceCheck is True and the simulation was terminated or did not converge, unless convergence_check_mode is ‘continue’.
NotImplementedError: If convergenceCheck is True and the product is nextnano.MSB.

Notes

The simulation is launched through the system shell, so execute_info['process'] is the shell process, not the simulator itself. On Windows, calling kill()/terminate() on it stops only the shell wrapper; the running simulation is NOT stopped.

Where the output goes is decided by overwrite/create_subdirectory, which are parameters rather than members of **kwargs: they steer nextnanopy, not the simulator, so they are also not config options. folder_output holds the directory that was chosen once the run has started.

get_variable(name)#

Return the input variable called name.

Equivalent to variables[name], except that only lookup by name is supported: variables also accepts an integer index, this method does not.

Parameters:

namestr: Name of the input variable.

Returns:

InputVariable: The input variable stored under name.

Raises:

KeyError: If name is not a key of variables.

set_variable(name, value=None, comment=None, unit=None)#

Change the value, the comment and/or the unit of an input variable.

Parameters:

namestr: Name of the input variable.
valueint, float or str, default=None: New value of the variable. If None, the value is left unchanged.
commentstr, default=None: New comment of the variable. If None, the comment is left unchanged.
unitstr, default=None: New unit of the variable. If None, the unit is left unchanged. The unit is not part of the input file text: it only feeds the unit and label attributes of the variable.

Returns:

InputVariable: The input variable that was changed.

Raises:

KeyError: If name is not a key of variables.