sisl.io.siesta.wfsxSileSiesta

class sisl.io.siesta.wfsxSileSiesta(filename, mode='r', *args, **kwargs)

Bases: SileBinSiesta

Binary WFSX file reader for Siesta

The WFSX file assumes that users initialize the object with a parent argument (or one of the other geometry related objects as shown below).

The parent argument is necessary to convert WFSX k-points from 1/Ang to reduced coordinates. When returning EigenstateElectron objects the parent of these objects are the equivalent of the parent argument upon initialization. Therefore please remember to pass a correct parent.

Parameters:

• parent (obj, optional) – a parent may contain a geometry, and/or a supercell

• geometry (Geometry, optional) – a geometry contains a cell with corresponding lattice vectors used to convert k [1/Ang] -> [b]

• lattice (Lattice, optional) – a supercell contains the lattice vectors to convert k

Plotting

plot	Plotting functions for the wfsxSileSiesta class.
plot.bands(fdf[, extra_vars, ...])	Creates a BandsData object and then plots a BandsPlot from it.
plot.fatbands(fdf[, ...])	Creates a BandsData object and then plots a FatbandsPlot from it.
plot.pdos(H[, geometry, ...])	Creates a PDOSData object and then plots a PdosPlot from it.
plot.wavefunction(data_geometry)	Creates a EigenstateData object and then plots a WavefunctionPlot from it.

Methods

base_directory([relative_to])	Retrieve the base directory of the file, relative to the path relative_to
dir_file([filename, filename_base])	File of the current Sile
read(*args, **kwargs)	Generic read method which should be overloaded in child-classes
read_basis()	Reads the basis contained in the WFSX file.
read_brillouinzone()	Read the brillouin zone object
read_eigenstate([k, spin, atol])	Reads a specific eigenstate from the file.
read_info()	Reads the information for all the k points contained in the file
read_sizes()	Reads the sizes related to this WFSX file
write(*args, **kwargs)	Generic write method which should be overloaded in child-classes
yield_eigenstate()	Iterates over the states in the WFSX file

Attributes

base_file	File of the current Sile
file	File of the current Sile

base_directory(relative_to='.')

Retrieve the base directory of the file, relative to the path relative_to

dir_file(filename=None, filename_base='')

File of the current Sile

plot.bands(fdf: str, extra_vars=(), need_H=False, *, Erange: tuple[float, float] | None = None, E0: float = 0.0, E_axis: Literal['x', 'y'] = 'y', bands_range: tuple[int, int] | None = None, spin: Literal[0, 1] | None = None, bands_style: StyleSpec = {'color': 'black', 'dash': 'solid', 'opacity': 1, 'width': 1}, spindown_style: StyleSpec = {'color': 'blue', 'width': 1}, colorscale: Colorscale | None = None, gap: bool = False, gap_tol: float = 0.01, gap_color: str = 'red', gap_marker: dict = {'size': 7}, direct_gaps_only: bool = False, custom_gaps: Sequence[dict] = [], line_mode: Literal['line', 'scatter', 'area_line'] = 'line', group_legend: bool = True, backend: str = 'plotly') → BandsPlot

Creates a BandsData object and then plots a BandsPlot from it.

Parameters:

• fdf – Path to the fdf file used to run the calculation. Needed to gather information about the geometry and the hamiltonian/overlap if needed.

• extra_vars – Additional variables to calculate for each eigenstate, apart from their energy.

  Each item of the list should be a dictionary with the following keys:

  • ‘name’, str: The name of the variable.

  • ‘getter’, callable: A function that gets 3 arguments: eigenstate, plot and

  spin index, and returns the values of the variable in a numpy array. This function will be called for each eigenstate object separately. That is, once for each (k-point, spin) combination. - ‘coords’, tuple of str: The names of the dimensions of the returned array. The number of coordinates should match the number of dimensions. - ‘coords_values’, dict: If this variable introduces a new coordinate, you should pass the values for that coordinate here. If the coordinates were already defined by another variable, they will already have values. If you are unsure that the coordinates are new, just pass the values for them, they will get overwritten.

  Each item can also be a string indicating the name of a known variable: ‘norm2’, ‘spin_moment’, ‘ipr’.

• need_H – Whether the Hamiltonian is needed to read the WFSX file.

• Erange – The energy range to plot. If None, the range is determined by bands_range.

• E0 – The energy reference.

• E_axis – Axis to plot the energies.

• bands_range – The bands to plot. Only used if Erange is None. If None, the 15 bands above and below the Fermi level are plotted.

• spin – Which spin channel to display. Only meaningful for spin-polarized calculations. If None and the calculation is spin polarized, both are plotted.

• bands_style – Styling attributes for bands.

• spindown_style – Styling attributes for the spin down bands (if present). Any missing attribute will be taken from bands_style.

• colorscale – Colorscale to use for the bands in case the color attribute is an array of values. If None, the default colorscale is used for each backend.

• gap – Whether to display the gap.

• gap_tol – Tolerance in k for determining whether two gaps are the same.

• gap_color – Color of the gap.

• gap_marker – Marker styles for the gap (as plotly marker’s styles).

• direct_gaps_only – Whether to only display direct gaps.

• custom_gaps – List of custom gaps to display. See the showcase notebooks for examples.

• line_mode – The method used to draw the band lines.

• group_legend – Whether to group all bands in the legend to show a single legend item.

  If the bands are spin polarized, bands are grouped by spin channel.

• backend – The backend to use to generate the figure.

See also

BandsPlot

The plot class used to generate the plot.

BandsData

The class to which data is converted.

plot.fatbands(fdf: str, extra_vars=(), need_H=False, *, Erange: tuple[float, float] | None = None, E0: float = 0.0, E_axis: Literal['x', 'y'] = 'y', bands_range: tuple[int, int] | None = None, spin: Literal[0, 1] | None = None, bands_style: StyleSpec = {'color': 'black', 'opacity': 1, 'width': 1}, spindown_style: StyleSpec = {'color': 'blue', 'width': 1}, gap: bool = False, gap_tol: float = 0.01, gap_color: str = 'red', gap_marker: dict = {'size': 7}, direct_gaps_only: bool = False, custom_gaps: Sequence[dict] = [], bands_mode: Literal['line', 'scatter', 'area_line'] = 'line', bands_group_legend: bool = True, groups: OrbitalQueries = [], fatbands_var: str = 'norm2', fatbands_mode: Literal['line', 'scatter', 'area_line'] = 'area_line', fatbands_scale: float = 1.0, backend: str = 'plotly') → FatbandsPlot

Creates a BandsData object and then plots a FatbandsPlot from it.

Parameters:

• fdf – Path to the fdf file used to run the calculation. Needed to gather information about the geometry and the hamiltonian/overlap if needed.

• extra_vars – Additional variables to calculate for each eigenstate, apart from their energy.

  Each item of the list should be a dictionary with the following keys:

  • ‘name’, str: The name of the variable.

  • ‘getter’, callable: A function that gets 3 arguments: eigenstate, plot and

  spin index, and returns the values of the variable in a numpy array. This function will be called for each eigenstate object separately. That is, once for each (k-point, spin) combination. - ‘coords’, tuple of str: The names of the dimensions of the returned array. The number of coordinates should match the number of dimensions. - ‘coords_values’, dict: If this variable introduces a new coordinate, you should pass the values for that coordinate here. If the coordinates were already defined by another variable, they will already have values. If you are unsure that the coordinates are new, just pass the values for them, they will get overwritten.

  Each item can also be a string indicating the name of a known variable: ‘norm2’, ‘spin_moment’, ‘ipr’.

• need_H – Whether the Hamiltonian is needed to read the WFSX file.

• Erange – The energy range to plot. If None, the range is determined by bands_range.

• E0 – The energy reference.

• E_axis – Axis to plot the energies.

• bands_range – The bands to plot. Only used if Erange is None. If None, the 15 bands above and below the Fermi level are plotted.

• spin – Which spin channel to display. Only meaningful for spin-polarized calculations. If None and the calculation is spin polarized, both are plotted.

• bands_style – Styling attributes for bands.

• spindown_style – Styling attributes for the spin down bands (if present). Any missing attribute will be taken from bands_style.

• gap – Whether to display the gap.

• gap_tol – Tolerance in k for determining whether two gaps are the same.

• gap_color – Color of the gap.

• gap_marker – Marker styles for the gap (as plotly marker’s styles).

• direct_gaps_only – Whether to only display direct gaps.

• custom_gaps – List of custom gaps to display. See the showcase notebooks for examples.

• bands_mode – The method used to draw the band lines.

• bands_group_legend – Whether to group all bands in the legend to show a single legend item.

  If the bands are spin polarized, bands are grouped by spin channel.

• groups – Orbital groups to plots. See showcase notebook for examples.

• fatbands_var – The variable to use from bands_data to determine the width of the fatbands. This variable must have as coordinates (k, band, orb, [spin]).

• fatbands_mode – The method used to draw the fatbands.

• fatbands_scale – Factor that scales the size of all fatbands.

• backend – The backend to use to generate the figure.

See also

FatbandsPlot

The plot class used to generate the plot.

BandsData

The class to which data is converted.

plot.pdos(H: ~sisl.physics.Hamiltonian, geometry: ~sisl.Geometry | None = None, data_Erange=(-2, 2), nE: int = 100, E0: float = 0, distribution=functools.partial(<function gaussian>, sigma=0.1, x0=0.0), *, groups: Sequence[OrbitalStyleQuery] = [{'name': 'DOS'}], Erange: tuple[float, float] = (-2, 2), E_axis: Literal['x', 'y'] = 'x', line_mode: Literal['line', 'scatter', 'area_line'] = 'line', line_scale: float = 1.0, backend: str = 'plotly') → PdosPlot

Creates a PDOSData object and then plots a PdosPlot from it.

Parameters:

• H – The Hamiltonian to which the eigenstates correspond. Used to get the overlap matrix and the spin type.

• geometry – The geometry of the system. If not provided, it is extracted from the Hamiltonian.

• data_Erange – The energy range in which to calculate the PDOS.

• nE – The number of energy points for which to calculate the PDOS.

• E0 – Reference energy to take as 0. Energy levels will be shifted by -E0.

• distribution – The distribution to use for smoothing the PDOS along the energy axis. Each state will be broadened by this distribution.

• groups – List of orbital specifications to filter and accumulate the PDOS. The contribution of each group will be displayed in a different line. See showcase notebook for examples.

• Erange – The energy range to plot.

• E_axis – Axis to project the energies.

• line_mode – Mode used to draw the PDOS lines.

• line_scale – Scaling factor for the width of all lines.

• backend – The backend to generate the figure.

See also

PdosPlot

The plot class used to generate the plot.

PDOSData

The class to which data is converted.

plot.wavefunction(data_geometry: Geometry, k: tuple[float, float, float] = (0, 0, 0), spin: int = 0, *, i: int = 0, geometry: Geometry | None = None, grid_prec: float = 0.2, grid: Grid | None = None, axes: Axes = ['z'], represent: Literal['real', 'imag', 'mod', 'phase', 'deg_phase', 'rad_phase'] = 'real', transforms: Sequence[str | Callable] = (), reduce_method: Literal['average', 'sum'] = 'average', boundary_mode: str = 'grid-wrap', nsc: tuple[int, int, int] = (1, 1, 1), interp: tuple[int, int, int] = (1, 1, 1), isos: Sequence[dict] = [], smooth: bool = False, colorscale: Colorscale | None = None, crange: tuple[float, float] | None = None, cmid: float | None = None, show_cell: Literal['box', 'axes', False] = 'box', cell_style: dict = {}, x_range: Sequence[float] | None = None, y_range: Sequence[float] | None = None, z_range: Sequence[float] | None = None, plot_geom: bool = False, geom_kwargs: dict = {}, backend: str = 'plotly') → WavefunctionPlot

Creates a EigenstateData object and then plots a WavefunctionPlot from it.

Parameters:

• fdf – The FDF file to be used as the root.

• data_geometry – The geometry to be used for the Hamiltonian.

• k – The k-point for which the eigenstate coefficients are desired.

• spin – The spin for which the eigenstate coefficients are desired.

• i – The index of the eigenstate to plot.

• geometry – Geometry to use to project the eigenstate to real space. If None, the geometry associated with the eigenstate is used.

• grid_prec – The precision of the grid where the wavefunction is projected.

• grid – The grid to plot.

• axes – The axes to project the grid to.

• represent – The representation of the grid to plot.

• transforms – List of transforms to apply to the grid before plotting.

• reduce_method – The method used to reduce the grid axes that are not displayed.

• boundary_mode – The method used to deal with the boundary conditions. Only used if the grid is to be orthogonalized. See scipy docs for more info on the possible values.

• nsc – The number of unit cells to display in each direction.

• interp – The interpolation factor to use for each axis to make the grid smoother.

• isos – List of isosurfaces or isocontours to plot. See the showcase notebooks for examples.

• smooth – Whether to ask the plotting backend to make an attempt at smoothing the grid display.

• colorscale – Colorscale to use for the grid display in the 2D representation. If None, the default colorscale is used for each backend.

• crange – Min and max values for the colorscale.

• cmid – The value at which the colorscale is centered.

• show_cell – Method used to display the unit cell. If False, the cell is not displayed.

• cell_style – Style specification for the cell. See the showcase notebooks for examples.

• x_range – The range of the x axis to take into account. Even if the X axis is not displayed! This is important because the reducing operation will only be applied on this range.

• y_range – The range of the y axis to take into account. Even if the Y axis is not displayed! This is important because the reducing operation will only be applied on this range.

• z_range – The range of the z axis to take into account. Even if the Z axis is not displayed! This is important because the reducing operation will only be applied on this range.

• plot_geom – Whether to plot the associated geometry (if any).

• geom_kwargs – Keyword arguments to pass to the geometry plot of the associated geometry.

• backend – The backend to use to generate the figure.

See also

WavefunctionPlot

The plot class used to generate the plot.

EigenstateData

The class to which data is converted.

read(*args, **kwargs)

Generic read method which should be overloaded in child-classes

Parameters:

kwargs – keyword arguments will try and search for the attribute read_<> and call it with the remaining **kwargs as arguments.

read_basis() → Atoms

Reads the basis contained in the WFSX file.

The WFSX file only contains information about the atom labels, which atom each orbital belongs to and the orbital quantum numbers. It is thus not complete in every sense.

Returns:

Atoms – the basis read.

read_brillouinzone() → BrillouinZone

Read the brillouin zone object

read_eigenstate(k=(0, 0, 0), spin: int = 0, atol: float = 1e-4) → EigenstateElectron

Reads a specific eigenstate from the file.

This method iterates over the states until it finds a match. Do not call this method repeatedly. If you want to loop eigenstates, use yield_eigenstate.

Parameters:

• k (array-like of shape (3,), optional) – The k point of the state you want to find.

• spin – The spin index of the state you want to find. Only meaningful for polarized calculations.

• atol – The threshold value for considering two k-points the same (i.e. to match the query k point with the states k point).

See also

yield_eigenstate

Returns:

EigenstateElectron or None – If found, the state that was queried.

Raises:

LookupError : – in case the requested k-point can not be found in the file.

read_info()

Reads the information for all the k points contained in the file

Returns:

• k (array of shape (nk, 3)) – k values of the k points contained in the file.

• weight (array of shape (nk,)) – weight of each k point

• nwf (array of shape (nspin, nk)) – number of wavefunctions that each kpoint(-spin) contains.

read_sizes()

Reads the sizes related to this WFSX file

Returns:

• int (number of spin components)

• int (number of orbitals in the unit-cell)

• int (number of k-points)

• bool (True if the file only contains the Gamma-point)

write(*args, **kwargs)

Generic write method which should be overloaded in child-classes

Parameters:

**kwargs – keyword arguments will try and search for the attribute write_ and call it with the remaining **kwargs as arguments.

yield_eigenstate()

Iterates over the states in the WFSX file

Yields:

EigenstateElectron

property base_file

File of the current Sile

property file

File of the current Sile

plot

Plotting functions for the wfsxSileSiesta class.