IrregularLattice¶

Inheritance Diagram

Methods

 IrregularLattice.__init__(regular_lattice[, …]) Initialize self. Count e.g. Calculate correct shape of the strengths for a coupling. Repeat the unit cell for infinite MPS boundary conditions; in place. IrregularLattice.from_hdf5(hdf5_loader, …) Load instance from a HDF5 file. 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). IrregularLattice.mps2lat_values(A[, axes, u]) Reshape/reorder A to replace an MPS index by lattice indices. Reshape/reorder an array 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. Provide possible orderings of the lattice sites. IrregularLattice.plot_basis(ax[, origin, shade]) Plot arrows indicating the basis vectors of the lattice. Mark two sites indified by periodic boundary conditions. Plot lines connecting nearest neighbors of the lattice. IrregularLattice.plot_order(ax[, order, …]) Plot a line connecting sites in the specified “order” and text labels enumerating them. IrregularLattice.plot_sites(ax[, markers]) Plot the sites of the lattice with markers. IrregularLattice.position(lat_idx) return ‘space’ position of one or multiple sites. IrregularLattice.possible_couplings(u1, u2, dx) Find possible MPS indices for two-site couplings. Generalization of possible_couplings() to couplings with more than 2 sites. IrregularLattice.save_hdf5(hdf5_saver, h5gr, …) Export self into a HDF5 file. return Site instance corresponding to an MPS index i Sanity check.

Class Attributes and Properties

 IrregularLattice.boundary_conditions Human-readable list of boundary conditions from bc and bc_shift. IrregularLattice.dim The dimension of the lattice. IrregularLattice.nearest_neighbors IrregularLattice.next_nearest_neighbors IrregularLattice.next_next_nearest_neighbors IrregularLattice.order Defines an ordering of the lattice sites, thus mapping the lattice to a 1D chain.
class tenpy.models.lattice.IrregularLattice(regular_lattice, remove=None, add=None, add_unit_cell=[], add_positions=None)[source]

A variant of a regular lattice, where we might have extra sites or sites missing.

Note

The lattice defines only the geometry of the sites, not the couplings; you can have position-dependent couplings/onsite terms despite having a regular lattice.

By adjusting the order and a few private attributes and methods, we can make functions like possible_couplings() work with a more “irregular” lattice structure, where some of the sites are missing and other sites added instead.

Parameters
• regular_lattice (Lattice) – The lattice this is based on.

• remove (2D array | None) – Each row is a lattice index (x_0, ..., x_{dim-1}, u) of a site to be removed. If None, don’t remove something.

• add (Tuple[2D array, list] | None) – Each row of the 2D array is a lattice index (x_0, ..., x_{dim-1}, u) specifiying where a site is to be added; u is the index of the site within the final unit_cell of the irregular lattice. For each row of the 2D array, there is one entry in the list specifying where the site is inserted in the MPS; the values are compared to the MPS indices of the regular lattice and sorted into it, so “2.5” goes between what was site 2 and 3 in the regular lattice. An entry None indicates that the site should be inserted after the lattice site (x_0, ..., x_{dim-1}, -1) of the regular_lattice.

• add_unit_cell (list of Site) – Extra sites to be added to the unit cell.

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

regular_lattice

The lattice this is based on.

Type

Lattice

remove, add

See above. Used in ordering() only.

Type

2D array | None

Examples

Let’s imagine that we have two different sites; for concreteness we can thing of a fermion site, which we represent with 'F', and a spin site 'S'.

You could now imagine that to have fermion chain with spins on the “bonds”. In the periodic/infinite case, you would simply define

>>> lat = Lattice([2], unit_cell=['F', 'S'], bc='periodic', bc_MPS='infinite')
>>> lat.mps_sites()
['F', 'S', 'F', 'S']


For a finite system, you don’t want to terminate with a spin on the right, so you need to remove the very last site by specifying the lattice index [L-1, 1] of that site:

>>> L = 4
>>> reg_lat = Lattice([L], unit_cell=['F', 'S'], bc='open', bc_MPS='finite')
>>> irr_lat = IrregularLattice(reg_lat, remove=[[L-1, 1]])
>>> irr_lat.mps_sites()
['F', 'S', 'F', 'S', 'F', 'S', 'F']


Another simple example would be to add a spin in the center of a fermion chain. In that case, we add another site to the unit cell and specify the lattice index as [(L-1)//2, 1] (where the 1 is the index of 'S' in the unit cell ['F', 'S'] of the irregular lattice). The None for the MPS index is equivalent to (L-1)/2 in this case.

>>> reg_lat = Lattice([L], unit_cell=['F'])
>>> irr_lat = IrregularLattice(reg_lat, add=([[(L-1)//2, 1]], [None]),
['F', 'F', 'S', 'F', 'F']

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 order 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.

classmethod from_hdf5(hdf5_loader, h5gr, subpath)[source]

Load instance from a HDF5 file.

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

Parameters
• hdf5_loader (Hdf5Loader) – Instance of the loading engine.

• 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

ordering(order)[source]

Provide possible orderings of the lattice sites.

Parameters

order – Argument for the Lattice.ordering() of the regular_lattice, or 2D ndarray providing the order of the regular lattice.

Returns

order – The order to be used for order, i.e. order with added/removed sites as specified by remove and add.

Return type

array, shape (N, D+1)

property order

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

Each row of the array contains the lattice indices for one site, the order of the rows thus specifies a path through the lattice, along which an MPS will wind through through the lattice.

You can visualize the order with plot_order().

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

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

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

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. Corresponds to dx argument of tenpy.models.model.CouplingModel.add_multi_coupling().

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 origin to the lower left corner of box spanned by dx.

property dim

The dimension of the lattice.

enlarge_mps_unit_cell(factor=2)[source]

Repeat the unit cell for infinite MPS boundary conditions; in place.

Parameters

factor (int) – The new number of sites in the MPS unit cell will be increased from N_sites to factor*N_sites_per_ring. Since MPS unit cells are repeated in the x-direction in our convetion, the lattice shape goes from (Lx, Ly, ..., Lu) to (Lx*factor, Ly, ..., Lu).

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

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

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 MPS indices along the specified axes are replaced by lattice indices, i.e., if MPS index j maps to lattice site (x0, x1, x2), then res_A[..., x0, x1, x2, ...] = A[..., j, ...].

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…

mps2lat_values_masked(A, axes=- 1, mps_inds=None, include_u=None)[source]

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

This is a generalization of mps2lat_values() allowing for the case of an arbitrary set of MPS indices present in each axis of A.

Parameters
• A (ndarray) – Some values.

• axes ((iterable of) int) – Chooses the axis of A which should be replaced. If multiple axes are given, you also need to give multiple index arrays as mps_inds.

• mps_inds ((list of) 1D ndarray) – Specifies for each axis in axes, for which MPS indices we have values in the corresponding axis of A. Defaults to [np.arange(A.shape[ax]) for ax in axes]. For indices accross the MPS unit cell and “infinite” bc_MPS, we shift x_0 accordingly.

• include_u ((list of) bool) – Specifies for each axis in axes, whether the u index of the lattice should be included into the output array res_A. Defaults to len(self.unit_cell) > 1.

Returns

res_A – Reshaped and reordered copy of A. Such that MPS indices along the specified axes are replaced by lattice indices, i.e., if MPS index j maps to lattice site (x0, x1, x2), then res_A[..., x0, x1, x2, ...] = A[..., mps_inds[j], ...].

Return type

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].

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,…).

multi_coupling_shape(dx)[source]

Calculate correct shape of the strengths for a multi_coupling.

Parameters

dx (2D array, shape (N_ops, dim)) – dx[i, :] is the translation vector in the lattice for the i-th operator. Corresponds to the dx of each operator given in the argument ops of tenpy.models.model.CouplingModel.add_multi_coupling().

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 origin to the lower left corner of box spanned by dx. (Unlike for coupling_shape() it can also contain entries > 0)

number_nearest_neighbors(u=0)[source]

Deprecated.

Deprecated since version 0.5.0: Use count_neighbors() instead.

number_next_nearest_neighbors(u=0)[source]

Deprecated.

Deprecated since version 0.5.0: Use count_neighbors() instead.

plot_basis(ax, origin=0.0, 0.0, shade=None, **kwargs)[source]

Plot arrows indicating the basis vectors of the lattice.

Parameters
plot_bc_identified(ax, direction=- 1, origin=None, cylinder_axis=False, **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.

• cylinder_axis (bool) – Whether to plot the cylinder axis as well.

• origin (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.

plot_coupling(ax, coupling=None, wrap=False, **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.

• wrap (bool) – If True, wrap

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

plot_order(ax, order=None, textkwargs={'color': 'r'}, **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_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().

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)

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
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(ops)[source]

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

Parameters

ops (list of (opname, dx, u)) – Same as the argument ops of add_multi_coupling().

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.

site(i)[source]

return Site instance corresponding to an MPS index i

test_sanity`()[source]

Sanity check.

Raises ValueErrors, if something is wrong.