sisl.io.tbtrans.tbtsencSileTBtrans

class sisl.io.tbtrans.tbtsencSileTBtrans(filename, mode='r', lvl=0, access=1, *args, **kwargs)

Bases: _devncSileTBtrans

TBtrans self-energy file object with downfolded self-energies to the device region

The \(\boldsymbol\Sigma\) object contains all self-energies on the specified k- and energy grid projected into the device region.

This is mainly an output file object from TBtrans and can be used as a post-processing utility for testing various things in Python.

Note that anything returned from this object are the self-energies in eV.

Examples

>>> H = Hamiltonian(device)
>>> se = tbtsencSileTBtrans(...)
>>> # Return the self-energy for the left electrode (unsorted)
>>> se_unsorted = se.self_energy('Left', 0.1, [0, 0, 0])
>>> # Return the self-energy for the left electrode (sorted)
>>> se_sorted = se.self_energy('Left', 0.1, [0, 0, 0], sort=True)
>>> # Query the indices in the full Hamiltonian
>>> pvt_unsorted = se.pivot('Left').reshape(-1, 1)
>>> pvt_sorted = se.pivot('Left', sort=True).reshape(-1, 1)
>>> # The following two lines are equivalent
>>> Hfull1[pvt_unsorted, pvt_unsorted.T] -= se_unsorted[:, :]
>>> Hfull2[pvt_sorted, pvt_sorted.T] -= se_sorted[:, :]
>>> np.allclose(Hfull1, Hfull2)
True
>>> # Query the indices in the device Hamiltonian
>>> dev_pvt = se.pivot('Left', in_device=True).reshape(-1, 1)
>>> dev_unpvt = se.pivot('Left', in_device=True, sort=True).reshape(-1, 1)
>>> Hdev_pvt[dev_pvt, dev_pvt.T] -= se_unsorted[:, :]
>>> Hdev[dpvt_sorted, dpvt_sorted.T] -= se_sorted[:, :]
>>> pvt_dev = se.pivot(in_device=True).reshape(-1, 1)
>>> np.allclose(Hdev_pvt, Hdev[pvt_dev, pvt_dev.T])
True

Plotting

`plot`	Plotting functions for the `tbtsencSileTBtrans` class.
`plot.geometry`(*args[, ...])	Calls `read_geometry` and creates a `GeometryPlot` from its output.

Methods

`Eindex`(E[, method])	Return the closest energy index corresponding to the energy `E`
`a2p`(atoms)	Return the pivoting orbital indices (0-based) for the atoms, possibly on an electrode
`a_down`(elec[, bulk])	Down-folding atomic indices for a given electrode
`a_elec`(elec)	Electrode atomic indices for the full geometry (sorted)
`base_directory`([relative_to])	Retrieve the base directory of the file, relative to the path relative_to
`bloch`(elec)	Bloch-expansion coefficients for an electrode
`broadening_matrix`(elec, E[, k, sort])	Return the broadening matrix from the electrode elec
`btd`([elec])	Block-sizes for the BTD method in the device/electrode region
`chemical_potential`(elec)	Return the chemical potential associated with the electrode elec
`close`()
`dir_file`([filename, filename_base])	File of the current Sile
`electron_temperature`(elec)	Electron bath temperature [Kelvin]
`eta`([elec])	The imaginary part used when calculating the self-energies in eV (or for the device
`info`([elec])	Information about the self-energy file available for extracting in this file
`iter`([group, dimension, variable, levels, root])	Iterator on all groups, variables and dimensions.
`kT`(elec)	Electron bath temperature [eV]
`kindex`(k)	Return the index of the k-point that is closests to the queried k-point (in reduced coordinates)
`mu`(elec)	Return the chemical potential associated with the electrode elec
`n_btd`([elec])	Number of blocks in the BTD partioning
`na_down`(elec)	Number of atoms in the downfolding region (without device downfolded region)
`no_down`(elec)	Number of orbitals in the downfolding region (plus device downfolded region)
`no_e`(elec)	Number of orbitals in the downfolded region of the electrode in the device
`o2p`(orbitals[, elec])	Return the pivoting indices (0-based) for the orbitals, possibly on an electrode
`pivot`([elec, in_device, sort])	Return the pivoting indices for a specific electrode (in the device region) or the device
`pivot_down`(elec)	Pivoting orbitals for the downfolding region of a given electrode
`read`(args, *kwargs)	Generic read method which should be overloaded in child-classes
`read_geometry`(args, *kwargs)	Returns Geometry object from this file
`read_lattice`()	Returns Lattice object from this file
`self_energy`(elec, E[, k, sort])	Return the self-energy from the electrode elec
`self_energy_average`(elec, E[, sort])	Return the k-averaged average self-energy from the electrode elec
`write`(args, *kwargs)	Generic write method which should be overloaded in child-classes

Attributes

`E`	Sampled energy-points in file
`a_buf`	Atomic indices (0-based) of device atoms
`a_dev`	Atomic indices (0-based) of device atoms (sorted)
`base_file`	File of the current Sile
`cell`	Unit cell in file
`elecs`	List of electrodes
`file`	File of the current Sile
`geom`	Same as `geometry`, but deprecated
`geometry`	The associated geometry from this file
`k`	Sampled k-points in file
`kpt`	Sampled k-points in file
`lasto`	Last orbital of corresponding atom
`nE`	Number of energy-points in file
`na`	Returns number of atoms in the cell
`na_b`	Number of atoms in the buffer region
`na_buffer`	Number of atoms in the buffer region
`na_d`	Number of atoms in the device region
`na_dev`	Number of atoms in the device region
`na_u`	Returns number of atoms in the cell
`ne`	Number of energy-points in file
`nk`	Number of k-points in file
`nkpt`	Number of k-points in file
`no`	Returns number of orbitals in the cell
`no_d`	Number of orbitals in the device region
`no_u`	Returns number of orbitals in the cell
`o_dev`	Orbital indices (0-based) of device orbitals (sorted)
`wk`	Weights of k-points in file
`wkpt`	Weights of k-points in file
`xa`	Atomic coordinates in file
`xyz`	Atomic coordinates in file

Eindex(E: Etype, method: Literal['nearest', 'above', 'below'] = 'nearest')

Return the closest energy index corresponding to the energy E

Parameters:

E – if int, return it-self, else return the energy index which is closests to the energy. For a str it will be parsed to a float and treated as such.
method – how non-equal values should be located. * nearest takes the closests value * above takes the closests value above E. * below takes the closests value below E.

a2p(atoms)

Return the pivoting orbital indices (0-based) for the atoms, possibly on an electrode

This is equivalent to:

>>> p = self.o2p(self.geometry.a2o(atom, True))

Will warn if an atom requested is not in the device list of atoms.

Parameters:: atoms (array_like or int) – atomic indices (0-based)

a_down(elec: str | int, bulk: bool = False)

Down-folding atomic indices for a given electrode

Parameters:

elec – electrode to retrieve indices for
bulk – whether the returned indices are only in the pristine electrode, or the down-folding region (electrode + downfolding region, not in device)

a_elec(elec: str | int)

Electrode atomic indices for the full geometry (sorted)

Parameters:: elec – electrode to retrieve indices for

base_directory(relative_to='.'): Retrieve the base directory of the file, relative to the path relative_to

bloch(elec: str | int)

Bloch-expansion coefficients for an electrode

Parameters:: elec – bloch expansions of electrode

broadening_matrix(elec, E, k=0, sort=False)[source]

Return the broadening matrix from the electrode elec

The broadening matrix is calculated as:

\[\boldsymbol \Gamma(E) = i [\boldsymbol\Sigma(E) - \boldsymbol\Sigma^\dagger(E)]\]

Parameters:

elec (str or int) – the corresponding electrode to return the broadening matrix from
E (float or int) – energy to retrieve the broadening matrix at, if a floating point the closest energy value will be found and returned, if an integer it will correspond to the exact index
k (array_like or int) – k-point to retrieve, if an integer it is the k-index in the file
sort (bool, optional) – if True the returned broadening matrix will be sorted according to the order of the orbitals in the non-pivoted geometry, otherwise the broadening matrix will be returned according to the pivoted orbitals in the device region.

btd(elec: int | str | None = None)

Block-sizes for the BTD method in the device/electrode region

Parameters:: elec – the BTD block sizes for the device (if none), otherwise the downfolding BTD block sizes for the electrode

chemical_potential(elec: str | int) → float: Return the chemical potential associated with the electrode elec

close()

dir_file(filename=None, filename_base=''): File of the current Sile

electron_temperature(elec: str | int) → float

Electron bath temperature [Kelvin]

Parameters:: elec – electrode to extract the temperature from

See also

kT: bath temperature in [eV]

eta(elec: int | str | None = None) → float

The imaginary part used when calculating the self-energies in eV (or for the device

Parameters:: elec – electrode to extract the eta value from. If not specified (or None) the device region eta will be returned.

info(elec=None)[source]

Information about the self-energy file available for extracting in this file

Parameters:: elec (str or int) – the electrode to request information from

iter(group=True, dimension=True, variable=True, levels=-1, root=None)

Iterator on all groups, variables and dimensions.

This iterator iterates through all groups, variables and dimensions in the Dataset

The generator sequence will _always_ be:

Group

Dimensions in group

Variables in group

As the dimensions are generated before the variables it is possible to copy groups, dimensions, and then variables such that one always ensures correct dependencies in the generation of a new SileCDF.

Parameters:

group (bool (True)) – whether the iterator yields Group instances
dimension (bool (True)) – whether the iterator yields Dimension instances
variable (bool (True)) – whether the iterator yields Variable instances
levels (int (-1)) – number of levels to traverse, with respect to root variable, i.e. number of sub-groups this iterator will return.
root (str (None)) – the base root to start iterating from.

Examples

Script for looping and checking each instance.

>>> for gv in self.iter():
...     if self.isGroup(gv):
...         # is group
...     elif self.isDimension(gv):
...         # is dimension
...     elif self.isVariable(gv):
...         # is variable

kT(elec: str | int) → float

Electron bath temperature [eV]

Parameters:: elec – electrode to extract the temperature from

See also

electron_temperature: bath temperature in [K]

kindex(k)

Return the index of the k-point that is closests to the queried k-point (in reduced coordinates)

Parameters:: k (array_like of float or int) – the queried k-point in reduced coordinates \(]-0.5;0.5]\). If int return it-self.

mu(elec: str | int) → float: Return the chemical potential associated with the electrode elec

n_btd(elec: int | str | None = None) → int

Number of blocks in the BTD partioning

Parameters:: elec – if None the number of blocks in the device region BTD matrix. Else the number of BTD blocks in the electrode down-folding.

na_down(elec: str | int) → int

Number of atoms in the downfolding region (without device downfolded region)

Parameters:: elec – Number of downfolding atoms for electrode elec

no_down(elec: str | int) → int

Number of orbitals in the downfolding region (plus device downfolded region)

Parameters:: elec – Number of downfolding orbitals for electrode elec

no_e(elec: str | int) → int

Number of orbitals in the downfolded region of the electrode in the device

Parameters:: elec – Specify the electrode to query number of downfolded orbitals

o2p(orbitals, elec: int | str | None = None)

Return the pivoting indices (0-based) for the orbitals, possibly on an electrode

Will warn if an orbital requested is not in the device list of orbitals.

Parameters:

orbitals (array_like or int) – orbital indices (0-based)
elec – electrode to return pivoting indices of (if None it is the device pivoting indices).

pivot(elec: int | str | None = None, in_device: bool = False, sort: bool = False)

Return the pivoting indices for a specific electrode (in the device region) or the device

Parameters:

elec – Can be None, to specify the device region pivot indices (default). Otherwise, it corresponds to the pivoting indicies in the downfolding region.
in_device – If True the pivoting table will be translated to the device region orbitals. If sort is also true, this would correspond to the orbitals directly translated to the geometry self.geometry.sub(self.a_dev).
sort – Whether the returned indices are sorted. Mostly useful if you want to handle the device in a non-pivoted order.

Examples

>>> se = tbtncSileTBtrans(...)
>>> se.pivot()
[3, 4, 6, 5, 2]
>>> se.pivot(sort=True)
[2, 3, 4, 5, 6]
>>> se.pivot(0)
[2, 3]
>>> se.pivot(0, in_device=True)
[4, 0]
>>> se.pivot(0, in_device=True, sort=True)
[0, 1]
>>> se.pivot(0, sort=True)
[2, 3]

See also

pivot_down: for the pivot table for electrodes down-folding regions

pivot_down(elec: str | int)

Pivoting orbitals for the downfolding region of a given electrode

Parameters:: elec – the corresponding electrode to get the pivoting indices for

plot.geometry(*args, data_kwargs={}, axes: Axes = ['x', 'y', 'z'], atoms: AtomsIndex = None, atoms_style: Sequence[AtomsStyleSpec] = [], atoms_scale: float = 1.0, atoms_colorscale: Colorscale | None = None, drawing_mode: Literal['scatter', 'balls', None] = None, bind_bonds_to_ats: bool = True, points_per_bond: int = 20, bonds_style: StyleSpec = {}, bonds_scale: float = 1.0, bonds_colorscale: Colorscale | None = None, show_atoms: bool = True, show_bonds: bool = True, show_cell: Literal['box', 'axes', False] = 'box', cell_style: StyleSpec = {}, nsc: tuple[int, int, int] = (1, 1, 1), atoms_ndim_scale: tuple[float, float, float] = (16, 16, 1), bonds_ndim_scale: tuple[float, float, float] = (1, 1, 10), dataaxis_1d: np.ndarray | Callable | None = None, arrows: Sequence[AtomArrowSpec] = (), backend='plotly') → GeometryPlot

Calls read_geometry and creates a GeometryPlot from its output.

Parameters:

axes – The axes to project the geometry to.
atoms – The atoms to plot. If None, all atoms are plotted.
atoms_style – List of style specifications for the atoms. See the showcase notebooks for examples.
atoms_scale – Scaling factor for the size of all atoms.
atoms_colorscale – Colorscale to use for the atoms in case the color attribute is an array of values. If None, the default colorscale is used for each backend.
drawing_mode – The method used to draw the atoms.
bind_bonds_to_ats – Whether to display only bonds between atoms that are being displayed.
points_per_bond – When the points are drawn using points instead of lines (e.g. in some frameworks to draw multicolor bonds), the number of points used per bond.
bonds_style – Style specification for the bonds. See the showcase notebooks for examples.
bonds_scale – Scaling factor for the width of all bonds.
bonds_colorscale – Colorscale to use for the bonds in case the color attribute is an array of values. If None, the default colorscale is used for each backend.
show_atoms – Whether to display the atoms.
show_bonds – Whether to display the bonds.
show_cell – Mode to display the cell. If False, the cell is not displayed.
cell_style – Style specification for the cell. See the showcase notebooks for examples.
nsc – Number of unit cells to display in each direction.
atoms_ndim_scale – Scaling factor for the size of the atoms for different dimensionalities (1D, 2D, 3D).
bonds_ndim_scale – Scaling factor for the width of the bonds for different dimensionalities (1D, 2D, 3D).
dataaxis_1d – Only meaningful for 1D plots. The data to plot on the Y axis.
arrows – List of arrow specifications to display. See the showcase notebooks for examples.
backend – The backend to use to generate the figure.

See also

GeometryPlot: The plot class used to generate the plot.
read_geometry: The method called to get the data.

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_geometry(*args, **kwargs): Returns Geometry object from this file

read_lattice() → Lattice: Returns Lattice object from this file

self_energy(elec, E, k=0, sort=False)[source]

Return the self-energy from the electrode elec

Parameters:

elec (str or int) – the corresponding electrode to return the self-energy from
E (float or int) – energy to retrieve the self-energy at, if a floating point the closest energy value will be found and returned, if an integer it will correspond to the exact index
k (array_like or int) – k-point to retrieve, if an integer it is the k-index in the file
sort (bool, optional) – if True the returned self-energy will be sorted according to the order of the orbitals in the non-pivoted geometry, otherwise the self-energy will be returned according to the pivoted orbitals in the device region.

self_energy_average(elec, E, sort=False)[source]

Return the k-averaged average self-energy from the electrode elec

Parameters:

elec (str or int) – the corresponding electrode to return the self-energy from
E (float or int) – energy to retrieve the self-energy at, if a floating point the closest energy value will be found and returned, if an integer it will correspond to the exact index
sort (bool, optional) – if True the returned self-energy will be sorted according to the order of the orbitals in the non-pivoted geometry, otherwise the self-energy will be returned according to the pivoted orbitals in the device region.

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.

property E: ndarray: Sampled energy-points in file

property a_buf: Atomic indices (0-based) of device atoms

property a_dev: Atomic indices (0-based) of device atoms (sorted)

property base_file: File of the current Sile

property cell: ndarray: Unit cell in file

property elecs: List of electrodes

property file: File of the current Sile

property geom: Same as geometry, but deprecated

property geometry: Geometry: The associated geometry from this file

property k: ndarray: Sampled k-points in file

property kpt: ndarray: Sampled k-points in file

property lasto: ndarray: Last orbital of corresponding atom

property nE: int: Number of energy-points in file

property na: int: Returns number of atoms in the cell

property na_b: int: Number of atoms in the buffer region

property na_buffer: int: Number of atoms in the buffer region

property na_d: int: Number of atoms in the device region

property na_dev: int: Number of atoms in the device region

property na_u: int: Returns number of atoms in the cell

property ne: int: Number of energy-points in file

property nk: int: Number of k-points in file

property nkpt: int: Number of k-points in file

property no: int: Returns number of orbitals in the cell

property no_d: int: Number of orbitals in the device region

property no_u: int: Returns number of orbitals in the cell

property o_dev

Orbital indices (0-based) of device orbitals (sorted)

See also

pivot: retrieve the device orbitals, non-sorted

plot: Plotting functions for the tbtsencSileTBtrans class.

property wk: ndarray: Weights of k-points in file

property wkpt: ndarray: Weights of k-points in file

property xa: ndarray: Atomic coordinates in file

property xyz: ndarray: Atomic coordinates in file