Lattice¶

class
Lattice
(a1, a2=None, a3=None)¶ Unit cell of a Bravais lattice, the basic building block of a tightbinding model
This class describes the primitive vectors, positions of sublattice sites and hopping parameters which connect those sites. All of this structural information is used to build up a larger system by translation.
A few prebuilt lattices are available in the Material Repository.
Parameters: a1, a2, a3 : array_like
Primitive vectors of a Bravais lattice. A valid lattice must have at least one primitive vector (
a1
), thus forming a simple 1dimensional lattice. Ifa2
is also specified, a 2D lattice is created. Passing values for all three vectors will create a 3D lattice.Attributes
hopping_energies
Unique energies indexed by hopping IDs min_neighbors
Minimum number of neighbours required at each lattice site ndim
The dimensionality of the lattice: number of primitive vectors offset
Global lattice offset: sublattice offsets are defined relative to this sublattices
List of Sublattice
vectors
Primitive lattice vectors Methods
__call__
(name)Get the hopping ID from its userfriendly name
__getitem__
(name)Get sublattice ID from its userfriendly name
add_hopping_matrices
(*pairs)Add hoppings in the matrix format add_hoppings
(*hoppings)Add multiple new hoppings add_one_hopping
(relative_index, ...)Add a new hopping add_one_sublattice
(name, offset[, ...])Add a new sublattice add_sublattices
(*sublattices)Add multiple new sublattices brillouin_zone
()Return a list of vertices which form the Brillouin zone (1D and 2D only) plot
([vector_position])Illustrate the lattice by plotting the primitive cell and its nearest neighbors plot_brillouin_zone
([decorate])Plot the Brillouin zone and reciprocal lattice vectors plot_vectors
(position[, scale])Plot lattice vectors in the xy plane reciprocal_vectors
()Calculate the reciprocal space lattice vectors register_hopping_energies
(mapping)Register a mapping of userfriendly names to hopping energies site_radius_for_plot
([max_fraction])Return a good estimate for the lattice site radius for plotting with_min_neighbors
(number)Return a copy of this lattice with a different minimum neighbor count with_offset
(position)Return a copy of this lattice with a different offset 
__call__
(name)¶ Get the hopping ID from its userfriendly
name

__getitem__
(name)¶ Get sublattice ID from its userfriendly
name

add_hopping_matrices
(*pairs)¶ Add hoppings in the matrix format
Parameters: *pairs
Each element is a tuple of
relative_index
andhopping_matrix
.

add_hoppings
(*hoppings)¶ Add multiple new hoppings
Parameters: *hoppings
Each element should be a tuple containing the arguments for a
add_one_hopping()
method call. See example.Examples
These three calls:
lattice.add_one_hopping([0, 0], 'a', 'b', 0.8) lattice.add_one_hopping([0, 1], 'a', 'a', 0.3) lattice.add_one_hopping([1, 1], 'a', 'b', 0.8)
Can be replaced with a single call to:
lattice.add_hoppings( ([0, 0], 'a', 'b', 0.8), ([0, 1], 'a', 'a', 0.3), ([1, 1], 'a', 'b', 0.8), )

add_one_hopping
(relative_index, from_sublattice, to_sublattice, hop_name_or_energy)¶ Add a new hopping
For each new hopping, its Hermitian conjugate is added automatically. Doing so manually, i.e. adding a hopping which is the Hermitian conjugate of an existing one, will result in an exception being raised.
Parameters: relative_index : array_like of int
Difference of the indices of the source and destination unit cells.
from_sublattice : str
Name of the sublattice in the source unit cell.
to_sublattice : str
Name of the sublattice in the destination unit cell.
hop_name_or_energy : float or str
The numeric value of the hopping energy or the name of a previously registered hopping.

add_one_sublattice
(name, offset, onsite_energy=0.0, alias=None)¶ Add a new sublattice
Parameters: name : str
Userfriendly identifier. The unique sublattice ID can later be accessed via this sublattice name as
lattice[sublattice_name]
.offset : array_like
Cartesian position with respect to the origin.
onsite_energy : float, optional
Onsite energy to be applied only to sites of this sublattice.
alias : str, optional
Given the name of a previously defined sublattice, the new sublattice is created as an alias for the old one. This is useful when defining a supercell which contains multiple sites of one sublattice family at different positions.

add_sublattices
(*sublattices)¶ Add multiple new sublattices
Parameters: *sublattices
Each element should be a tuple containing the arguments for a
add_one_sublattice()
method call. See example.Examples
These three calls:
lattice.add_one_sublattice('a', [0, 0], 0.5) lattice.add_one_sublattice('b', [0, 1], 0.0) lattice.add_one_sublattice('c', [1, 0], 0.3)
Can be replaced with a single call to:
lattice.add_sublattices( ('a', [0, 0], 0.5), ('b', [0, 1], 0.0), ('c', [1, 0], 0.3) )

brillouin_zone
()¶ Return a list of vertices which form the Brillouin zone (1D and 2D only)
Returns: List[array_like] Examples
>>> lat_1d = Lattice(a1=1) >>> np.allclose(lat_1d.brillouin_zone(), [pi, pi]) True >>> lat_2d = Lattice(a1=[0, 1], a2=[0.5, 0.5]) >>> np.allclose(lat_2d.brillouin_zone(), [[0, 2*pi], [2*pi, 0], [0, 2*pi], [2*pi, 0]]) True

plot
(vector_position='center', **kwargs)¶ Illustrate the lattice by plotting the primitive cell and its nearest neighbors
Parameters: vector_position : array_like or ‘center’
Cartesian position to be used as the origin for the lattice vectors. By default the origin is placed in the center of the primitive cell.
**kwargs
Forwarded to
System.plot()
.

plot_brillouin_zone
(decorate=True, **kwargs)¶ Plot the Brillouin zone and reciprocal lattice vectors
Parameters: decorate : bool
Label the vertices of the Brillouin zone and show the reciprocal vectors
**kwargs
Forwarded to
plt.plot()
.

plot_vectors
(position, scale=1.0)¶ Plot lattice vectors in the xy plane
Parameters: position : array_like
Cartesian position to be used as the origin for the vectors.
scale : float
Multiply the length of the vectors by this number.

reciprocal_vectors
()¶ Calculate the reciprocal space lattice vectors
Returns: list Examples
>>> lat = Lattice(a1=[0, 1], a2=[0.5, 0.5]) >>> np.allclose(lat.reciprocal_vectors(), [[4*pi, 0, 0], [2*pi, 2*pi, 0]]) True

register_hopping_energies
(mapping)¶ Register a mapping of userfriendly names to hopping energies
Parameters: mapping : dict
Keys are userfriendly hopping names and values are the numeric values of the hopping energy.

site_radius_for_plot
(max_fraction=0.33)¶ Return a good estimate for the lattice site radius for plotting
Calculated heuristically base on the length (1D) or area (2D) of the unit cell. In order to prevent overlap between sites, if the computed radius is too large, it will be clamped to a fraction of the shortest interatomic spacing.
Parameters: max_fraction : float
Set the upper limit of the calculated radius as this fraction of the shortest interatomic spacing in the lattice unit cell. Should be less than 0.5 to avoid overlap between neighboring lattice sites.
Returns: float

with_min_neighbors
(number)¶ Return a copy of this lattice with a different minimum neighbor count
Parameters: number : int
The minimum number of neighbors.
Returns:

with_offset
(position)¶ Return a copy of this lattice with a different offset
It must be within half the length of a primitive lattice vector
Parameters: position : array_like
Cartesian offset in the same length unit as the lattice vectors.
Returns:

hopping_energies
¶ Unique energies indexed by hopping IDs

min_neighbors
¶ Minimum number of neighbours required at each lattice site
When constructing a finitesized system, lattice sites with less neighbors than this minimum will be considered as “dangling” and they will be removed.

ndim
¶ The dimensionality of the lattice: number of primitive vectors

offset
¶ Global lattice offset: sublattice offsets are defined relative to this
It must be within half the length of a primitive lattice vector.

sublattices
¶ List of
Sublattice

vectors
¶ Primitive lattice vectors
