tbplas.SuperCell

class tbplas.SuperCell(prim_cell: PrimitiveCell, dim: Tuple[int, int] | Tuple[int, int, int], pbc: Tuple[bool, bool] | Tuple[bool, bool, bool] = (False, False, False), check_dim: bool = True, vacancies: Iterable[int] | ndarray = None, orb_pos_modifier: Callable[[ndarray], None] = None)

Class for representing a supercell from which the sample is constructed.

_prim_cell

primitive cell from which the supercell is constructed

Type:: ‘PrimitiveCell’ instance

_dim

dimension of the supercell along a, b, and c directions

Type:: (3, ) int32 array

_pbc

whether to enable periodic condition along a, b, and c directions 0 for False, 1 for True.

Type:: (3, ) int32 array

_vacancy_set

indices of vacancies in supercell representation

Type:: Set[int]

_cached_data

cached array attributes

Type:: ‘SCCachedData’

_hop_modifier

modification to hopping terms in the supercell

Type:: ‘IntraHopping’ instance

_orb_pos_modifier

modification to orbital positions in the supercell

Type:: function

Notes

Minimal supercell dimension of single-orbital primitive cell

Assume that we have a primitive cell located at R=0. The furthest primitive cell between which hopping terms exist is located at R=N. It can be proved that if the dimension of supercell along that direction is less than N, the same matrix element hij will appear more than one time in hop_ind and hop_eng of ‘SuperCell’ class, as well as its conjugate counterpart. This will complicate the program and significantly slow it down, which situation we must avoid.

Further, if the dimension of supercell falls in [N, 2*N], hij will appear only one time, yet its conjugate counterpart still exists. Although no problems have been found so far, we still need to avoid this situation.

So the minimal dimension of supercell is 2*N+1, where N is the index of the furthest primitive cell between which hopping terms exists. Otherwise, the ‘SuperCell’ class, as well as the core functions of ‘_get_num_hop_sc’ and ‘build_hop’ will not work properly.

In the hr.dat file produced by Wannier90, there is an N_min and an N_max for the furthest primitive cell index. In that case, N should be the maximum of |N_max| and |N_min| as the result of translational symmetry.

For a multiple-orbital primitive cell, the minimal supercell dimension may be not that large. We may even build a 1*1*1 supercell. Call the ‘check_dim’ method of ‘PrimitiveCell’ class to check if this is possible.

hop_modifier

We reduce hopping terms according to the conjugate relation: <0, bra|H|R, ket> = <0, ket|H|-R, bra>*.

So actually only half of hopping terms are stored.

If the hopping terms claimed here are already included in the supercell, they will overwrite the existing terms. If the hopping terms or their conjugate counterparts are new to the supercell, they will be added to hop_* arrays. The dr array will also be updated accordingly.

__init__(prim_cell: PrimitiveCell, dim: Tuple[int, int] | Tuple[int, int, int], pbc: Tuple[bool, bool] | Tuple[bool, bool, bool] = (False, False, False), check_dim: bool = True, vacancies: Iterable[int] | ndarray = None, orb_pos_modifier: Callable[[ndarray], None] = None) → None

NOTE: The indices of vacancies are always defined with respect to the pristine supercell, i.e., supercell without any vacancies. For example, for a pristine supercell with 18 orbitals, vacancies [0, 1] will remove the first 2 orbitals, yielding a supercell with 16 orbitals. For the 16 orbital supercell, add_vacancies([0, 1]) or set_vacancies([0, 1]) will add any new vacancies, since [0, 1] are defined w.r.t pristine supercell, and have already been declared as vacancies. This rule also applies to trim(). :param prim_cell: primitive cell from which the supercell is constructed :param dim: dimension of the supercell along a, b and c directions :param pbc: whether to enable periodic boundary condition along a, b,

and c directions

Parameters:

check_dim – whether to check supercell dimension using the single-orbital rule
vacancies – list or equivalent int64 array of indices of vacancies in supercell representation
orb_pos_modifier – modification to orbital positions in the supercell

Methods

`__init__`(prim_cell, dim[, pbc, check_dim, ...])	NOTE: The indices of vacancies are always defined with respect to the pristine supercell, i.e., supercell without any vacancies. For example, for a pristine supercell with 18 orbitals, vacancies [0, 1] will remove the first 2 orbitals, yielding a supercell with 16 orbitals. For the 16 orbital supercell, add_vacancies([0, 1]) or set_vacancies([0, 1]) will add any new vacancies, since [0, 1] are defined w.r.t pristine supercell, and have already been declared as vacancies. This rule also applies to trim(). :param prim_cell: primitive cell from which the supercell is constructed :param dim: dimension of the supercell along a, b and c directions :param pbc: whether to enable periodic boundary condition along a, b, and c directions :param check_dim: whether to check supercell dimension using the single-orbital rule :param vacancies: list or equivalent int64 array of indices of vacancies in supercell representation :param orb_pos_modifier: modification to orbital positions in the supercell.
`add_hopping`(rn, orb_i, orb_j, energy)	Add a new term to the hopping modifier.
`add_subscriber`(sub)	Add a subscriber :param sub: the new subscriber :return: None
`add_vacancies`(vacancies)	Add a list of vacancies to the orbital set.
`check_editable`()	Check if the object is unlocked for modification.
`get_array`([with_orb_eng, with_orb_pos, with_hop])	Get all arrays in a single call.
`get_hop`()	Get hopping indices, energies and distances.
`get_lattice_area`([direction])	Get the area formed by lattice vectors normal to given direction. :param direction: direction of area, e.g. "c" indicates the area formed by lattice vectors in the aOb plane. :return: area formed by lattice vectors in NM^2.
`get_lattice_volume`()	Get the volume formed by all three lattice vectors in NM^3.
`get_orb_eng`()	Get energies of all orbitals in the supercell. :return: (num_orb_sc,) float64 array on-site energies of orbitals in the supercell in eV.
`get_orb_map`()	Get the orbital map for indexing orbitals.
`get_orb_pos`()	Get positions of all orbitals in the supercell. :return: (num_orb_sc, 3) float64 array Cartesian coordinates of orbitals in the supercell in nm.
`get_reciprocal_vectors`()	Get the Cartesian coordinates of reciprocal lattice vectors in 1/NM. :return: (3, 3) float64 array reciprocal vectors in 1/NM.
`lock`()	Lock the object.
`plot`(axes[, with_orbitals, with_cells, ...])	Plot lattice vectors, orbitals, and hopping terms to axes. :param axes: axes on which the figure will be plotted :param with_orbitals: whether to plot orbitals as filled circles :param with_cells: whether to plot borders of primitive cells :param with_conj: whether to plot conjugate hopping terms as well :param orb_color: function for coloring the orbitals :param hop_as_arrows: whether to plot hopping terms as arrows :param hop_eng_cutoff: cutoff for showing hopping terms :param hop_color: color of hopping terms :param view: kind of view point, should be in 'ab', 'bc', 'ca', 'ba', 'cb', 'ac' :return: None.
`set_orb_pos_modifier`([orb_pos_modifier])	Reset orb_pos_modifier.
`set_vacancies`(vacancies)	Reset the set of vacancies.
`trim`()	Trim dangling orbitals and associated hopping terms.
`unlock`()	Unlock the object.
`update`()	Call subscribers to update their data.

Attributes

`num_orb_pc`	Get the number of orbitals of primitive cell.
`num_orb_sc`	Get the number of orbitals of supercell.
`num_vac`	Get the number of vacancies of supercell.
`prim_cell`	Interface for the '_prim_cell' attribute.
`sc_lat_vec`	Get the lattice vectors of supercell. :return: (3, 3) float64 array lattice vectors of primitive cell in nm.

__hash__() → int: Return hash(self).

__init__(prim_cell: PrimitiveCell, dim: Tuple[int, int] | Tuple[int, int, int], pbc: Tuple[bool, bool] | Tuple[bool, bool, bool] = (False, False, False), check_dim: bool = True, vacancies: Iterable[int] | ndarray = None, orb_pos_modifier: Callable[[ndarray], None] = None) → None

NOTE: The indices of vacancies are always defined with respect to the pristine supercell, i.e., supercell without any vacancies. For example, for a pristine supercell with 18 orbitals, vacancies [0, 1] will remove the first 2 orbitals, yielding a supercell with 16 orbitals. For the 16 orbital supercell, add_vacancies([0, 1]) or set_vacancies([0, 1]) will add any new vacancies, since [0, 1] are defined w.r.t pristine supercell, and have already been declared as vacancies. This rule also applies to trim(). :param prim_cell: primitive cell from which the supercell is constructed :param dim: dimension of the supercell along a, b and c directions :param pbc: whether to enable periodic boundary condition along a, b,

and c directions

Parameters:

check_dim – whether to check supercell dimension using the single-orbital rule
vacancies – list or equivalent int64 array of indices of vacancies in supercell representation
orb_pos_modifier – modification to orbital positions in the supercell

add_hopping(rn: Tuple[int, int] | Tuple[int, int, int], orb_i: int, orb_j: int, energy: complex) → None: Add a new term to the hopping modifier. :param rn: cell index of the hopping term, i.e. R :param orb_i: index of orbital i in <i,0|H|j,R> :param orb_j: index of orbital j in <i,0|H|j,R> :param energy: hopping integral in eV :return: None

add_subscriber(sub: Any) → None: Add a subscriber :param sub: the new subscriber :return: None

add_vacancies(vacancies: Iterable[int] | ndarray) → None

Add a list of vacancies to the orbital set.

NOTE: see __init__ for the rule of indices of vacancies.

Parameters:: vacancies – list or equivalent int64 array of id_sc list of indices of vacancies in supercell representation
Returns:: None

check_editable() → None: Check if the object is unlocked for modification. :return: None

get_array(with_orb_eng: bool = True, with_orb_pos: bool = True, with_hop: bool = True) → namedtuple: Get all arrays in a single call. :param with_orb_eng: whether to include orb_eng in result :param with_orb_pos: whether to include orb_pos in result :param with_hop: whether to include hop_ind, hop_end and dr in result :return: namedtuple with arrays as attributes

get_hop() → Tuple[ndarray, ndarray, ndarray]

Get hopping indices, energies and distances.

The hopping terms will be reduced by conjugate relation. So only half of them will be returned as results.

If periodic conditions are enabled, orbital indices in hop_ind[:, 1] may be wrapped back if it falls out of the supercell. Nevertheless, the distances in dr are still the ones before wrapping. This is essential for adding magnetic field, calculating band structure and many properties involving dr.

Returns:: (hop_ind, hop_eng, dr) hop_ind: (num_hop_sc, 2) int64 array row and column indices of hopping terms reduced by conjugate relation hop_eng: (num_hop_sc,) complex128 array energies of hopping terms in accordance with hop_ind in eV dr: (num_hop_sc, 3) float64 array distances of hopping terms in accordance with hop_ind in nm

get_lattice_area(direction: str = 'c') → float

Get the area formed by lattice vectors normal to given direction. :param direction: direction of area, e.g. “c” indicates the area formed

by lattice vectors in the aOb plane.

Returns:: area formed by lattice vectors in NM^2

get_lattice_volume() → float: Get the volume formed by all three lattice vectors in NM^3. :return: volume in NM^3

get_orb_eng() → ndarray: Get energies of all orbitals in the supercell. :return: (num_orb_sc,) float64 array

on-site energies of orbitals in the supercell in eV

get_orb_map() → RegularOrbitalMapVac

Get the orbital map for indexing orbitals.

NOTE: This function should be called everytime after the supercell changes. DO NOT reuse the result of last call, as its array attributes may be out of date.

Returns:: orbital map

get_orb_pos() → ndarray: Get positions of all orbitals in the supercell. :return: (num_orb_sc, 3) float64 array

Cartesian coordinates of orbitals in the supercell in nm

get_reciprocal_vectors() → ndarray: Get the Cartesian coordinates of reciprocal lattice vectors in 1/NM. :return: (3, 3) float64 array

reciprocal vectors in 1/NM

lock() → None: Lock the object. Modifications are not allowed then unless the ‘unlock’ method is called. :return: None

plot(axes: Axes, with_orbitals: bool = True, with_cells: bool = True, with_conj: bool = False, orb_color: Callable[[ndarray], List[str]] = None, hop_as_arrows: bool = True, hop_eng_cutoff: float = 1e-05, hop_color: str = 'r', view: str = 'ab') → None

Plot lattice vectors, orbitals, and hopping terms to axes. :param axes: axes on which the figure will be plotted :param with_orbitals: whether to plot orbitals as filled circles :param with_cells: whether to plot borders of primitive cells :param with_conj: whether to plot conjugate hopping terms as well :param orb_color: function for coloring the orbitals :param hop_as_arrows: whether to plot hopping terms as arrows :param hop_eng_cutoff: cutoff for showing hopping terms :param hop_color: color of hopping terms :param view: kind of view point, should be in ‘ab’, ‘bc’, ‘ca’, ‘ba’,

‘cb’, ‘ac’

Returns:: None

set_orb_pos_modifier(orb_pos_modifier: Callable = None) → None: Reset orb_pos_modifier. :param orb_pos_modifier: modifier to orbital positions :return: None

set_vacancies(vacancies: Iterable[int] | ndarray) → None

Reset the set of vacancies.

NOTE: see __init__ for the rule of indices of vacancies.

Parameters:: vacancies – list or equivalent int64 array of id_sc list of indices of vacancies in supercell representation
Returns:: None

trim() → None

Trim dangling orbitals and associated hopping terms.

NOTE: see __init__ for the rule of indices of vacancies.

Returns:: None.

unlock() → None: Unlock the object. Modifications are allowed then. :return: None

update() → None: Call subscribers to update their data. :return: None

__weakref__: list of weak references to the object

property num_orb_pc: int: Get the number of orbitals of primitive cell. :return: number of orbitals in primitive cell.

property num_orb_sc: int: Get the number of orbitals of supercell. :return: number of orbitals in supercell

property num_vac: int: Get the number of vacancies of supercell. :return: number of vacancies in supercell

property prim_cell: PrimitiveCell: Interface for the ‘_prim_cell’ attribute. :return: the primitive cell

property sc_lat_vec: ndarray: Get the lattice vectors of supercell. :return: (3, 3) float64 array

lattice vectors of primitive cell in nm.