quantax.sites.Lattice#

class quantax.sites.Lattice#

Bases: Sites

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

__init__(extent: Sequence[int], basis_vectors: Sequence[float], site_offsets: Sequence[float] | None = None, boundary: int | Sequence[int] = 1, particle_type: PARTICLE_TYPE | str = PARTICLE_TYPE.spin, Nparticles: None | int | Tuple[int, int] = None, double_occ: bool | None = None)#
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)

  • Nparticles – The number of particles in the system. If unspecified, the number of particles is non-conserved. If specified, use an int to specify the total particle number, or use a tuple (n_up, n_dn) to specify the number of spin-up and spin-down particles.

  • 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: ndarray#

Number of lattice cells.

property basis_vectors: ndarray#

Basis vectors of the lattice.

property reciprocal_vectors: ndarray#

Reciprocal lattice vectors.

property site_offsets: ndarray#

Site offsets in a unit cell.

property boundary: ndarray#

Boundary condition for each dimension.

property index_from_xyz: ndarray#

A numpy array with index_from_xyz[index_in_unit_cell, x, y, z] = index.

property xyz_from_index: ndarray#

A numpy array with xyz_from_index[index] = [index_in_unit_cell, x, y, z].

property Nfmodes: int#

The number of fermionic modes, which should be Nsites for spinless fermions and 2 * Nsites for spin and spinful fermions.

property Nmodes: int#

The number of qubit degrees of freedom, which should be Nsites for spins or spinless fermions and 2 * Nsites for spinful fermions.

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

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#

Real space coordinates of all sites.

property dist: ndarray#

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 | Sequence[ndarray] | tuple#

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.

orbitals(use_real: bool = False) → ndarray | Tuple[ndarray, ndarray]#

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.

property sign: ndarray#

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.

plot(figsize: Sequence[int | float] = (10, 10), markersize: int | float | None = None, color_in_cell: Sequence[str] | None = None, show_index: bool = True, index_fontsize: int | float | None = None, neighbor_bonds: int | Sequence[int] = 1)#

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_in_cell – A list 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.