View source for Simplifying the Use of CellSets in DataSets 2

The current DataSet class in VTK-m comprises a group of cell sets, a group of fields, and a group of coordinate systems. The management of fields and coordinate systems is pretty straightforward because they behave pretty similarly across different types of cell models. However, the cell set object is handled problematically because the type of this class depends on the type of data structure (for example structured vs. explicit cell connections). Currently, DataSet stores a pointer to an abstract CellSet superclass with some unknown specialization for the particular data structure.

This is currently causing two problems. The first problem is that memory management is not well established. The abstract CellSet object must be stored as a pointer. It is typically allocated outside of DataSet and then passed to that class. Who is responsible for deleting it and when? Currently this is being solved by wrapping the pointer in a boost smart_ptr, but we really want to keep boost out of the VTK-m API.

The second problem is more serious. Once the CellSet is stored in the DataSet, its type is essentially lost. So whenever you use a DataSet, you have to somehow magically know what the CellSet actually is and do a dynamic_cast to the appropriate concrete type. It's a silly system since if you have to know the type anyway, you may as well store it in a static type. If you don't know the type, you have to write a lot of code to try all types it might be.

Ultimately, data sets (and in particular, the cell set part) should be designed in one of two ways. Either the data set should be strongly typed such that any code using it knows specifically what the type should be, or the data set has a polymorphic data set with a means to dynamically schedule it (much like a dynamic array handle). The current implementation is sort of in the middle of these two approaches and does a good job at neither.

Our first design for [[Simplifying the Use of CellSets in DataSets]] proposed statically typing the <tt>DataSet</tt> class to the cell set type. However, this implementation is problematic. Instead, this design keeps the implementation essentially how it is but adds a <tt>DynamicCellSet</tt> class to manage the data.

== Managing Dynamic Cell Sets ==

The dynamic cell sets will be managed by a new class named <tt>DynamicCellSet</tt>. This class will manage <tt>CellSet</tt> objects of unknown types in the same way that <tt>DynamicArrayHandle</tt> manages <tt>ArrayHandle</tt> objects of unknown types. This dynamic class serves two purposes: resource management and automatic casting.

=== Resource Management ===

<tt>DynamicCellSet</tt> provides resource management by behaving like a smart pointer. The object copies in a <tt>CellSet</tt> of a concrete type at creation and stores a reference to the newly created cell set object as the abstract superclass. <tt>DynamicCellSet</tt> maintains a reference count to the cell set pointer so that copies of the dynamic cell set can be created. All copies point to the same <tt>CellSet</tt> object and the <tt>CellSet</tt> is automatically deleted when all copies of <tt>DynamicCellSet</tt>s leave scope. This is easily implemented with a <tt>boost::smart_ptr</tt>. Since <tt>smart_ptr</tt> is hidden within private members, it does not break VTK-m API requirements to not rely on boost. (That is, the implementation could be changed without breaking any other code.)

Sometimes you want a new instance of the cell set of the same type rather than a reference to the same object. Thus, <tt>DynamicCellSet</tt> will also have a <tt>NewInstance</tt> method that allocates a new <tt>CellSet</tt> object and returns a new <tt>DynamicCellSet</tt> containing it.

=== Automatic Casting ===

The point of using an abstract version of <tt>CellSet</tt> is to manage when you don't know (or are not sure about) the type for <tt>CellSet</tt>. But eventually the abstract object must be cast to a concrete type to invoke an operation on that. Ultimately this means trying some list of possible types.

The <tt>DynamicCellSet</tt> will manage this casting on itself so that this feature is encapsulated and does not have to be replicated throughout the code. This casting is implemented with a <tt>CastAndCall</tt> method (similar to the functionality of the method of the same name in <tt>DynamicArrayHandle</tt>). This method takes a functor object and calls that object with a valid cast to a concrete <tt>CellSet</tt> type.

The <tt>CastAndCall</tt> method tries a default set of cell types (which is structured cells of dimensionality of 2 or 3 or explicit cells with all storages of the default type). This list to try can be modified in two ways. The first way is to define <tt>VTKM_DEFAULT_CELL_SET_LIST_TAG</tt> before including any VTK-m headers. This will globally redefine the default cell sets. The second way is to call <tt>ResetTypeList</tt> on the <tt>DynamicCellSet</tt>. This will return a <tt>DynamicCellSet</tt>-like object that shares the <tt>CellSet</tt> reference and behaves the same except that <tt>CastAndCall</tt> tries the new list of <tt>CellSet</tt> types provided.

The header for dynamic cell sets will also define a specialization for <tt>vtkm::cont::internal::DynamicTransformTraits</tt> so that whenever a <tt>DynamicCellSet</tt> is passed to a dispatcher <tt>Invoke</tt> method it will automatically use this cast and call feature to statically cast it.

Note that if <tt>DynamicCellSet</tt> is passed to the <tt>Invoke</tt> method, then it will not be possible to call methods like <tt>GetNodeToCellConnectivity</tt> on it. At the very least the return type would depend on the cell set type. Instead, this method will be called internally in the dispatcher.

== Cleaning up the CellSet Classes ==

This is a somewhat different topic, but the class structure underneath the cell set classes is a bit inconsistent, which makes it a bit confusing. Here is a breakdown of the classes and what I think I understand about them.

* '''CellSet''' A <tt>CellSet</tt> holds all the information about the topology. It contains all the information about how topological elements are connected (nodes to edges to faces to cells and all possible combinations). Some of these connections are directly accessible. Others might need some processing. For example, you might need to build the links from cells to nodes in an explicit cell set.
* '''Connectivity''' A <tt>Connectivity</tt> class describes the connections from one topological element to another. For examples, the connectivity from nodes to cells describes how cells are connected and fields are interpolated. The connectivity from cells to nodes describes all the cells incident on a node and allows cell to point operations.
* '''Structure''' There is really only a <tt>Structure</tt> class for structured grids and as far as I can tell, it is a convenience class to define methods for different dimensionality and different connectivity directions.

For sake of clarity and convention I suggest the following:

* The name of the connectivity classes be <tt>ConnectivityExplicit</tt> and <tt>ConnectivityRegular</tt> rather than <tt>ExplicitConnectivity</tt> and <tt>RegularConnectivity</tt>. This follows the VTK-m convention.
* The connectivity classes should all be in the <tt>vtkm::cont</tt> package. Functionality that is identical in both control and execution environment (such as what you find in the current <tt>RegularConnectivity</tt> and <tt>RegularStructure</tt> classes) should be in the vtkm::internal package (unless there is a reason to use the functionality outside of the cell set support objects).
*:<font color="forestgreen">vtkm::internal sounds good. It was put in vtkm mostly because of an unfamiliarity with the directory structure and their uses, etc. --[[User:Dpugmire|Dpugmire]] ([[User talk:Dpugmire|talk]]) 09:01, 24 July 2015 (EDT)</font>

* For each connectivity type in the control environment, there is a matching one in the execution environment (<tt>vtkm::exec</tt>). This will be used internally by the worklet to get connection information.
*:<font color="forestgreen">Should the control and execution classes be the same name or different? Which way is more clear? [[User:Kmorel|Kmorel]] ([[User talk:Kmorel|talk]]) 10:56, 20 July 2015 (EDT)</font>
* The <tt>TopologyType</tt> enum should be changed to a collection of tag structures (e.g. <tt>struct TopologyTypeCellTag {};</tt>). Tags are a bit less awkward for templates and overloading, and as far as I can tell these enumerations are not used for anything other than template resolution.
* The user code should not have to call the get connectivity method on the cell set. This should be handled within the worklet (more specifically in the transport). Which type of connectivity to get (node to cell vs. cell to node or any other combination) should be defined by the workout type. This means there will be a different worklet type for each from-to combination. That might lead to worklets templated on the from-to pair.
* There is inconsistency in the class names for structured grids. The cell set class was named structured but the connectivity class is named regular. I think the appropriate name is structured since if you apply an explicit coordinate system it becomes irregular. So the names should be <tt>CellSetStructured</tt> and <tt>ConnectivityStructured</tt>. However, the <tt>Make*RegularDataSet</tt> method names in <tt>MakeTestDataSet.h</tt> are correct since that is making it with a uniform coordinate system to make it regular.
* There is also inconsistency in using the names "point" and "node", both of which are used to refer to the vertices in the cell structure. Generally, VTK-m should use point, which follows the VTK naming convention. However, I propose to use the name "node" to refer to the local index of vertices in the cell. For example, say you have a 10x10 2D structured grid. All quadrilateral cells of this mesh have nodes 0, 1, 2, and 3. The first quadrilateral has points 0, 1, 11, and 10. The second quadrilateral has points 1, 2, 12, and 11.

: <font color="forestgreen">Should we add the concept of extents to the structured cell sets? VTK uses a 6 id min/max extent rather than a 3 id dimension for structured 3D grids. Dax adopted this simply because that is what VTK did. But everyone finds extents confusing and I don't know if they are important? Do we need them in VTK-m? [[User:Kmorel|Kmorel]] ([[User talk:Kmorel|talk]]) 10:56, 20 July 2015 (EDT)</font>
:: <font color="forestgreen">I talked to both Jeremy and Berk about this. Both felt that there is probably little to be gained by expressing the extent over the dimensions, so it is probably not worth the added complexity. [[User:Kmorel|Kmorel]] ([[User talk:Kmorel|talk]]) 08:48, 23 July 2015 (EDT)</font>