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 

20 

21from tbkit.lattice import Lattice 

22import tbkit.error_handling as error_handling 

23 

24 

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

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

27 

28 

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

30 ''' 

31 1D chain: one site per unit cell. 

32 

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

34 ''' 

35 error_handling.positive_real(a, 'a') 

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

37 

38 

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

40 ''' 

41 Square lattice: one site per unit cell. 

42 

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

44 ''' 

45 error_handling.positive_real(a, 'a') 

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

47 

48 

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

50 ''' 

51 Triangular lattice: one site per unit cell. 

52 

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

54 ''' 

55 error_handling.positive_real(a, 'a') 

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

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

58 

59 

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

61 ''' 

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

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

64 for ready-made finite flakes of various shapes. 

65 

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

67 ''' 

68 error_handling.positive_real(a, 'a') 

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

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

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

72 return _lat(unit_cell, prim_vec) 

73 

74 

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

76 ''' 

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

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

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

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

81 

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

83 

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

85 

86 lat = lattices.kagome() 

87 kag = KSpace(lat) 

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

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

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

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

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

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

94 ''' 

95 error_handling.positive_real(a, 'a') 

96 a1 = (2*a, 0.) 

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

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

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

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

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

102 

103 

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

105 ''' 

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

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

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

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

110 

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

112 

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

114 

115 lat = lattices.lieb() 

116 lb = KSpace(lat) 

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

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

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

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

121 ''' 

122 error_handling.positive_real(a, 'a') 

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

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

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

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