tbkit package#

tbkit.lattice module#

class tbkit.lattice.Lattice(unit_cell: list[dict], prim_vec: list[tuple[float, float]])[source]#

Bases: object

Build up 1D or 2D lattice. Lattice is defined by the discrete operation:

\[\mathbf{R} = n_1\mathbf{a}_1 + n_2\mathbf{a}_2\]

where $\mathbf{a}_1$ and $\mathbf{a}_2$ are the two primitive vectors and $n_1$ and $n_2$ are the number of unit cells along $\mathbf{a}_1$ and $\mathbf{a}_2$.

Parameters:

unit_cell –
List of dictionaries. One dictionary per site within the unit cell. Each dictionary has two keys:
- ’tag’, one-character string. Label of the associated sublattice.
- ’r0’, Tuple. Position.
prim_vec –
List of tuples. Define the primitive vectors. List of one/two tuples for 1D/2D respectively:
- Tuple, cartesian coordinate of the primitive vector $\mathbf{a}_1$.
- Tuple, cartesian coordinate of the primitive vector $\mathbf{a}_2$.

Example usage:

# Line-Centered Square lattice
unit_cell = [{'tag': 'a', 'r0': (0., 0.)}, {'tag': 'a', 'r0': (0., 1.)}]
prim_vec = [(0, 2), (2, 0)]
lat = lattice(unit_cell=unit_cell, prim_vec=prim_vec)

get_lattice(n1: int, n2: int = 1) → None[source]#

Get the lattice positions.

Parameters:

n1 – Positive Integer. Number of unit cells along $\mathbf{a}_1$.
n2 – Positive Integer. Default value 1. Number of unit cells along $\mathbf{a}_2$.

Example usage:

# Line-Centered Square lattice
unit_cell = [{'tag': 'a', 'r0': (0., 0.)}, {'tag': 'a', 'r0': (0., 1.)}]
prim_vec = [(0, 2), (2, 0)]
lat = lattice(unit_cell=unit_cell, prim_vec=prim_vec)
lat.get_lattice(n1=4, n2=5)

add_sites(coor: NDArray) → None[source]#

Add sites.

Parameters:: coor – Structured array with keys: {‘x’, ‘y’, ‘tag’}.

Example usage:

# Square lattice
unit_cell = [{'tag': 'a', 'r0': (0., 0.)}]
prim_vec = [(0, 1), (1, 0)]
lat = lattice(unit_cell=unit_cell, prim_vec=prim_vec)
lat.get_lattice(n1=2, n2=2)
coor = np.array([(-1., -1, 'b'), (-2., -2, 'c')],
                          dtype=[('x', 'f8'), ('y', 'f8'), ('tag', 'U1')])
lat.add_sites(coor)

remove_sites(index: list[int]) → None[source]#

Remove sites defined by their indices (use method lattice.plot(plt_index=True) to get access to the site indices).

Parameters:: index – List. Site indices to be removed.

Example usage:

# Square lattice
unit_cell = [{'tag': 'a', 'r0': (0., 0.)}]
prim_vec = [(0, 1), (1, 0)]
lat = lattice(unit_cell=unit_cell, prim_vec=prim_vec)
lat.get_lattice(n1=2, n2=2)
lat.remove_sites([0, 2])

remove_dangling() → None[source]#: Remove dangling sites (sites connected with just another site).

shift_x(shift: float) → None[source]#

Shift the x coordinates.

Parameters:: shift – Real number. Shift value.

shift_y(shift: float) → None[source]#

Shift the y coordinates.

Parameters:: shift – Real number. Shift value.

change_sign_x() → None[source]#: Change x coordinates sign.

change_sign_y() → None[source]#: Change y coordinates sign.

boundary_line(cx: float, cy: float, co: float) → None[source]#

Select sites according to $c_yy+c_xx > c_0$.

Parameters:

cx – Real number. cx value.
cy – Real number. cy value.
co – Real number. co value.

ellipse_in(rx: float, ry: float, x0: float, y0: float) → None[source]#

Select sites according to

\[(x-x_0)^2/a^2+(y-y_0)^2/b^2 < 1\, .\]

Parameters:

rx – Positive Real number. Radius along $x$.
ry – Positive Real number. Radius along $y$.
x0 – Real number. $x$ center.
y0 – Real number. $y$ center.

ellipse_out(rx: float, ry: float, x0: float, y0: float) → None[source]#

Select sites according to

\[(x-x_0)^2/a^2+(y-y_0)^2/b^2 > 1\, .\]

Parameters:

rx – Positive Real number. Radius along $x$.
ry – Positive Real number. Radius along $y$.
x0 – Real number. $x$ center.
y0 – Real number. $y$ center.

center() → None[source]#: Fix the center of mass of the lattice at (0, 0).

rotation(theta: float) → None[source]#

Rotate the lattice structure about the origin by the angle $\theta$.

Parameters:: theta – Rotation angle in degrees.

clean_coor() → None[source]#: Keep only the sites with different coordinates.

plot(ms: float = 20, fs: float = 20, plt_index: bool = False, axis: bool = False, figsize: tuple[float, float] | None = None) → Figure[source]#

Plot the lattice in real space.

Parameters:

ms – Positive number. Default value 20. Markersize.
fs – Positive number. Default value 20. Fontsize.
plt_index – Boolean. Default value False. Plot site labels.
axis – Boolean. Default value False. Plot axis.
figsize – Tuple. Default value None. Figsize.

Returns:

fig – Figure.

show() → None[source]#: Emulate Matplotlib method plt.show().

tbkit.lattice.lattice#: alias of Lattice

tbkit.system module#

class tbkit.system.System(lat: Lattice)[source]#

Bases: object

Solve the Tight-Binding eigenvalue problem of a lattice defined by the class lattice.

Parameters:: lat – lattice class instance.

clear_hopping() → None[source]#: Clear structured array hop.

get_distances() → None[source]#: Private method. Get distances and angles of the edges.

print_distances(n: int = 1) → None[source]#

Print distances and positive angles (in degrees) $\phi_+\in[0, 180)$ of the nth shortest edges. Negative angles are given by: $\phi_-= \phi_+-180$ and $\phi_+\in[-180, 0)$.

Parameters:: n – Positive integer. Number of shortest edges.

set_onsite(dict_onsite: dict[str, complex]) → None[source]#

Set onsite energies.

Parameters:: dict_onsite – Dictionary. key: sublattice tag, val: onsite energy.

Example usage:

# Line-Centered Square lattice
sys.set_onsite({'a': -1j, 'b': -2j})

fill_store_hop(n: int) → None[source]#

Private method.

Store in store_hop indices (with $i < j$), positive angles, and tags of a given type of hopping.

set_hopping(list_hop: list[dict], upper_part: bool = True) → None[source]#

Set lattice hoppings.

Parameters:

list_hop –
List of Dictionaries. Dictionary with keys (‘n’, ‘ang’, ‘tag’, ‘t’) where:
- ’n’ Positive integer, type of hoppings:
  ’n’: 1 for nearest neighbours.
  
  ’n’: 2 for next-nearest neighbours.
  
  ’n’: 3 for next-next-nearest neighbours.
  
  etc…
- ’ang’ value, float, angle, in deg, of the hoppings. (optional).
  Hopping angles are given by the method print_distances.
  
  If $ang \in[0, 180)$, fill the Hamiltonian upper part.
  
  If $ang \in[-180, 0)$, fill the Hamiltonian lower part.
- ’tag’ string of length 2 (optional).
  
  Hopping tags.
- ’t’ Complex number.
  
  Hopping value.
upper_part –
Boolean. Default value True.
- True get hoppings with ($i<j$) i.e. fill the Hamiltonian upper part.
- False get hoppings with ($i>j$) i.e. fill the Hamiltonian lower part.

Example usage:

# fill upper part:
sys.set_hopping([{'n': 1, 't': 1.}])
# fill lower part:
sys.set_hopping([{'n': 1, 't': 1.}], upper_part=False)
# fill upper part: specifying the angles:
sys.set_hopping([{'n': 1, 'ang': 0., 't': 1.}, {'n': 1, 'ang': 90., 't': 2.}])
# fill lower part:
sys.set_hopping([{'n': 1, 'ang': -180., 't': 1.}, {'n': 1, 'ang': -90., 't': 2.}],
                           upper_part=False)
# fill upper part: specifying the tags:
sys.set_hopping([{'n': 1, 'tag': 'ab', 't': 1.}, {'n': 1, 'tag': 'ba', 't': 2.}])
# fill lower part:
sys.set_hopping([{'n': 1, 'tag': 'ab', 't': 1.}, {'n': 1, 'tag': 'ba', 't': 2.}],
                           upper_part=False)
# fill upper part: specifying the angles and tags:
sys.set_hopping([{'n': 1, 'ang': 0., 'tag': 'ab', 't': 1.},
                            {'n': 1, 'ang': 0., 'tag': 'ba', 't': 2.},
                            {'n': 1, 'ang': 90., 'tag': 'ab', 't': 3.},
                            {'n': 1, 'ang': 90., 'tag': 'ba', 't': 4.}])
# fill lower part:
sys.set_hopping([{'n': 1, 'ang': -180., 'tag': 'ab', 't': 1.},
                            {'n': 1, 'ang': -180., 'tag': 'ba', 't': 2.},
                            {'n': 1, 'ang': -90., 'tag': 'ab', 't': 3.},
                            {'n': 1, 'ang': -90., 'tag': 'ba', 't': 4.}],
                           upper_part=False)

Note

A Hermitian hopping matrix can be build-up only using its upper part OR only using its lower part. The full matrix is then automatic built by Hermitian conjugaison.

If both upper AND lower parts are used to build up the hopping matrix. non Hermitian conjugaison is not performed i.e. non-Hermitian hopping matrix can be built.

check_sites() → None[source]#: Private method. Check if the number of sites was changed after calling the method system.set_hopping().

set_given_hopping(n: int, size: int, dic: dict, mask: NDArray, upper_part: bool) → NDArray[source]#

Private method. Fill self.hop.

Parameters:

n – Integer. Hopping type.
size – Integer. Number of hoppings.
dic – Dictionary. Hopping dictionary.
mask – np.ndarray. Mask.
upper_part – Boolean. If True, self.hop[‘i’] < self.hop[‘j’].

set_hopping_manual(dict_hop: dict[tuple[int, int], complex], upper_part: bool = True) → None[source]#

Set hoppings manually.

Parameters:

dict_hop – Dictionary of hoppings. key: hopping indices, val: hopping values.
upper_part –
Boolean.
- True, fill the Hamiltonian upper part.
- False, fill the Hamiltonian lower part.

set_hopping_dis(alpha: complex) → None[source]#

Set uniform hopping disorder.

Parameters:: alpha – Complex or Real number. Disorder stength.

Example usage:

sys.set_hopping_dis(alpha=0.1)

set_peierls_phase(phase: Callable[[...], NDArray]) → None[source]#

Apply the Peierls substitution to the existing hoppings, to capture the effect of an orbital magnetic field:

\[t_{ij} \to t_{ij}\, e^{i\phi_{ij}}\, ,\quad \phi_{ij} = \frac{2\pi}{\Phi_0}\int_{\mathbf{r}_i}^{\mathbf{r}_j} \mathbf{A}\cdot d\mathbf{l}\]

where $\mathbf{A}$ is the vector potential, integrated along the straight bond from site $i$ to site $j$.

Must be called after set_hopping / set_hopping_manual (it rescales the existing hoppings in place) and before get_ham. For a uniform perpendicular field, use the convenience method set_magnetic_field instead.

Parameters:: phase – Callable. phase(xi, yi, xj, yj) returns $\phi_{ij}$, the (real-valued) Peierls phase for the bond from $(x_i, y_i)$ to $(x_j, y_j)$. Called with Numpy arrays (one value per hopping in sys.hop).

Note

get_ham automatically assigns the reversed bond its complex conjugate, so the Hamiltonian stays Hermitian as long as phase is antisymmetric under swapping $i$ and $j$ – true for the line integral of any vector potential, since reversing the integration path negates it.

Example usage:

# Peierls phase from a uniform field via the Landau gauge
# A = (0, B x): captures the same physics as set_magnetic_field,
# just in a different (equally valid) gauge.
B = 0.05
sys.set_peierls_phase(lambda xi, yi, xj, yj: B * (yj - yi) * (xi + xj) / 2)

set_magnetic_field(alpha: float) → None[source]#

Set a uniform perpendicular magnetic field via the Peierls substitution (see set_peierls_phase), using the symmetric gauge $\mathbf{A} = \frac{B}{2}(-y, x)$:

\[\phi_{ij} = \pi\alpha\,(x_iy_j - x_jy_i)\]

Parameters:: alpha – Real number. Flux density $B/\Phi_0$, in flux quanta per unit area (in the lattice’s length units) – i.e. the flux through a region of area $S$ is $\alpha S$ flux quanta.

Example usage:

# one flux quantum per 100 unit cells of a lattice with
# lattice constant 1:
sys.set_magnetic_field(alpha=0.01)

set_onsite_dis(alpha: complex) → None[source]#

Set uniform onsite disorder.

Parameters:: alpha – Complex or Real number. Disorder stength.

Example usage:

sys.set_onsite_dis(alpha=0.1)

set_onsite_def(onsite_def: dict[int, complex]) → None[source]#

Set specific onsite energies.

Parameters:: onsite_def – Dictionary. key: site indices, val: onsite values.

Example usage:

sys.set_onsite_def({0: 1., 1: -1j})

set_hopping_def(hopping_def: dict[tuple[int, int], complex]) → None[source]#

Set specific hoppings.

Parameters:: hopping_def – Dictionary of hoppings. key: hopping indices, val: hopping values.

Example usage:

sys.set_hopping_def({(0, 1): 1., (1, 2): -1j})

set_new_hopping(list_hop: list[dict], ind: NDArray) → None[source]#

Private method. Set new hoppings.

Parameters:

list_hop – List of Dictionary (see set_hopping definition).
ind – List. List of indices.

find_square(xlims: tuple[float, float], ylims: tuple[float, float]) → NDArray[source]#

Private method. Find hoppings within the square.

Parameters:

xlims – List or Tuple. $x$ interval.
ylims – List or Tuple. $y$ interval.

find_ellipse(rx: float, ry: float, x0: float, y0: float) → NDArray[source]#

Private method. Find hoppings within the ellipse.

Parameters:

rx – Positive Float. Radius along $x$.
ry – Positive Float. Radius along $y$.
x0 – Float. Default value 0. $x$ center.
y0 – Float. Default value 0. $y$ center.

change_hopping_square(list_hop: list[dict], xlims: tuple[float, float], ylims: tuple[float, float] = [-1.0, 1.0]) → None[source]#

Change hopping values.

Parameters:

list_hop – List of Dictionary (see set_hopping definition).
xlims – List or Tuple. $x$ interval.
ylims – List or Tuple. $y$ interval.

change_hopping_ellipse(list_hop: list[dict], rx: float, ry: float, x0: float = 0.0, y0: float = 0.0) → None[source]#

Change hopping values.

Parameters:

list_hop – List of Dictionary (see set_hopping definition).
rx – Positive Float. Radius along $x$.
ry – Positive Float. Radius along $y$.
x0 – Float. Default value 0. $x$ center.
y0 – Float. Default value 0. $y$ center.

get_coor_hop() → None[source]#: Get the site coordinates in hopping space only considering the nearest neighbours hoppings.

get_ham() → None[source]#: Get the Tight-Binding Hamiltonian using sys.hop.

get_eig(eigenvec: bool = False, left: bool = False) → None[source]#

Get the eigenergies, eigenvectors and polarisation.

Parameters:

eigenvec – Boolean. Default value False. If True, get the eigenvectors.
left – Boolean. Default value False. If True, get the left eigenvectors too. Relevant for non-Hermitian matrices.

get_ipr() → None[source]#: Get the Inverse Participation Ratio:

\[IPR_n = \sum_i|\psi_i^{n}|^4\, .\]

get_petermann() → None[source]#: Get the Petermann factor:

\[K_n = \frac{\langle\psi_L^{n}|\psi_L^{n}\rangle\langle\psi_R^{n}|\psi_R^{n}\rangle}{|\langle\psi_L^{n}|\psi_R^{n}\rangle|^2}\, .\]

Note

LA.eig fixes the norm such that $\langle\psi_L^{n}|\psi_L^{n}\rangle = 1$ and $\langle\psi_R^{n}|\psi_R^{n}\rangle = 1$.

get_intensity_pola_max(tag_pola: str) → NDArray[float64][source]#

Get the state with largest polarization on one sublattice.

Parameters:

tag_pola – One-character string. Sublattice tag.

Returns:

intensity – Intensity of max polarized state on tag.

get_intensity_pola_min(tag_pola: str) → NDArray[float64][source]#

Get the state with smallest polarization on one sublattice.

Parameters:

tag_pola – One-character string. Sublattice tag.

Returns:

intensity – Intensity of min polarized state on tag.

get_intensity_en(lims: tuple[float, float]) → NDArray[float64][source]#

Get, if any, the intensity of the sum of the states between lims[0] and lims[1].

Parameters:

lims – List. lims[0] energy min, lims[1] energy max.

Returns:

intensity – Sum of the intensities between (lims[0], lims[1]).

tbkit.system.system#: alias of System

tbkit.kspace module#

tbkit.kspace.PAULI = {'0': array([[1.+0.j, 0.+0.j], [0.+0.j, 1.+0.j]]), 'x': array([[0.+0.j, 1.+0.j], [1.+0.j, 0.+0.j]]), 'y': array([[ 0.+0.j, -0.-1.j], [ 0.+1.j, 0.+0.j]]), 'z': array([[ 1.+0.j, 0.+0.j], [ 0.+0.j, -1.+0.j]])}#: Pauli matrices (plus the identity, key '0'), for building spinful hoppings/onsite terms (spin-orbit coupling, Zeeman splitting, …) when KSpace is constructed with spin=True.

tbkit.kspace.reciprocal_vectors(prim_vec: list[tuple[float, float]]) → list[tuple[float, float]][source]#

Get the reciprocal lattice vectors $\mathbf{b}_i$ such that $\mathbf{a}_i\cdot\mathbf{b}_j = 2\pi\delta_{ij}$.

Parameters:

prim_vec – List of one/two tuples. Primitive vectors (see class lattice).

Returns:

rec_vec – List of one/two tuples. Reciprocal vectors.

class tbkit.kspace.KSpace(lat: Lattice, spin: bool = False)[source]#

Bases: object

Build and solve the Tight-Binding Bloch Hamiltonian $H(\mathbf{k})$ of a periodic lattice defined by the class lattice.

Hoppings are defined between orbitals of the unit cell, separated by a lattice vector $\mathbf{R} = n_1\mathbf{a}_1+n_2\mathbf{a}_2$:

\[H_{ij}(\mathbf{k}) = \sum_{\mathbf{R}} t_{ij}(\mathbf{R})\, e^{i\mathbf{k}\cdot\mathbf{R}}\]

Parameters:

lat – lattice class instance. Only unit_cell and prim_vec are used (the instance need not call get_lattice).
spin – Boolean. Default value False. If True, every site of unit_cell carries a spin-1/2 degree of freedom (norb doubles to 2*len(unit_cell), ordered site-major: orbitals 2*i, 2*i+1 are the up/down components of site i). set_onsite and set_hopping then accept 2x2 (spin) matrices in addition to plain numbers, to build spin-orbit coupling or Zeeman terms – see PAULI for ready-made Pauli matrices.

Example usage:

# graphene, nearest-neighbor hopping t
DX, DY = 0.5 * 3 ** 0.5, 0.5
unit_cell = [{'tag': 'a', 'r0': (0., 0.)}, {'tag': 'b', 'r0': (DX, DY)}]
prim_vec = [(2*DX, 0.), (DX, 1.5)]
lat = Lattice(unit_cell=unit_cell, prim_vec=prim_vec)
gra = KSpace(lat)
gra.set_hopping([{'i': 0, 'j': 1, 'R': (0, 0), 't': 1.},
                        {'i': 0, 'j': 1, 'R': (-1, 0), 't': 1.},
                        {'i': 0, 'j': 1, 'R': (0, -1), 't': 1.}])

set_onsite(dict_onsite: dict[str, complex | Sequence[complex]]) → None[source]#

Set the onsite energies, by sublattice tag.

Parameters:: dict_onsite – Dictionary. key: tag, val: onsite energy (a plain number), or, if spin=True, a plain number (applied equally to both spins), a pair (E_up, E_down) of numbers (a spin splitting along z), or a 2x2 complex matrix (a general spin structure, e.g. an in-plane Zeeman field built from PAULI).

Example usage:

kag.set_onsite({'a': 1., 'b': -1.})
# spinful: same onsite energy for both spins on 'a', a Zeeman
# splitting along z on 'b':
kag_spin.set_onsite({'a': 1., 'b': (1., -1.)})
# spinful: an in-plane Zeeman field on 'a':
kag_spin.set_onsite({'a': Bx*PAULI['x']})

set_hopping(list_hop: list[dict]) → None[source]#

Set the hoppings between orbitals of the unit cell.

Only one representative of each hopping needs to be given: its Hermitian conjugate ($j\to i$, $\mathbf{R}\to-\mathbf{R}$) is added automatically.

Parameters:

list_hop –

List of dictionaries with keys (‘i’, ‘j’, ‘R’, ‘t’):

’i’, ‘j’: Positive integers. Site indices within the unit cell (following the order of unit_cell).
’R’: Tuple of one/two integers $(n_1, n_2)$. Lattice vector $\mathbf{R}=n_1\mathbf{a}_1+n_2\mathbf{a}_2$ separating the two sites.
’t’: Complex number, or, if spin=True, either a complex number (spin-independent hopping) or a 2x2 complex matrix (a general, possibly spin-mixing, hopping – e.g. built from PAULI for Rashba or intrinsic spin-orbit coupling).

Example usage:

# 1D chain, nearest-neighbor hopping t between the only orbital
# and its right neighbor:
chain.set_hopping([{'i': 0, 'j': 0, 'R': (1,), 't': 1.}])
# spinful: spin-independent hopping t, plus a Rashba-like
# spin-flip term of strength alpha:
chain_spin.set_hopping([{'i': 0, 'j': 0, 'R': (1,),
                                        't': t*PAULI['0'] + 1j*alpha*PAULI['y']}])

clear_hopping() → None[source]#: Clear the hoppings set by set_hopping.

get_ham(k: ArrayLike) → NDArray[complex128][source]#

Get the dense Bloch Hamiltonian $H(\mathbf{k})$.

Parameters:

k – Tuple/list/ndarray of one/two real numbers. In 2D, the $\mathbf{k}$ point in the same Cartesian frame as prim_vec. In 1D, the crystal momentum along the primitive vector (so the Brillouin zone spans $2\pi/|\mathbf{a}_1|$), which coincides with $k_x$ for a chain aligned with $x$.

Returns:

ham – Complex ndarray, shape (norb, norb).

get_bands(ks: ArrayLike, eigenvec: bool = False) → NDArray[float64] | tuple[NDArray[float64], NDArray[complex128]][source]#

Diagonalize $H(\mathbf{k})$ over a set of k-points.

Parameters:

ks – ndarray, shape (nk, dim). k-points.
eigenvec – Boolean. Default value False. If True, also return the eigenvectors.

Returns:

en – Real ndarray, shape (nk, norb). Band energies, sorted ascending.
vn – Complex ndarray, shape (nk, norb, norb), only if eigenvec is True. vn[k, :, n] is the nth eigenvector at ks[k].

k_path(points: list[ArrayLike], nk: int) → tuple[NDArray[float64], NDArray[float64]][source]#

Build a k-path through a list of high-symmetry points, and get the associated bands.

Parameters:

points – List of at least two k-points (each a tuple/list of one/two real numbers).
nk – Positive integer. Number of k-points per path segment.

Returns:

ks_dist – Real ndarray. Cumulative distance along the path, to be used as the x-axis of a band-structure plot.
en – Real ndarray, shape (len(ks_dist), norb). Band energies.

mesh_grid(nk: int | tuple[int, int]) → tuple[list[NDArray[float64]], NDArray[float64]][source]#

Private method. Build a uniform grid of fractional coordinates spanning the Brillouin zone (each in [0, 1)), and the corresponding Cartesian k-points.

Parameters:

nk – Positive integer, or tuple of dim positive integers. Number of k-points along each reciprocal lattice vector.

Returns:

fracs – List of dim real ndarrays, shape (nk1, nk2) each (or (nk1,) in 1D): fractional coordinates of the grid.
ks – Real ndarray, shape (nk1*nk2, dim) (or (nk1, dim) in 1D).

mesh_bands(nk: int | tuple[int, int]) → NDArray[float64][source]#

Diagonalize $H(\mathbf{k})$ over a uniform mesh spanning the Brillouin zone.

Parameters:

nk – Positive integer, or tuple of dim positive integers. Number of k-points along each reciprocal lattice vector.

Returns:

en – Real ndarray, shape (nk1*nk2, norb). Band energies over the mesh (flattened).

berry_curvature(bands: int | list[int], nk: int | tuple[int, int] = 30) → NDArray[float64][source]#

Get the Berry curvature of a group of bands over a uniform Brillouin-zone mesh, using the gauge-invariant lattice method of Fukui, Hatsugai and Suzuki (J. Phys. Soc. Jpn. 74, 1674 (2005)): the flux through each mesh plaquette is minus the phase of the product of the (Slater-determinant) overlaps between the occupied subspaces at its four corners.

Parameters:

bands – Positive integer, or list of positive integers. Band index, or indices of a group of bands (e.g. all occupied bands below a gap).
nk – Positive integer, or tuple of 2 positive integers. Default value 30. Number of k-points along each reciprocal lattice vector.

Returns:

curv – Real ndarray, shape (nk1, nk2). Berry curvature (flux through each plaquette, in radians). Summing curv and dividing by $2\pi$ gives the Chern number, see chern_number.

chern_number(bands: int | list[int], nk: int | tuple[int, int] = 30) → float[source]#

Get the Chern number of a group of bands:

\[C = \frac{1}{2\pi}\int_{BZ} \Omega(\mathbf{k})\, d^2k\]

an integer (up to the numerical precision set by nk) for a group of bands that is isolated from the rest of the spectrum by a gap everywhere in the Brillouin zone. See berry_curvature.

Parameters:

bands – Positive integer, or list of positive integers. Band index, or indices of a group of bands (e.g. all occupied bands below a gap).
nk – Positive integer, or tuple of 2 positive integers. Default value 30. Number of k-points along each reciprocal lattice vector.

Returns:

chern – Real number, close to an integer.

plot_dos(nk: int | tuple[int, int] = 30, broadening: float = 0.05, kernel: str = 'gaussian', e_grid: ArrayLike | None = None, fs: float = 20, lw: float = 2.0, figsize: tuple[float, float] | None = None) → Figure[source]#

Plot the (broadened) density of states, obtained by diagonalizing $H(\mathbf{k})$ over a uniform Brillouin-zone mesh – see tbkit.dos.density_of_states.

Parameters:

nk – Positive integer, or tuple of dim positive integers. Default value 30. Number of k-points along each reciprocal lattice vector.
broadening – Positive real number. Default value 0.05. Kernel width.
kernel – String. Default value ‘gaussian’. ‘gaussian’ or ‘lorentzian’.
e_grid – Real ndarray. Default value None. Energies at which to evaluate the density of states.
fs – Positive number. Default value 20. Fontsize.
lw – Positive number. Default value 2. Linewidth.
figsize – Tuple. Default value None. Figure size.

Returns:

fig – Figure.

plot_bands(node_labels: list[str] | None = None, fs: float = 20, lw: float = 2.0, ms: float = 0.0, c: str = 'b', lims: tuple[float, float] | None = None, figsize: tuple[float, float] | None = None) → Figure[source]#

Plot the band structure computed by k_path or get_bands.

Parameters:

node_labels – List of strings. Default value None. Labels of the high-symmetry points passed to k_path.
fs – Positive number. Default value 20. Fontsize.
lw – Positive number. Default value 2. Linewidth.
ms – Positive number. Default value 0. Marker size.
c – Default value ‘b’. Line color.
lims – List. Default value None. Energy plot limits.
figsize – Tuple. Default value None. Figure size.

Returns:

fig – Figure.

show() → None[source]#: Emulate Matplotlib method plt.show().

tbkit.kspace.ribbon(lat: Lattice, list_hop: list[dict], width: int, direction: int = 1, onsite: dict | None = None, spin: bool = False) → KSpace[source]#

Cut a ribbon out of a 2D periodic model: periodic along one primitive vector, finite (open boundary, width unit cells) along the other. This is the standard way to see edge states in a band structure (e.g. the zero-energy edge band of a zigzag graphene ribbon, or the helical edge states of a Kane-Mele ribbon).

Parameters:

lat – Lattice class instance (2D, i.e. two primitive vectors). Only unit_cell and prim_vec are used.
list_hop – List of dictionaries, in the same format passed to KSpace.set_hopping – the hoppings of the periodic (2D) model that the ribbon is cut from.
width – Positive integer. Number of unit cells across the ribbon.
direction – 0 or 1. Default value 1. Which primitive vector (lat.prim_vec[direction]) becomes finite; the other stays periodic.
onsite – Dictionary. Default value None. Onsite energies, in the same format passed to KSpace.set_onsite – applied identically on every row of the ribbon.
spin – Boolean. Default value False. See KSpace.

Returns:

rib – KSpace instance, 1D-periodic, with width * len(lat.unit_cell) sites (each site of lat, repeated once per row across the ribbon; row w’s copy of site i is orbital w*len(lat.unit_cell) + i).

Example usage:

# zigzag graphene ribbon, 20 unit cells wide
list_hop = [{'i': 0, 'j': 1, 'R': (0, 0), 't': 1.},
                  {'i': 0, 'j': 1, 'R': (-1, 0), 't': 1.},
                  {'i': 0, 'j': 1, 'R': (0, -1), 't': 1.}]
rib = ribbon(lat, list_hop, width=20)

tbkit.lattices module#

A small library of common 2D Bravais lattices, ready to feed into tbkit.lattice.Lattice, tbkit.system.System, or tbkit.kspace.KSpace.

Each function returns a fresh Lattice instance with unit_cell and prim_vec already set (call get_lattice yourself to build a finite flake, or hand it straight to KSpace for a periodic/band-structure calculation). Nearest-neighbor sites are a distance a apart.

Example usage:

import tbkit.lattices as lattices
lat = lattices.kagome()
lat.get_lattice(n1=6, n2=6)

tbkit.lattices.chain(a: float = 1.0) → Lattice[source]#

1D chain: one site per unit cell.

Parameters:: a – Positive real number. Default value 1. Lattice constant.

tbkit.lattices.square(a: float = 1.0) → Lattice[source]#

Square lattice: one site per unit cell.

Parameters:: a – Positive real number. Default value 1. Lattice constant.

tbkit.lattices.triangular(a: float = 1.0) → Lattice[source]#

Triangular lattice: one site per unit cell.

Parameters:: a – Positive real number. Default value 1. Lattice constant.

tbkit.lattices.honeycomb(a: float = 1.0) → Lattice[source]#

Honeycomb lattice (e.g. graphene): two sites per unit cell, nearest neighbors a distance a apart. See also tbkit.graphene.GrapheneLattice for ready-made finite flakes of various shapes.

Parameters:: a – Positive real number. Default value 1. Nearest-neighbor distance.

tbkit.lattices.kagome(a: float = 1.0) → Lattice[source]#

Kagome lattice: three sites per unit cell (tags ‘a’, ‘b’, ‘c’), arranged as corner-sharing triangles on a triangular Bravais lattice. With uniform nearest-neighbor hopping, this lattice famously has an exactly flat band (at E = -2t for hopping amplitude t).

Parameters:: a – Positive real number. Default value 1. Nearest-neighbor distance.

Example usage (nearest-neighbor hopping, for tbkit.kspace.KSpace):

lat = lattices.kagome()
kag = KSpace(lat)
kag.set_hopping([{'i': 0, 'j': 1, 'R': (0, 0), 't': t},
                        {'i': 0, 'j': 1, 'R': (-1, 0), 't': t},
                        {'i': 0, 'j': 2, 'R': (0, 0), 't': t},
                        {'i': 0, 'j': 2, 'R': (0, -1), 't': t},
                        {'i': 1, 'j': 2, 'R': (0, 0), 't': t},
                        {'i': 1, 'j': 2, 'R': (1, -1), 't': t}])

tbkit.lattices.lieb(a: float = 1.0) → Lattice[source]#

Lieb lattice: three sites per unit cell (tag ‘a’: corner site; tags ‘b’, ‘c’: edge-center sites) on a square Bravais lattice. With uniform nearest-neighbor hopping, this lattice famously has an exactly flat band (at E = 0), squeezed between two dispersive bands.

Parameters:: a – Positive real number. Default value 1. Nearest-neighbor distance.

Example usage (nearest-neighbor hopping, for tbkit.kspace.KSpace):

lat = lattices.lieb()
lb = KSpace(lat)
lb.set_hopping([{'i': 0, 'j': 1, 'R': (0, 0), 't': t},
                       {'i': 0, 'j': 1, 'R': (-1, 0), 't': t},
                       {'i': 0, 'j': 2, 'R': (0, 0), 't': t},
                       {'i': 0, 'j': 2, 'R': (0, -1), 't': t}])

tbkit.dos module#

Density of states from a set of eigenenergies, real-space (tbkit.system.System) or reciprocal-space (tbkit.kspace.KSpace, sampled over a k-mesh).

tbkit.dos.density_of_states(energies: ArrayLike, e_grid: ArrayLike | None = None, broadening: float = 0.05, kernel: str = 'gaussian') → tuple[NDArray[float64], NDArray[float64]][source]#

Get the density of states, broadened by a Gaussian or Lorentzian kernel of width broadening:

\[\rho(E) = \sum_n g(E-E_n)\, ,\quad g(x) = \frac{1}{\sqrt{2\pi}\sigma}e^{-x^2/2\sigma^2}\ \text{(gaussian)} \ \text{or}\ g(x) = \frac{1}{\pi}\frac{\sigma}{x^2+\sigma^2}\ \text{(lorentzian)}\]

Each level contributes a kernel of unit area, so $\int\rho(E)dE$ equals the number of levels in energies, for an e_grid wide enough to contain the tails.

Parameters:

energies – Array of (real) eigenenergies. Any shape (e.g. the en attribute of System, or of KSpace after get_bands over a k-mesh – flattened automatically).
e_grid – Real ndarray. Default value None. Energies at which to evaluate the density of states. If None, a grid of 401 points spanning [min(energies)-3*broadening, max(energies)+3*broadening] is used.
broadening – Positive real number. Default value 0.05. Kernel width $\sigma$.
kernel – String. Default value ‘gaussian’. ‘gaussian’ or ‘lorentzian’.

Returns:

e_grid – Real ndarray. The energy grid used.
dos – Real ndarray, same shape as e_grid. Density of states.

tbkit.plot module#

class tbkit.plot.Plot(sys: System, colors: list[str] | None = None)[source]#

Bases: object

Plot the results of the classes lattice or system.

Parameters:

sys – class instance system.
colors – Default value None. Color plot.

plt_hopping(coor: NDArray, hop: NDArray, c: float, ax: Axes | None = None) → None[source]#: Private method called by lattice_generic.

lattice_generic(coor: NDArray, ms: float, lw: float, c: float, fs: float, axis: bool, plt_hop: bool, plt_hop_low: bool, plt_index: bool, figsize: tuple[float, float] | None, ax: Axes | None = None) → Figure[source]#: Private method called by lattice and lattice_hop.

lattice(ms: float = 20, lw: float = 5.0, c: float = 3.0, fs: float = 20, axis: bool = False, plt_hop: bool = False, plt_hop_low: bool = False, plt_index: bool = False, figsize: tuple[float, float] | None = None, ax: Axes | None = None) → Figure[source]#

Plot lattice.

Parameters:

ms – Positive number. Default value 20. Markersize.
c – Positive number. Default value 3. Coefficient. Hopping linewidths given by c*hop[‘t’].
fs – Positive number. Default value 20. Fontsize.
plt_hop – Boolean. Default value False. Plot hoppings.
plt_hop_low – Boolean. Default value False. Plot hoppings diagonal low.
plt_index – Boolean. Default value False. Plot site labels.
axis – Boolean. Default value False. Plot axis.
figsize – Tuple. Default value None. Figure size.
ax – Axes. Default value None. Draw on this axis instead of creating a figure of its own – to place several lattices side by side in one figure. figsize is then ignored.

Returns:

fig – Figure.

lattice_hop(ms: float = 20, lw: float = 5, c: float = 3.0, fs: float = 20, axis: bool = False, plt_hop: bool = False, plt_hop_low: bool = False, plt_index: bool = False, figsize: tuple[float, float] | None = None, ax: Axes | None = None) → Figure[source]#

Plot lattice in hopping space.

Parameters:

ms – Positive Float. Default value 20. Markersize.
c – Positive Float. Default value 3. Coefficient. Hopping linewidths given by c*hop[‘t’].
fs – Positive Float. Default value 20. Fontsize.
axis – Boolean. Default value False. Plot axis.
plt_hop – Boolean. Default value False. Plot hoppings.
plt_index – Boolean. Default value False. Plot site labels.
figsize – Tuple. Default value None. Figure size.
ax – Axes. Default value None. Draw on this axis instead of creating a figure of its own – to place several lattices side by side in one figure. figsize is then ignored.

Returns:

fig – Figure.

spectrum_hist(nbr_bins: int = 61, fs: float = 20, lims: tuple[float, float] | None = None) → None[source]#

Plot the spectrum.

Parameters:

nbr_bins – Default value 61. Number of bins of the histogram.
lims – List, lims[0] energy min, lims[1] energy max.

dos(broadening: float = 0.05, kernel: str = 'gaussian', e_grid: ArrayLike | None = None, fs: float = 20, lw: float = 2.0, figsize: tuple[float, float] | None = None) → Figure[source]#

Plot the (broadened) density of states, see tbkit.dos.density_of_states.

Parameters:

broadening – Positive real number. Default value 0.05. Kernel width.
kernel – String. Default value ‘gaussian’. ‘gaussian’ or ‘lorentzian’.
e_grid – Real ndarray. Default value None. Energies at which to evaluate the density of states.
fs – Positive number. Default value 20. Fontsize.
lw – Positive number. Default value 2. Linewidth.
figsize – Tuple. Default value None. Figure size.

Returns:

fig – Figure.

spectrum(ms: float = 10, fs: float = 20, lims: tuple[float, float] | None = None, tag_pola: str | None = None, ipr: bool | None = None, petermann: bool | None = None) → Figure[source]#

Plot spectrum (eigenenergies real part (blue circles), and sublattice polarization if pola not empty (red circles).

Parameters:

ms – Default value 10. Markersize.
fs – Default value 20. Fontsize.
lims – List, lims[0] energy min, lims[1] energy max.
tag_pola – Default value None. One-character string. Tag of the sublattice.
ipr – Default value None. If True plot the Inverse Participation Ratio.
petermann – Default value None. If True plot the Petermann factor.

Returns:

fig – Figure.

Plot sublattice polarization.

Parameters:

fig – Figure. Default value None. (used by the method spectrum).
ax1 – Axis. Default value None. (used by the method spectrum).
ms – Positive Float. Default value 10. Markersize.
fs – Positive Float. Default value 20. Fontsize.
lims – List, lims[0] energy min, lims[1] energy max.
tag_pola – One-character string. Default value None. Tag of the sublattice.
ind – List. Default value None. List of indices. (used in the method spectrum).

Returns:

fig – Figure.

ipr(fig: Figure | None = None, ax1: Axes | None = None, ms: float = 10, fs: float = 20, lims: tuple[float, float] | None = None, ind: NDArray | None = None) → tuple[Figure, Axes][source]#

Plot the Inverse Participation Ratio.

Parameters:

fig – Figure. Default value None. (used by the method spectrum).
ax1 – Axis. Default value None. (used by the method spectrum).
ms – Positive Float. Default value 10. Markersize.
fs – Positive Float. Default value 20. Fontsize.
lims – List. lims[0] energy min, lims[1] energy max.
ind – List. Default value None. List of indices. (used in the method spectrum).

Returns:

fig – Figure.

petermann(fig: Figure | None = None, ax1: Axes | None = None, ms: float = 10, fs: float = 20, lims: tuple[float, float] | None = None, ind: NDArray | None = None) → tuple[Figure, Axes][source]#

Plot the Petermann factor.

Parameters:

fig – Figure. Default value None. (used by the method spectrum).
ax1 – Axis. Default value None. (used by the method spectrum).
ms – Positive Float. Default value 10. Markersize.
fs – Positive Float. Default value 20. Fontsize.
lims – List. lims[0] energy min, lims[1] energy max.
ind – List. Default value None. List of indices. (used in the method spectrum).

Returns:

fig – Figure.

spectrum_complex(ms: float = 10.0, fs: float = 20.0, lims: tuple[float, float] | None = None) → Figure[source]#

Plot complex value eigenenergies, real part (blue circles), and imaginary part (red circles).

Parameters:

ms – Positive Float. Default value 20. Markersize.
fs – Positive Float. Default value 20. Font size.
lims – List. lims[0] energy min, lims[1] energy max.

Returns:

fig – Figure.

intensity_1d(intensity: NDArray, ms: float = 20.0, lw: float = 2.0, fs: float = 20.0, title: str = '$|\\psi^{(j)}|^2$') → Figure[source]#

Plot intensity for 1D lattices.

Parameters:

intensity – np.array. Field intensity.
ms – Positive Float. Default value 20. Markersize.
lw – Positive Float. Default value 2. Linewith, connect sublattice sites.
fs – Positive Float. Default value 20. Font size.
title – String. Default value ‘Intensity’. Figure title.

intensity_disk(intensity: NDArray, s: float = 200.0, fs: float = 20.0, lims: tuple[float, float] | None = None, figsize: tuple[float, float] | None = None, title: str = '$|\\psi|^2$') → Figure[source]#

Plot the intensity. Colormap with identical disk shape.

Parameters:

intensity – np.array.Field intensity.
s – Default value 200. Disk size.
fs – Default value 20. Font size.
lims – List. Default value None. Colormap limits.
figsize – Tuple. Default value None. Figure size.
title – String. Default value ‘$|psi_n|^2$’. Title.

Returns:

fig – Figure.

intensity_area(intensity: NDArray, s: float = 1000.0, lw: float = 1.0, fs: float = 20.0, plt_hop: bool = False, figsize: tuple[float, float] | None = None, title: str = '$|\\psi|^2$') → Figure[source]#

Plot the intensity. Intensity propotional to disk shape.

Parameters:

intensity – np.array. Intensity.
s – Positive Float. Default value 1000. Circle size given by s * intensity.
lw – Positive Float. Default value 1. Hopping linewidths.
fs – Positive Float. Default value 20. Fontsize.
plt_hop – Boolean. Default value False. Plot hoppings.
figsize – Tuple. Default value None. Figure size.
title – String. Default value ‘$|psi_{ij}|^2$’. Figure title.

Returns:

fig – Figure.

butterfly(betas: NDArray, butterfly: NDArray, lw: float = 1.0, fs: float = 20.0, lims: tuple[float, float] | None = None, title: str = '') → Figure[source]#

Plot energies depending on a parameter.

Parameters:

betas – np.array. Parameter values.
butterfly – np.array. Eigenvalues.
lw – Positive Float. Default value 1. Hopping linewidths.
fs – Positive Float. Default value 20. Fontsize.
lims – List, lims[0] energy min, lims[1] energy max.
title – Default value ‘’. Figure title.

show() → None[source]#: Emulate Matplotlib method plt.show().

tbkit.plot.plot#: alias of Plot

tbkit.propagation module#

class tbkit.propagation.Propagation(lat: Lattice)[source]#

Bases: object

Get lattice time evolution. Time dependent Schrodinger equation solved by Crank-Nicolson method.

Parameters:: lat – lattice class instance.

get_propagation(ham: spmatrix, psi_init: NDArray, steps: int, dz: float, norm: bool = False) → None[source]#

Get the time evolution.

Parameters:

ham – sparse.csr_matrix. Tight-Binding Hamilonian.
psi_init – np.ndarray. Initial state.
steps – Positive Integer. Number of steps.
dz – Positive number. Step.
norm – Boolean. Default value False. Renormalize the state to $\sum_i|\psi_i|^2 = 1$ at each step. The Crank-Nicolson step is unitary, so this only matters for a non-Hermitian Hamiltonian (gain/loss), where the norm is not conserved.

get_pumping(hams: list[spmatrix], psi_init: NDArray, steps: int, dz: float, norm: bool = True) → None[source]#

Get the time evolution with adiabatic pumpings.

Parameters:

hams – List of sparse.csr_matrices. Tight-Binding Hamilonians.
psi_init – np.ndarray. Initial state.
steps – Positive integer. Number of steps.
dz – Positive number. Step.
norm – Boolean. Default value True. Renormalize the state to $\sum_i|\psi_i|^2 = 1$ at each step.

plt_propagation_1d(prop_type: str = 'real', fs: float = 20, figsize: tuple[float, float] | None = None) → Figure[source]#

Plot time evolution for 1D systems.

Parameters:: fs – Default value 20. Fontsize.

prop_smooth_1d(prop: NDArray, a: float = 10, no: int = 40) → NDArray[source]#

Private function. Used in plt_propagation_1d. Smooth propagation for 1D systems. Perform Gaussian interpolation $e^{-a(x-x_i)^2}$,

Parameters:

prop – Propagation.
a – Default value 15. Gaussian Parameter.
no – Default value 40. Number of points of each Gaussian.

Returns:

smooth – Smoothed propagation.

get_animation(s: float = 300.0, fs: float = 20.0, prop_type: str = 'real', figsize: tuple[float, float] | None = None) → FuncAnimation[source]#

Get time evolution animation.

Parameters:

s – Default value 300. Circle size.
fs – Default value 20. Fontsize.
figsize – Tuple. Default value None. Figsize.
prop_type – Default value None. Figsize.

Returns:

ani – Animation.

get_animation_nb(s: float = 300.0, fs: float = 20.0, prop_type: str = 'real', figsize: tuple[float, float] | None = None) → FuncAnimation[source]#

Get time evolution animation for iPython notebooks.

Parameters:

s – Default value 300. Circle shape.
fs – Default value 20. Fontsize.

Returns:

ani – Animation.

plt_prop_dimer(lw: float = 5, fs: float = 20) → Figure[source]#

Plot time evolution for dimers.

Parameters:

lw – Default value 5. Linewidth.
fs – Default value 20. Fontsize.

Returns:

fig – Figure.

tbkit.propagation.propagation#: alias of Propagation

tbkit.save module#

class tbkit.save.Save(dir_name: str, dir_main: str | None = None, params: dict | None = None, file_format: str = 'png')[source]#

Bases: object

Create folder and save figures / animations obtained via plot or propagation.

Parameters:

dir_name – String. Name of the sub-directory the figures are stored in.
dir_main – String. Default value None. Path of the main directory. If None, figures are stored under 'figs/'.
params – Dictionary. Default value None. Parameters appended to file names.
file_format – Default value ‘png’. Figure format.

create_dir() → None[source]#: Create the directory the figures are stored in, if it does not exist.

file_name() → str[source]#

Create the file name.

Returns:

file_name – File name.

fig(fig: Figure, name: str) → None[source]#

Save the figure in the directory defined by the method dir_name().

Parameters:

fig – Matplotlib fig.
name – String. Fist part of the file name.

fig_lat(fig: Figure, name: str) → None[source]#

Save the figure in the directory defined by the method dir_name().

Parameters:

fig – Matplotlib fig.
name – String. First part of the file name.

ani(ani: FuncAnimation, name: str, fps: int = 10) → None[source]#

Save the animation, as MP4, in the directory defined by dir_name.

Parameters:

ani – Matplotlib FuncAnimation.
name – String. First part of the file name.
fps – Positive integer. Default value 10. Frames per second.

tbkit.save.save#: alias of Save

tbkit.graphene module#

class tbkit.graphene.GrapheneLattice[source]#

Bases: Lattice

triangle_zigzag(n: int) → None[source]#

Triangular flake with zigzag terminations.

Param:

Int. Number of plackets along the edges.

hexagon_zigzag(n: int) → None[source]#

Hexagonal flake with zigzag terminations.

Param:

Int. Number of plackets along the edges.

triangle_armchair(n: int) → None[source]#

Triangular flake with armchair terminations.

Param:

Int. Number of plackets along the edges.

hexagon_armchair(n: int) → None[source]#

Hexagonal flake with armchair terminations.

Param:

Int. Number of plackets along each edge.

square(n: int) → None[source]#

Squared flake.

Param:

Int. Number of plackets along x.

circle(n: int) → None[source]#

Circular flake.

Param:

Int. Number of plackets along the diameter.

class tbkit.graphene.GrapheneSystem(lat: Lattice)[source]#

Bases: System

set_hop_linear_strain(t: complex, beta: float) → None[source]#

Set nearest-neighbor hoppings according to a linear triaxial strain:

\[t_{ij} = t\left(1 + \tfrac14\beta\, \hat{\boldsymbol\delta}_{ij}\cdot\mathbf{r}_{ij}\right)\]

with $\hat{\boldsymbol\delta}_{ij}$ the bond direction and $\mathbf{r}_{ij}$ its midpoint. The strain is measured from the coordinate origin, so centre the flake on it (see lattice.center) before calling this.

Parameters:

t – Hopping value without strain.
beta – Strength of the strain. See get_beta_lims for the range that keeps every hopping positive.

get_butterfly(t: complex, N: int) → None[source]#

Get energies depending on strain.

Parameters:

t – Unstrained hopping value.
N – Positive integer. Number of strain values between the minimal and maximal strains given by get_beta_lims.

get_beta_lims() → NDArray[float64][source]#

Get the extremal strain values keeping every hopping positive.

Under set_hop_linear_strain a bond’s amplitude is $t(1+\tfrac14\beta s_{ij})$, so it stays positive for every bond iff $-4/\max_{ij} s_{ij} < \beta < -4/\min_{ij} s_{ij}$.

Returns:

beta_lims – Real ndarray of length 2, [beta_min, beta_max] (ascending). A bound is infinite if the corresponding $s_{ij}$ never takes that sign.

tbkit.graphene.grapheneLat#: alias of GrapheneLattice

tbkit.graphene.grapheneSys#: alias of GrapheneSystem

tbkit.error_handling module#

tbkit.error_handling.boolean(var, var_name)[source]#

Check if var is a boolean.

Raises:: TypeError – Parameter var must be a bool.

tbkit.error_handling.positive_int(var, var_name)[source]#

Check if var is a positive integer.

Raises:

TypeError – Parameter var must be an integer.
ValueError – Parameter var must be a positive integer.

tbkit.error_handling.positive_int_lim(var, var_name, nmax)[source]#

Check if var is a positive integer smaller than nmax.

Raises:

TypeError – Parameter var must be an integer.
ValueError – Parameter var must be a positive integer.
ValueError – Parameter var must be a positive integer smaller than nmax.

tbkit.error_handling.real_number(var, var_name)[source]#

Check if parameter var is a real number.

Raises:: TypeError – Parameter var must be a real number.

tbkit.error_handling.positive_real(var, var_name)[source]#

Check if parameter var is a positive number.

Raises:

TypeError – Parameter var must be a real number.
ValueError – Parameter var must be a positive number.

tbkit.error_handling.positive_real_zero(var, var_name)[source]#

Check if parameter var is a positive number or zero.

Raises:

TypeError – Parameter var must be a real number.
ValueError – Parameter var must be a positive number or zero.

tbkit.error_handling.negative_real(var, var_name)[source]#

Check if parameter var is a negative number.

Raises:

TypeError – Parameter var must be a real number.
ValueError – Parameter var must be a negative number.

tbkit.error_handling.number(var, var_name)[source]#

Check if parameter var is a number.

Raises:: TypeError – Parameter var must be a real number.

tbkit.error_handling.is_callable(var, var_name)[source]#

Check if parameter var is callable.

Raises:: TypeError – Parameter var must be callable.

tbkit.error_handling.larger(var1, var_name1, var2, var_name2)[source]#

Check if var1 larger than val.

Raises:: ValueError – Parameter var1 larger than var2.

tbkit.error_handling.smaller(var1, var_name1, var2, var_name2)[source]#

Check if var1 smaller than var2.

Raises:: ValueError – Parameter var1 must be smaller than var2.

tbkit.error_handling.string(var, var_name)[source]#

Check if parameter var is a string.

Raises:: TypeError – Parameter var must be a string.

tbkit.error_handling.ndarray(var, var_name, length)[source]#

Check if parameter var is a numpy array.

Raises:

TypeError – Parameter var must be a numpy ndarray.
ValueError – length array must be equal to length.

tbkit.error_handling.ndarray_null(var, var_name)[source]#

Check if parameter var is not a null numpy array.

Raises:: ValueError – Parameter var must not be a null numpy ndarray.

tbkit.error_handling.ndarray_empty(var, var_name)[source]#

Check if parameter var is not an empty numpy array.

Raises:: ValueError – Parameter var must not be an emptynumpy ndarray.

tbkit.error_handling.list_tuple_2elem(var, var_name)[source]#

Check if parameter var is a list/tuple with 2 elements.

Raises:

TypeError – Parameter var must be a list/tuple.
ValueError – Parameter var must contain 2 elements.

tbkit.error_handling.tuple_2elem(var, var_name)[source]#

Check if parameter var is a tuple with 2 elements.

Raises:

TypeError – Parameter var must be a tuple.
ValueError – Parameter var must contain 2 elements.

tbkit.error_handling.lat(lat)[source]#: Check if parameter is an instance of the lattice. :raises TypeError: Parameter must be an instance of the class lattice.

tbkit.error_handling.unit_cell(unit_cell)[source]#

Check parameter unit_cell.

Raises:

TypeError – Parameter unit_cell must be a list.
KeyError – Dictionaries must contain the key “tag”.
KeyError – Dictionaries must contain the key “r0”.
TypeError – Key “tags” must contain a one-character string.
ValueError – Key “tags” must contain a one-character string.
ValueError – Key “r0” must contain be a list.
TypeError – Key “r0” must contain be a tuple.
ValueError – Key “r0” must contain a tuple of length two.
ValueError – Key “r0” must contain a tuple of two real numbers.

tbkit.error_handling.prim_vec(prim_vec)[source]#

Check parameter prim_vec.

Raises:

TypeError – Parameter prim_vec must be a list.
ValueError – Parameter prim_vec must be a list of length 1 for 1D lattices or length 2 fro 2D lattices.
TypeError – List elements must be tuples.
ValueError – List elements must be 1 or 2 tuples.
ValueError – Tuples must be of length 2.
ValueError – Tuples must containt real numbers.
ValueError – Norm of coor should be larger than 0.1.

tbkit.error_handling.get_lattice(prim_vec, n1, n2)[source]#

Check method get_lattice.

Raises:

TypeError – Parameter n1 must be an integer.
TypeError – Parameter n2 must be an integer.
ValueError – Parameter n1 must be a positive integer.
ValueError – Parameter n2 must be a positive integer.

tbkit.error_handling.coor(coor)[source]#: Check if coor is a structured array with dtype=[(‘x’, ‘f8’), (‘y’, ‘f8’), (‘tag’, ‘U1’)].

tbkit.error_handling.coor_1d(coor)[source]#: Check if coor is 1d (coor[‘y’] = cst). :raises ValueError: coor must be 1d( coor[‘y’] = cst)..

tbkit.error_handling.remove_sites(index, sites)[source]#

Check method remove_sites.

Raises:

TypeError – Parameter index must be a list.
ValueError – Parameter index must be a list of integers.
ValueError – Indices must be between 0 and sites -1. of integers between 0 and sites

tbkit.error_handling.shift(shift)[source]#: Check shift_x and shift_y. :raises TypeError: Parameter delta must be a real number.

tbkit.error_handling.boundary_line(cx, cy, co)[source]#: Check boundary_line. :raises TypeError: Parameter cx must be a real number. :raises TypeError: Parameter cy must be a real number. :raises TypeError: Parameter co must be a real number.

tbkit.error_handling.sites(sites)[source]#: Check if get_lattice has been called (coor not empty). :raises RuntimeError: Run method lat.get_lattice first.

tbkit.error_handling.sys(sys)[source]#: Check if parameter is an instance of the system. :raises TypeError: Parameter must be an instance of the class system.

tbkit.error_handling.print_hopping(n, nmax)[source]#

Check method print_vec_hopping.

Raises:

TypeError – Parameter nmax must be an integer.
ValueError – Parameter nmax must be a positive integer. between 1 and n_max-1.

tbkit.error_handling.set_onsite(onsite, tags)[source]#

Check method set_onsite.

Raises:

TypeError – Parameter onsite must be a dictionary.
ValueError – Parameter onsite keys must be a tag.
ValueError – Parameter onsite values must be real and/or complex numbers.

tbkit.error_handling.set_hopping(list_hop, n_max)[source]#

Check method set_hopping.

Raises:

TypeError – Parameter list_hop must be a list.
TypeError – Parameter list_hop must be a list of dictionary.
KeyError – “n” and “t” must be dictionary keys.
KeyError – “tag” or “ang” must be a key.
KeyError – “tag” and “ang” must be a key.
ValueError – Dictionaries must be of length 2, 4, or 4.
ValueError – “n” must be between 1 and nmax”

tbkit.error_handling.index(ind, dic)[source]#: check if ind not empy.

tbkit.error_handling.set_hopping_def(hop, hopping_def, sites)[source]#

Check method set_hop_def.

Raises:

TypeError – Parameter hopping_def must be a dictionary
TypeError – hopping_def keys must be lists.
ValueError – hopping_def keys must be lists of length 2.
ValueError – hopping_def keys must be lists of integers.
TypeError – hopping_def keys must be lists.
ValueError – hopping_def keys must be integers between 0 and sites-1.
ValueError – hopping_def keys must be different integers between 0 and sites-1.
TypeError – hopping_def values must be numbers.

tbkit.error_handling.set_onsite_def(onsite_def, sites)[source]#

Check method set_ons_def.

Raises:

TypeError – Parameter onsite_def must be a dictionary.
TypeError – onsite_def keys must be integers.
TypeError – onsite_def values must be numbers.
ValueError – onsite_def keys must be integers between $[0, sites)$.

tbkit.error_handling.hop_n1(hop)[source]#

Check method if self.hop contains nearest neighbours hoppings.

Raises:: ValueError – self.hop must contain nearest neighbours hoppings.

tbkit.error_handling.empty_onsite(onsite)[source]#

Check if onsite not empty.

Raises:: RuntimeError – Run method set_onsite first.

tbkit.error_handling.empty_hop(hop)[source]#

Check if hop not empty.

Raises:: RuntimeError – Run method set_hopping first.

tbkit.error_handling.hop_sites(hop, sites)[source]#

Check if hop indices are smaller than sites.

Raises:: ValueError – Run method sys.clean_hopping.

tbkit.error_handling.empty_coor(coor)[source]#

Check if coor not empty.

Raises:: RuntimeError – Run method lattice.get_lattice first.

tbkit.error_handling.empty_coor_hop(coor_hop)[source]#

Check if coor_hop not empty.

Raises:: RuntimeError – Run method system.get_coor_hop first.

tbkit.error_handling.empty_ham(ham)[source]#

Check if Hamiltonian not empty.

Raises:: RuntimeError – Run method system.get_ham first.

tbkit.error_handling.empty_en(en)[source]#

Check if en not empty.

Raises:: RuntimeError – Run method get_ham first.

tbkit.error_handling.empty_pola(pola)[source]#

Check if pola not empty.

Raises:: RuntimeError – Run method get_eig(eigenvec=True) first.

tbkit.error_handling.empty_vn(vn)[source]#

Check if vn not empty.

Raises:: RuntimeError – Run method get_eig(eigenvec=True) first.

tbkit.error_handling.empty_ipr(ipr)[source]#: Check if ipr not empty.

tbkit.error_handling.empty_ndarray(arr, method)[source]#: Check if arr is a not empty np.ndarray.

tbkit.error_handling.tag(tag, tags)[source]#

Check tag.

Raises:

TypeError – Parameter tag must be a string.
ValueError – Parameter tag is not in tags.

tbkit.error_handling.angle(angle, angles, upper_part)[source]#

Check angle.

Raises:

TypeError –
Parameter angle must be
- a positive number if upper_part is True
- a negative real if upper_part is False.
ValueError – Parameter angle is not in hop[‘ang’].

tbkit.error_handling.lims(lims)[source]#

Check parameter lims.

Raises:

TypeError – Parameter lims must be a list.
TypeError – Parameter lims[0] must be a real number.
TypeError – Parameter lims[1] must be a real number.
ValueError – lims must be a list of length 2.
ValueError – lims[0] must be smaller than lims[1].

tbkit.error_handling.lims_positive(lims)[source]#

Check parameter lims.

Raises:

TypeError – Parameter lims must be a list.
TypeError – Parameter lims[0] must be a positive real number.
TypeError – Parameter lims[1] must be a positive real number.
ValueError – lims must be a list of length 2.
ValueError – lims[0] must be smaller than lims[1].

tbkit.error_handling.fig(fig)[source]#

Check if fig is an instance of Figure.

Raises:: TypeError – fig must be an instance of Figure.

tbkit.error_handling.ani(ani)[source]#

Check if ani is an instance of FuncAnimation.

Raises:: TypeError – ani must be an instance of FuncAnimation.

tbkit.error_handling.file_format(file_format)[source]#

Check if file_format is a string ‘png’, ‘pdf’, ‘ps’, ‘eps’, or ‘svg’.

Raises:

TypeError – file_format must be a string.
ValueError – file_format must be a string given by ‘png’, ‘pdf’, ‘ps’, ‘eps’, or ‘svg’.

tbkit.error_handling.get_pump(hams)[source]#

tbkit.error_handling.prop_type(prop_type)[source]#

tbkit.error_handling.k_vector(vec, var_name, ndim)[source]#

Check that vec is a tuple/list of ndim real numbers.

Raises:

TypeError – Parameter var_name must be a tuple/list.
ValueError – Parameter var_name must be of length ndim.
TypeError – Parameter var_name must contain real numbers.

tbkit.error_handling.spin_matrix(t, var_name)[source]#

Check a spinful “t” or onsite value: either a plain number, or a 2x2 complex matrix.

Raises:: TypeError – Parameter var_name must be a number or a 2x2 matrix.

tbkit.error_handling.set_hopping_kspace(list_hop, n_sites, ndim, spin=False)[source]#

Check method kspace.set_hopping.

Raises:

TypeError – Parameter list_hop must be a list of dictionaries.
KeyError – “i”, “j”, “R”, and “t” must be dictionary keys.
ValueError – “i” and “j” must be site indices between 0 and n_sites-1.
ValueError – “R” must be a tuple of ndim integers.
TypeError – “t” must be a real or complex number (or, if spin, a 2x2 matrix).

tbkit.error_handling.set_onsite_kspace(dict_onsite, tags, spin=False)[source]#

Check method kspace.set_onsite.

Raises:

TypeError – Parameter dict_onsite must be a dictionary.
ValueError – keys must be tags.
TypeError – values must be real or complex numbers (or, if spin, a pair of real/complex numbers, or a 2x2 matrix).

tbkit.error_handling.k_path_points(points, ndim)[source]#

Check parameter points used by kspace.k_path.

Raises:

TypeError – Parameter points must be a list.
ValueError – Parameter points must contain at least two k-points.

tbkit.error_handling.dos_kernel(kernel)[source]#

Check parameter kernel used by dos.density_of_states.

Raises:

TypeError – Parameter kernel must be a string.
ValueError – Parameter kernel must be “gaussian” or “lorentzian”.

tbkit.error_handling.nk(nk, ndim)[source]#

Check parameter nk used by kspace.mesh_bands / kspace.berry_curvature.

Raises:

TypeError – Parameter nk must be an integer or a tuple of integers.
ValueError – Parameter nk (or each of its elements) must be a positive integer.
ValueError – Parameter nk must be a tuple of length ndim.

tbkit.error_handling.dim_2(dim)[source]#

Check that the model is 2D. Berry curvature / Chern number are only defined for a 2D Brillouin zone.

Raises:: ValueError – This calculation requires a 2D lattice.

tbkit.error_handling.direction(direction)[source]#

Check parameter direction used by kspace.ribbon.

Raises:

TypeError – Parameter direction must be an integer.
ValueError – Parameter direction must be 0 or 1.

tbkit.error_handling.band_indices(bands, norb)[source]#

Check parameter bands used by kspace.berry_curvature.

Raises:

TypeError – Parameter bands must be a non-empty list of integers.
ValueError – Parameter bands must be a list of distinct band indices between 0 and norb-1.