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

hoppings Dict of names and HoppingFamily
min_neighbors Minimum number of neighbours required at each lattice site
ndim The dimensionality of the lattice: number of primitive vectors
nhop Number of hopping families
nsub Number of sublattices
offset Global lattice offset: sublattice offsets are defined relative to this
sublattices Dict of names and Sublattice
vectors Primitive lattice vectors

Methods

add_aliases(\*aliases) Add multiple new aliases
add_hoppings(\*hoppings) Add multiple new hoppings
add_one_alias(name, original, position) Add a sublattice alias - useful for creating supercells
add_one_hopping(relative_index, from_sub, ...) Add a new hopping
add_one_sublattice(name, position[, ...]) 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([axes, 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
add_aliases(*aliases)

Add multiple new aliases

Parameters:

*aliases

Each element should be a tuple containing the arguments for add_one_alias(). Works just like add_sublattices().

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_alias(name, original, position)

Add a sublattice alias - useful for creating supercells

Create a new sublattice called name with the same properties as original (same onsite energy) but with at a different position. The new name is only used during lattice construction and the original will be used for the final system and Hamiltonian. This is useful when defining a supercell which contains multiple sites of one sublattice family at different positions.

Parameters:

name : str

User-friendly identifier of the alias.

original : str

Name of the original sublattice. It must already exist.

position : array_like

Cartesian position with respect to the origin. Usually different than the original.

add_one_hopping(relative_index, from_sub, to_sub, 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_sub : str

Name of the sublattice in the source unit cell.

to_sub : 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, position, onsite_energy=0.0, alias='')

Add a new sublattice

Parameters:

name : str

User-friendly identifier. The unique sublattice ID can later be accessed via this sublattice name as lattice[sublattice_name].

position : array_like

Cartesian position with respect to the origin.

onsite_energy : float

Onsite energy to be applied only to sites of this sublattice.

alias : str

Deprecated: Use add_one_alias() instead.

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(axes='xy', vector_position='center', **kwargs)

Illustrate the lattice by plotting the primitive cell and its nearest neighbors

Parameters:

axes : str

The spatial axes to plot. E.g. ‘xy’, ‘yz’, etc.

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.

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:

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.

Returns:

Lattice

hoppings

Dict of names and HoppingFamily

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

nhop

Number of hopping families

nsub

Number of sublattices

offset

Global lattice offset: sublattice offsets are defined relative to this

It must be within half the length of a primitive lattice vector.

sublattices

Dict of names and Sublattice

vectors

Primitive lattice vectors