Coverage for tbkit/lattices.py: 100%

1""" 

2A small library of common 2D Bravais lattices, ready to feed into 

3:class:`tbkit.lattice.Lattice`, :class:`tbkit.system.System`, or 

4:class:`tbkit.kspace.KSpace`. 

5 

6Each function returns a fresh ``Lattice`` instance with *unit_cell* and 

7*prim_vec* already set (call ``get_lattice`` yourself to build a finite 

8flake, or hand it straight to ``KSpace`` for a periodic/band-structure 

9calculation). Nearest-neighbor sites are a distance *a* apart. 

10 

11Example usage:: 

12 

13 import tbkit.lattices as lattices 

14 lat = lattices.kagome() 

15 lat.get_lattice(n1=6, n2=6) 

16""" 

17from __future__ import annotations 

18 

19from math import sqrt 

20from typing import Sequence 

21 

22from tbkit.lattice import Lattice 

23import tbkit.error_handling as error_handling 

24 

25 

26def _lat(unit_cell: list[dict], prim_vec: Sequence[tuple[float, ...]]) -> Lattice: 

27 return Lattice(unit_cell=unit_cell, prim_vec=prim_vec) 

28 

29 

30def chain(a: float = 1.) -> Lattice: 

31 ''' 

32 1D chain: one site per unit cell. 

33 

34 :param a: Positive real number. Default value 1. Lattice constant. 

35 ''' 

36 error_handling.positive_real(a, 'a') 

37 return _lat([{'tag': 'a', 'r0': (0., 0.)}], [(a, 0.)]) 

38 

39 

40def square(a: float = 1.) -> Lattice: 

41 ''' 

42 Square lattice: one site per unit cell. 

43 

44 :param a: Positive real number. Default value 1. Lattice constant. 

45 ''' 

46 error_handling.positive_real(a, 'a') 

47 return _lat([{'tag': 'a', 'r0': (0., 0.)}], [(a, 0.), (0., a)]) 

48 

49 

50def triangular(a: float = 1.) -> Lattice: 

51 ''' 

52 Triangular lattice: one site per unit cell. 

53 

54 :param a: Positive real number. Default value 1. Lattice constant. 

55 ''' 

56 error_handling.positive_real(a, 'a') 

57 return _lat([{'tag': 'a', 'r0': (0., 0.)}], 

58 [(a, 0.), (0.5*a, 0.5*sqrt(3)*a)]) 

59 

60 

61def honeycomb(a: float = 1.) -> Lattice: 

62 ''' 

63 Honeycomb lattice (e.g. graphene): two sites per unit cell, nearest 

64 neighbors a distance *a* apart. See also :class:`tbkit.graphene.GrapheneLattice` 

65 for ready-made finite flakes of various shapes. 

66 

67 :param a: Positive real number. Default value 1. Nearest-neighbor distance. 

68 ''' 

69 error_handling.positive_real(a, 'a') 

70 dx, dy = 0.5*sqrt(3)*a, 0.5*a 

71 unit_cell = [{'tag': 'a', 'r0': (0., 0.)}, {'tag': 'b', 'r0': (dx, dy)}] 

72 prim_vec = [(2*dx, 0.), (dx, 1.5*a)] 

73 return _lat(unit_cell, prim_vec) 

74 

75 

76def kagome(a: float = 1.) -> Lattice: 

77 ''' 

78 Kagome lattice: three sites per unit cell (tags 'a', 'b', 'c'), arranged 

79 as corner-sharing triangles on a triangular Bravais lattice. With 

80 uniform nearest-neighbor hopping, this lattice famously has an exactly 

81 flat band (at E = -2t for hopping amplitude t). 

82 

83 :param a: Positive real number. Default value 1. Nearest-neighbor distance. 

84 

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

86 

87 lat = lattices.kagome() 

88 kag = KSpace(lat) 

89 kag.set_hopping([{'i': 0, 'j': 1, 'R': (0, 0), 't': t}, 

90 {'i': 0, 'j': 1, 'R': (-1, 0), 't': t}, 

91 {'i': 0, 'j': 2, 'R': (0, 0), 't': t}, 

92 {'i': 0, 'j': 2, 'R': (0, -1), 't': t}, 

93 {'i': 1, 'j': 2, 'R': (0, 0), 't': t}, 

94 {'i': 1, 'j': 2, 'R': (1, -1), 't': t}]) 

95 ''' 

96 error_handling.positive_real(a, 'a') 

97 a1 = (2*a, 0.) 

98 a2 = (a, sqrt(3)*a) 

99 unit_cell = [{'tag': 'a', 'r0': (0., 0.)}, 

100 {'tag': 'b', 'r0': (a, 0.)}, 

101 {'tag': 'c', 'r0': (0.5*a, 0.5*sqrt(3)*a)}] 

102 return _lat(unit_cell, [a1, a2]) 

103 

104 

105def lieb(a: float = 1.) -> Lattice: 

106 ''' 

107 Lieb lattice: three sites per unit cell (tag 'a': corner site; tags 

108 'b', 'c': edge-center sites) on a square Bravais lattice. With uniform 

109 nearest-neighbor hopping, this lattice famously has an exactly flat 

110 band (at E = 0), squeezed between two dispersive bands. 

111 

112 :param a: Positive real number. Default value 1. Nearest-neighbor distance. 

113 

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

115 

116 lat = lattices.lieb() 

117 lb = KSpace(lat) 

118 lb.set_hopping([{'i': 0, 'j': 1, 'R': (0, 0), 't': t}, 

119 {'i': 0, 'j': 1, 'R': (-1, 0), 't': t}, 

120 {'i': 0, 'j': 2, 'R': (0, 0), 't': t}, 

121 {'i': 0, 'j': 2, 'R': (0, -1), 't': t}]) 

122 ''' 

123 error_handling.positive_real(a, 'a') 

124 unit_cell = [{'tag': 'a', 'r0': (0., 0.)}, 

125 {'tag': 'b', 'r0': (a, 0.)}, 

126 {'tag': 'c', 'r0': (0., a)}] 

127 return _lat(unit_cell, [(2*a, 0.), (0., 2*a)])