Kagome¶
full name: tenpy.models.lattice.Kagome
parent module:
tenpy.models.lattice
type: class
Inheritance Diagram
Methods

Initialize self. 

Count e.g. 
Calculate correct shape of the strengths for a coupling. 


Load instance from a HDF5 file. 

Translate lattice indices 
Translate MPS index i to lattice indices 


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 

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 N lattice sites. 

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. 

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

Plot the sites of the lattice with markers. 

return ‘space’ position of one or multiple sites. 

Find possible MPS indices for twosite couplings. 

Generalization of 

Export self into a HDF5 file. 

return 
Sanity check. 
Class Attributes and Properties
Humanreadable list of boundary conditions from 









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

class
tenpy.models.lattice.
Kagome
(Lx, Ly, sites, **kwargs)[source]¶ Bases:
tenpy.models.lattice.Lattice
A Kagome lattice.
 Parameters

property
boundary_conditions
¶ Humanreadable list of boundary conditions from
bc
andbc_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
 Returns
number – Number of nearest neighbors (or whatever key specified) for the uth 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

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.

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

lat2mps_idx
(lat_idx)[source]¶ Translate lattice indices
(x_0, ..., x_{D1}, u)
to MPS index i. Parameters
lat_idx (array_like [.., dim+1]) – The last dimension corresponds to lattice indices
(x_0, ..., x_{D1}, u)
. All lattice indices should be positive and smaller than the corresponding entry inself.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_{dim1}, 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_{dim1}, 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 isNone
, orA.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 toself.unit_cell[u]
, as returned bymps_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…

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

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

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, …, dim1, dim)
(False, …, False, False)
'default'
'snake'
(0, 1, …, dim1, dim)
(True, …, True, True)
'snakeCstyle'
'Fstyle'
(dim1, …, 1, 0, dim)
(False, …, False, False)
'snakeFstyle'
(dim1, …, 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'
forget_order()
and'grouped'
forget_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
See also
get_order()
generates the order from equivalent priority and snake_winding.
get_order_grouped()
variant of get_order.
plot_order()
visualizes the resulting order.

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 2dimensional 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
.

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
), useself.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_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
) useorder
.textkwargs (
None
 dict) – If notNone
, we add text labels enumerating the sites in the plot. The dictionary can contain keyword arguments forax.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 markermarkers[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 realspace.
 Return type
ndarray,
(..., dim)

possible_couplings
(u1, u2, dx)[source]¶ Find possible MPS indices for twosite couplings.
For periodic boundary conditions (
bc[a] == False
) the indexx_a
is taken moduloLs[a]
and runs throughrange(Ls[a])
. For open boundary conditions,x_a
is limited to0 <= x_a < Ls[a]
and0 <= 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 twosite 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
u0 (int) – Argument u0 of
add_multi_coupling()
.other_us (list of int) – The u of the other_ops in
add_multi_coupling()
.dx (array, shape (len(other_us), lat.dim+1)) – The dx specifying relative operator positions of the other_ops in
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.

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"
, andbc_MPS
as"order_for_MPS"
. Moreover, it savesdim
andN_sites
as HDF5 attributes.