DataFile#

class nextnanopy.DataFile(fullpath, product=None, **loader_kwargs)#

Bases: Output

The contents of one nextnano output file, whatever its format.

Picks the loader that matches the file, runs it on construction, and takes over the Coord and Variable objects it produced together with its metadata. Only a .txt file needs product to be named – every other extension maps to the same loader whichever product wrote it.

Parameters:

fullpathstr or pathlib.Path: Path to the file.
productstr, default=None: Product that wrote the file: 'nextnano++', 'nextnano3', 'nextnano.NEGF', 'nextnano.NEGF_classic' or 'nextnano.MSB'. If omitted, a .txt file is loaded by trial and error; every other extension resolves to its loader either way.
**loader_kwargs: Passed to the loader.

Attributes:

fullpathstr or pathlib.Path: Path to the file. Settable, and the path properties below follow it.
productstr or None: The product passed in, unchanged.
coordsDictList: Coord objects, keyed by name.
variablesDictList: Variable objects, keyed by name.
metadatadict: Extra information recorded by the loader. What it holds depends on the format, and the .vtr loader records none.
dataDictList: coords and variables in one mapping. Built afresh on every access, so assigning into it changes nothing. Read-only.
folderstr: Folder holding the file. Read-only.
filenamestr: File name with the extension. Read-only.
filename_onlystr: File name without the extension. Read-only.
extensionstr: File extension, leading dot included. Read-only.
vtkpyvista.DataObject: The mesh as pyvista read it. Only a .vtr file has one.

Raises:

FileNotFoundError: If fullpath is not a file.
NotImplementedError: If no loader fits, which for a txt file means the guess found nothing.

Notes

Only a .txt file warns when product is left out, and the warning is worth heeding: the guess reads the file with one product’s parser after another and keeps the first that comes back with named variables, which is a heuristic, not a detection. Every other extension resolves without warning.

The loader is chosen from the file name, never from the contents. The extension picks the format (.dat, .vtr, .fld etc), and for .txt the stem narrows it further (variables_input, total_charges). Both are the names nextnano writes by default, so renaming a file loads it with the wrong parser, or raises if the new extension is unknown.

plot(legend=False, y_axis_name='', subplots=False)#

Draw a quick preview of the data with matplotlib.

What is drawn follows the number of coordinates: with none the first variable serves as the x axis, with one the variables are drawn against that coordinate, and with two each variable becomes a colour mesh.

Parameters:

legendbool, default=False: Whether to draw a legend. Used only for the line plots, that is a file with no coordinate or one; a colour mesh is named by its title instead.
y_axis_namestr, default=’’: Prefix of the y-axis label, which is written as name[unit]. Used only for a file with no coordinate or one.
subplotsbool, default=False: Whether to stack the variables as axes of a single figure. Used only for a file with two coordinates and more than one variable, where the alternative is one figure per variable.

Returns:

matplotlib.figure.Figure: The figure drawn. With two coordinates, several variables and subplots=False, one figure is made per variable and only the last one is returned.
matplotlib.axes.Axes or numpy.ndarray: The axes of that figure, an array of them when subplots=True.

Raises:

NotImplementedError: If the file has more than two coordinates.
ImportError: If matplotlib is not installed. It is an optional dependency, pip install nextnanopy[plot].

Notes

Nothing appears until matplotlib.pyplot.show is called, unless the session draws figures by itself as a notebook does.

save(filepath, format='dat')#

Save the data from the DataFile instance to a specified file in various formats.

Parameters:

filepathstr

The file path where the data will be saved.

formatstr, optional

The format in which the data should be saved. Default is ‘dat’. Supported formats:

‘dat’ (for 1D files): Data is saved in a plain text format (.dat) with whitespace-separated values.
‘VTKAscii’ (for 2D/3D files): Data is saved in VTK ASCII format (.vtk) suitable for visualization tools.
‘AvsAscii_one_file’ (for 2D/3D files): Data is saved in AVS/Express ASCII format (.fld) for AVS/Express software.

Raises:

NotImplementedError: If the provided ‘format’ is not supported for saving.
ValueError: If ‘dat’ is asked for and the file has more than one coordinate.
KeyError: If ‘dat’ is asked for and the file was not loaded from a .dat, since only that loader records the headers this format writes back.

Examples

>>> # Assuming `data_file` is an instance of the `DataFile` class
>>> data_file.save('data_file.dat', format='dat')  # Save data in .dat format
>>> data_file.save('data_file.vtk', format='VTKAscii')  # Save data in VTK ASCII format
>>> data_file.save('data_file.fld', format='AvsAscii_one_file')  # Save data in AVS/Express ASCII format

get_coord(key)#

Return the coordinate stored under key.

Parameters:

keystr or int: Name of the coordinate, or its position in coords.

Returns:

Coord: The stored object, not a copy.

Raises:

KeyError: If key is neither a name nor a valid position in coords.

get_variable(key)#

Return the variable stored under key.

Parameters:

keystr or int: Name of the variable, or its position in variables.

Returns:

Variable: The stored object, not a copy.

Raises:

KeyError: If key is neither a name nor a valid position in variables.