Some suggestions for the overview design documentation

[twindus]

Some suggestions and questions for the overview design document at https://github.com/NWChemEx-Project/TensorWrapper/edit/master/docs/source/developer/design/overview.rst

For setting up the tensor (line 72 and after): Won't someone need to know what tensor library or libraries that will be used underneath the covers? I realize that maybe we don't want the user to have to know about this, but like the runtime environment, this is probably something that the user might want to input if they have a specific library they want to use. Maybe it is part of something like the runtime in a crude way?

Line 133: I don't know what "logical" means here. I am guessing that it means just the basic specification of the tensor? Maybe a better term would be "physical"? - although I am not sure that it is better.

Line 174: I think I understand what you mean by these being out of scope in a general way. However spin, spatial, and permutational symmetry have to be representable in the API. So, are they really out of scope? I didn't see an immediate way to change the wording, but hopefully it is clear what I am getting at.

Lin 264: I thought that we were going to worry about tile sparsity, not element-wise sparsity. Am I missing something?

Line 288: The link didn't get translated properly. I wasn't sure how to make it work, so just note it here.

Lines 310 and 311: I don't understand the difference between distribution and distribution strategy.

Line 343: What are multi-process tensors?

Line 369: Define CSL in the terminology page and provide a link.

[ryanmrichard]

I'm working on changes now, but to quickly answer the respective points:

• Backend selection is exposed to the user via the Allocator component.
• Physical is how the tensor is literally laid out on the machine; logical is the opposite of that, it's how the user wants to interact with it. Think of the ERIs. Logically they are a rank 4 tensor where each mode has an extent of "number of aos". In a distributed context, ERIs are physically a nested, jagged, rank 8 tensor where the outer layer has rank four and the modes are spanned by the tiles, the inner layer is also rank four, with the modes spanned by aos within the tile. Interacting with a tensor through it's logical layout will usually be done differently than interacting with it via its physical layout.
• I think I see what you're saying, but I'd still argue they're out of scope. For them to be in scope, TensorWrapper would need to make explicit design decisions to support them. In worrying about exploiting sparsity and symmetry we'll have already worried about everything to account for spin etc.
• I don't think you truly can separate them. Tile sparsity is element sparsity in a nested tensor.
• Noted.
• This is left over language and will need cleaned up.
• Tensors where different processes own different pieces. We usually call them distributed, but I'd argue that they don't actually need to be distributed.
• Noted

[twindus]

Thanks. I see what you are saying. For the spin, etc. in-scope or out-of-scope issue: probably just being more explicit about them being related to sparsity and symmetry will be enough to clarify it.