Lattice¶

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, a3array_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

`__call__`(name)	Call self as a function.
`__getitem__`(name)
`_visible_sublattices`(axes)	Return the sublattices which are visible when viewed top-down in the `axes` plane
`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)
`from_impl`(impl)
`plot`([axes, vector_position, ax])	Illustrate the lattice by plotting the primitive cell and its nearest neighbors
`plot_brillouin_zone`([decorate, ax])	Plot the Brillouin zone and reciprocal lattice vectors
`plot_vectors`(position[, scale, ax])	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: str) → str¶: Call self as a function.

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 multiple new hoppings

Warning

The hoppings in pybinding are implemented as the Hermitian conjugate,

\[\begin{split}\langle \text{to} | \hat H | \text{from} \rangle = \left(\begin{matrix}0 & t^\dagger\\t & 0\end{matrix}\right)\end{split}\]

the element \(t^\dagger\) is the input for the hoppings function.

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 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:

namestr: User-friendly identifier of the alias.
originalstr: Name of the original sublattice. It must already exist.
positionarray_like: Cartesian position with respect to the origin. Usually different than the original.

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.

Warning

The hoppings in pybinding are implemented as the Hermitian conjugate,

\[\begin{split}\langle \text{to} | \hat H | \text{from} \rangle = \left(\begin{matrix}0 & t^\dagger\\t & 0\end{matrix}\right)\end{split}\]

the element \(t^\dagger\) is the input for the hoppings function.

Parameters:

relative_indexarray_like of int: Difference of the indices of the source and destination unit cells.
from_substr: Name of the sublattice in the source unit cell.
to_substr: Name of the sublattice in the destination unit cell.
hop_name_or_energyfloat or str: The numeric value of the hopping energy or the name of a previously registered hopping.

Add a new sublattice

Warning

The hoppings in pybinding are implemented as the Hermitian conjugate,

\[\begin{split}\langle \text{to} | \hat H | \text{from} \rangle = \left(\begin{matrix}0 & t^\dagger\\t & 0\end{matrix}\right)\end{split}\]

the element \(t^\dagger\) is the input for the hoppings function. However, the onsite energy is not affected by this and should be given in the normal manner.

Parameters:

namestr: User-friendly identifier. The unique sublattice ID can later be accessed via this sublattice name as lattice[sublattice_name].
positionarray_like: Cartesian position with respect to the origin.
onsite_energyfloat: Onsite energy to be applied only to sites of this sublattice.
aliasstr: Deprecated: Use add_one_alias() instead.

Add multiple new sublattices

Warning

The hoppings in pybinding are implemented as the Hermitian conjugate,

\[\begin{split}\langle \text{to} | \hat H | \text{from} \rangle = \left(\begin{matrix}0 & t^\dagger\\t & 0\end{matrix}\right)\end{split}\]

the element \(t^\dagger\) is the input for the hoppings function. However, the onsite energy is not affected by this and should be given in the normal manner.

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() → List[ndarray]¶

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(np.array(lat_2d.brillouin_zone()), np.array([[0, -2*pi], [2*pi, 0], [0, 2*pi], [-2*pi, 0]]))
True

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

Parameters:

axesstr: The spatial axes to plot. E.g. ‘xy’, ‘yz’, etc.
vector_positionarray_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.
axOptional[plt.Axes]: The axis to plot on.
**kwargs: Forwarded to System.plot().

plot_brillouin_zone(decorate: bool = True, ax: Axes | None = None, **kwargs) → None¶

Plot the Brillouin zone and reciprocal lattice vectors

Parameters:

decoratebool: Label the vertices of the Brillouin zone and show the reciprocal vectors
axOptional[plt.Axes]: Axis to plot the billouin-zone on.
**kwargs: Forwarded to plt.plot().

Plot lattice vectors in the xy plane

Parameters:

positionarray_like: Cartesian position to be used as the origin for the vectors.
scalefloat: Multiply the length of the vectors by this number.
axOptional[plt.Axes]: The axis to plot on.

reciprocal_vectors() → List[ndarray]¶

Calculate the reciprocal space lattice vectors

Returns:

list

Examples

>>> lat = Lattice(a1=[0, 1], a2=[0.5, 0.5])
>>> np.allclose(np.array(lat.reciprocal_vectors()), np.array([[-2*pi, 2*pi, 0], [4*pi, 0, 0]]))
True

register_hopping_energies(mapping: dict) → None¶

Register a mapping of user-friendly names to hopping energies

Warning

The hoppings in pybinding are implemented as the Hermitian conjugate,

\[\begin{split}\langle \text{to} | \hat H | \text{from} \rangle = \left(\begin{matrix}0 & t^\dagger\\t & 0\end{matrix}\right)\end{split}\]

the element \(t^\dagger\) is the input for the hoppings function.

Parameters:

mappingdict: Keys are user-friendly hopping names and values are the numeric values of the hopping energy.

site_radius_for_plot(max_fraction: float = 0.33) → float¶

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_fractionfloat: 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) → Lattice¶

Return a copy of this lattice with a different minimum neighbor count

Parameters:

numberint: The minimum number of neighbors.

Returns:

Lattice

Return a copy of this lattice with a different offset

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

Parameters:

positionarray_like: Cartesian offset in the same length unit as the lattice vectors.

Returns:

Lattice

property hoppings: dict¶: Dict of names and HoppingFamily

property min_neighbors: int¶

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.

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

property nhop: int¶: Number of hopping families

property nsub: int¶: Number of sublattices

property offset: <property object at 0x7f77a37bc810>¶

Global lattice offset: sublattice offsets are defined relative to this

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

property sublattices: dict¶: Dict of names and Sublattice

property vectors: list¶: Primitive lattice vectors