# Lattice¶

Inheritance Diagram

Methods

 Lattice.__init__(Ls, unit_cell[, order, bc, …]) Initialize self. Lattice.count_neighbors([u, key]) Count e.g. Calculate correct shape of the strengths for a coupling. Lattice.from_hdf5(hdf5_loader, h5gr, subpath) Load instance from a HDF5 file. Lattice.lat2mps_idx(lat_idx) Translate lattice indices (x_0, ..., x_{D-1}, u) to MPS index i. Translate MPS index i to lattice indices (x_0, ..., x_{dim-1}, u). Lattice.mps2lat_values(A[, axes, u]) Reshape/reorder A to replace an MPS index by lattice indices. return an index array of MPS indices for which the site within the unit cell is u. Similar as mps_idx_fix_u(), but return also the corresponding lattice indices. Return a list of sites for all MPS indices. Calculate correct shape of the strengths for a multi_coupling. Deprecated. Deprecated. Lattice.ordering(order) Provide possible orderings of the N lattice sites. Lattice.plot_basis(ax, **kwargs) Plot arrows indicating the basis vectors of the lattice. Lattice.plot_bc_identified(ax[, direction, …]) Mark two sites indified by periodic boundary conditions. Lattice.plot_coupling(ax[, coupling]) Plot lines connecting nearest neighbors of the lattice. Lattice.plot_order(ax[, order, textkwargs]) Plot a line connecting sites in the specified “order” and text labels enumerating them. Lattice.plot_sites(ax[, markers]) Plot the sites of the lattice with markers. Lattice.position(lat_idx) return ‘space’ position of one or multiple sites. Lattice.possible_couplings(u1, u2, dx) Find possible MPS indices for two-site couplings. Generalization of possible_couplings() to couplings with more than 2 sites. Lattice.save_hdf5(hdf5_saver, h5gr, subpath) Export self into a HDF5 file. Lattice.site(i) return Site instance corresponding to an MPS index i Sanity check.

Class Attributes and Properties

 Lattice.boundary_conditions Human-readable list of boundary conditions from bc and bc_shift. Lattice.dim The dimension of the lattice. Lattice.nearest_neighbors Lattice.next_nearest_neighbors Lattice.next_next_nearest_neighbors Lattice.order Defines an ordering of the lattice sites, thus mapping the lattice to a 1D chain.
class tenpy.models.lattice.Lattice(Ls, unit_cell, order='default', bc='open', bc_MPS='finite', basis=None, positions=None, nearest_neighbors=None, next_nearest_neighbors=None, next_next_nearest_neighbors=None, pairs=None)[source]

Bases: object

A general, regular lattice.

The lattice consists of a unit cell which is repeated in dim different directions. A site of the lattice is thus identified by lattice indices (x_0, ..., x_{dim-1}, u), where 0 <= x_l < Ls[l] pick the position of the unit cell in the lattice and 0 <= u < len(unit_cell) picks the site within the unit cell. The site is located in ‘space’ at sum_l x_l*basis[l] + unit_cell_positions[u] (see position()). (Note that the position in space is only used for plotting, not for defining the couplings.)

In addition to the pure geometry, this class also defines an order of all sites. This order maps the lattice to a finite 1D chain and defines the geometry of MPSs and MPOs. The MPS index i corresponds thus to the lattice sites given by (x_0, ..., x_{dim-1}, u) = tuple(self.order[i]). Infinite boundary conditions of the MPS repeat in the first spatial direction of the lattice, i.e., if the site at (x_0, x_1, …, x_{dim-1},u) has MPS index i, the site at at (x_0 + a*Ls[0], x_1 ..., x_{dim-1}, u) corresponds to MPS index i + N_sites. Use mps2lat_idx() and lat2mps_idx() for conversion of indices. The function mps2lat_values() performs the necessary reshaping and re-ordering from arrays indexed in MPS form to arrays indexed in lattice form.

Parameters
• Ls (list of int) – the length in each direction

• unit_cell (list of Site) – The sites making up a unit cell of the lattice. If you want to specify it only after initialization, use None entries in the list.

• order (str | ('standard', snake_winding, priority) | ('grouped', groups)) – A string or tuple specifying the order, given to ordering().

• bc ((iterable of) {'open' | 'periodic' | int}) – Boundary conditions in each direction of the lattice. A single string holds for all directions. An integer shift means that we have periodic boundary conditions along this direction, but shift/tilt by -shift*lattice.basis[0] (~cylinder axis for bc_MPS='infinite') when going around the boundary along this direction.

• bc_MPS ('finite' | 'segment' | 'infinite') – Boundary conditions for an MPS/MPO living on the ordered lattice. If the system is 'infinite', the infinite direction is always along the first basis vector (justifying the definition of N_rings and N_sites_per_ring).

• basis (iterable of 1D arrays) – For each direction one translation vectors shifting the unit cell. Defaults to the standard ONB np.eye(dim).

• positions (iterable of 1D arrays) – For each site of the unit cell the position within the unit cell. Defaults to np.zeros((len(unit_cell), dim)).

• nearest_neighbors (None | list of (u1, u2, dx)) – Deprecated. Specify as pairs['nearest_neighbors'] instead.

• next_nearest_neighbors (None | list of (u1, u2, dx)) – Deprecated. Specify as pairs['next_nearest_neighbors'] instead.

• next_next_nearest_neighbors (None | list of (u1, u2, dx)) – Deprecated. Specify as pairs['next_next_nearest_neighbors'] instead.

• pairs (dict) – Of the form {'nearest_neighbors': [(u1, u2, dx), ...], ...}. Typical keys are 'nearest_neighbors', 'next_nearest_neighbors'. For each of them, it specifies a list of tuples (u1, u2, dx) which can be used as parameters for add_coupling() to generate couplings over each pair of ,e.g., 'nearest_neighbors'. Note that this adds couplings for each pair only in one direction!

dim
Type

int

order
Type

ndarray (N_sites, dim+1)

boundary_conditions
Ls

the length in each direction.

Type

tuple of int

shape

the ‘shape’ of the lattice, same as Ls + (len(unit_cell), )

Type

tuple of int

N_cells

the number of unit cells in the lattice, np.prod(self.Ls).

Type

int

N_sites

the number of sites in the lattice, np.prod(self.shape).

Type

int

N_sites_per_ring

Defined as N_sites / Ls[0], for an infinite system the number of cites per “ring”.

Type

int

N_rings

Alias for Ls[0], for an infinite system the number of “rings” in the unit cell.

Type

int

unit_cell

the sites making up a unit cell of the lattice.

Type

list of Site

bc

Boundary conditions of the couplings in each direction of the lattice, translated into a bool array with the global bc_choices.

Type

bool ndarray

bc_shift

The shift in x-direction when going around periodic boundaries in other directions.

Type

None | ndarray(int)

bc_MPS

Boundary conditions for an MPS/MPO living on the ordered lattice. If the system is 'infinite', the infinite direction is always along the first basis vector (justifying the definition of N_rings and N_sites_per_ring).

Type

‘finite’ | ‘segment’ | ‘infinite’

basis

translation vectors shifting the unit cell. The row i gives the vector shifting in direction i.

Type

ndarray (dim, Dim)

unit_cell_positions

for each site in the unit cell a vector giving its position within the unit cell.

Type

ndarray, shape (len(unit_cell), Dim)

pairs

See above.

Type

dict

_order

The place where order is stored.

Type

ndarray (N_sites, dim+1)

_strides

necessary for mps2lat_idx()

Type

ndarray (dim, )

_perm

permutation needed to make order lexsorted.

Type

ndarray (N, )

_mps2lat_vals_idx

index array for reshape/reordering in mps2lat_vals()

Type

ndarray shape

_mps_fix_u

for each site of the unit cell an index array selecting the mps indices of that site.

Type

tuple of ndarray (N_cells, ) np.intp

_mps2lat_vals_idx_fix_u

similar as _mps2lat_vals_idx, but for a fixed u picking a site from the unit cell.

Type

tuple of ndarray of shape Ls

test_sanity()[source]

Sanity check.

Raises ValueErrors, if something is wrong.

save_hdf5(hdf5_saver, h5gr, subpath)[source]

Export self into a HDF5 file.

This method saves all the data it needs to reconstruct self with from_hdf5().

Specifically, it saves unit_cell, Ls, unit_cell_positions, basis, boundary_conditions, pairs under their name, bc_MPS as "boundary_conditions_MPS", and bc_MPS as "order_for_MPS". Moreover, it saves dim and N_sites as HDF5 attributes.

Parameters
• hdf5_saver (Hdf5Saver) – Instance of the saving engine.

• h5gr (:classGroup) – HDF5 group which is supposed to represent self.

• subpath (str) – The name of h5gr with a '/' in the end.

Load instance from a HDF5 file.

This method reconstructs a class instance from the data saved with save_hdf5().

Parameters

• h5gr (Group) – HDF5 group which is represent the object to be constructed.

• subpath (str) – The name of h5gr with a '/' in the end.

Returns

obj – Newly generated class instance containing the required data.

Return type

cls

property dim

The dimension of the lattice.

property order

Defines an ordering of the lattice sites, thus mapping the lattice to a 1D chain.

This order defines how an MPS/MPO winds through the lattice.

ordering(order)[source]

Provide possible orderings of the N lattice sites.

This function can be overwritten by derived lattices to define additional orderings. The following orders are defined in this method:

order

equivalent priority

equivalent snake_winding

'Cstyle'

(0, 1, …, dim-1, dim)

(False, …, False, False)

'default'

'snake'

(0, 1, …, dim-1, dim)

(True, …, True, True)

'snakeCstyle'

'Fstyle'

(dim-1, …, 1, 0, dim)

(False, …, False, False)

'snakeFstyle'

(dim-1, …, 1, 0, dim)

(False, …, False, False)

Parameters

order (str | ('standard', snake_winding, priority) | ('grouped', groups)) – Specifies the desired ordering using one of the strings of the above tables. Alternatively, an ordering is specified by a tuple with first entry specifying a function, 'standard' for get_order() and 'grouped' for get_order_grouped(), and other arguments in the tuple as specified in the documentation of these functions.

Returns

order – the order to be used for order.

Return type

array, shape (N, D+1), dtype np.intp

get_order()

generates the order from equivalent priority and snake_winding.

get_order_grouped()

variant of get_order.

plot_order()

visualizes the resulting order.

property boundary_conditions

Human-readable list of boundary conditions from bc and bc_shift.

Returns

boundary_conditions – List of "open" or "periodic", one entry for each direction of the lattice.

Return type

list of str

position(lat_idx)[source]

return ‘space’ position of one or multiple sites.

Parameters

lat_idx (ndarray, (... , dim+1)) – Lattice indices.

Returns

pos – The position of the lattice sites specified by lat_idx in real-space.

Return type

ndarray, (..., dim)

site(i)[source]

return Site instance corresponding to an MPS index i

mps_sites()[source]

Return a list of sites for all MPS indices.

Equivalent to [self.site(i) for i in range(self.N_sites)].

This should be used for sites of 1D tensor networks (MPS, MPO,…).

mps2lat_idx(i)[source]

Translate MPS index i to lattice indices (x_0, ..., x_{dim-1}, u).

Parameters

i (int | array_like of int) – MPS index/indices.

Returns

lat_idx – First dimensions like i, last dimension has len dim+1 and contains the lattice indices (x_0, …, x_{dim-1}, u) corresponding to i. For i accross the MPS unit cell and “infinite” bc_MPS, we shift x_0 accordingly.

Return type

array

lat2mps_idx(lat_idx)[source]

Translate lattice indices (x_0, ..., x_{D-1}, u) to MPS index i.

Parameters

lat_idx (array_like [.., dim+1]) – The last dimension corresponds to lattice indices (x_0, ..., x_{D-1}, u). All lattice indices should be positive and smaller than the corresponding entry in self.shape. Exception: for “infinite” bc_MPS, an x_0 outside indicates shifts accross the boundary.

Returns

i – MPS index/indices corresponding to lat_idx. Has the same shape as lat_idx without the last dimension.

Return type

array_like

mps_idx_fix_u(u=None)[source]

return an index array of MPS indices for which the site within the unit cell is u.

If you have multiple sites in your unit-cell, an onsite operator is in general not defined for all sites. This functions returns an index array of the mps indices which belong to sites given by self.unit_cell[u].

Parameters

u (None | int) – Selects a site of the unit cell. None (default) means all sites.

Returns

mps_idx – MPS indices for which self.site(i) is self.unit_cell[u]. Ordered ascending.

Return type

array

mps_lat_idx_fix_u(u=None)[source]

Similar as mps_idx_fix_u(), but return also the corresponding lattice indices.

Parameters

u (None | int) – Selects a site of the unit cell. None (default) means all sites.

Returns

• mps_idx (array) – MPS indices i for which self.site(i) is self.unit_cell[u].

• lat_idx (2D array) – The row j contains the lattice index (without u) corresponding to mps_idx[j].

mps2lat_values(A, axes=0, u=None)[source]

Reshape/reorder A to replace an MPS index by lattice indices.

Parameters
• A (ndarray) – Some values. Must have A.shape[axes] = self.N_sites if u is None, or A.shape[axes] = self.N_cells if u is an int.

• axes ((iterable of) int) – chooses the axis which should be replaced.

• u (None | int) – Optionally choose a subset of MPS indices present in the axes of A, namely the indices corresponding to self.unit_cell[u], as returned by mps_idx_fix_u(). The resulting array will not have the additional dimension(s) of u.

Returns

res_A – Reshaped and reordered verions of A. Such that an MPS index j is replaced by res_A[..., self.order, ...] = A[..., np.arange(self.N_sites), ...]

Return type

ndarray

Examples

Say you measure expection values of an onsite term for an MPS, which gives you an 1D array A, where A[i] is the expectation value of the site given by self.mps2lat_idx(i). Then this function gives you the expectation values ordered by the lattice:

>>> print(lat.shape, A.shape)
(10, 3, 2) (60,)
>>> A_res = lat.mps2lat_values(A)
>>> A_res.shape
(10, 3, 2)
>>> A_res[lat.mps2lat_idx(5)] == A[5]
True

If you have a correlation function C[i, j], it gets just slightly more complicated:

>>> print(lat.shape, C.shape)
(10, 3, 2) (60, 60)
>>> lat.mps2lat_values(C, axes=[0, 1]).shape
(10, 3, 2, 10, 3, 2)

If the unit cell consists of different physical sites, an onsite operator might be defined only on one of the sites in the unit cell. Then you can use mps_idx_fix_u() to get the indices of sites it is defined on, measure the operator on these sites, and use the argument u of this function.

>>> u = 0
>>> idx_subset = lat.mps_idx_fix_u(u)
>>> A_u = A[idx_subset]
>>> A_u_res = lat.mps2lat_values(A_u, u=u)
>>> A_u_res.shape
(10, 3)
>>> np.all(A_res[:, :, u] == A_u_res[:, :])
True

Todo

make sure this function is used for expectation values…

count_neighbors(u=0, key='nearest_neighbors')[source]

Count e.g. the number of nearest neighbors for a site in the bulk.

Parameters
• u (int) – Specifies the site in the unit cell, for which we should count the number of neighbors (or whatever key specifies).

• key (str) – Key of pairs to select what to count.

Returns

number – Number of nearest neighbors (or whatever key specified) for the u-th site in the unit cell, somewhere in the bulk of the lattice. Note that it might not be the correct value at the edges of a lattice with open boundary conditions.

Return type

int

number_nearest_neighbors(u=0)[source]

Deprecated.

number_next_nearest_neighbors(u=0)[source]

Deprecated.

possible_couplings(u1, u2, dx)[source]

Find possible MPS indices for two-site couplings.

For periodic boundary conditions (bc[a] == False) the index x_a is taken modulo Ls[a] and runs through range(Ls[a]). For open boundary conditions, x_a is limited to 0 <= x_a < Ls[a] and 0 <= x_a+dx[a] < lat.Ls[a].

Parameters
• u2 (u1,) – Indices within the unit cell; the u1 and u2 of add_coupling()

• dx (array) – Length dim. The translation in terms of basis vectors for the coupling.

Returns

• mps1, mps2 (array) – For each possible two-site coupling the MPS indices for the u1 and u2.

• lat_indices (2D int array) – Rows of lat_indices correspond to rows of mps_ijkl and contain the lattice indices of the “lower left corner” of the box containing the coupling.

• coupling_shape (tuple of int) – Len dim. The correct shape for an array specifying the coupling strength. lat_indices has only rows within this shape.

possible_multi_couplings(u0, other_us, dx)[source]

Generalization of possible_couplings() to couplings with more than 2 sites.

Given the arguments of add_coupling() determine the necessary shape of strength.

Parameters
Returns

• mps_ijkl (2D int array) – Each row contains MPS indices i,j,k,l,…` for each of the operators positions. The positions are defined by dx (j,k,l,… relative to i) and boundary coundary conditions of self (how much the box for given dx can be shifted around without hitting a boundary - these are the different rows).

• lat_indices (2D int array) – Rows of lat_indices correspond to rows of mps_ijkl and contain the lattice indices of the “lower left corner” of the box containing the coupling.

• coupling_shape (tuple of int) – Len dim. The correct shape for an array specifying the coupling strength. lat_indices has only rows within this shape.

coupling_shape(dx)[source]

Calculate correct shape of the strengths for a coupling.

Parameters

dx (tuple of int) – Translation vector in the lattice for a coupling of two operators.

Returns

• coupling_shape (tuple of int) – Len dim. The correct shape for an array specifying the coupling strength. lat_indices has only rows within this shape.

• shift_lat_indices (array) – Translation vector from lower left corner of box spanned by dx to the origin.

multi_coupling_shape(dx)[source]

Calculate correct shape of the strengths for a multi_coupling.

Parameters

dx (tuple of int) – Translation vector in the lattice for a coupling of two operators.

Returns

• coupling_shape (tuple of int) – Len dim. The correct shape for an array specifying the coupling strength. lat_indices has only rows within this shape.

• shift_lat_indices (array) – Translation vector from lower left corner of box spanned by dx to the origin.

plot_sites(ax, markers=['o', '^', 's', 'p', 'h', 'D'], **kwargs)[source]

Plot the sites of the lattice with markers.

Parameters
• ax (matplotlib.axes.Axes) – The axes on which we should plot.

• markers (list) – List of values for the keywork marker of ax.plot() to distinguish the different sites in the unit cell, a site u in the unit cell is plotted with a marker markers[u % len(markers)].

• **kwargs – Further keyword arguments given to ax.plot().

plot_order(ax, order=None, textkwargs={}, **kwargs)[source]

Plot a line connecting sites in the specified “order” and text labels enumerating them.

Parameters
• ax (matplotlib.axes.Axes) – The axes on which we should plot.

• order (None | 2D array (self.N_sites, self.dim+1)) – The order as returned by ordering(); by default (None) use order.

• textkwargs (None | dict) – If not None, we add text labels enumerating the sites in the plot. The dictionary can contain keyword arguments for ax.text().

• **kwargs – Further keyword arguments given to ax.plot().

plot_coupling(ax, coupling=None, **kwargs)[source]

Plot lines connecting nearest neighbors of the lattice.

Parameters
• ax (matplotlib.axes.Axes) – The axes on which we should plot.

• coupling (list of (u1, u2, dx)) – By default (None), use self.pairs['nearest_neighbors']. Specifies the connections to be plotted; iteating over lattice indices (i0, i1, …), we plot a connection from the site (i0, i1, ..., u1) to the site (i0+dx[0], i1+dx[1], ..., u2), taking into account the boundary conditions.

• **kwargs – Further keyword arguments given to ax.plot().

plot_basis(ax, **kwargs)[source]

Plot arrows indicating the basis vectors of the lattice.

Parameters
• ax (matplotlib.axes.Axes) – The axes on which we should plot.

• **kwargs – Keyword arguments specifying the “arrowprops” of ax.annotate.

plot_bc_identified(ax, direction=-1, shift=None, **kwargs)[source]

Mark two sites indified by periodic boundary conditions.

Works only for lattice with a 2-dimensional basis.

Parameters
• ax (matplotlib.axes.Axes) – The axes on which we should plot.

• direction (int) – The direction of the lattice along which we should mark the idenitified sites. If None, mark it along all directions with periodic boundary conditions.

• shift (None | np.ndarray) – The origin starting from where we mark the identified sites. Defaults to the first entry of unit_cell_positions.

• **kwargs – Keyword arguments for the used ax.plot.