tbplas.SuperCell

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

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

Reduction

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.

Rules

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 ‘SuperCell’, they will be appended to hop_* arrays. The dr array will also be updated accordingly.

_hop_modifier

modification to hopping terms in the supercell

Type:: ‘IntraHopping’ instance

_orb_pos_modifier

modification to orbital positions in the supercell

Type:: function

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

Parameters:

prim_cell – primitive cell from which the supercell is constructed
dim – dimension of the supercell along a, b, and c directions
pbc – whether to enable periodic boundary condition along a, b and c directions
vacancies – indices of vacancies in primitive cell representation
orb_pos_modifier – modification to orbital positions in the supercell

Returns:

None

Raises:

SCDimLenError – if len(dim) != 2 or 3
SCDimSizeError – if dimension is smaller than minimal value
PBCLenError – if len(pbc) != 2 or 3
IDPCLenError – if any vacancy does not have right length
IDPCIndexError – if cell or orbital index of any vacancy is out of range

Methods

`__init__`(prim_cell, dim[, pbc, vacancies, ...])	param prim_cell: primitive cell from which the supercell is constructed
`add_hopping`(rn, orb_i, orb_j, energy)	Add a new term to the hopping modifier.
`add_subscriber`(sub_name, sub_obj)	Add a new subscriber.
`add_vacancies`(vacancies)	Add a list of vacancies to the orbital set.
`add_vacancy`(vacancy)	Wrapper over 'add_vacancies' to add a single vacancy to the orbital set.
`check_lock`()	Check the lock state of the object.
`get_hop`()	Get hopping indices, energies and distances.
`get_lattice_area`([direction])	Get the area formed by lattice vectors normal to given direction.
`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.
`get_orb_pos`()	Get positions of all orbitals in the supercell.
`get_reciprocal_vectors`()	Get the Cartesian coordinates of reciprocal lattice vectors in 1/NM.
`lock`(sub_name)	Lock the object.
`orb_id_pc2sc`(id_pc)	Convert orbital (NOT VACANCY) index from pc representation to sc representation.
`orb_id_pc2sc_array`(id_pc_array)	Convert an array of orbital (NOT VACANCY) indices from pc representation to sc representation.
`orb_id_sc2pc`(id_sc)	Convert orbital (NOT VACANCY) index from sc representation to pc representation.
`orb_id_sc2pc_array`(id_sc_array)	Convert an array of orbital (NOT VACANCY) indices from sc representation to pc representation.
`plot`(axes[, with_orbitals, with_cells, ...])	Plot lattice vectors, orbitals, and hopping terms to axes.
`set_orb_pos_modifier`([orb_pos_modifier])	Reset orb_pos_modifier.
`set_vacancies`([vacancies])	Reset the set of vacancies.
`sync_array`([force_sync])	Synchronize vac_id_sc and orb_id_pc according to primitive cell and vacancies.
`trim`()	Trim dangling orbitals and associated hopping terms.
`unlock`()	Unlock the object.
`update`()	Update all subscribers.

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.
`pc_hop_eng`	Get the energies of hopping terms of primitive cell.
`pc_hop_ind`	Get the indices of hopping terms of primitive cell.
`pc_lat_vec`	Get the lattice vectors of primitive cell.
`pc_orb_eng`	Get the energies of orbitals of primitive cell.
`pc_orb_pos`	Get the orbital positions of primitive cell.
`pc_origin`	Get the lattice origin of primitive cell.
`prim_cell`	Interface for the '_prim_cell' attribute.
`sc_lat_vec`	Get the lattice vectors of supercell.

__hash__() → int: Return the hash of this instance.

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

Parameters:

prim_cell – primitive cell from which the supercell is constructed
dim – dimension of the supercell along a, b, and c directions
pbc – whether to enable periodic boundary condition along a, b and c directions
vacancies – indices of vacancies in primitive cell representation
orb_pos_modifier – modification to orbital positions in the supercell

Returns:

None

Raises:

SCDimLenError – if len(dim) != 2 or 3
SCDimSizeError – if dimension is smaller than minimal value
PBCLenError – if len(pbc) != 2 or 3
IDPCLenError – if any vacancy does not have right length
IDPCIndexError – if cell or orbital index of any vacancy is out of range

add_hopping(rn: Union[Tuple[int, int], Tuple[int, int, int]], orb_i: int, orb_j: int, energy: complex) → None

Add a new term to the hopping modifier.

Parameters:

rn – cell index of the hopping term, i.e. R
orb_i – index of orbital i in <i,0|H|j,R>
orb_j – index of orbital j in <i,0|H|j,R>
energy – hopping integral in eV

Returns:

None

Raises:

LockError – if the supercell is locked
SCOrbIndexError – if orb_i or orb_j falls out of range
SCHopDiagonalError – if rn == (0, 0, 0) and orb_i == orb_j
CellIndexLenError – if len(rn) != 2 or 3

add_subscriber(sub_name: str, sub_obj: Any) → None

Add a new subscriber.

Parameters:

sub_name – subscriber name
sub_obj – subscriber object

Returns:

None

add_vacancies(vacancies: Union[Iterable[Tuple[int, int, int, int]], ndarray]) → None

Add a list of vacancies to the orbital set.

Parameters:

vacancies – list of (ia, ib, ic, io) or equivalent int32 arrays list of indices of vacancies in primitive cell representation

Returns:

None

Raises:

LockError – if the object is locked
IDPCLenError – if length of vacancy index is not 4
IDPCIndexError – if cell or orbital index of vacancy is out of range

add_vacancy(vacancy: Union[Tuple[int, int, int, int], ndarray]) → None

Wrapper over ‘add_vacancies’ to add a single vacancy to the orbital set.

Parameters:

vacancy – (ia, ib, ic, io) or equivalent int32 array vacancy index in primitive cell representation

Returns:

None

Raises:

LockError – if the object is locked
IDPCLenError – if length of vacancy index is not 4
IDPCIndexError – if cell or orbital index of vacancy is out of range

check_lock() → None

Check the lock state of the object.

Returns:: None
Raises:: LockError – if the object is locked

get_hop() → Tuple[ndarray, 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_j 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 dx and dy.

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

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

Get the area formed by lattice vectors normal to given direction.

Parameters:: 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.

Returns:: volume in NM^3

get_orb_eng() → ndarray

Get energies of all orbitals in the supercell.

Returns:: (num_orb_sc,) float64 array on-site energies of orbitals in the supercell in eV

get_orb_pos() → ndarray

Get positions of all orbitals in the supercell.

Returns:: (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.

Returns:: (3, 3) float64 array reciprocal vectors in 1/NM

lock(sub_name: str) → None

Lock the object. Modifications are not allowed then unless the ‘unlock’ method is called.

Parameters:: sub_name – identifier of the subscriber
Returns:: None
Raises:: ValueError – if sub_name is not in subscribers

orb_id_pc2sc(id_pc: Union[Tuple[int, int, int, int], ndarray]) → int

Convert orbital (NOT VACANCY) index from pc representation to sc representation.

NOTE: This method is safe, but EXTREMELY SLOW. If you are going to call this method many times, use orb_id_pc2sc_array instead.

Parameters:

id_pc – (ia, ib, ic, io), or equivalent int32 array index of orbital in primitive cell representation

Returns:

index of orbital in supercell representation

Raises:

IDPCLenError – if len(id_pc) != 4
IDPCIndexError – if cell or orbital index of id_pc is out of range
IDPCTypeError – if id_pc is not tuple or numpy array
IDPCVacError – if id_pc corresponds to a vacancy

orb_id_pc2sc_array(id_pc_array: ndarray) → ndarray

Convert an array of orbital (NOT VACANCY) indices from pc representation to sc representation.

Parameters:

id_pc_array – (num_orb, 4) int32 array orbital indices in primitive cell representation

Returns:

(num_orb,) int64 array orbital indices in supercell representation

Raises:

IDPCLenError – if id_pc_array.shape[1] != 4
IDPCIndexError – if any id_pc in id_pc_array is out of range
IDPCVacError – if any id_pc in id_pc_array is a vacancy

orb_id_sc2pc(id_sc: int) → ndarray

Convert orbital (NOT VACANCY) index from sc representation to pc representation.

NOTE: This method is safe, but EXTREMELY SLOW. If you are going to call this method many times, use orb_id_sc2pc_array instead.

Parameters:: id_sc – index of orbital in supercell representation
Returns:: (4,) int32 array index of orbital in primitive cell representation
Raises:: IDSCIndexError – if id_sc is out of range

orb_id_sc2pc_array(id_sc_array: ndarray) → ndarray

Convert an array of orbital (NOT VACANCY) indices from sc representation to pc representation.

Parameters:

id_sc_array – (num_orb,) int64 array orbital indices in supercell representation

Returns:

(num_orb, 4) int32 array orbital indices in primitive cell representation

Raises:

ValueError – if id_sc_array is not a vector
IDSCIndexError – if any id_sc in id_sc_array is out of range

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.

Parameters:

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

Returns:

None

Raises:

IDPCIndexError – if cell or orbital index of bra or ket in hop_modifier is out of range
IDPCVacError – if bra or ket in hop_modifier corresponds to a vacancy
ValueError – if view is illegal

set_orb_pos_modifier(orb_pos_modifier: Callable = None) → None

Reset orb_pos_modifier.

Parameters:: orb_pos_modifier – modifier to orbital positions
Returns:: None
Raises:: LockError – if the supercell is locked

set_vacancies(vacancies: Union[Iterable[Tuple[int, int, int, int]], ndarray] = None) → None

Reset the set of vacancies.

Parameters:

vacancies – list of (ia, ib, ic, io) or equivalent int32 arrays list of indices of vacancies in primitive cell representation

Returns:

None

Raises:

LockError – if the object is locked
IDPCLenError – if length of vacancy index is not 4
IDPCIndexError – if cell or orbital index of vacancy is out of range

sync_array(force_sync: bool = False) → None

Synchronize vac_id_sc and orb_id_pc according to primitive cell and vacancies.

NOTE: The core function ‘_id_pc2sc_vac’ requires vac_id_sc to be sorted in increasing order. Otherwise, it won’t work properly! So we must sort it here.

Parameters:

force_sync – whether to force synchronizing the arrays even if primitive cell and vacancy_set did not change

Returns:

None

Raises:

PCOrbEmptyError – if cell does not contain orbitals
PCHopEmptyError – if cell does not contain hopping terms

trim() → None

Trim dangling orbitals and associated hopping terms.

Returns:: None.
Raises:: LockError – if the object is locked

unlock() → None

Unlock the object. Modifications are allowed then.

Returns:: None

update() → None

Update all subscribers.

Returns:: None

__weakref__: list of weak references to the object (if defined)

property num_orb_pc: int

Get the number of orbitals of primitive cell.

Returns:: number of orbitals in primitive cell.

property num_orb_sc: int

Get the number of orbitals of supercell.

Returns:: number of orbitals in supercell

property num_vac: int

Get the number of vacancies of supercell.

Returns:: number of vacancies in supercell

property pc_hop_eng: ndarray

Get the energies of hopping terms of primitive cell.

Returns:: (num_hop_pc,) complex128 array hopping energies of primitive cell in eV

property pc_hop_ind: ndarray

Get the indices of hopping terms of primitive cell.

Returns:: (num_hop_pc, 5) int32 array indices of hopping terms of primitive cell

property pc_lat_vec: ndarray

Get the lattice vectors of primitive cell.

Returns:: (3, 3) float64 array lattice vectors of primitive cell in nm.

property pc_orb_eng: ndarray

Get the energies of orbitals of primitive cell.

Returns:: (num_orb_pc,) float64 array energies of orbitals of primitive cell in eV.

property pc_orb_pos: ndarray

Get the orbital positions of primitive cell.

Returns:: (num_orb_pc, 3) float64 array fractional positions of primitive cell

property pc_origin: ndarray

Get the lattice origin of primitive cell.

Returns:: (3,) float64 array lattice origin of primitive cell in NM

property prim_cell: PrimitiveCell

Interface for the ‘_prim_cell’ attribute.

Returns:: the primitive cell

property sc_lat_vec: ndarray

Get the lattice vectors of supercell.

Returns:: (3, 3) float64 array lattice vectors of primitive cell in nm.