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
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 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)¶ Call self as a function.

add_aliases
(*aliases)¶ Add multiple new aliases
Parameters:  *aliases
Each element should be a tuple containing the arguments for
add_one_alias()
. Works just likeadd_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 asoriginal
(same onsite energy) but with at a differentposition
. The newname
is only used during lattice construction and theoriginal
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
Userfriendly 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
Userfriendly 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(), [[2*pi, 2*pi, 0], [4*pi, 0, 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:

hoppings
¶ Dict of names and
HoppingFamily

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

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