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 ofnum_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 tohamiltonian_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 thehoppings
matrixParameters: - 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
. Therow
andcol
indices of the sparse matrix are used to draw lines between lattice sites, whiledata
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:
-
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()
. Therow
andcol
indices of the sparse matrix are used to draw lines between lattice sites, whiledata
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 ondata
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 discretecolors
parameter should be used. For continuous data, setting acmap
(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 thecmap
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:
-
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