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