system¶

Structural information and utilities

Classes

`Sites`(positions[, ids])	Reference implementation of `AbstractSites`
`System`(impl[, lattice])	Structural data of a tight-binding model

Functions

`plot_hoppings`(positions, hoppings[, width, …])	Plot lines between lattice sites at `positions` based on the `hoppings` matrix
`plot_periodic_boundaries`(positions, …[, …])	Plot the periodic boundaries of a system
`plot_sites`(positions, data[, radius, …])	Plot circles at lattice site `positions` with colors based on `data`
`structure_plot_properties`([axes, site, …])	Process structure plot properties

class Sites(positions, ids=None)¶

Reference implementation of AbstractSites

__getitem__(item)¶: Matches numpy indexing behavior and applies it to all attributes

argsort_nearest(target_position, target_site_family=None)¶

Return an ndarray of site indices, sorted by distance from the target

Parameters:	target_position : array_like target_site_family : int Look for a specific sublattice site. By default any will do.
Returns:	np.ndarray

Examples

>>> sites = Sites(([0, 1, 1.1], [0, 0, 0], [0, 0, 0]), [0, 1, 0])
>>> np.all(sites.argsort_nearest([1, 0, 0]) == [1, 2, 0])
True
>>> np.all(sites.argsort_nearest([1, 0, 0], target_site_family=0) == [2, 0, 1])
True

distances(target_position)¶

Return the distances of all sites from the target position

Parameters:	target_position : array_like

Examples

>>> sites = Sites(([0, 1, 1.1], [0, 0, 0], [0, 0, 0]), [0, 1, 0])
>>> np.allclose(sites.distances([1, 0, 0]), [1, 0, 0.1])
True

find_nearest(target_position, target_site_family='')¶

Return the index of the position nearest the target

Parameters:	target_position : array_like target_site_family : Optional[str] Look for a specific sublattice site. By default any will do.
Returns:	int

Examples

>>> sites = Sites(([0, 1, 1.1], [0, 0, 0], [0, 0, 0]), [0, 1, 0])
>>> sites.find_nearest([1, 0, 0])
1
>>> sites.find_nearest([1, 0, 0], target_site_family=0)
2

ids¶: Site family identifies. Multiple sites can share the same ID, e.g. sites which belong to the same sublattice.

positions¶: Named tuple of x, y, z positions

size¶: Total number of sites

x¶: 1D array of coordinates

xyz¶: Return a new array with shape=(N, 3). Convenient, but slow for big systems.

y¶: 1D array of coordinates

z¶: 1D array of coordinates

class System(impl: _pybinding.System, lattice=None)¶

Structural data of a tight-binding model

Stores positions, sublattice and hopping IDs for all lattice sites.

__getitem__(idx)¶: Same rules as numpy indexing

count_neighbors()¶: Return the number of neighbors for each site

cropped(**limits)¶

Return a copy which retains only the sites within the given limits

Parameters:	**limits Attribute names and corresponding limits. See example.

Examples

Leave only the data where -10 <= x < 10 and 2 <= y < 4:

new = original.cropped(x=[-10, 10], y=[2, 4])

find_nearest(position, sublattice='')¶

Find the index of the atom closest to the given position

Parameters:	position : array_like Where to look. sublattice : Optional[str] Look for a specific sublattice site. By default any will do.
Returns:	int

plot(num_periods=1, **kwargs)¶

Plot the structure: sites, hoppings and periodic boundaries (if any)

Parameters:	num_periods : int Number of times to repeat the periodic boundaries. **kwargs Additional plot arguments as specified in `structure_plot_properties()`.

reduce_orbitals(data)¶

Sum up the contributions of individual orbitals in the given data

Takes a 1D array of hamiltonian_size and returns a 1D array of num_sites size where the multiple orbital data has been reduced per site.

Parameters:	data : array_like Must be 1D and the equal to the size of the Hamiltonian matrix
Returns:	array_like

to_hamiltonian_indices(system_idx)¶

Translate the given system index into its corresponding Hamiltonian indices

System indices are always scalars and index a single (x, y, z) site position. For single-orbital models there is a 1:1 correspondence between system and Hamiltonian indices. However, for multi-orbital models the Hamiltonian indices are 1D arrays with a size corresponding to the number of orbitals on the target site.

Parameters:	system_idx : int
Returns:	array_like

with_data(data) → pybinding.results.StructureMap¶: Map some data to this system

boundaries¶: Boundary hoppings between different translation units (only for infinite systems)

expanded_positions¶: positions expanded to hamiltonian_size by replicating for each orbital

hamiltonian_size¶

The size of the Hamiltonian matrix constructed from this system

Takes into account the number of orbitals/spins at each lattice site which makes hamiltonian_size >= num_sites.

hoppings¶: Sparse matrix of hopping IDs

num_sites¶: Total number of lattice sites

positions¶: Lattice site positions. Named tuple with x, y, z fields, each a 1D array.

sub¶: 1D array of sublattices IDs, short for .sublattices

sublattices¶: 1D array of sublattices IDs

x¶: 1D array of coordinates, short for .positions.x

xyz¶: Return a new array with shape=(N, 3). Convenient, but slow for big systems.

y¶: 1D array of coordinates, short for .positions.y

z¶: 1D array of coordinates, short for .positions.z

plot_hoppings(positions, hoppings, width=1.0, offset=(0, 0, 0), blend=1.0, color='#666666', axes='xyz', boundary=(), draw_only=(), **kwargs)¶

Plot lines between lattice sites at positions based on the hoppings matrix

Parameters:

positions : Tuple[array_like, array_like, array_like]: Site coordinates in the form of an (x, y, z) tuple of 1D arrays.
hoppings : coo_matrix: Sparse matrix with the hopping data, usually System.hoppings. The row and col indices of the sparse matrix are used to draw lines between lattice sites, while data determines the color.
width : float: Width of the hopping plot lines.
offset : Tuple[float, float, float]: Offset all positions by a constant value.
blend : float: Blend all colors to white (fake alpha blending): expected values between 0 and 1.
axes : str: The spatial axes to plot. E.g. ‘xy’, ‘yz’, etc.
color : str: Set the same color for all hopping lines. To assign a different color for each hopping ID, use the cmap parameter.
boundary : Tuple[int, array_like]: If given, apply the boundary (sign, shift).
draw_only : Iterable[str]: Only draw lines for the hoppings named in this list.
**kwargs: Forwarded to matplotlib.collections.LineCollection.

Returns:

matplotlib.collections.LineCollection

plot_periodic_boundaries(positions, hoppings, boundaries, data, num_periods=1, **kwargs)¶

Plot the periodic boundaries of a system

Parameters:

positions : Tuple[array_like, array_like, array_like]: Site coordinates in the form of an (x, y, z) tuple of 1D arrays.
hoppings : coo_matrix: Sparse matrix with the hopping data, usually System.hoppings(). The row and col indices of the sparse matrix are used to draw lines between lattice sites, while data determines the color.
boundaries : List[Boundary]: Periodic boundaries of a System.
data : array_like: Color data at each site. Should be a 1D array of the same size as positions.
num_periods : int: Number of times to repeat the periodic boundaries.
**kwargs: Additional plot arguments as specified in structure_plot_properties().

plot_sites(positions, data, radius=0.025, offset=(0, 0, 0), blend=1.0, cmap='auto', axes='xyz', **kwargs)¶

Plot circles at lattice site positions with colors based on data

Parameters:

positions : Tuple[array_like, array_like, array_like]: Site coordinates in the form of an (x, y, z) tuple of 1D arrays.
data : array_like: Color data at each site. Should be a 1D array of the same size as positions. If the data is discrete with few unique values, the discrete colors parameter should be used. For continuous data, setting a cmap (colormap) is preferred.
radius : Union[float, array_like]: Radius (in data units) of the plotted circles representing lattice sites. Should be a scalar value or an array with the same size as positions.
offset : Tuple[float, float, float]: Offset all positions by a constant value.
blend : float: Blend all colors to white (fake alpha blending): expected values between 0 and 1.
cmap : Union[str, List[str]]: Either a regular matplotlib colormap or a list of discrete colors to apply to the drawn circles. In the latter case, it is assumed that data is discrete with only a few unique values. For example, sublattice data for graphene will only contain two unique values for the A and B sublattices which will be assigned the first two colors from the cmap list. For continuous data, a regular matplotlib colormap should be used instead.
axes : str: The spatial axes to plot. E.g. ‘xy’, ‘yz’, etc.
**kwargs: Forwarded to matplotlib.collections.CircleCollection.

Returns:

matplotlib.collections.CircleCollection

structure_plot_properties(axes='xyz', site=None, hopping=None, boundary=None, **kwargs)¶

Process structure plot properties

Parameters:	axes : str The spatial axes to plot. E.g. ‘xy’ for the default view, or ‘yz’, ‘xz’ and similar to plot a rotated view. site : dict Arguments forwarded to `plot_sites()`. hopping : dict Arguments forwarded to `plot_hoppings()`. boundary : dict Arguments forwarded to `plot_periodic_boundaries()`. **kwargs Additional args are reserved for internal implementation.
Returns:	dict