sisl_toolbox.btd.DownfoldElectrode

class sisl_toolbox.btd.DownfoldElectrode

Bases: Electrode

Electrode downfolded through a region of H

The self-energy of electrode (any Electrode, also a DownfoldElectrode) is placed on elec of H, and is then downfolded through the region down to the last block of the region.

The electrode may be partially downfolded, i.e. part of elec may be in the last block (the device region). Then the electrode self-energy couples the downfolded electrode indices directly to the last block, and they must all be in the block before the last block. The self-energy of the electrode indices in the last block is added to the downfolded self-energy.

The rows of the returned self-energy are the orbitals of the last block, in the order they appear in the downfolding region (see orbs).

Indices are atoms, {"atoms": idx} (equivalent) or {"orbitals": idx} (not accounting for spin). Atoms are expanded to all their orbitals (in order).

Parameters:

electrode – the electrode being downfolded
H – Hamiltonian containing (at least) the downfolding region. Couplings along the semi-infinite directions of electrode are removed (on a copy), the electrode self-energy replaces them.
elec – indices of H corresponding to the rows of the electrode self-energy (in that order)
down –
the downfolding region of H, either
- a PermuteBTD: the region (including elec and the last block) in block-tri-diagonal order, the last block are the indices that the self-energy is downfolded to.
- an array: the indices of the region (including the downfolded part of elec, excluding the last block). The order and blocks are found from elec (see downfold_partition), and the last block are the indices of H coupling to the region (and the indices of elec not in down).
eta_device – imaginary part used in the downfolding region (for real energies)
bulk – whether the electrode region of H (the downfolded part of elec) is replaced by the bulk electrode matrix (Electrode.bulk_matrix). Couplings to the rest of H (including the electrode indices in the last block) are taken from H. Requires electrode.has_bulk.
name – name of the electrode, defaults to the electrode name (see Electrode)

Methods

`bulk_matrix`(E[, k, dtype, format])	Return \(E\mathbf S - \mathbf H\) of the bulk electrode
`from_fdf`(fdf, name[, prefix, mu, use_gf, ...])	Create the electrode from the `%block TS.Elec.<name>` in an fdf file
`se2broadening`(SE)	Convert the self-energy SE to the broadening matrix, see `Electrode.se2broadening` of electrode
`self_energy`(E[, k, dtype])	Return the downfolded self-energy

Attributes

`eta`	Imaginary part used for the self-energy calculation of electrode (if known)
`has_bulk`	Whether `bulk_matrix` is implemented for this electrode

classmethod from_fdf(fdf, name, prefix='TBT', mu=None, use_gf=False, downfold=True)

Create the electrode from the %block TS.Elec.<name> in an fdf file

The returned class depends on the content of the block:

a single semi-inf-direction (e.g. -a3) returns a BlochElectrode using a sisl.physics.RecursiveSI self-energy, or the GF file (when use_gf is true).
multiple semi-inf-direction (e.g. ab or abc) returns a RealSpaceElectrode using the GF file. This requires use_gf, since the real-space self-energy cannot be created from the fdf file (create a RealSpaceElectrode with a sisl.physics.RealSpaceSE instead).

When downfold is true, and the electrode is not (fully) in the device region, the above electrode is (partially) downfolded into the device region, and a DownfoldElectrode is returned. This reads the device Hamiltonian (TBT.HS) and the other electrodes (TS.Elecs) to determine the downfolding region, see downfold_partition and DeviceGreen.from_fdf for the fdf flags used. The downfolding region is found for atoms or orbitals according to the atom+/orb+ prefix of TBT.BTD.Pivot.Elec.<name> (or TBT.BTD.Pivot.Elecs), defaulting to atoms.

The electrode Hamiltonian is shifted by delta-Ef and the chemical potential. A GF file should already contain these shifts. File names are relative to the directory of the fdf file.

Other options from the fdf file are stored in the info attribute:

bulk: whether the electrode Hamiltonian is used in the electrode region (true), or the device Hamiltonian (false), in the downfolding region, or the device region (for electrodes fully in TBT.Atoms.Device)
dEf: the delta-Ef shift of the electrode Hamiltonian
mu: the chemical potential shift
chemical_potential: name of the chemical potential (or None)
position: the electrode-position value (or None)
V_fraction: the fraction of the bias in the electrode couplings
semi_inf: the semi-infinite directions (sisl notation, e.g. ["-c"])
na: number of atoms of the electrode in the device (including Bloch expansions)
gf: the GF file name (or None)

When downfold is true, the orbs attribute holds the orbitals of the device Hamiltonian where the self-energy is placed (the electrode orbitals for electrodes fully in the device region).

Parameters:

fdf (SileLike) – fdf file to read the parameters from
name (str) – name of the electrode, i.e. the block TS.Elec.<name>
prefix (Literal['TBT', 'TS']) – which prefix to use, if TBT it will prefer TBT prefix, but fall back to TS prefixes. If TS, only these prefixes will be used.
mu (Optional[float]) – chemical potential of the electrode [eV], if None it is read from the %block TS.ChemPot.<chemical-potential> (and the bias). As in TranSiesta, chemical-potential defaults to the only chemical potential in TS.ChemPots, or the one named as the electrode. Without TS.ChemPots, Left and Right are V/2 and -V/2. Without TBT.ChemPots (and TS.ChemPots) and no bias, TBtrans uses a single chemical potential at 0 for all electrodes.
use_gf (bool) – whether the self-energies are read from the GF file of the block (GF or TBT.Elec.<name>.GF), otherwise they are calculated in memory (the GF file is ignored). Electrodes without a GF file are always calculated in memory.
downfold (bool) – whether the electrode is downfolded into the device region (unless it is fully in the device region). Use false to get the electrode itself, e.g. for DeviceGreen.from_tbt.

Return type:

Electrode

bulk_matrix(E, k=(0, 0, 0), *, dtype=np.complex128, format='array', **kwargs)

Return \(E\mathbf S - \mathbf H\) of the bulk electrode

The rows (and columns) are the same as for self_energy. For real energies, eta is added to E. Only available when has_bulk is true.

Parameters:

E (complex) – energy
k (Sequence[float]) – k-point
dtype – data-type of the returned matrix
format (str) – format of the returned matrix, "array" for a dense matrix, or a sparse format (e.g. "csr"), see sisl.physics.Hamiltonian.Hk
**kwargs – passed to sisl.physics.Hamiltonian.Hk (e.g. spin)

se2broadening(SE)[source]

Convert the self-energy SE to the broadening matrix, see Electrode.se2broadening of electrode

Parameters:: SE (ndarray)
Return type:: ndarray

self_energy(E, k=(0, 0, 0), *, dtype=np.complex128, **kwargs)[source]

Return the downfolded self-energy

Parameters:

E (complex)
k (Sequence[float])

Return type:

ndarray

property eta: float | None: Imaginary part used for the self-energy calculation of electrode (if known)

property has_bulk: bool: Whether bulk_matrix is implemented for this electrode