tbplas.PrimitiveCell

class tbplas.PrimitiveCell(lat_vec: ndarray = array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]), origin: ndarray = array([0., 0., 0.]), unit: float = 0.1)

Class for representing the primitive cell.

_lat_vec

Cartesian coordinates of lattice vectors in NANO METER Each ROW corresponds to one lattice vector.

Type:

(3, 3) float64 array

_origin

Cartesian coordinates of origin of lattice vectors in NANO METER

Type:

(3,) float64 array

_orbital_list

list of orbitals in the primitive cell

Type:

List[Orbital]

_hopping_dict

container of hopping terms in the primitive cell Only half of the hopping terms are stored. Conjugate terms are added automatically when constructing the Hamiltonian.

Type:

‘IntraHopping’ instance

_hash_dict

hashes of attributes to be used by ‘sync_*’ methods to update the arrays

Type:

Dict[str, int]

_orb_pos

FRACTIONAL positions of all orbitals

Type:

(num_orb, 3) float64 array

_orb_eng

on-site energies of all orbitals in eV

Type:

(num_orb,) float64 array

_hop_ind

indices of all hopping terms

Type:

(num_hop, 5) int32 array

_hop_eng

energies of all hopping terms in eV

Type:

(num_hop,) complex128 array

extended

number of times the primitive cell has been extended Some response functions will be divided by this attribute to average them to the very primitive cell since the primitive cell itself may be formed by replicating another cell. In most cases it will be an integer. However, if the primitive cell has been created by reshaping another cell, it will become a float.

Type:

float

__init__(lat_vec: ndarray = array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]), origin: ndarray = array([0., 0., 0.]), unit: float = 0.1) → None
Parameters:

  • lat_vec – (3, 3) float64 array Cartesian coordinates of lattice vectors in arbitrary unit

  • origin – (3,) float64 array Cartesian coordinate of lattice origin in arbitrary unit

  • unit – conversion coefficient from arbitrary unit to NM

Returns:

None

Raises:

  • LatVecError – if shape of lat_vec is not (3, 3)

  • ValueError – if shape of origin is not (3,)

Methods

__init__([lat_vec, origin, unit])

param lat_vec:

(3, 3) float64 array

add_hopping(rn, orb_i, orb_j, energy)

Add a new hopping term to the primitive cell, or update an existing hopping term.

add_hopping_dict(hop_dict)

Add a matrix of hopping terms to the primitive cell, or update existing hopping terms.

add_orbital(position[, energy, label])

Add a new orbital to the primitive cell.

add_orbital_cart(position[, unit])

Add a new orbital to the primitive cell in CARTESIAN coordinates.

add_subscriber(sub_name, sub_obj)

Add a new subscriber.

apply_pbc([pbc])

Apply periodic boundary conditions by removing hopping terms between cells along non-periodic direction.

calc_bands(k_points[, enable_mpi, echo_details])

Calculate band structure along given k_path.

calc_dos(k_points[, enable_mpi, echo_details])

Calculate density of states for given energy range and step.

check_lock()

Check the lock state of the object.

get_hopping(rn, orb_i, orb_j)

Get given hopping term or its conjugate counterpart.

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_orbital(orb_i)

Get given orbital instance.

get_reciprocal_vectors()

Get the Cartesian coordinates of reciprocal lattice vectors in 1/NM.

lock(sub_name)

Lock the object.

plot([fig_name, fig_size, fig_dpi, ...])

Plot lattice vectors, orbitals, and hopping terms.

print()

Print orbital and hopping information.

print_hk([convention])

Print analytical Hamiltonian as the function of k-point.

remove_hopping(rn, orb_i, orb_j)

Remove given hopping term.

remove_orbital(orb_i)

Wrapper over 'remove_orbitals' to remove a single orbital.

remove_orbitals(indices)

Remove given orbitals and associated hopping terms, then update remaining hopping terms.

reset_lattice([lat_vec, origin, unit, fix_orb])

Reset lattice vectors and origin.

set_ham_csr(k_point[, convention])

Set up sparse Hamiltonian in csr format for given k-point.

set_ham_dense(k_point, ham_dense[, convention])

Set up dense Hamiltonian for given k-point.

set_orbital(orb_i[, position, energy, label])

Modify the position, energy and label of an existing orbital.

set_orbital_cart(orb_i[, position, unit])

Modify the position, energy and label of an existing orbital with Cartesian coordinates.

sync_array(**kwargs)

Synchronize orb_pos, orb_eng, hop_ind and hop_eng according to orbitals and hopping terms.

sync_hop([force_sync])

Synchronize hop_ind and hop_eng according to the hopping terms.

sync_orb([force_sync])

Synchronize orb_pos and orb_eng according to the orbitals.

trim()

Trim dangling orbitals and associated hopping terms.

unlock()

Unlock the object.

update()

Update all subscribers.

verify_hoppings()

Check if the primitive cell has hopping terms.

verify_orbitals()

Check if the primitive cell has orbitals.

Attributes

dr

Get the hopping distances in FRACTIONAL coordinates.

dr_ang

Get the hopping distances in ANGSTROM.

dr_nm

Get the hopping distances in NM.

hop_eng

Interface for the '_hop_eng' attribute.

hop_ind

Interface for the '_hop_ind' attribute.

hoppings

Interface for the hopping terms.

lat_vec

Interface for the '_lat_vec' attribute.

num_hop

Get the number of hopping terms WITHOUT considering conjugate relation.

num_orb

Get the number of orbitals in the primitive cell.

orb_eng

Interface for the '_orb_eng' attribute.

orb_pos

Interface for the '_orb_pos' attribute.

orb_pos_ang

Get the Cartesian coordinates of orbitals in ANGSTROM.

orb_pos_nm

Get the Cartesian coordinates of orbitals in NANOMETER.

orbitals

Interface for the '_orbital_list' attribute.

origin

Interface for the '_origin' attribute.
__hash__() → int

Return the hash of this instance.

__init__(lat_vec: ndarray = array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]), origin: ndarray = array([0., 0., 0.]), unit: float = 0.1) → None
Parameters:

  • lat_vec – (3, 3) float64 array Cartesian coordinates of lattice vectors in arbitrary unit

  • origin – (3,) float64 array Cartesian coordinate of lattice origin in arbitrary unit

  • unit – conversion coefficient from arbitrary unit to NM

Returns:

None

Raises:

  • LatVecError – if shape of lat_vec is not (3, 3)

  • ValueError – if shape of origin is not (3,)

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 to the primitive cell, or update an existing hopping term.

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 primitive cell is locked

  • PCOrbIndexError – if orb_i or orb_j falls out of range

  • PCHopDiagonalError – if rn == (0, 0, 0) and orb_i == orb_j

  • CellIndexLenError – if len(rn) != 2 or 3

add_hopping_dict(hop_dict: HopDict) → None

Add a matrix of hopping terms to the primitive cell, or update existing hopping terms.

Reserved for compatibility with old version of TBPLaS.

Parameters:

hop_dict – hopping dictionary

Returns:

None

Raises:

LockError – if the primitive cell is locked

add_orbital(position: Union[Tuple[float, float], Tuple[float, float, float]], energy: float = 0.0, label: Hashable = 'X') → None

Add a new orbital to the primitive cell.

Parameters:

  • position – FRACTIONAL coordinate of the orbital

  • energy – on-site energy of the orbital in eV

  • label – orbital label

Returns:

None

Raises:

  • LockError – if the primitive cell is locked

  • OrbPositionLenError – if len(position) != 2 or 3

add_orbital_cart(position: Union[Tuple[float, float], Tuple[float, float, float]], unit: float = 0.1, **kwargs) → None

Add a new orbital to the primitive cell in CARTESIAN coordinates.

Parameters:

  • position – Cartesian coordinate of orbital in arbitrary unit

  • unit – conversion coefficient from arbitrary unit to NM

  • kwargs – keyword arguments for ‘add_orbital’

Returns:

None

Raises:

  • LockError – if the primitive cell is locked

  • OrbPositionLenError – if len(position) != 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

apply_pbc(pbc: Tuple[bool, bool, bool] = (True, True, True)) → None

Apply periodic boundary conditions by removing hopping terms between cells along non-periodic direction.

Parameters:

pbc – whether pbc is enabled along 3 directions

Returns:

None

Raises:

  • LockError – if the primitive cell is locked

  • ValueError – if len(pbc) != 3

calc_bands(k_points: ndarray, enable_mpi: bool = False, echo_details: bool = True, **kwargs) → Tuple[ndarray, ndarray]

Calculate band structure along given k_path.

Parameters:

  • k_points – (num_kpt, 3) float64 array FRACTIONAL coordinates of the k-points

  • enable_mpi – whether to enable parallelization over k-points using mpi

  • echo_details – whether to output parallelization details

  • kwargs – arguments for ‘calc_bands’ of ‘DiagSolver’ class

Returns:

(k_len, bands) k_len: (num_kpt,) float64 array in 1/NM length of k-path in reciprocal space, for plotting band structure bands: (num_kpt, num_orb) float64 array Energies corresponding to k-points in eV

calc_dos(k_points: ndarray, enable_mpi: bool = False, echo_details: bool = True, **kwargs) → Tuple[ndarray, ndarray]

Calculate density of states for given energy range and step.

Parameters:

  • k_points – (num_kpt, 3) float64 array FRACTIONAL coordinates of the k-points

  • enable_mpi – whether to enable parallelization over k-points using mpi

  • echo_details – whether to output parallelization details

  • kwargs – arguments for ‘calc_dos’ of ‘DiagSolver’ class

Returns:

(energies, dos) energies: (num_grid,) float64 array energy grid corresponding to e_min, e_max and e_step dos: (num_grid,) float64 array density of states in states/eV

check_lock() → None

Check the lock state of the object.

Returns:

None

Raises:

LockError – if the object is locked

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

Get given hopping term or its conjugate counterpart.

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>

Returns:

hopping energy in eV

Raises:

  • PCHopNotFoundError – if rn + (orb_i, orb_j) or its conjugate counterpart is not found in the hopping terms

  • PCOrbIndexError – if orb_i or orb_j falls out of range

  • PCHopDiagonalError – if rn == (0, 0, 0) and orb_i == orb_j

  • CellIndexLenError – if len(rn) != 2 or 3

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_orbital(orb_i: int) → Orbital

Get given orbital instance.

Parameters:

orb_i – index of the orbital

Returns:

the i-th orbital

Raises:

PCOrbIndexError – if orb_i falls out of range

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

plot(fig_name: str = None, fig_size: Tuple[float, float] = None, fig_dpi: int = 300, with_orbitals: bool = True, with_cells: bool = True, with_conj: bool = True, orb_color: Callable[[List[Orbital]], 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.

If figure name is given, save the figure to file. Otherwise, show it on the screen.

Parameters:

  • fig_name – file name to which the figure will be saved

  • fig_size – width and height of the figure

  • fig_dpi – resolution of the figure file

  • 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 If true, hopping terms will be plotted as arrows using axes.arrow() method. Otherwise, they will be plotted as lines using LineCollection. The former is more intuitive but much slower.

  • hop_eng_cutoff – cutoff for showing hopping terms

  • hop_color – color of hopping terms

  • view – kind of view point

Returns:

None

Raises:

ValueError – if view is illegal

print() → None

Print orbital and hopping information.

Returns:

None

print_hk(convention: int = 1) → None

Print analytical Hamiltonian as the function of k-point.

Parameters:

convention – convention for setting up the Hamiltonian

Returns:

None

Raises:

  • ValueError – if convention not in (1, 2)

  • PCOrbEmptyError – if cell does not contain orbitals

  • PCHopEmptyError – if cell does not contain hopping terms

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

Remove given hopping term.

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>

Returns:

None

Raises:

  • LockError – if the primitive cell is locked

  • PCHopNotFoundError – if rn + (orb_i, orb_j) or its conjugate counterpart is not found in the hopping terms

  • PCOrbIndexError – if orb_i or orb_j falls out of range

  • PCHopDiagonalError – if rn == (0, 0, 0) and orb_i == orb_j

  • CellIndexLenError – if len(rn) != 2 or 3

remove_orbital(orb_i: int) → None

Wrapper over ‘remove_orbitals’ to remove a single orbital.

Parameters:

orb_i – index of the orbital to remove

Returns:

None

Raises:

  • LockError – if the primitive cell is locked

  • PCOrbIndexError – if orb_i falls out of range

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

Remove given orbitals and associated hopping terms, then update remaining hopping terms.

Parameters:

indices – indices of orbitals to remove

Returns:

None

Raises:

  • LockError – if the primitive cell is locked

  • PCOrbIndexError – if orb_i falls out of range

reset_lattice(lat_vec: ndarray = None, origin: ndarray = None, unit: float = 0.1, fix_orb: bool = True) → None

Reset lattice vectors and origin.

Parameters:

  • lat_vec – (3, 3) float64 array Cartesian coordinates of lattice vectors in arbitrary unit

  • origin – (3,) float64 array Cartesian coordinate of lattice origin in arbitrary unit

  • unit – conversion coefficient from arbitrary unit to NM

  • fix_orb – whether to keep Cartesian coordinates of orbitals unchanged after resetting lattice

Returns:

None

Raises:

  • LockError – if the primitive cell is locked

  • LatVecError – if shape of lat_vec is not (3, 3)

  • ValueError – if shape of origin is not (3,)

set_ham_csr(k_point: ndarray, convention: int = 1) → csr_matrix

Set up sparse Hamiltonian in csr format for given k-point.

This is the interface to be called by external exact solvers. The callers are responsible to call the ‘sync_array’ method.

Parameters:

  • k_point – (3,) float64 array FRACTIONAL coordinate of the k-point

  • convention – convention for setting up the Hamiltonian

Returns:

sparse Hamiltonian

Raises:

  • ValueError – if convention not in (1, 2)

  • PCOrbEmptyError – if cell does not contain orbitals

  • PCHopEmptyError – if cell does not contain hopping terms

set_ham_dense(k_point: ndarray, ham_dense: ndarray, convention: int = 1) → None

Set up dense Hamiltonian for given k-point.

This is the interface to be called by external exact solvers. The callers are responsible to call the ‘sync_array’ method and initialize ham_dense as a zero matrix.

Parameters:

  • k_point – (3,) float64 array FRACTIONAL coordinate of the k-point

  • ham_dense – (num_orb, num_orb) complex128 array incoming Hamiltonian

  • convention – convention for setting up the Hamiltonian

Returns:

None

Raises:

  • ValueError – if convention not in (1, 2)

  • PCOrbEmptyError – if cell does not contain orbitals

  • PCHopEmptyError – if cell does not contain hopping terms

set_orbital(orb_i: int, position: Union[Tuple[float, float], Tuple[float, float, float]] = None, energy: float = None, label: Hashable = None) → None

Modify the position, energy and label of an existing orbital.

If position, energy or label is None, then the corresponding attribute will not be modified.

Parameters:

  • orb_i – index of the orbital to modify

  • position – new FRACTIONAL coordinate of the orbital

  • energy – new on-site energy of the orbital in eV

  • label – new orbital label

Returns:

None

Raises:

  • LockError – if the primitive cell is locked

  • PCOrbIndexError – if orb_i falls out of range

  • OrbPositionLenError – if len(position) != 2 or 3

set_orbital_cart(orb_i: int, position: Union[Tuple[float, float], Tuple[float, float, float]] = None, unit: float = 0.1, **kwargs) → None

Modify the position, energy and label of an existing orbital with Cartesian coordinates.

If position, energy or label is None, then the corresponding attribute will not be modified.

Parameters:

  • orb_i – index of the orbital to modify

  • position – Cartesian coordinate of orbital in arbitrary unit

  • unit – conversion coefficient from arbitrary unit to NM

  • kwargs – keyword arguments for ‘set_orbital’

Returns:

None

Raises:

  • LockError – if the primitive cell is locked

  • PCOrbIndexError – if orb_i falls out of range

  • OrbPositionLenError – if len(position) != 2 or 3

sync_array(**kwargs) → None

Synchronize orb_pos, orb_eng, hop_ind and hop_eng according to orbitals and hopping terms.

Parameters:

kwargs – arguments for ‘sync_orb’ and sync_’hop’

Returns:

None

sync_hop(force_sync: bool = False) → None

Synchronize hop_ind and hop_eng according to the hopping terms.

Parameters:

force_sync – whether to force synchronizing the arrays even if the hopping terms did not change

Returns:

None

sync_orb(force_sync: bool = False) → None

Synchronize orb_pos and orb_eng according to the orbitals.

Parameters:

force_sync – whether to force synchronizing the arrays even if the orbitals did not change

Returns:

None

trim() → None

Trim dangling orbitals and associated hopping terms.

Returns:

None

Raises:

LockError – if the primitive cell is locked

unlock() → None

Unlock the object. Modifications are allowed then.

Returns:

None

update() → None

Update all subscribers.

Returns:

None

verify_hoppings() → None

Check if the primitive cell has hopping terms.

Returns:

None

Raises:

PCHopEmptyError – if num_hop == 0

verify_orbitals() → None

Check if the primitive cell has orbitals.

Returns:

None

Raises:

PCOrbEmptyError – if num_orb == 0

__weakref__

list of weak references to the object (if defined)

property dr: ndarray

Get the hopping distances in FRACTIONAL coordinates.

Returns:

(num_hop, 3) float64 array hopping distances in FRACTIONAL coordinates

property dr_ang: ndarray

Get the hopping distances in ANGSTROM.

Returns:

(num_hop, 3) float64 array hopping distances in ANGSTROM

property dr_nm: ndarray

Get the hopping distances in NM.

Returns:

(num_hop, 3) float64 array hopping distances in NM

property hop_eng: ndarray

Interface for the ‘_hop_eng’ attribute.

Returns:

(num_hop,) complex128 array hopping energies

property hop_ind: ndarray

Interface for the ‘_hop_ind’ attribute.

Returns:

(num_hop, 5) int32 array hopping indices

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

Interface for the hopping terms.

Returns:

hopping terms

property lat_vec: ndarray

Interface for the ‘_lat_vec’ attribute.

Returns:

(3, 3) float64 array Cartesian coordinates of lattice vectors in NM

property num_hop: int

Get the number of hopping terms WITHOUT considering conjugate relation.

Returns:

number of hopping terms

property num_orb: int

Get the number of orbitals in the primitive cell.

Returns:

number of orbitals

property orb_eng: ndarray

Interface for the ‘_orb_eng’ attribute.

Returns:

(num_orb,) float64 array on-site energies in eV

property orb_pos: ndarray

Interface for the ‘_orb_pos’ attribute.

Returns:

(num_orb, 3) float64 array fractional coordinates or orbitals

property orb_pos_ang: ndarray

Get the Cartesian coordinates of orbitals in ANGSTROM.

Returns:

(num_orb, 3) float64 array Cartesian coordinates of orbitals in arbitrary NANOMETER

property orb_pos_nm: ndarray

Get the Cartesian coordinates of orbitals in NANOMETER.

Returns:

(num_orb, 3) float64 array Cartesian coordinates of orbitals in NANOMETER

property orbitals: List[Orbital]

Interface for the ‘_orbital_list’ attribute.

Returns:

list of orbitals

property origin: ndarray

Interface for the ‘_origin’ attribute.

Returns:

(3,) float64 array Cartesian coordinate of origin in NM