Wolfram Language Paclet Repository
Community-contributed installable additions to the Wolfram Language
Index conventions and contraction path
Index conventions and contraction path
|
This tech note pins down the index conventions the TensorNetworks`` kernel uses and shows how the same contraction reads in each one. The conventions look alike (everything is a list of small integers) but they count different things, and conflating them is the usual source of confusion. We work computation-first: every claim below is produced by a cell you can rerun, and we read the meaning off the output rather than asserting it.
Wolfram
Five conventions appear. Four of them number legs, where a leg is a single index of a tensor (one of its axes); one numbers operands, where an operand is a whole tensor taking part in a contraction. The operands are not fixed: at the start they are the input tensors, and each contraction step replaces the two tensors it combines with their single result, so an operand can be an original input or an intermediate produced by an earlier step. Keeping the leg-versus-operand split in mind answers most questions on sight: when you see a list of integer pairs, ask "pairs of what", legs or operands.
Convention | An integer means | A contraction is written as | |
EinsteinSummation | an abstract name | the same name on two tensors | |
TensorNetwork | a tensor-position, leg-label tag per leg | a bond group (the legs sharing a label) | |
TensorContract | a slot in the flattened TensorProduct | a pair of global slots | |
ArrayDot | an axis within one operand | a pair of operand-local axes | |
contraction-path position | a position in the operand list | a pair of operands to multiply |
Three of these four leg conventions give a leg a fixed identity, no matter how the network is contracted; the fourth, the operand-local axes, is meaningful only during a contraction step. We build one small network, read its indices in those three fixed conventions, then see how a contraction path (operands) and (operand-local axes) re-express the same sums, and close with the two cases a repeated index can take beyond a plain pairwise contraction: broadcasting and hyperedges. Each section re-creates the running network so it stands on its own.
ArrayDot
ArrayDot
Setup: one small network
Setup: one small network
We use three tensors in a chain, with labels , , , , : carries , carries , carries . So is a bond between and , while and are two bonds between and , and (on ) and (on ) are the free legs. We ask for the output in the natural order . We use symbolic arrays () so the structural outputs display by name rather than as numbers.
EinsteinSummation
i=1
j=2
k=3
l=4
m=5
t1
(i,j)
t2
(j,k,l)
t3
(k,l,m)
j
t1
t2
k
l
t2
t3
i
t1
m
t3
(i,m)
Define the tensors and the network:
In[1]:=
t1=ArraySymbol["t1",{2,3}];t2=ArraySymbol["t2",{3,4,5}];t3=ArraySymbol["t3",{4,5,2}];tn=
[{t1,t2,t3},{{1,2},{2,3,4},{3,4,5}}{1,5}]
 | TensorNetwork |
Out[1]=
TensorNetwork
 |  |
|
The tensor network is binary: every index sits on at most two tensors, so every contraction is an ordinary pair of tensors. The doubled bond between and makes the multi-axis case concrete, and the rank-3 tensors make the blocks nontrivial. As an string the same network is . The three-or-more case is the subject of the last section.
t2
t3
ArrayDot
TensorContract
EinsteinSummation
"ij,jkl,klm->im"
1. Reading the legs: EinsteinSummation, data labels, global slots
1. Reading the legs: EinsteinSummation, data labels, global slots
Three of the four leg conventions give a leg a fixed identity, independent of any contraction; we read them off the tensor network here. The fourth, the operand-local axes, comes with the contraction in section 3.
ArrayDot
Rebuild the running network for this section:
In[2]:=
t1=ArraySymbol["t1",{2,3}];t2=ArraySymbol["t2",{3,4,5}];t3=ArraySymbol["t3",{4,5,2}];tn=
[{t1,t2,t3},{{1,2},{2,3,4},{3,4,5}}{1,5}];
 | TensorNetwork |
EinsteinSummation labels. A label is an abstract name. A label that appears on two tensors is contracted; a label that appears once is free; the part after fixes the output order. That is the entire convention, and already encodes it: , , repeat (contracted), , appear once (free), and the output is the two free legs.
->
"ij,jkl,klm->im"
j
k
l
i
m
Data labels. is the low-level form the rest of the kernel consumes. It tags every leg with its tensor position and its label (a of position over label), so a leg is addressable by which tensor and which label. List the per-leg labels:
In[3]:=
tn["Indices"]
Out[3]=
{{,},{,,},{,,}}
1
1
2
1
2
2
3
2
4
2
3
3
4
3
5
3
Each entry is one leg, tagged by tensor position (the base) and label (the superscript); the position-2, label-4 entry, for instance, is tensor 2's -leg. Read off the bonds:
EinsteinSummation
l
In[4]:=
tn["Bonds"]
Out[4]=
{{,}3,{,}4,{,}5}
2
1
2
2
3
2
3
3
4
2
4
3
This gives the three bond groups with their dimensions: the -bond has dimension 3, the -bond dimension 4, and the -bond dimension 5. Each bond pairs the two legs that share a label and records the dimension summed over it. Now the free legs, the labels that appear on only one tensor:
j
k
l
In[5]:=
tn["FreeIndices"]
Out[5]=
{1,5}
The result is , the free labels in the requested output order. Now tag every leg as either a bond group or a bare free label:
{1,5}
i,m
In[6]:=
tn["Contractions"]
Out[6]=
{{,{,}},{{,},{,},{,}},{{,},{,},}}
1
1
2
1
2
2
2
1
2
2
3
2
3
3
4
2
4
3
3
2
3
3
4
2
4
3
5
3
The result mirrors the per-tensor shape: the row for is its free followed by the -bond; the row for is the -, - and -bonds; the row for is the -bond, the -bond, then its free . A leg shown as a bare label is free; a leg shown as a list is contracted, and that list names exactly the legs it sums with.
t1
i
j
t2
j
k
l
t3
k
l
m
The same bond-versus-free structure is easier to take in as a picture. Draw the network as a hypergraph:
In[7]:=
tn["Hypergraph"]
Out[7]=
In this drawing the vertices are the indices and each edge is a tensor, spanning the indices it carries: over , over , over . An index that lies on two tensors is a contracted bond, that is, a vertex shared by two edges: joins and , while and both join and (the doubled bond). An index on a single tensor is free, a vertex in just one edge: on and on . This is the same split that the contractions listing gave, now visible at a glance. Note it is the dual of the usual tensor-network diagram, where tensors are nodes and indices are lines; here the two roles are swapped.
i,j,k,l,m
t1
{i,j}
t2
{j,k,l}
t3
{k,l,m}
j
t1
t2
k
l
t2
t3
i
t1
m
t3
Global slots. Contraction flattens the operands into one , and a global index is a slot position in that flattened product. Lower the spec to see those slots:
EinsteinSummation
In[8]:=
 | EinsteinSummation |
Out[8]=
TensorContract,{{2,3},{4,6},{5,7}}
2
t1
3
t2
3
t3
The output is an inactive of the with contraction pairs . The integers are slot positions in the flattened . To see the slots explicitly, flatten the data labels:
{{2,3},{4,6},{5,7}}
TensorProduct[t1,t2,t3]
In[9]:=
Catenate[tn["Indices"]]
Out[9]=
{,,,,,,,}
1
1
2
1
2
2
3
2
4
2
3
3
4
3
5
3
The result lists the eight legs in order, and the -th element is global slot : its base is the tensor, its superscript the label. So owns slots 1-2, owns 3-5, owns 6-8, and the lowering reads: sum slot 2 with 3 (the two 's), 4 with 6 (), 5 with 7 (). The free slots 1 () and 8 () survive in slot order , which is the order we requested, so there is no trailing transpose. Output order is its own convention: free legs survive tensor-then-leg, and requesting a different order would append a .
n
n
EinsteinSummation
t1
t2
t3
j
k
l
i
m
(i,m)
2. The contraction-path convention: pairwise steps over operands
2. The contraction-path convention: pairwise steps over operands
Contraction happens pairwise and in sequence. A path is a list of steps; each step picks two tensors from the current pool, sums over every leg they share, and puts the resulting tensor back in the pool for the later steps. The path numbers operands, not legs: it says which two tensors meet at each step, and the legs that get summed are simply whatever those two share. The final value does not depend on the order, but the order is what the executor walks, and it fixes which indices are summed when.
Rebuild the running network for this section:
In[10]:=
t1=ArraySymbol["t1",{2,3}];t2=ArraySymbol["t2",{3,4,5}];t3=ArraySymbol["t3",{4,5,2}];tn=
[{t1,t2,t3},{{1,2},{2,3,4},{3,4,5}}{1,5}];
| TensorNetwork |
Get a contraction path for the tensor network and keep it:
In[11]:=
path=
[tn]
| GreedyContractionPath |
Out[11]=
{{2,3},{1,2}}
The result is two steps over the three operands . Step 1's contracts operands 2 and 3 (, ); their result re-enters the pool, now , so step 2's means and . Operand numbers are reused because after each contraction the two inputs are replaced by their single result. ( is one of several functions that compute such a path; they differ in the cost of the path they return, not in any index convention, so we just use one.)
{{2,3},{1,2}}
{t1,t2,t3}
{2,3}
t2
t3
{t1,t2t3}
{1,2}
t1
t2t3
The path is an abstract recipe; the executor turns it into an explicit nest of pairwise contractions. Build that expression, left inactive so we can read the plan:
In[12]:=
ic=
[tn,path]
| TensorNetworkContraction |
Out[12]=
ArrayDot,ArrayDot,,{{2,1},{3,2}},{{2,1}}
2
t1
3
t2
3
t3
The output is (inactive), read inside-out. The inner is step 1: contract and over their two shared legs (the operand-local axis pairs of section 3). The outer is step 2: contract with that intermediate over their shared . The nesting is the order, and each node carries the axes summed at that step.
ArrayDot[t1,ArrayDot[t2,t3,{{2,1},{3,2}}],{{2,1}}]
t2
t3
k,l
{{2,1},{3,2}}
t1
j
The same thing is clearer as a tree. Render the contraction hierarchy with dimension labels:
In[13]:=
| ContractionTree |
Out[13]=
The leaves are the input tensors (dims , , ), and each internal node is one pairwise contraction, annotated by the axes it sums and the dimensions of its result. The lower node contracts with over to make a tensor (legs ); the root contracts with that over to make the final (legs ). Reading the tree bottom-up gives the exact contraction sequence, and reading a node tells you which legs were summed there.
{2,3}
{3,4,5}
{4,5,2}
t2
t3
{{2,1},{3,2}}
{3,2}
j,m
t1
{{2,1}}
{2,2}
i,m
In words, the sequence is: start with , , ; step 1 sums the two shared legs to get the intermediate ; step 2 sums the shared to get . Every step sums exactly the legs common to the two operands it joins, and the free legs of both survive into the result.
t1
(i,j)
t2
(j,k,l)
t3
(k,l,m)
k,l
(j,m)
j
(i,m)
The path itself never mentions ; the summed legs are implied by which operands meet. Recover them explicitly:
j,k,l
In[14]:=
| PathIndexContractions |
| TensorNetworkData |
Out[14]=
{{4,6},{5,7},{2,3}}
The output lists the summed legs as global slots, one step at a time: step 1 sums slots () and (), step 2 sums (). Those are exactly the lowering pairs from section 1, regrouped by path step, the bridge from the operand-only path back to the leg conventions.
{{4,6},{5,7},{2,3}}
{4,6}
k
{5,7}
l
{2,3}
j
Finally, the operand numbering has an alternative that never reuses a number, giving every tensor and intermediate a permanent id. Request it:
In[15]:=
| GreedyContractionPath |
Out[15]=
{{2,3},{4,1}}
The same tree now reads : merging operands 2 and 3 creates the intermediate with id 4, and step 2 joins operand 1 with that stable 4. Same sequence, two operand-numbering conventions.
{{2,3},{4,1}}
3. The ArrayDot convention: operand-local axes
3. The ArrayDot convention: operand-local axes
The executor contracts two tensors at a time, and its default primitive uses the fourth leg convention: it names each operand's own axes. A contraction is a list of pairs, each axis counted within its own tensor. The doubled bond between and (the shared legs ) makes this concrete. Instantiate the two tensors numerically (call the instances and ) and contract over three equivalent ways:
{axisInA,axisInB}
t2
t3
k,l
b
c
k,l
In[16]:=
With[{b=RandomReal[1,{3,4,5}],c=RandomReal[1,{4,5,2}]},ArrayDot[b,c,{{2,1},{3,2}}]ArrayDot[b,c,2]TensorContract[TensorProduct[b,c],{{2,4},{3,5}}]]
Out[16]=
True
The result is , so all three name the same contraction. The first is the pair form: contracts 's axis 2 () with 's axis 1 (), contracts 's axis 3 () with 's axis 2 (). The second is the count form , which contracts 's last two axes with 's first two; it works here only because the shared axes happen to be 's trailing block and 's leading block. The third is the global-slot form, and comparing it to the pair form gives the translation: an -axis keeps its number, while 's axis is the global slot (here , so 's axes 1,2 are global slots 4,5). The point of the operand-local convention is that a pairwise step never builds the growing flattened slot list; it only ever names two operands' own axes, which is why is the cheap default.
True
ArrayDot
{2,1}
t2
k
t3
k
{3,2}
t2
l
t3
l
ArrayDot[b,c,2]
t2
t3
t2
t3
a
b
bi
rank[a]+bi
rank[t2]=3
t3
ArrayDot
4. The same contraction in every convention
4. The same contraction in every convention
Putting it together, here is the single sum over (the bond between and ) in all five conventions:
j
t1
t2
5. What else a repeated index can mean
5. What else a repeated index can mean
A repeated index in the tensor network is always a plain pairwise contraction. Two other cases exist, and each has its own index convention.
Lower the four-tensor network:
A contraction path is still built from pairwise steps, and a hyperedge fits them without a three-way group: a step sums an index its two operands share only when no other tensor and no output still carries it, and otherwise keeps it, once, as a batch index of the result. The index rides along every step that still needs it and is summed by the last one. Build the four-tensor network:
The greedy path runs over its four tensors directly:
Where this leaves us
Where this leaves us
We built one network and read its indices in every convention the kernel uses: