document `similar_from_indices`?

[simeonschaub]

First of all, awesome package! I want to use TensorOperations in https://github.com/simeonschaub/CoolTensors.jl, but I think to get it to return the correct output type, I need to implement a specialized method of similar_from_indices. Would it be possible to add a short explanation on what the various arguments are exactly for similar_from_indices?

[Jutho]

Yes, I changed how this works in the latest release but did not update the docs accordingly. Provided that your custom tensor type listens to the call Base.similar(some_tensor_object, some_eltype, some_structure_specification), e.g. for standard arrays similar(array, eltype, size), then the minimal set of methods that you need to overload are the documented methods in
src/implementation/stridedarray.jl. I will leave this issue open as a reminder to fix the documentation.

[simeonschaub]

Thanks for the quick response! What I am still wondering, is whether similar_from_indices could be used to preserve information about each axis, which in my case is covariance. For example, I want a (1, 1) T"'," tensor A concatenated with a T"'" vector x to produce another T"'" vector y when I write @tensor y[i] := A[i, j] * x[j]. After looking into this a bit, I don't think this is possible by just implementing similar, because then I don't know which indices get contracted and which should be preserved in the resulting tensor. It seems like I could solve that by implementing similar_from_indices, but I haven't quite figured out how.

[simeonschaub]

I think I mostly got it now, the only thing I'm still a bit confused about is the difference between the arguments p1 and p2.

[Jutho]

That's something I specifically added for my use case in TensorKit.jl, where tensors have two sets of indices, and you can permute arbitrary among and in between them. For most cases, you should just join p1 and p2 together into p = (p1..., p2...) and together this forms a permutation.

There is syntax in the left hand side to specify two types of indices, either as

@tensor A[i1 i2 i3; i4 i5]

or

@tensor A[(i1,i2,i3),(i4,i5)]

For tensors in the right hand side, this is ignored and both sets of indices are anyway grouped into one.

[simeonschaub]

Ah, thanks, that makes sense! In CoolTensors, co- and contravariant indices can have an arbitrary order, so I don't think I will make use of this functionality, but that's good to know. Not at my PC atm, but I will try to put this into a docstring and make a PR.