UPDATE January 2020: Since November 2019 TensorOperations implements an ncon interface as well. It hence provides everything that this package does, plus much more, such as smart management of temporary arrays. We hence recommend using TensorOperations instead of NCon from now on. Future maintenance of NCon may or may not happen.
NCon exports the function ncon, which provides a convenient interface for
contracting networks of tensors in a given order. It is a Julia port of the
MATLAB function described in
arXiv:1402.0939, although without some of
the fancier features. NCon relies on the
TensorOperations package for
implementation of pair-wise tensor contractions.
julia> ]
pkg> add "git://github.com/mhauru/NCon.jl"ncon(L, v; forder=nothing, order=nothing, check_indices=false)
The first argument L is a Tuple of tensors (multidimensional Arrays).
The second argument v is a Tuple of Vectors, one for each tensor in
L.
Each v[i] consists of Ints, each of which labels an index of L[i].
Positive labels mark indices which are to be contracted (summed over).
So if for instance v[m][i] == 2 and v[n][j] == 2, then the ith index of
L[m] and the jth index of L[n] are to be summed over.
Negative labels mark indices which are to remain free (uncontracted).
The keyword argument order is an Array of all the positive labels, which
specifies the order in which the pair-wise tensor contractions are to be done.
By default it is sort(all-positive-numbers-in-v). Note that whenever an index
joining two tensors is about to be contracted together, ncon contracts at the
same time all indices connecting these two tensors, even if some of them only
come up later in order.
Correspondingly forder specifies the order to which the remaining free
indices are to be permuted. By default it is sort(all-negative-numbers-in-v, rev=true), meaning for instance [-1,-2,...].
If check_indices=true (by default it's false) then checks are performed to
make sure the contraction is well-defined. If not, an ArgumentError with a
helpful description of what went wrong is provided.
A matrix product:
julia> using NCon
julia> A = rand(3,4);
julia> B = rand(4,5);
julia> C = ncon((A, B), ([-1,1], [1,-2]));
julia> size(C)
(3,5)Here the last index of A and the first index of B are contracted.
The result is a tensor with two free indices, labeled by -1 and -2.
The one labeled with -1 becomes the first index of the result. If we gave the
additional argument forder=[-2,-1] the tranpose would be returned instead.
A more complicated example:
julia> A = rand(3,4,5);
julia> B = rand(5,3,6,7,6);
julia> C = rand(7,2);
julia> D = ncon((A, B, C), ([3,-2,2], [2,3,1,4,1], [4,-1]));
julia> size(D)
(2,4)By default, the contractions are done in the order [1,2,3,4]. This may not be the optimal choice, in which case we should specify a better contraction order as a keyword argument.
Disconnected networks are also possible:
julia> A = rand(2,3);
julia> B = rand(4);
julia> C = ncon((A, B), ([-3,-2], [-1]));
julia> size(C)
(4,3,2)This is the same as the tensor product of A and B, with the indices
permuted to the desired order. When contracting disconnected networks, the
connected parts are always contracted first, and their tensor product is taken
at the end.
L and v may also be a single tensor and its index list, if a trace is taken:
julia> A = rand(3,2,3);
julia> B = ncon(A, [1,-1,1]);
julia> size(B)
(2,)