lattpy.data

This module contains objects for low-level representation of lattice systems.

class lattpy.data.DataMap(alphas, pairs, distindices)[source]

Bases: object

Object for low-level representation of sites and site-pairs.

Parameters:

alphas(N) np.ndarray: The atom indices of the sites.
pairs(M, 2) np.ndarray: An array of index-pairs of the lattice sites.
distindices(M) np.ndarray: The distance-indices for each pair

Notes

This object is not intended to be instantiated by the user. Use the map method of latticeData or the dmap method of the main ``Lattice```object.

property size: The number of the data points (sites + neighbor pairs)

property indices: The indices of the data points as rows and collumns.

property rows: The rows of the data points.

property cols: The columns of the data points.

property nbytes: The number of bytes stored in the datamap.

indices_indptr()[source]

Constructs the indices and indptr arrays used for CSR/BSR matrices.

CSR/BSR sparse matrix format: The block column indices for row i are stored in indices[indptr[i]:indptr[i+1]] and their corresponding block values are stored in data[indptr[i]: indptr[i+1]].

Returns:

indices(N, ) np.ndarray: CSR/BSR format index array.
indptr(M, ) np.ndarray: CSR/BSR format index pointer array.

See also

scipy.sparse.csr_matrix: Compressed Sparse Row matrix
scipy.sparse.bsr_matrix: Block Sparse Row matrix

onsite(alpha=None)[source]

Creates a mask of the site elements for the atoms with the given index.

Parameters:

alphaint, optional: Index of the atom in the unitcell. If None a mask for all atoms is returned. The default is None.

Returns:

masknp.ndarray

hopping(distidx=None)[source]

Creates a mask of the site-pair elements with the given distance index.

Parameters:

distidxint, optional: Index of distance to neighboring sites, default is 0 (nearest neighbors). If None a mask for neighbor-connections is returned. The default is None.

Returns:

masknp.ndarray

zeros(norb=None, dtype=None)[source]

Creates an empty data-arary.

Parameters:

norbint, optional: The number of orbitals M. By default, only a single orbital is used.
dtypeint or str or np.dtype, optional: The data type of the array. By default, it is set automatically.

Returns:

datanp.ndarray: The empty data array. If a single orbital is used the array is one-dimensional, otherwise the array has the shape (N, M, M).

build_csr(data, shape=None, dtype=None)[source]

Constructs a CSR matrix using the given data and the indices of the data map.

Parameters:

data(N,) np.ndarray: The input data for constructing the CSR matrix. The data array should be filled using the built-in mask methods of the DataMap class.
shapetuple, optional: The shape of the resulting matrix. If None (default), the shape is inferred from the data and indices of the matrix.
dtypeint or str or np.dtype, optional: The data type of the matrix. By default, it is set automatically.

Returns:

sparse_mat(M, M) scipy.sparse.csr.csr_matrix: The sparse matrix representing the lattice data.

build_bsr(data, shape=None, dtype=None)[source]

Constructs a BSR matrix using the given data and the indices of the data map.

Parameters:

data(N, B, B) np.ndarray: The input data for constructing the BSR matrix. The array must be 3-dimensional, where the first axis N represents the number of blocks and the last two axis B the size of each block. The data array should be filled using the built-in mask methods of the DataMap class.
shapetuple, optional: The shape of the resulting matrix. If None (default), the shape is inferred from the data and indices of the matrix.
dtypeint or str or np.dtype, optional: The data type of hte matrix. By default, it is set automatically.

Returns:

sparse_mat(M, M) scipy.sparse.csr.bsr_matrix: The sparse matrix representing the lattice data.

class lattpy.data.LatticeData(*args)[source]

Bases: object

Object for storing the indices, positions and neighbors of lattice sites.

Parameters:

indicesarray_like of iterable of int: The lattice indices of the sites.
positionsarray_like of iterable of int: The positions of the sites.
neighborsiterable of iterable of of int: The neighbors of the sites.
distancesiterabe of iterable of int: The distances of the neighbors.

property dim: The dimension of the data points.

property num_sites: The number of sites stored.

property num_distances: The number of distances of the neighbor data.

property nbytes: Returns the number of bytes stored.

copy()[source]: Creates a deep copy of the instance.

reset()[source]: Resets the LatticeData instance.

set(indices, positions, neighbors, distances)[source]

Sets the data of the LatticeData instance.

Parameters:

indices(N, D+1) np.ndarray: The lattice indices of the sites.
positions(N, D) np.ndarray: The positions of the sites.
neighbors(N, M) np.ndarray: The neighbors of the sites.
distances(N, M) iterabe of iterable of int: The distances of the neighbors.

remove(sites)[source]

get_limits()[source]

Computes the geometric limits of the positions of the stored sites.

Returns:

limitsnp.ndarray: The minimum and maximum value for each axis of the position data.

get_index_limits()[source]

Computes the geometric limits of the lattice indices of the stored sites.

Returns:

limits: np.ndarray: The minimum and maximum value for each axis of the lattice indices.

get_cell_limits()[source]

Computes the geometric limits of the lattice cells of the stored sites.

Returns:

limits: np.ndarray: The minimum and maximum value for each axis of the translation indices.

get_translation_limits()[source]

Computes the geometric limits of the translation vectors of the stored sites.

Returns:

limitsnp.ndarray: The minimum and maximum value for each axis of the lattice indices.

neighbor_mask(site, distidx=None, periodic=None, unique=False)[source]

Creates a mask for the valid neighbors of a specific site.

Parameters:

siteint: The index of the site.
distidxint, optional: The index of the distance. If None the data for all distances is returned. The default is None (all neighbors).
periodicbool, optional: Periodic neighbor flag. If None the data for all neighbors is returned. If a bool is passed either the periodic or non-periodic neighbors are masked. The default is None (all neighbors).
uniquebool, optional: If ‘True’, each unique pair is only return once. The defualt is False.

Returns:

masknp.ndarray

set_periodic(indices, distances, nvecs, axes)[source]

Adds periodic neighbors to the invalid slots of the neighbor data

Parameters:

indicesdict: Indices of the periodic neighbors. All dictionaries have the site as key and a list of np.ndarray as values.
distancesdict: The distances of the periodic neighbors.
nvecsdict: The translation vectors of the periodic neighbors.
axesdict: Index of the translation axis of the periodic neighbors.

sort(ax=None, indices=None, reverse=False)[source]

remove_periodic()[source]

sort_neighbors()[source]

add_neighbors(site, neighbors, distances)[source]

append(*args, copy=False)[source]

get_positions(alpha)[source]: Returns the atom positions of a sublattice.

get_neighbors(site, distidx=None, periodic=None, unique=False)[source]

Returns the neighbors of a lattice site.

See the neighbor_mask-method for more information on parameters

Returns:

neighborsnp.ndarray: The indices of the neighbors.

iter_neighbors(site, unique=False)[source]

Iterates over the neighbors of all distance levels.

See the neighbor_mask-method for more information on parameters

Yields:

distidxint
neighborsnp.ndarray

map()[source]

Builds a map containing the atom-indices, site-pairs and distances.

Returns:

datamapDataMap

site_mask(mins=None, maxs=None, invert=False)[source]

Creates a mask for the position data of the sites.

Parameters:

minssequence or float or None, optional: Optional lower bound for the positions. The default is no lower bound.
maxssequence or float or None, optional: Optional upper bound for the positions. The default is no upper bound.
invertbool, optional: If True, the mask is inverted. The default is False.

Returns:

masknp.ndarray: The mask containing a boolean value for each site.

find_sites(mins=None, maxs=None, invert=False)[source]

Returns the indices of sites inside or outside the given limits.

Parameters:

minssequence or float or None, optional: Optional lower bound for the positions. The default is no lower bound.
maxssequence or float or None, optional: Optional upper bound for the positions. The default is no upper bound.
invertbool, optional: If True, the mask is inverted and the positions outside of the bounds will be returned. The default is False.

Returns:

indices: np.ndarray: The indices of the masked sites.

find_outer_sites(ax, offset)[source]

Returns the indices of the outer sites along a specific axis.

Parameters:

axint: The geometrical axis.
offsetint: The width of the outer slices.

Returns:

indicesnp.ndarray: The indices of the masked sites.