tbplas.SCInterHopping

class tbplas.SCInterHopping(sc_bra: SuperCell, sc_ket: SuperCell)

Container class for hopping terms between different supercells within the sample.

_sc_bra

the ‘bra’ supercell from which the hopping terms exist

Type:

‘SuperCell’ instance

_sc_ket

the ‘ket’ supercell to which the hopping terms exist

Type:

‘SuperCell’ instance

Notes

  1. Reduction

Since inter-hopping terms exist within different super-cells, there is no need to reduce them according to the conjugate relation.

  1. Rules

We restrict hopping terms to be from the (0, 0, 0) ‘bra’ supercell to any ‘ket’ supercell. The counterparts are restored via the conjugate relation:

<bra, R0, i|H|ket, Rn, j> = <ket, R0, j|H|bra, -Rn, i>*

__init__(sc_bra: SuperCell, sc_ket: SuperCell) None
Parameters:
  • sc_bra – the ‘bra’ supercell from which the hopping terms exist

  • sc_ket – the ‘ket’ supercell to which the hopping terms exist

Methods

__init__(sc_bra, sc_ket)

param sc_bra:

the 'bra' supercell from which the hopping terms exist

add_hopping(rn, orb_i, orb_j, energy)

Add a new hopping term or update existing term.

add_subscriber(sub_name, sub_obj)

Add a new subscriber.

check_lock()

Check the lock state of the object.

get_hop([check_dup])

Get hopping indices, energies and distances.

get_hopping(rn, orb_i, orb_j)

Get an existing hopping term.

lock(sub_name)

Lock the object.

plot(axes[, with_conj, hop_as_arrows, ...])

Plot hopping terms to axes.

purge()

Remove empty cell indices.

remove_hopping(rn, orb_i, orb_j)

Remove an existing hopping term.

remove_orbital(orb_i)

Wrapper over 'remove_orbitals' to remove a single orbital.

remove_orbitals(indices)

Remove the hopping terms corresponding to a list of orbitals and update remaining hopping terms.

remove_rn(rn)

Remove all the hopping terms of given cell index.

sync_array(**kwargs)

Abstract interface for 'sync_array' method of derived classes.

to_array([use_int64])

Convert hopping terms to array of 'hop_ind' and 'hop_eng', for constructing attributes of 'PrimitiveCell' or 'Sample'.

to_list()

Flatten all hopping terms into a list.

unlock()

Unlock the object.

update()

Update all subscribers.

Attributes

cell_indices

Get the list of cell indices.

hoppings

Interface for the '__hoppings' attribute.

num_hop

Count the number of hopping terms.

sc_bra

Interface for the '_sc_bra' attribute.

sc_ket

Interface for the '_sc_ket' attribute.

__hash__() int

Return the hash of this instance.

__init__(sc_bra: SuperCell, sc_ket: SuperCell) None
Parameters:
  • sc_bra – the ‘bra’ supercell from which the hopping terms exist

  • sc_ket – the ‘ket’ supercell to which the hopping terms exist

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

Add a new hopping term or update existing term.

Parameters:
  • rn – (r_a, r_b, r_c), cell index

  • orb_i – orbital index or bra

  • orb_j – orbital index of ket

  • energy – hopping energy

Returns:

None

Raises:

LockError – is the object is locked

add_subscriber(sub_name: str, sub_obj: Any) None

Add a new subscriber.

Parameters:
  • sub_name – subscriber name

  • sub_obj – subscriber object

Returns:

None

check_lock() None

Check the lock state of the object.

Returns:

None

Raises:

LockError – if the object is locked

get_hop(check_dup: bool = False) Tuple[ndarray, ndarray, ndarray, ndarray]

Get hopping indices, energies and distances.

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.

Parameters:

check_dup – whether to check for duplicate hopping terms in the results

Returns:

(hop_i, hop_j, hop_v, dr) hop_i: (num_hop,) int64 array row indices of hopping terms hop_j: (num_hop,) int64 array column indices of hopping terms hop_v: (num_hop,) complex128 array energies of hopping terms in accordance with hop_i and hop_j in eV dr: (num_hop, 3) float64 array distances of hopping terms in accordance with hop_i and hop_j in nm

Raises:
  • InterHopVoidError – if no hopping terms have been added to the instance

  • ValueError – if duplicate terms have been detected

get_hopping(rn: Union[Tuple[int, int], Tuple[int, int, int]], orb_i: int, orb_j: int) Tuple[complex, bool]

Get an existing hopping term.

Parameters:
  • rn – (r_a, r_b, r_c), cell index

  • orb_i – orbital index or bra

  • orb_j – orbital index of ket

Returns:

(energy, status) where energy is the hopping energy and status is the flag whether the term has been found

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

plot(axes: Axes, with_conj: bool = False, hop_as_arrows: bool = True, hop_eng_cutoff: float = 1e-05, hop_color: str = 'r', view: str = 'ab') None

Plot hopping terms to axes.

Parameters:
  • axes – axes on which the figure will be plotted

  • with_conj – whether to plot conjugate hopping terms as well

  • 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:
  • InterHopVoidError – if no hopping terms have been added to the instance

  • ValueError – if view is illegal

purge() None

Remove empty cell indices.

Returns:

None

remove_hopping(rn: Union[Tuple[int, int], Tuple[int, int, int]], orb_i: int, orb_j: int) bool

Remove an existing hopping term.

Parameters:
  • rn – (r_a, r_b, r_c), cell index

  • orb_i – orbital index or bra

  • orb_j – orbital index of ket

Returns:

where the hopping term is removed, False if not found

remove_orbital(orb_i: int) None

Wrapper over ‘remove_orbitals’ to remove a single orbital.

Parameters:

orb_i – orbital index to remove

Returns:

None

Raises:

LockError – if the object is locked

remove_orbitals(indices: Union[Iterable[int], ndarray]) None

Remove the hopping terms corresponding to a list of orbitals and update remaining hopping terms.

Parameters:

indices – indices of orbitals to remove

Returns:

None

remove_rn(rn: Union[Tuple[int, int], Tuple[int, int, int]]) bool

Remove all the hopping terms of given cell index.

Parameters:

rn – (r_a, r_b, r_c), cell index

Returns:

where the hopping terms are removed, False if not found

sync_array(**kwargs) None

Abstract interface for ‘sync_array’ method of derived classes.

to_array(use_int64: bool = False) Tuple[ndarray, ndarray]

Convert hopping terms to array of ‘hop_ind’ and ‘hop_eng’, for constructing attributes of ‘PrimitiveCell’ or ‘Sample’.

Parameters:

use_int64 – whether to use 64-bit integer for hop_ind, should be enabled for ‘SuperCell’ and ‘SCInterHopping’ classes

Returns:

(hop_ind, hop_eng) hop_ind: (num_hop, 5) int32/int64 array, hopping indices hop_eng: (num_hop,) complex128 array, hopping energies

to_list() List[Tuple[int, int, int, int, int, complex]]

Flatten all hopping terms into a list.

Returns:

list of hopping terms (rb, rb, rc, orb_i, orb_j, energy)

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 cell_indices: List[Tuple[int, int, int]]

Get the list of cell indices.

Returns:

list of cell indices

property hoppings: Dict[Tuple[int, int, int], Dict[Tuple[int, int], complex]]

Interface for the ‘__hoppings’ attribute.

property num_hop: int

Count the number of hopping terms.

Returns:

number of hopping terms

property sc_bra: SuperCell

Interface for the ‘_sc_bra’ attribute.

property sc_ket: SuperCell

Interface for the ‘_sc_ket’ attribute.