system¶

Structural information and utilities

Classes

`System`(impl[, lattice])	Structural data of a tight-binding model
`_CppSites`(impl)	Tailored to the internal C++ compressed sublattice representation

Functions

`_data_units_to_points`(ax, value)	Convert a value from data units to points
`_make_shift_set`(boundaries, level)	Return a set of boundary shift combinations for the given repetition level
`decorate_structure_plot`([axes, add_margin, ax])
`plot_hopping_values`(system[, ax])	Show the hopping energy over each hopping line (mainly for debugging)
`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_site_indices`(system[, ax])	Show the Hamiltonian index next to each atom (mainly for debugging)
`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

Reference implementation of AbstractSites

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

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

Parameters:

target_positionarray_like
target_site_familyint: 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])
>>> bool(np.all(sites.argsort_nearest([1, 0, 0]) == [1, 2, 0]))
True
>>> bool(np.all(sites.argsort_nearest([1, 0, 0], target_site_family=0) == [2, 0, 1]))
True

Return the distances of all sites from the target position

Parameters:

target_positionarray_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

Return the index of the position nearest the target

Parameters:

target_positionarray_like
target_site_familyOptional[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])
>>> int(sites.find_nearest([1, 0, 0]))
1
>>> int(sites.find_nearest([1, 0, 0], target_site_family=0))
2

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

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

property size: int¶: Total number of sites

property x¶: 1D array of coordinates

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

property y¶: 1D array of coordinates

property z¶: 1D array of coordinates

class System(impl: System, lattice: Lattice | None = None)¶

Structural data of a tight-binding model

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

__getitem__(idx: int | List[int]) → Structure¶: Same rules as numpy indexing

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

cropped(**limits) → Structure¶

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 the index of the atom closest to the given position

Parameters:

positionarray_like: Where to look.
sublatticeOptional[str]: Look for a specific sublattice site. By default any will do.

Returns:

int

plot(num_periods: int = 1, ax: Axes | None = None, **kwargs) → CircleCollection | None¶

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

Parameters:

num_periodsint: Number of times to repeat the periodic boundaries.
axOptional[plt.Axes]: The axis to plot on.
**kwargs: Additional plot arguments as specified in structure_plot_properties().

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:

dataarray_like: Must be 1D and the equal to the size of the Hamiltonian matrix

Returns:

array_like

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:

dataarray_like: Must be 1D and the equal to the size of the Hamiltonian matrix
idxint: List of booleans that are included.

Returns:

array_like

to_hamiltonian_indices(system_idx: int) → ndarray¶

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_idxint

Returns:

array_like

with_data(data: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → StructureMap¶: Map some data to this system

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

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

property expanded_sublattices: AliasArray¶: sublattices expanded to hamiltonian_size by replicating for each orbital

property hamiltonian_size: int¶

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.

property hoppings: Hoppings¶: Sparse matrix of hopping IDs

property num_sites: int¶: Total number of lattice sites

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

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

property sublattices: ndarray¶: 1D array of sublattices IDs

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

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

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

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

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

Parameters:

positionsTuple[array_like, array_like, array_like]: Site coordinates in the form of an (x, y, z) tuple of 1D arrays.
hoppingscoo_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.
widthfloat: Width of the hopping plot lines.
offsetTuple[float, float, float]: Offset all positions by a constant value.
blendfloat: Blend all colors to white (fake alpha blending): expected values between 0 and 1.
axesstr: The spatial axes to plot. E.g. ‘xy’, ‘yz’, etc.
colorstr: Set the same color for all hopping lines. To assign a different color for each hopping ID, use the cmap parameter.
boundaryTuple[int, array_like]: If given, apply the boundary (sign, shift).
draw_onlyIterable[str]: Only draw lines for the hoppings named in this list.
axOptional[plt.Axes]: The axis to plot on.
**kwargs: Forwarded to matplotlib.collections.LineCollection.

Returns:

matplotlib.collections.LineCollection

Plot the periodic boundaries of a system

Parameters:

positionsTuple[array_like, array_like, array_like]: Site coordinates in the form of an (x, y, z) tuple of 1D arrays.
hoppingscoo_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.
boundariesList[Boundary]: Periodic boundaries of a System.
dataarray_like: Color data at each site. Should be a 1D array of the same size as positions.
num_periodsint: Number of times to repeat the periodic boundaries.
axOptional[plt.Axes]: The axis to plot on.
**kwargs: Additional plot arguments as specified in structure_plot_properties().

Plot circles at lattice site positions with colors based on data

Parameters:

positionsTuple[array_like, array_like, array_like]: Site coordinates in the form of an (x, y, z) tuple of 1D arrays.
dataarray_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.
radiusUnion[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.
offsetTuple[float, float, float]: Offset all positions by a constant value.
blendfloat: Blend all colors to white (fake alpha blending): expected values between 0 and 1.
cmapUnion[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.
axesstr: The spatial axes to plot. E.g. ‘xy’, ‘yz’, etc.
axOptional[plt.Axes]: The axis to plot on.
**kwargs: Forwarded to matplotlib.collections.CircleCollection.

Returns:

matplotlib.collections.CircleCollection

structure_plot_properties(axes: Literal['xyz', 'xy', 'xz', 'yx', 'yz', 'zx', 'zy'] = 'xyz', site: dict | None = None, hopping: dict | None = None, boundary: dict | None = None, **kwargs) → dict¶

Process structure plot properties

Parameters:

axesstr: The spatial axes to plot. E.g. ‘xy’ for the default view, or ‘yz’, ‘xz’ and similar to plot a rotated view.
sitedict: Arguments forwarded to plot_sites().
hoppingdict: Arguments forwarded to plot_hoppings().
boundarydict: Arguments forwarded to plot_periodic_boundaries().
**kwargs: Additional args are reserved for internal implementation.

Returns:

dict