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

_cached_data

cached array attributes

Type:: ‘PCCachedData’

__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

Methods

`__init__`([lat_vec, origin, unit])
`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, energy, label])	Add a new orbital to the primitive cell in CARTESIAN coordinates.
`add_subscriber`(sub)	Add a subscriber :param sub: the new subscriber :return: None
`apply_magnetic_field`(intensity[, gauge])	Apply magnetic field perpendicular to xOy-plane to -z direction via Peierls substitution.
`apply_pbc`([pbc])	Apply periodic boundary conditions by removing hopping terms between cells along non-periodic direction.
`check_dim`()	Checks if a 1x1x1 supercell can be built from this primitive cell by searching for duplicate hopping terms.
`check_editable`()	Check if the object is unlocked for modification.
`get_array`()	Get all array attributes for sending to C++ extensions. :return: name tuple with orb_eng, orb_pos, hop_ind, hop_eng, lat_vec and origin as attributes.
`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. :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_orbital`(orb_i)	Get given orbital instance.
`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`([fig_name, fig_size, fig_dpi, ...])	Plot lattice vectors, orbitals, and hopping terms.
`print`()	Print orbital and hopping information.
`print_cxx`()	Print c++ code for constructing the primitive cell.
`print_hk`([convention])	Print analytical Hamiltonian as the function of k-point.
`print_py`()	Print python code for constructing the primitive cell.
`remove_hopping`(rn, orb_i, orb_j)	Remove given hopping term or its conjugate counterpart. :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> :return: None :raises PCHopNotFoundError: if the hop term or its conjugate counterpart is not found.
`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. :param lat_vec: (3, 3) float64 array Cartesian coordinates of lattice vectors in arbitrary unit :param origin: (3, ) float64 array Cartesian coordinate of lattice origin in arbitrary unit :param unit: conversion coefficient from arbitrary unit to NM :param fix_orb: whether to keep Cartesian coordinates of orbitals unchanged after resetting lattice :return: None.
`rotate`([angle, center, shift])	Rotate and shift primitive cell with respect to z-axis. :param angle: twisting angle in RADIANs, NOT degrees :param center: (3, ) float64 array Cartesian coordinates of the rotation center in NANOMETER :param shift: distance of shift in NANOMETER :return: None.
`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.
`trim`()	Trim dangling orbitals and associated hopping terms.
`unlock`()	Unlock the object.
`update`()	Call subscribers to update their data.

Attributes

`dr`	Get the hopping distances in FRACTIONAL coordinates. :return: (num_hop, 3) float64 array hopping distances in FRACTIONAL coordinates.
`dr_ang`	Get the hopping distances in ANGSTROM. :return: (num_hop, 3) float64 array hopping distances in ANGSTROM.
`dr_nm`	Get the hopping distances in NM. :return: (num_hop, 3) float64 array hopping distances in NM.
`hop_eng`	Interface for the '_hop_eng' attribute. :return: (num_hop,) complex128 array hopping energies.
`hop_ind`	Interface for the '_hop_ind' attribute. :return: (num_hop, 5) int32 array hopping indices.
`hoppings`	Interface for the hopping terms.
`lat_vec`	Interface for the '_lat_vec' attribute. :return: (3, 3) float64 array Cartesian coordinates of lattice vectors in NM.
`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. :return: (num_orb,) float64 array on-site energies in eV.
`orb_pos`	Interface for the '_orb_pos' attribute. :return: (num_orb, 3) float64 array fractional coordinates or orbitals.
`orb_pos_ang`	Get the Cartesian coordinates of orbitals in ANGSTROM. :return: (num_orb, 3) float64 array Cartesian coordinates of orbitals in arbitrary NANOMETER.
`orb_pos_nm`	Get the Cartesian coordinates of orbitals in NANOMETER. :return: (num_orb, 3) float64 array Cartesian coordinates of orbitals in NANOMETER.
`orbitals`	Interface for the '_orbital_list' attribute.
`origin`	Interface for the '_origin' attribute. :return: (3, ) float64 array Cartesian coordinate of origin in NM.

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

__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

add_hopping(rn: 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. :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_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

add_orbital(position: Tuple[float, float] | Tuple[float, float, float], energy: float = 0.0, label: Hashable = 'X') → None: Add a new orbital to the primitive cell. :param position: FRACTIONAL coordinate of the orbital :param energy: on-site energy of the orbital in eV :param label: orbital label :return: None

add_orbital_cart(position: Tuple[float, float] | Tuple[float, float, float], unit: float = 0.1, energy: float = 0.0, label: Hashable = 'X') → None: Add a new orbital to the primitive cell in CARTESIAN coordinates. :param position: Cartesian coordinate of orbital in arbitrary unit :param unit: conversion coefficient from arbitrary unit to NM :param energy: on-site energy of the orbital in eV :param label: orbital label :return: None

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

apply_magnetic_field(intensity: float, gauge: int = 0) → None

Apply magnetic field perpendicular to xOy-plane to -z direction via Peierls substitution.

Reference: [1] https://journals.aps.org/prb/pdf/10.1103/PhysRevB.51.4940 [2] https://journals.jps.jp/doi/full/10.7566/JPSJ.85.074709

Parameters:

intensity – magnetic B field in Tesla
gauge – gauge of vector potential of the magnetic field to -z 0 for (By, 0, 0), 1 for (0, -Bx, 0), 2 for (0.5By, -0.5Bx, 0)

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. :param pbc: whether pbc is enabled along 3 directions :return: None

check_dim() → None

Checks if a 1x1x1 supercell can be built from this primitive cell by searching for duplicate hopping terms.

We require that the hopping terms should not contain diagonal terms (i==j) since they are redundant with the on-site terms in the sparse Hamiltonian and hopping distances. Yet, the off-diagonal terms should appear only once. Although these requirements are unphysical, they SIGNIFICANTLY simplify the functions for constructing the sparse matrices. For large models, these requirements are typically satisfied.

Returns:: None

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

get_array() → namedtuple: Get all array attributes for sending to C++ extensions. :return: name tuple with orb_eng, orb_pos, hop_ind, hop_eng, lat_vec and

origin as attributes

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

Get given hopping term or its conjugate counterpart.

If not found, an exception will be raised. This is an on-purpose design, since the caller has no obligation to know what terms are in the cell. A LOT of functions and scripts rely on this behavior. DO NOT change it.

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 the hop term or its conjugate counterpart is not found

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_orbital(orb_i: int) → Orbital: Get given orbital instance. :param orb_i: index of the orbital :return: the i-th orbital

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(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

print() → None: Print orbital and hopping information. :return: None

print_cxx() → None: Print c++ code for constructing the primitive cell. :return: None

print_hk(convention: int = 1) → None: Print analytical Hamiltonian as the function of k-point. :param convention: convention for setting up the Hamiltonian :return: None

print_py() → None: Print python code for constructing the primitive cell. :return: None

remove_hopping(rn: Tuple[int, int] | Tuple[int, int, int], orb_i: int, orb_j: int) → None: Remove given hopping term or its conjugate counterpart. :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> :return: None :raises PCHopNotFoundError: if the hop term or its conjugate counterpart

is not found

remove_orbitals(indices: Iterable[int] | ndarray) → None: Remove given orbitals and associated hopping terms, then update remaining hopping terms. :param indices: indices of orbitals to remove :return: None

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

Reset lattice vectors and origin. :param lat_vec: (3, 3) float64 array

Cartesian coordinates of lattice vectors in arbitrary unit

Parameters:

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

rotate(angle: float = 0.0, center: ndarray = array([0., 0., 0.]), shift: float = 0.0) → None

Rotate and shift primitive cell with respect to z-axis. :param angle: twisting angle in RADIANs, NOT degrees :param center: (3, ) float64 array

Cartesian coordinates of the rotation center in NANOMETER

Parameters:: shift – distance of shift in NANOMETER
Returns:: None

set_orbital(orb_i: int, position: 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

set_orbital_cart(orb_i: int, position: Tuple[float, float] | Tuple[float, float, float] = None, unit: float = 0.1, energy: float = None, label: Hashable = None) → 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
energy – new on-site energy of the orbital in eV
label – new orbital label

Returns:

None

trim() → None: Trim dangling orbitals and associated hopping terms. :return: 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 dr: ndarray: Get the hopping distances in FRACTIONAL coordinates. :return: (num_hop, 3) float64 array

hopping distances in FRACTIONAL coordinates

property dr_ang: ndarray: Get the hopping distances in ANGSTROM. :return: (num_hop, 3) float64 array

hopping distances in ANGSTROM

property dr_nm: ndarray: Get the hopping distances in NM. :return: (num_hop, 3) float64 array

hopping distances in NM

property hop_eng: ndarray: Interface for the ‘_hop_eng’ attribute. :return: (num_hop,) complex128 array

hopping energies

property hop_ind: ndarray: Interface for the ‘_hop_ind’ attribute. :return: (num_hop, 5) int32 array

hopping indices

property hoppings: Dict[Tuple[int, int, int], Dict[Tuple[int, int], complex]]: Interface for the hopping terms. :return: hopping terms

property lat_vec: ndarray: Interface for the ‘_lat_vec’ attribute. :return: (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. :return: number of hopping terms

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

property orb_eng: ndarray: Interface for the ‘_orb_eng’ attribute. :return: (num_orb,) float64 array

on-site energies in eV

property orb_pos: ndarray: Interface for the ‘_orb_pos’ attribute. :return: (num_orb, 3) float64 array

fractional coordinates or orbitals

property orb_pos_ang: ndarray: Get the Cartesian coordinates of orbitals in ANGSTROM. :return: (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. :return: (num_orb, 3) float64 array

Cartesian coordinates of orbitals in NANOMETER

property orbitals: List[Orbital]: Interface for the ‘_orbital_list’ attribute. :return: list of orbitals

property origin: ndarray: Interface for the ‘_origin’ attribute. :return: (3, ) float64 array

Cartesian coordinate of origin in NM