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 

11Examples 

12-------- 

13Example usage:: 

14 

15 import tbkit.lattices as lattices 

16 lat = lattices.kagome() 

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

18""" 

19from __future__ import annotations 

20 

21from math import sqrt 

22from typing import Sequence 

23 

24from tbkit.lattice import Lattice 

25import tbkit.error_handling as error_handling 

26 

27 

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

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

30 

31 

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

33 ''' 

34 1D chain: one site per unit cell. 

35 

36 Parameters 

37 ---------- 

38 a : Positive real number, default 1 

39 Lattice constant. 

40 ''' 

41 error_handling.positive_real(a, 'a') 

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

43 

44 

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

46 ''' 

47 Square lattice: one site per unit cell. 

48 

49 Parameters 

50 ---------- 

51 a : Positive real number, default 1 

52 Lattice constant. 

53 ''' 

54 error_handling.positive_real(a, 'a') 

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

56 

57 

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

59 ''' 

60 Triangular lattice: one site per unit cell. 

61 

62 Parameters 

63 ---------- 

64 a : Positive real number, default 1 

65 Lattice constant. 

66 ''' 

67 error_handling.positive_real(a, 'a') 

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

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

70 

71 

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

73 ''' 

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

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

76 for ready-made finite flakes of various shapes. 

77 

78 Parameters 

79 ---------- 

80 a : Positive real number, default 1 

81 Nearest-neighbor distance. 

82 ''' 

83 error_handling.positive_real(a, 'a') 

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

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

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

87 return _lat(unit_cell, prim_vec) 

88 

89 

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

91 ''' 

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

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

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

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

96 

97 Parameters 

98 ---------- 

99 a : Positive real number, default 1 

100 Nearest-neighbor distance. 

101 

102 Examples 

103 -------- 

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

105 

106 lat = lattices.kagome() 

107 kag = KSpace(lat) 

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

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

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

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

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

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

114 ''' 

115 error_handling.positive_real(a, 'a') 

116 a1 = (2*a, 0.) 

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

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

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

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

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

122 

123 

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

125 ''' 

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

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

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

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

130 

131 Parameters 

132 ---------- 

133 a : Positive real number, default 1 

134 Nearest-neighbor distance. 

135 

136 Examples 

137 -------- 

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

139 

140 lat = lattices.lieb() 

141 lb = KSpace(lat) 

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

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

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

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

146 ''' 

147 error_handling.positive_real(a, 'a') 

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

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

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

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