Add symmetric tensor tutorial to docs as appendix

[leburgel]

Adds the symmetric tensor tutorial from the quantumghent tensor tutorials to the docs as an appendix, as discussed in #289.

In the process, I add subblock and subblocks to the library docs, since these were missing before so I couldn't reference their docstrings.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

After the build completes, the updated documentation will be available here

[leburgel]

Not really the main point here, but I would also prefer it if all toc depths in docs/src/index.md were set to 2. I've always thought the depth-3 ones look very busy.

[lkdvos]

Will try and go through in more detail, some small comments:

It might make the notation a bit lighter if we replace ComplexF64 with Float64 for the cases where this is applicable, I know we don't default to this in MPSKit for various reasons, but here it seems a bit much to me.

For git reasons it might be convenient to break lines at sentences instead of splitting at linewidth. It also tends to make paragraphs less jumpy for small changes/comments

[lkdvos]

Can we add here that this can be done automatically for the entire array with the TensorMap constructor as well? I think the explicit example is still relevant since it demonstrates what is going on, but we should probably get the message across that it isn't needed to do this manually (provided you have the correct basis for the dense array)

[leburgel]

Ah, I didn't think of this in the original tutorial, but it does seem very relevant here. The only issue is that I'm not really sure myself what the right dense array basis is for different symmetries. Is there any documentation at all on what the chosen ordering of sectors is for each sector type that's implemented? Because if this information can't be reliably found, it feels a bit strange to showcase this feature if there's no way to apply it reliably in the general case.

For SU(2) here I'm sure I can guess the irrep ordering so people could adapt that to their own SU(2)-symmetric operators, but for most other symmetries (even U(1) for example I think) I would be rather at a loss how to initialize the dense array in the first place.

[leburgel]

Also, I don't want to be too annoying, but if the internal sector ordering changes as any point like it did for SU(3) that would give extremely annoying breakages for people who use this approach.

So thinking about this more broadly, is calling the constructor for homspaces with non-trivial symmetries directly on a dense data array really something we want people to be doing at all?

[lkdvos]

There is some functionality for figuring this out:

• They are concatenated in the order determined by Base.isless(x::I, y::I) where {I <: Sector}
• axes(V, sector) will tell you the range of values, so for example axes(SU2Space(0 => 2, 1/2 => 2), SU2Irrep(1/2)) == 3:6.
  In general, I think we are committed to not changing this, as this would indeed be a massive breaking change.

This is actually unrelated to the fusiontree ordering that happened (apparently in v0.13, I checked), which actually only shuffled the order of the internal data in the .data field.
I agree that these are extremely annoying breakages, which we try to avoid at all costs, but this would have been unaffected here. (and we typically have more support for upgrading old code, see e.g. https://github.com/QuantumKitHub/TensorKit.jl#transferring-tensormap-data-from-older-versions-to-v013)

I definitely understand the problem though, but I would argue that the hardest part is our (currently undocumented) basis choice of the clebsch gordan coefficients, not the order in which different sectors are concatenated, which is actually quite well-determined (although definitely also underdocumented).
Here this issue is just not showing up since we only have tensors with a single sector per leg...

[leburgel]

I don't know if I just never knew about the axes functionality for (product)spaces or I just forgot, but this is very useful. This then solves the problem of finding the right dense array basis for all Abelian groups at least. This is actually documented here, which is already very nice. However, the statement

Currently, the only non-abelian sectors are Irrep[SU₂] and Irrep[CU₁], for which the internal structure is the natural one.

is not actually that helpful, where I take some particular offense to the "the natural one" part.

I was indeed confusing two things before. I also had the basis choice for the Clebsch-Gordan coefficients in mind, in particular the ordering of the 'magnetic quantum number' within each irrep. Even here, while I think I know what the 'natural one' is, this really might depend on person to person. So I think the bottom line is that a user can only use the constructor from a dense data array for sector types for which they know exactly what the corresponding fusiontensor is, up to the basis choice inside each representation space.

Going back to being annoying then, even for the SU(2) example as it is in the tutorial, I already just assumed that the fusiontensor for SU(2) was a WignerSymbols.clebschgordan. I know this, but the only way to actually find out is to hunt down the source. So for one, I should probably switch to using fusiontensor here instead of going through WignerSymbols.clebschgordan in the example. Then I can manually state what the choice of basis within each representation space is, solving the problem for SU(2) at least. And then I can state that you can do the same just using the constructor from a dense array, provided you know exactly what fusiontensor actually does.

[lkdvos]

I agree with you, both that "natural" is not the best wording and that we should absolutely document this. Concretely, I was thinking of starting documentation for TensorKitSectors that at least states the basis for the fusiontensor there. For TensorKit there then needs to be slightly more explanation to show how to go from trivalent fusiontensor to the full fusiontree. Just obtaining the numerical tensor can actually be done with convert(Array, (f1, f2)), which is also not a great interface, so there I would even suggest overloading fusiontensor(f1, f2) instead?

PS, just wanted to mention that on top of the ordering of the magnetic quantum number there is an additional sign degree of freedom for each of these basis states, again fixed by an (undocumented) convention, so this also has to be specified. In general though, I am actually not entirely sure how to do this, i.e. it still requires a "reference point" to write down a basis?

[leburgel]

I tried to rewrite/add things to address this as best I could. I hope this resolves things more or less.

PS, just wanted to mention that on top of the ordering of the magnetic quantum number there is an additional sign degree of freedom for each of these basis states

I would think that this doesn't matter in this context as long as people either use fusiontensor to manually project out reduced tensor elements, or just go through the TensorMap constructor from the dense data array. I would think this only becomes a problem when you try to manually project out Clebsch-Gordans that you defined yourself, where you run the risk of not matching the TensorKit internal sign convention.

[Jutho]

I always doubt about whether "whose" can be used with reference to subjects that are not persons but objects, or whether instead one should use:

"the Ising model, the Hamiltonian of which is given by"

[leburgel]

It seems to be generally accepted, and I personally don't mind anthropomorphizing here and there to make things sound less formal.

[Jutho]

Unlike hyperlinks, equation references are printed in dark blue, even in dark mode. This makes them very hard to read. Even in the light theme, they clearly have a distinct blue color from hyperlinks, which is not very pretty. Not sure if that can easily be changed.

[leburgel]

I also noticed this, and am very annoyed by it. I've tried to look into how I could solve this, but it seems like a very painful mathjax-css rabit hole. I'll give it another go if I have time, but not sure if I can reasonably solve this...

[Jutho]

In the FusionStyle trait, we are not actually using the "abelian" vs "non-abelian" nomenclature, because at some point it became confusing if you also want to consider Vec[G]. For a non-abelian group, the "fusion" of the simple objects of Vec[G] is unique. However, it does depend on the order: a ⊗ b != b ⊗ a. Hence, there cannot be a braiding. On the other hand, for Rep[G], it does hold that a ⊗ b == b ⊗ a, also for a non-abelian group.

So then, what does abelian mean: does it mean unique fusion, or independent of the order fusion?

Note that I have no problem with calling the group abelian or non-abelian; but I would prefer to avoid calling fusion rules abelian.

[leburgel]

Ah I see. I tend to think of fusion rules from the perspective of anyon models. In that context, I'm pretty sure "non-Abelian" fusion rules exactly mean that there are objects with non-unique fusion, and this is standard terminology. From that point of view, I would say the fusion rules of Vec[G] are always Abelian, which is indeed a very confusing thing to say if G is non-Abelian.

The problem only problem I have with using the terminology used in the FusionStyle trait is that it is quite non-standard, precisely because it's made to cover general cases. So while more correct, it would also be less familiar and therefore less intuitive I think. Similarly, I think people might be more familiar with the notion of Abelian and non-Abelian anyons than they are with considering the category Vec[G]. In this entire section and in all the references linked, I'm explicitly talking about fusion rules of irreps, so I don't actually feel like this is giving any unfair implications, since for irreps it's well defined what non-Abelian fusion rules are.

I the end, I would be fine with switching to "unique fusion rules" and "non-unique fusion rules" instead of "Abelian fusion rules" and "non-Abelian fusion rules". But I would actually prefer not to because I think the latter is more familiar, even though I agree it's less correct.

[Jutho]

Can we not consistently use subblock, or reduced matrix element, instead of simply block, and reserve the latter for the diagonal matrix blocks?

[leburgel]

I think I added this note simply because I noticed I was mixing everything, and this was the quickest fix. But I agree this might be needlessly confusing, I'll replace all careless "block" uses by "subblocks" or "reduced tensor elements". I like "tensor" more than "matrix" personally because you plug in an actual multidimensional array, but then still failed to use it consistently.

[leburgel]

I think I got rid of all lazy unspecified "block" mentions, should be more consistent now.