# Lattice¶

class Lattice(a1, a2=None, a3=None)

Unit cell of a Bravais lattice, the basic building block of a tight-binding 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 1-dimensional lattice. If a2 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 user-friendly name __getitem__(name) Get sublattice ID from its user-friendly 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 user-friendly 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 user-friendly name

__getitem__(name)

Get sublattice ID from its user-friendly name

add_hopping_matrices(*pairs)

Add hoppings in the matrix format

Parameters: *pairs Each element is a tuple of relative_index and hopping_matrix.
add_hoppings(*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)


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)

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)

Parameters: name : str User-friendly 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)

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)


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 user-friendly names to hopping energies

Parameters: mapping : dict Keys are user-friendly 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 inter-atomic spacing.

Parameters: max_fraction : float Set the upper limit of the calculated radius as this fraction of the shortest inter-atomic spacing in the lattice unit cell. Should be less than 0.5 to avoid overlap between neighboring lattice sites. 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. Lattice
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. Lattice
hopping_energies

Unique energies indexed by hopping IDs

min_neighbors

Minimum number of neighbours required at each lattice site

When constructing a finite-sized 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