MultiCouplingTerms

full name: tenpy.networks.terms.MultiCouplingTerms
parent module: tenpy.networks.terms
type: class

Inheritance Diagram

Methods

`MultiCouplingTerms.__init__`(L)
`MultiCouplingTerms.add_coupling_term`(...[, ...])	Add a two-site coupling term on given MPS sites.
`MultiCouplingTerms.add_multi_coupling_term`(...)	Add a multi-site coupling term.
`MultiCouplingTerms.add_to_graph`(graph)	Add terms represented by self to an MPOGraph.
`MultiCouplingTerms.coupling_term_handle_JW`(...)	Helping function to call before `add_coupling_term()`.
`MultiCouplingTerms.from_hdf5`(hdf5_loader, ...)	Load instance from a HDF5 file.
`MultiCouplingTerms.max_range`()	Determine the maximal range in `coupling_terms`.
`MultiCouplingTerms.multi_coupling_term_handle_JW`(...)	Helping function to call before `add_multi_coupling_term()`.
`MultiCouplingTerms.plot_coupling_terms`(ax, lat)	"Plot coupling terms into a given lattice.
`MultiCouplingTerms.remove_zeros`([tol_zero])	Remove entries close to 0 from `coupling_terms`.
`MultiCouplingTerms.save_hdf5`(hdf5_saver, ...)	Export self into a HDF5 file.
`MultiCouplingTerms.to_TermList`()	Convert `coupling_terms` into a `TermList`.
`MultiCouplingTerms.to_nn_bond_Arrays`(sites)	Convert the `coupling_terms` into Arrays on nearest neighbor bonds.

class tenpy.networks.terms.MultiCouplingTerms(L)[source]

Bases: CouplingTerms

Operator names, site indices and strengths representing general M-site coupling terms.

Generalizes the coupling_terms of CouplingTerms to M-site couplings. The structure of the nested dictionary coupling_terms is similar, but we allow an arbitrary recursion depth of the dictionary and build the MPOGraph simultaneously from the left and right. Doing this from both sides simultaneously is necessary to keep the scaling of the MPO bond dimension optimal, which we try to achieve by reusing states of the MPO graph as much as possible as follows.

Each individual term gets split up at site switchLR (default: center of the coupling). To the left of switchLR, we only use “almost-left-canonical” states in the MPO graph, i.e., states where only the basic set of operators defined by the sites were applied with prefactor 1. Similarly, “almost-right-canonical” states are inserted into the MPO graph coming from the right. At site switchLR, we connect an almost-left- to an almost-right-canonical state in the MPO graph with the overall strength prefactor for the term. Since the almost-left/right-canonical states in the MPO graph represent well-defined strings of operators that were applied, they can be re-used for different terms. For example, A_i B_j C_k and A_i B_{j+1} C_k with i < j < j+1 < k can re-use the MPO graph states left of site j and right of j+1 if switchLR is j or j+1.

Parameters:: L (int) – Number of sites.

L

Number of sites.

Type:: int

connections

One entry (switchLR, op_switch, shift, strength) for each (multi) coupling term added, with op_switch being the operator acting on site switchLR, and shift defined below.

Type:: list of (int, str, int, float)

terms_left, terms_right

Nested dictionaries of the following form for left and right:

terms_left = {
    ijkl[0]:
        {(ops_ijkl[0], op_string[0]):
            {ijkl[1]:
                {(ops_ijkl[1], op_string[1]):
                    ...
                        {ijkl[n]:
                            {(ops_ijkl[n],  op_string[n]):
                                {-1: [counter, ...]}
                        }   }
            }   }
   }   }
terms_right = {
    ijkl[-1] - shift:
        {(ops_ijkl[-1], op_string[-1]):
            {ijkl[-2] - shift:
                {(ops_ijkl[-2], op_string[-2]):
                    ...
                        {ijkl[m] - shift:
                            {(ops_ijkl[m],  op_string[m]):
                                {L + 1: [counter, ...]}
                        }   }
            }   }
    }   }

Here, n and m (and hence the nesting depth) are determined by switchLR, namely n is the largest index such that ijkl[n] < switchLR, similarly m is the smallest index such that switchLR < ijkl[m]. If there is no such index, we directly insert the -1: [counter, ...] part at the first level of terms_left or terms_right, respectively. The counter provides the index to connections for the given term. The shift for the terms_right is a multiple of L such that 0 <= ijkl[-1] - shift < L.

Type:: dict of dict

max_range()[source]

Determine the maximal range in coupling_terms.

Returns:: max_range – The maximum of j - i for the i, j occurring in a term of coupling_terms.
Return type:: int

add_multi_coupling_term(strength, ijkl, ops_ijkl, op_string='Id', switchLR='middle_i')[source]

Add a multi-site coupling term.

Parameters:

strength (float) – The strength of the coupling term.
ijkl (list of int) – The MPS indices of the sites on which the operators acts. With i, j, k, ... = ijkl, we require that they are ordered ascending, i < j < k < ... and that 0 <= i < N_sites. Indices >= N_sites indicate couplings between different unit cells of an infinite MPS.
ops_ijkl (list of str) – Names of the involved operators on sites i, j, k, ....
op_string ((list of) str) – Names of the operator to be inserted between the operators, e.g., op_string[0] is inserted between i and j. A single name holds for all in-between segments.
switchLR (int | 'middle_i' | 'middle_op') –
The site where we switch from building the coupling from the left to building the coupling from the right for an efficient MPO representation. This has implications for the final MPO bond dimension, but the optimal value depends on what other terms there are in the Hamiltonian. We therefore provide a few heuristic choices that can be given as the following strings.

middle_i :
The overall middle index (ijkl[0] + ijkl[-1] + 1) // 2, the default choice. Somewhat reasonable if we don’t know anything about the terms, but often not optimal

middle_op :
The index of the middle operator ijkl[len(ijkl) // 2]. This is for example a good choice if you have combinations A[i] B[i+1] C[i+j] + A[i] B[i+j-1] C[i+j] for large j and various B.

multi_coupling_term_handle_JW(strength, term, sites, op_string=None)[source]

Helping function to call before add_multi_coupling_term().

Handle/figure out Jordan-Wigner strings if needed.

Parameters:

strength (float) – The strength of the term.
term (list of (str, int)) – List of tuples (op_i, i) where i is the MPS index of the site the operator named op_i acts on. We require the operators to be sorted (strictly ascending) by sites. If necessary, call order_combine_term() beforehand.
sites (list of Site) – Defines the local Hilbert space for each site. Used to check whether the operators need Jordan-Wigner strings.
op_string (None | str) –
Operator name to be used as operator string between the operators, or None if the Jordan Wigner string should be figured out.

Warning

None figures out for each segment between the operators, whether a Jordan-Wigner string is needed. This is different from a plain 'JW', which just applies a string on each segment!

Returns:

Arguments for MultiCouplingTerms.add_multi_coupling_term() such that the added term corresponds to the parameters of this function.

Return type:

strength, ijkl, ops_ijkl, op_string

add_coupling_term(strength, i, j, op_i, op_j, op_string='Id', switchLR=None)[source]

Add a two-site coupling term on given MPS sites.

Parameters:

strength (float) – The strength of the coupling term.
i (int) – The MPS indices of the two sites on which the operator acts. We require 0 <= i < N_sites and i < j, i.e., op_i acts “left” of op_j. If j >= N_sites, it indicates couplings between unit cells of an infinite MPS.
j (int) – The MPS indices of the two sites on which the operator acts. We require 0 <= i < N_sites and i < j, i.e., op_i acts “left” of op_j. If j >= N_sites, it indicates couplings between unit cells of an infinite MPS.
op1 (str) – Names of the involved operators.
op2 (str) – Names of the involved operators.
op_string (str) – The operator to be inserted between i and j.

add_to_graph(graph)[source]

Add terms represented by self to an MPOGraph.

Parameters:: graph (MPOGraph) – The graph into which the terms from coupling_terms should be added.

remove_zeros(tol_zero=1e-15)[source]

Remove entries close to 0 from coupling_terms.

Parameters:: tol_zero (float) – Entries in terms_left and terms_right with strength < tol_zero are considered to be zero and removed.

to_TermList()[source]: Convert coupling_terms into a TermList. :returns: term_list – Representation of the terms as a list of terms. :rtype: TermList

coupling_term_handle_JW(strength, term, sites, op_string=None)[source]

Helping function to call before add_coupling_term().

Parameters:

strength (float) – The strength of the coupling term.
term ([(str, int), (str, int)]) – List of two tuples [(op_i, i), (op_j, j)] where i is the MPS index of the site the operator named op_i acts on; we require i < j.
sites (list of Site) – Defines the local Hilbert space for each site. Used to check whether the operators need Jordan-Wigner strings.
op_string (None | str) –
Operator name to be used as operator string between the operators, or None if the Jordan Wigner string should be figured out.

Warning

None figures out for each segment between the operators, whether a Jordan-Wigner string is needed. This is different from a plain 'JW', which just applies a string on each segment!

Returns:

Arguments for MultiCouplingTerms.add_multi_coupling_term() such that the added term corresponds to the parameters of this function.

Return type:

strength, i, j, op_i, op_j, op_string

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

plot_coupling_terms(ax, lat, style_map='default', common_style={'linestyle': '--'}, text=None, text_pos=0.4)[source]

“Plot coupling terms into a given lattice.

This function plots the coupling_terms

Parameters:

ax (matplotlib.axes.Axes) – The axes on which we should plot.
lat (Lattice) – The lattice for plotting the couplings, most probably the M.lat of the corresponding model M, see lat.
style_map (function | None) – Function which get’s called with arguments i, j, op_i, op_string, op_j, strength for each two-site coupling and should return a keyword-dictionary with the desired plot-style for this coupling. By default (None), the linewidth is given by the absolute value of strength, and the linecolor depends on the phase of strength (using the hsv colormap).
common_style (dict) – Common style, which overwrites values of the dictionary returned by style_map. A 'label' is only used for the first plotted line.
text (format_string | None) – If not None, we add text labeling the couplings in the plot. Available keywords are i, j, op_i, op_string, op_j, strength as well as strength_abs, strength_angle, strength_real.
text_pos (float) – Specify where to put the text on the line between i (0.0) and j (1.0), e.g. 0.5 is exactly in the middle between i and j.