LegPipe¶
full name: tenpy.linalg.charges.LegPipe
parent module:
tenpy.linalg.charges
type: class
-
class
tenpy.linalg.charges.
LegPipe
(legs, qconj=1, sort=True, bunch=True)[source]¶ Bases:
tenpy.linalg.charges.LegCharge
A LegPipe combines multiple legs of a tensor to one.
Often, it is necessary to “combine” multiple legs into one: for example to perfom a SVD, the tensor needs to be viewed as a matrix.
This class does exactly this job: it combines multiple LegCharges (‘incoming legs’) into one ‘pipe’ (the ‘outgoing leg’). The pipe itself is a
LegCharge
, with indices running from 0 to the product of the individual legs’ ind_len, corresponding to all possible combinations of input leg indices.(This class is implemented in
tenpy.linalg.charges
but also imported intenpy.linalg.np_conserved
for convenience.)- Parameters
- legslist of
LegCharge
The legs which are to be combined.
- qconj{+1, -1}
A flag telling whether the charge of the resulting pipe points inwards (+1, default) or outwards (-1).
- sortbool
Whether the outgoing pipe should be sorted. Default
True
; recommended. Note: callingsort()
after initialization converts to a LegCharge.- bunchbool
Whether the outgoing pipe should be bunched. Default
True
; recommended. Note: callingbunch()
after initialization converts to a LegCharge.
- legslist of
Notes
For np.reshape, taking, for example, \(i,j,... \rightarrow k\) amounted to \(k = s_1*i + s_2*j + ...\) for appropriate strides \(s_1,s_2\).
In the charged case, however, we want to block \(k\) by charge, so we must implicitly permute as well. This reordering is encoded in q_map.
Each qindex combination of the nlegs input legs \((i_1, ..., i_{nlegs})\), will end up getting placed in some slice \(a_j:a_{j+1}\) of the outgoing pipe. Within this slice, the data is simply reshaped in usual row-major fashion (‘C’-order), i.e., with strides \(s_1 > s_2 > ...\).
It will be a subslice of a new total block labeled by qindex \(I_s\). Because many charge combinations fuse to the same total charge, in general there will be many tuples \((i_1, ..., i_{nlegs})\) belonging to the same \(I_s\). The rows of q_map are precisely the collections of
[b_j, b_{j+1}, I_s, i_1, . . . , i_{nlegs}]
. Here, \(b_j:b_{j+1}\) denotes the slice of this qindex combination within the total block I_s, i.e.,b_j = a_j - self.slices[I_s]
.The rows of q_map are lex-sorted first by
I_s
, then thei
. EachI_s
will have multiple rows, and the order in which they are stored in q_map is the order the data is stored in the actual tensor, i.e., it might look like[ ..., [ b_j, b_{j+1}, I_s, i_1, ..., i_{nlegs} ], [ b_{j+1}, b_{j+2}, I_s, i'_1, ..., i'_{nlegs} ], [ 0, b_{j+3}, I_s + 1, i''_1, ..., i''_{nlegs} ], [ b_{j+3}, b_{j+4}, I_s + 1, i'''_1, ..., i'''_{nlegs}], ...]
The charge fusion rule is:
self.charges[Qi]*self.qconj == sum([l.charges[qi_l]*l.qconj for l in self.legs]) mod qmod
Here the qindex
Qi
of the pipe corresponds to qindicesqi_l
on the individual legs.- Attributes
- nlegsint
The number of legs.
- legstuple of
LegCharge
The original legs, which were combined in the pipe.
- subshapetuple of int
ind_len for each of the incoming legs.
- subqshapetuple of int
block_number for each of the incoming legs.
- q_map: array[np.intp, ndim=2]
Shape (block_number, 3 + nlegs). Rows:
[ b_j, b_{j+1}, I_s, i_1, ..., i_{nlegs}]
, See Notes below for details.- q_map_slicesarray[np.intp, ndim=1]
Defined such that the row indices of in
range(q_map_slices[I_s], q_map_slices[I_s+1])
haveq_map[:, 2] == I_s
.- _perm1D array
A permutation such that
q_map[_perm, 3:]
is sorted by i_l.- _strides1D array
Strides for mapping incoming qindices i_l to the index of
q_map[_perm, :]
.
Methods
bunch
(self, \*args, \*\*kwargs)Convert to LegCharge and call
LegCharge.bunch()
.charge_sectors
(self)Return unique rows of self.charges.
conj
(self)Return a shallow copy with opposite
self.qconj
.copy
(self)Return a (shallow) copy of self.
extend
(self, extra)Return a new
LegCharge
, which extends self with futher charges.flip_charges_qconj
(self)Return a copy with both negative qconj and charges.
from_add_charge
(legs[, chargeinfo])Add the (independent) charges of two or more legs to get larger qnumber.
from_change_charge
(leg, charge, new_qmod[, …])Remove a charge from a LegCharge.
from_drop_charge
(leg[, charge, chargeinfo])Remove a charge from a LegCharge.
from_qdict
(chargeinfo, qdict[, qconj])Create a LegCharge from qdict form.
from_qflat
(chargeinfo, qflat[, qconj])Create a LegCharge from qflat form.
from_qind
(chargeinfo, slices, charges[, qconj])Just a wrapper around self.__init__(), see class doc-string for parameters.
from_trivial
(ind_len[, chargeinfo, qconj])Create trivial (qnumber=0) LegCharge for given len of indices ind_len.
get_charge
(self, qindex)Return charge
self.charges[qindex] * self.qconj
for a given qindex.get_qindex
(self, flat_index)Find qindex containing a flat index.
get_qindex_of_charges
(self, charges)Return the slice selecting the block for given charge values.
get_slice
(self, qindex)Return slice selecting the block for a given qindex.
is_blocked
(self)Returns whether self is blocked, i.e.
is_bunched
(self)Checks whether
bunch()
would change something.is_sorted
(self)Returns whether self.charges is sorted lexiographically.
map_incoming_flat
(self, incoming_indices)Map (flat) incoming indices to an index in the outgoing pipe.
outer_conj
(self)Like
conj()
, but don’t changeqconj
for incoming legs.perm_flat_from_perm_qind
(self, perm_qind)Convert a permutation of qind (acting on self) into a flat permutation.
perm_qind_from_perm_flat
(self, perm_flat)Convert flat permutation into qind permutation.
project
(self, \*args, \*\*kwargs)Convert self to LegCharge and call
LegCharge.project()
.sort
(self, \*args, \*\*kwargs)Convert to LegCharge and call
LegCharge.sort()
.test_contractible
(self, other)Raises a ValueError if charges are incompatible for contraction with other.
test_equal
(self, other)Test if charges are equal including qconj.
test_sanity
(self)Sanity check, raises ValueErrors, if something is wrong.
to_LegCharge
(self)Convert self to a LegCharge, discarding the information how to split the legs.
to_qdict
(self)Return charges in qdict form.
to_qflat
(self)Return charges in qflat form.
-
to_LegCharge
(self)[source]¶ Convert self to a LegCharge, discarding the information how to split the legs.
Usually not needed, but called by functions, which are not implemented for a LegPipe.
-
conj
(self)[source]¶ Return a shallow copy with opposite
self.qconj
.- Returns
- conjugated
LegCharge
Shallow copy of self with flipped
qconj
. Whenever we contract two legs, they need to be conjugated to each other. The incoming legs of the pipe are also conjugated.
- conjugated
-
sort
(self, *args, **kwargs)[source]¶ Convert to LegCharge and call
LegCharge.sort()
.
-
bunch
(self, *args, **kwargs)[source]¶ Convert to LegCharge and call
LegCharge.bunch()
.
-
project
(self, *args, **kwargs)[source]¶ Convert self to LegCharge and call
LegCharge.project()
.In general, this could be implemented for a LegPipe, but would make
split_legs()
more complicated, thus we keep it simple. If you really want to project and split afterwards, use the following work-around, which is for example used inexact_diagonalization
:Create the full pipe and save it separetely.
Convert the Pipe to a Leg & project the array with it.
[… do calculations …]
To split the ‘projected pipe’ of A, create and empty array B with the legs of A, but replace the projected leg by the full pipe. Set A as a slice of B. Finally split the pipe.
-
map_incoming_flat
(self, incoming_indices)[source]¶ Map (flat) incoming indices to an index in the outgoing pipe.
- Parameters
- incoming_indicesiterable of int
One (flat) index on each of the incoming legs.
- Returns
- outgoing_indexint
The index in the outgoing leg.
-
charge_sectors
(self)¶ Return unique rows of self.charges.
- Returns
- chargesarray[QTYPE, ndim=2]
Rows are the rows of self.charges lexsorted and without duplicates.
-
extend
(self, extra)¶ Return a new
LegCharge
, which extends self with futher charges.This is needed to formally increase the dimension of an Array.
-
flip_charges_qconj
(self)¶ Return a copy with both negative qconj and charges.
- Returns
- conj_charges
LegCharge
(Shallow) copy of self with negative qconj and charges, thus representing the very same charges.
test_equal()
of self with conj_charges will not raise an error.
- conj_charges
-
classmethod
from_add_charge
(legs, chargeinfo=None)¶ Add the (independent) charges of two or more legs to get larger qnumber.
- Parameters
- legsiterable of
LegCharge
The legs for which the charges are to be combined/added.
- chargeinfo
ChargeInfo
The ChargeInfo for all charges; create new if
None
.
- legsiterable of
- Returns
- combined
LegCharge
A LegCharge with the charges of both legs. Is neither sorted nor bunched!
- combined
-
classmethod
from_change_charge
(leg, charge, new_qmod, new_name='', chargeinfo=None)¶ Remove a charge from a LegCharge.
- Parameters
- leg
LegCharge
The leg from which to drop/remove a charge.
- chargeint | str
Number or name of the charge (within chinfo) for which mod is to be changed.
- new_qmodint
The new mod to be set for charge in the
ChargeInfo
.- new_namestr
The new name for charge.
- chargeinfo
ChargeInfo
The ChargeInfo with charge changed; create new if
None
.
- leg
- Returns
- leg
LegCharge
A LegCharge with the specified charge changed. Is neither sorted nor bunched!
- leg
-
classmethod
from_drop_charge
(leg, charge=None, chargeinfo=None)¶ Remove a charge from a LegCharge.
- Parameters
- leg
LegCharge
The leg from which to drop/remove a charge.
- chargeint | str
Number or name of the charge (within chinfo) which is to be dropped.
None
means dropping all charges.- chargeinfo
ChargeInfo
The ChargeInfo with charge dropped; create new if
None
.
- leg
- Returns
- dropped
LegCharge
A LegCharge with the specified charge dropped. Is neither sorted nor bunched!
- dropped
-
classmethod
from_qdict
(chargeinfo, qdict, qconj=1)¶ Create a LegCharge from qdict form.
- Parameters
- chargeinfo
ChargeInfo
The nature of the charge.
- qdictdict
A dictionary mapping a tuple of charges to slices.
- chargeinfo
-
classmethod
from_qflat
(chargeinfo, qflat, qconj=1)¶ Create a LegCharge from qflat form.
Does neither bunch nor sort. We recommend to sort (and bunch) afterwards, if you expect that tensors using the LegCharge have entries at all positions compatible with the charges.
- Parameters
- chargeinfo
ChargeInfo
The nature of the charge.
- qflatarray_like (ind_len, qnumber)
qnumber charges for each index of the leg on entry.
- qconj{-1, 1}
A flag telling whether the charge points inwards (+1) or outwards (-1).
- chargeinfo
-
classmethod
from_qind
(chargeinfo, slices, charges, qconj=1)¶ Just a wrapper around self.__init__(), see class doc-string for parameters.
-
classmethod
from_trivial
(ind_len, chargeinfo=None, qconj=1)¶ Create trivial (qnumber=0) LegCharge for given len of indices ind_len.
-
get_charge
(self, qindex)¶ Return charge
self.charges[qindex] * self.qconj
for a given qindex.
-
get_qindex
(self, flat_index)¶ Find qindex containing a flat index.
Given a flat index, to find the corresponding entry in an Array, we need to determine the block it is saved in. For example, if
slices = [[0, 3], [3, 7], [7, 12]]
, the flat index5
corresponds to the second entry,qindex = 1
(since 5 is in [3:7]), and the index within the block would be2 = 5 - 3
.- Parameters
- flat_indexint
A flat index of the leg. Negative index counts from behind.
- Returns
- qindexint
The qindex, i.e. the index of the block containing flat_index.
- index_within_blockint
The index of flat_index within the block given by qindex.
-
get_qindex_of_charges
(self, charges)¶ Return the slice selecting the block for given charge values.
Inverse function of
get_charge()
.- Parameters
- charges1D array_like
Charge values for which the slice of the block is to be determined.
- Returns
- slice(i, j)slice
Slice of the charge values for
- Raises
- ValueErrorif the answer is not unique (because self is not blocked).
-
get_slice
(self, qindex)¶ Return slice selecting the block for a given qindex.
-
is_blocked
(self)¶ Returns whether self is blocked, i.e. qindex map 1:1 to charge values.
-
is_sorted
(self)¶ Returns whether self.charges is sorted lexiographically.
-
perm_flat_from_perm_qind
(self, perm_qind)¶ Convert a permutation of qind (acting on self) into a flat permutation.
-
perm_qind_from_perm_flat
(self, perm_flat)¶ Convert flat permutation into qind permutation.
- Parameters
- perm_flat1D array
A permutation acting on self, which doesn’t mix the blocks of qind.
- Returns
- perm_qind1D array
The permutation of self.qind described by perm_flat.
- Raises
- ValueError
If perm_flat mixes blocks of different qindex.
-
test_contractible
(self, other)¶ Raises a ValueError if charges are incompatible for contraction with other.
- Parameters
- other
LegCharge
The LegCharge of the other leg condsidered for contraction.
- other
- Raises
- ValueError
If the charges are incompatible for direct contraction.
See also
test_equal
self.test_contractible(other)
just performsself.test_equal(other.conj())
.
Notes
This function checks that two legs are ready for contraction. This is the case, if all of the following conditions are met:
the
ChargeInfo
is equalthe slices are equal
the charges are the same up to opposite signs
qconj
:self.charges * self.qconj = - other.charges * other.qconj
In general, there could also be a change of the total charge, see Introduction to np_conserved This special case is not considered here - instead use
gauge_total_charge()
, if a change of the charge is desired.If you are sure that the legs should be contractable, check whether the charges are actually valid or whether
self
andother
are blocked or should be sorted.
-
test_equal
(self, other)¶ Test if charges are equal including qconj.
Check that all of the following conditions are met:
the
ChargeInfo
is equalthe slices are equal
the charges are the same up to the signs
qconj
:self.charges * self.qconj = other.charges * other.qconj
See also
test_contractible
self.test_equal(other)
is equivalent toself.test_contractible(other.conj())
.
-
to_qdict
(self)¶ Return charges in qdict form.
Raises ValueError, if not blocked.
-
to_qflat
(self)¶ Return charges in qflat form.