Add Website Documentation About Index

[mabruzzo]

I think it would be useful to write a page of high-level documentation about the Index class and how it is used.

It's something that I have a good mental model for, but it's always a little challenging to confirm that it works as I think it does (from going through the Charm++ documentation), and it would be nice to have a single source of truth to be able to easily refer to. I'm not going to get a chance to write this documentation at this moment, so I figured I would just post my notes I have about it here to make this easier in the future (if somebody else gets to this sooner):

You shouldn't think of enzo::block_array() as an ordinary array. Instead, think about it like a dictionary (the Charm++ documentation would calls it a sparse collection of a Chares). There is a 1-to-1 mapping between a given value of Index and Block chare arrays.

• The Index class internally maps a 3D location in space to a unique string of 96 bits.
• The Index object has 3 main parts:
  1. The level of the block (Except when discussing negative levels, I suspect that level data may be slightly redundant - But this is an implementation detail, that shouldn't be documented).
  2. The index of the block on the root grid (where the block lives or its ancestor lives)
  3. The octree child-index relative to that position on the root index
• Currently, when you construct an instance of Index from 3 integers, that refers to a location on the root grid.
• If you wanted to specify the Index of an arbitrary child, you would need to use the set_child method.
• The conversion between an instance of the Index class to something that Charm++ knows how to use is handled by the CkArrayIndexIndex class (Charm++ knows to make this conversion because of the array[Index] Block {... line in Cello/mesh.ci.

I don't totally understand how the indexing works for negative levels. (My guess is that the array indices are used...). @jobordner do you have any insights

As an aside. In the future we might want to consider moving away from the use of bitfields in the underlying future (and instead depend on bitwise operations for an array of 3 uint32_t values). While the bitfields provide a lot of convenience, I'm pretty sure that we are technically depending on implementation-defined behavior. Technically, the our usage of the union also violates the C++ standard. (In practice, neither of choices probably won't ever be much of an issue - I suspect lots of code depends on these behaviors and most compilers wouldn't dare changing it)