quantax.sites.Lattice#

class quantax.sites.Lattice#

Bases: Sites

A special kind of Sites with periodic structure in real space.

Parameters:

extent – Number of copies in each basis vector direction.
basis_vectors – Basis vectors of the lattice. Should be a 2D array with different rows for different basis vectors.
site_offsets – The site coordinates in the unit cell. By default, there is only one site at the origin of the unit cell. Otherwise, this should be a 2D array with different rows for different sites in a cell.
boundary –
Boundary condition of the system. It can be an int specifying the boundary for all axes, or a sequence of ints each for an axis. The meaning of each number is
- 1: Periodic boundary condition (PBC)
- 0: Open boundary condition (OBC)
- -1: Anti-periodic boundary condition (APBC)
APBC is not allowed for spin systems.
particle_type – The particle type of the system: spin, spinful fermion, or spinless fermion. Specify it with a PARTICLE_TYPE member, or equivalently its name as a string (e.g. "spinful_fermion").
Nparticles – The number of particles in the system. If unspecified, the particle number is non-conserved, except spin systems which default to Nsites (i.e. no magnetization conservation, since the total spin count is always Nsites). If specified, use an int for the total particle number, or a tuple (n_up, n_dn) for the number of spin-up and spin-down particles. For spin systems the total is always Nsites, so a magnetization sector must be fixed with a tuple (n_up, n_dn) summing to Nsites rather than an int.
double_occ – Whether double occupancy is allowed. Default to True for spinful fermions and False otherwise.

property shape: tuple[int, ...]#: Shape of the lattice. The first element is the number of sites in a unit cell, and the remainings are the spatial extent.

property ncells: int#: Number of lattice cells.

property basis_vectors: NDArray[float64]#: Basis vectors of the lattice.

property reciprocal_vectors: NDArray[floating]#: Reciprocal lattice vectors.

property site_offsets: NDArray[float64]#: Site offsets in a unit cell.

property boundary: NDArray[int64]#: Boundary condition for each dimension.

property index_from_xyz: NDArray[int64]#: A numpy array with index_from_xyz[index_in_unit_cell, x, y, z] = index.

property xyz_from_index: NDArray[int64]#: A numpy array with xyz_from_index[index] = [index_in_unit_cell, x, y, z].

orbitals(use_real: bool = False) → NDArray[floating | complexfloating]#

Get the single-particle orbitals in momentum space, sorted by tight-binding energy.

Parameters:: use_real – Whether to return real-valued orbitals.
Returns:: Orbital $phi_{ialpha}$ of shape (Nsites, Nsites), where i represents different sites and $alpha$ represents different k-orbitals. For lattices with multiple sites per unit cell, the orbitals are block-diagonal in the sublattice, i.e. each k-orbital is a plane wave localized on one sublattice.

to_neighbor_repr(x: NDArray | Array) → NDArray | Array#: Rearrange per-site features so that sites adjacent in the array are also neighbors on the lattice. For a generic lattice the two orderings already coincide, so this is the identity; lattices whose default site ordering does not match adjacency (e.g. TriangularB) override it.

property Nfmodes: int#: The number of fermionic modes, which should be Nsites for spinless fermions and 2 * Nsites for spin and spinful fermions. This is used when a system is mapped to a fermionic representation (e.g. mean-field or backflow states), where a spin maps to two fermionic modes (spin-up and spin-down) per site.

property Nmodes: int#: The length of a configuration array, i.e. the number of local degrees of freedom stored per sample. This is Nsites for spins or spinless fermions and 2 * Nsites for spinful fermions (one entry per spin-up and spin-down mode).

property Nparticles: int | tuple[int, int] | None#

The number of particles.

None: No particle conservation.
int: Conservation of total particle number.
Tuple[int, int]: Conservation of spin-up and spin-down particle numbers.

property Nsites: int#: The number of sites

property Ntotal: int | None#: The total number of particles.

property coord: NDArray[float64]#: Real space coordinates of all sites.

property dist: NDArray[float64]#: Matrix of the real space distance between all site pairs.

Tip

dist[2, 3] is the distance between site 2 and 3.

property double_occ: bool#: Whether the system allows double occupancy.

get_neighbor(n_neighbor: int | Sequence[int] = 1, return_sign: bool = False) → NDArray[int64] | tuple[NDArray[int64], NDArray[int64]] | list[NDArray[int64]] | tuple[list[NDArray[int64]], list[NDArray[int64]]]#

Gets n’th-nearest neighbor site pairs.

Parameters:

n_neighbor – The n’th-nearest neighbor to obtain. The nearest neighbor is given by 1. If it’s a sequence, then multiple neighbors will be returned in the same order.
return_sign – Whether this function should also return the sign of neighbor bonds. The sign is non-trivial only for fermionic systems with anti-periodic boundary conditions.

Returns:

neighbor: If n_neighbor is int, then a 2D numpy array with each row a pair of neighbor site indeces. If n_neighbor is sequence, then a list with each item a 2D numpy array corresponding to n_neighbor items.
sign: The sign of neighbor bonds. Only provided if return_sign is True.

property is_fermion: bool#: Whether the system is made of fermions.

property is_spinful: bool#: Whether the system is spinful.

property ndim: int#: The number of spatial dimensions, e.g., 2 for square lattice and 3 for cubic.

property particle_type: PARTICLE_TYPE#: The type of particle in the system. See PARTICLE_TYPE.

property sign: NDArray[int64]#: Matrix of the sign between all site pairs. For example, in a fermionic system with anti-periodic boundary conditions, the sign of bonds crossing the boundary is -1, while other bonds have sign +1.

Tip

sign[2, 3] is the sign of the bond connecting site 2 and 3.

to_original_repr(x: NDArray | Array) → NDArray | Array#: Inverse of to_neighbor_repr, mapping the neighbor representation back to the original site ordering. Identity for a generic lattice.

Plot the sites and neighbor bonds in the real space, with the adjusted color for lattice.

Parameters:

figsize – Figure size.
markersize – Size of markers that represent the sites.
color – A tuple containing colors for different sites with the same offset in the unit cell. The length should be the same as the number of sites in a single unit cell.
show_index – Whether to show index number at each site.
index_fontsize – Fontsize if the index number is shown.
neighbor_bonds – The n’th-nearest neighbor bonds to show. If this is a sequence, then multiple neighbors will be shown. Set this to 0 to hide all neighbor bonds.

Returns:

A matplotlib figure containing the plot of lattice.