Deep Rework of AMR Data Model in VTK

Introduction

Adaptive Mesh Refinement (AMR) is a popular method of numerical simulation used to adapt the accuracy of the simulation, which produces volumes of data of different levels of detail.

While this can be achieved using an unstructured grid, using a dedicated data model is preferred as it improves computation speed and memory usage.

Support for such data was added in VTK data model a long time ago with success although with a small adoption rate by the community.

In essence, an AMR dataset is just a collection of regular grids of different sizes and refinements, organized by levels, each more refined than the previous.
It comes in two flavors, OverlappingAMR and NonOverlappingAMR.

OverlappingAMR, as its name indicates, contains grids that overlap each other, with each level covering the whole domain. NonOverlapping, on the contrary, contains grids without any kind of overlap which is made for a more intricate grid organization at the higher levels.

OverlappingAMR is usually more efficient at the cost of some data duplication in the coarser levels.

This data model has been used in VTK within different readers, writers and filters with varying degrees of adoption. VTK contains functional filters for OverlappingAMR but readers are few. ParaView contains multiple readers for NonOverlappingAMR as it corresponds to the output of multiple simulation codes, but the number of compatible filters is limited.

In VTK 9.6.0, the AMR data model has been greatly improved in order to simplify its usages and adoption by the community.

Inheritance

In order to bring this part of the VTK data model into its next steps, a deep rework was needed.
Indeed, in VTK 9.5.0 and before, the class hierarchy of AMR looked like that:

As one can see clearly, the AMR classes do not inherit from vtkDataObjectTree, which has become the main API to use when supporting composite datasets since the introduction of vtkPartitionedDataSetCollection.

Indeed, AMR data model relies on the hierarchical data model of VTK, which, in short, lets a data object store other data objects, with or without an explicit hierarchy. vtkCompositeDataSet is a free-form, without hierarchy, structure which means the AMR structure itself had to be stored on the AMR object and made it non-standard.

This has resulted in more and more custom implementation of filters and representations for AMR being introduced or AMR support for new filters just not being implemented at all, as many filters only support vtkDataObjectTree, not vtkCompositeDataSet.

The obvious solution here was to make the AMR data model classes inherit from vtkPartitionedDataSetCollection instead.
This was recently done and the inheritance now looks like this:

Now AMR data is “just” a vtkPartitionedDataSetCollection, which is a vtkDataObjectTree.This should limit the need for custom filters implementations, as one can just iterate on grids and process them one after another.

a vtkPartitionedDataSetCollection does handle hierarchy which lets us rely on this generic logic to store the AMR structure.

This has led to many simplifications in VTK and ParaView code.

Generalization

A second issue with the previous design is the fact that the AMR data model in VTK supports only perfectly regular grids, called either vtkUniformGrid or vtkImageData in VTK.

Indeed, the VTK data model supports many different types of regular grids, and vtkImageData is clearly the most common use case for AMR data. However, it would make as much sense to support vtkRectilinearGrid as well,a regular grid with varying x, y and z intervals.

However, in order to be able to support different types of grids, first, there should be a common API between these grids. This is why a new intermediate class is now available, vtkCartesianGrid. The inheritance graph looks like this:

This lets us replace all the API that were specific to vtkUniformGrid and use vtkCartesianGrid instead in the AMR data model. vtkCartesianGrid is a novel intermediate class from which both vtkImageData and vtkRectilinearGrid inherits. You can now create AMR data composed of rectilinear grids, or even your own implementation of a vtkCartesianGrid.

What about VTK users

If you used AMR data in VTK, these changes may have an impact on your VTK dependent software and scripts.

Indeed, in these developments we took great care to communicate with the community as a whole and to ensure good deprecation of any of the features and methods that should disappear at some point. That being said, you want to read carefully the compilation warnings to make sure everything you do with AMR will keep working.

VTK 9.6.0 will contain these deprecations and the methods will be removed in VTK 9.8.0 or 10.0.0.

What about ParaView users

If you used AMR data in ParaView before, well, nothing should change at all, your statefiles and data should work as well as before.

Future Work

While these changes are complete per se, there is always more work to be done, especially:
– Improve support for all types of AMR on many filters
– Complete deprecation of vtkUnformGridAMR, which is now an empty shell
– Complete deprecation of vtkUnformGrid, which is now an empty shell
– Add support for vtkRectilinearGrid in the VTKHDF format

If any of these items interest you, please reach out to Kitware, we would love to help!

Conclusion

The AMR data model in VTK is now more versatile and powerful, as well as compatible with many filters on ParaView, making it the right choice to represent multi resolution data in VTK and ParaView.
These changes are available in VTK 9.6.0 and ParaView 6.1.0.

Acknowledgment

This work was funded by CEA, DAM, DIF, F-91297 Arpajon, France