% -*- latex -*-

\chapter{Data Sets}
\label{chap:DataSets}
\label{chap:DataSet}

\index{data set|(}

A \keyterm{data set}, implemented with the \vtkmcont{DataSet} class,
contains and manages the geometric data structures that \VTKm operates on.
A data set comprises the following 3 data structures.

\begin{description}
\item[Cell Set] \index{cell set}
  A cell set describes topological connections.
  A cell set defines some number of points in space and how they connect to form cells, filled regions of space.
  A data set has exactly one cell set.
\item[Field] \index{field}
  A field describes numerical data associated with the topological elements in a cell set.
  The field is represented as an array, and each entry in the field array corresponds to a topological element (point, edge, face, or cell).
  Together the cell set topology and discrete data values in the field provide an interpolated function throughout the volume of space covered by the data set.
  A cell set can have any number of fields.
\item[Coordinate System] \index{coordinate system}
  A coordinate system is a special field that describes the physical location of the points in a data set.
  Although it is most common for a data set to contain a single coordinate system, \VTKm supports data sets with no coordinate system such as abstract data structures like graphs that might not have positions in a space.
  \textidentifier{DataSet} also supports multiple coordinate systems for data that have multiple representations for position.
  For example, geospatial data could simultaneously have coordinate systems defined by 3D position, latitude-longitude, and any number of 2D projections.
\end{description}

In addition to the base \vtkmcont{DataSet}, \VTKm provides \vtkmcont{PartitionedDataSet} to represent data partitioned into multiple domains.
A \textidentifier{PartitionedDataSet} is implemented as a collection of \textidentifier{DataSet} objects.
Partitioned data sets are described later in Section~\ref{sec:DataSets:PartitionedDataSet}.

\section{Building Data Sets}
\label{sec:DataSets:Building}

\index{data set!building|(}

Before we go into detail on the cell sets, fields, and coordinate systems
that make up a data set in \VTKm, let us first discuss how to build a data
set. One simple way to build a data set is to load data from a file using
the \vtkmio{} module. Reading files is discussed in detail in
Chapter~\ref{chap:FileIO}.

This section describes building data sets of different types using a set of
classes named \textidentifier{DataSetBuilder*}, which provide a convenience layer
on top of \vtkmcont{DataSet} to make it easier to create data sets.

\begin{didyouknow}
  To simplify the introduction of \textidentifier{DataSet}s, this section uses the simplest mechanisms.
  In many cases this involves loading data in a \textcode{std::vector} and passing that to \VTKm, which usually causes the data to be copied.
  This is not the most efficient method to load data into \VTKm.
  Although it is sufficient for small data or data that come from a ``slow'' source, such as a file, it might be a bottleneck for large data generated by another library.
  It is possible to adapt \VTKm's \textidentifier{DataSet} to externally defined data.
  This is done by wrapping existing data into what is called \textidentifier{ArrayHandle}, but this is a more advanced topic that will not be addressed in this chapter.
  \textidentifier{ArrayHandle}s are introduced in Chapter \ref{chap:BasicArrayHandles} and more adaptive techniques are described in later chapters.
\end{didyouknow}

\subsection{Creating Uniform Grids}

\index{uniform grid}
\index{regular grid}
\index{image}

Uniform grids are meshes that have a regular array structure with points
uniformly spaced parallel to the axes. Uniform grids are also sometimes
called regular grids or images.

The \vtkmcont{DataSetBuilderUniform} class can be used to easily create 2-
or 3-dimensional uniform grids. \textidentifier{DataSetBuilderUniform} has
several versions of a method named \classmember*{DataSetBuilderUniform}{Create} that takes the number
of points in each dimension, the origin, and the spacing. The origin is the
location of the first point of the data (in the lower left corner), and the
spacing is the distance between points in the x, y, and z directions. The
\classmember*{DataSetBuilderUniform}{Create} methods also take an optional name for the coordinate
system and an optional name for the cell set.

The following example creates a \vtkmcont{DataSet} containing a uniform
grid of $101 \times 101 \times 26$ points.

\vtkmlisting{Creating a uniform grid.}{CreateUniformGrid.cxx}

If not specified, the origin will be at the coordinates $(0,0,0)$ and the
spacing will be $1$ in each direction. Thus, in the previous example the
width, height, and depth of the mesh in physical space will be $100$,
$100$, and $25$, respectively, and the mesh will be centered at $(50, 50,
12.5)$. Let us say we actually want a mesh of the same dimensions, but we
want the $z$ direction to be stretched out so that the mesh will be the
same size in each direction, and we want the mesh centered at the origin.

\vtkmlisting{Creating a uniform grid with custom origin and spacing.}{CreateUniformGridCustomOriginSpacing.cxx}

\subsection{Creating Rectilinear Grids}

\index{rectilinear grid}

A rectilinear grid is similar to a uniform grid except that a rectilinear
grid can adjust the spacing between adjacent grid points. This allows the
rectilinear grid to have tighter sampling in some areas of space, but the
points are still constrained to be aligned with the axes and each other. The
irregular spacing of a rectilinear grid is specified by providing a
separate array each for the x, y, and z coordinates.

The \vtkmcont{DataSetBuilderRectilinear} class can be used to easily create
2- or 3-dimensional rectilinear grids.
\textidentifier{DataSetBuilderRectilinear} has several versions of a method
named \classmember*{DataSetBuilderRectilinear}{Create} that takes these coordinate arrays and builds a
\vtkmcont{DataSet} out of them. The arrays can be supplied as either
standard C arrays or as \textcode{std::vector} objects, in which case the
data in the arrays are copied into the \textidentifier{DataSet}. These
arrays can also be passed as \textidentifier{ArrayHandle} objects (introduced later in this book), in which
case the data are shallow copied.

The following example creates a \vtkmcont{DataSet} containing a rectilinear
grid with $201 \times 201 \times 101$ points with different irregular
spacing along each axis.

\vtkmlisting{Creating a rectilinear grid.}{CreateRectilinearGrid.cxx}

\subsection{Creating Explicit Meshes}

\index{explicit mesh}
\index{unstructured grid}

An explicit mesh is an arbitrary collection of cells with arbitrary connections.
It can have multiple different types of cells.
Explicit meshes are also known as unstructured grids.
Explicit meshes can contain cells of different shapes.
The shapes that \VTKm currently supports are listed in Figure \ref{fig:CreateExplicitMeshesCellShapes}.

\begin{figure}[htb]
  \centering
  \input{CellShapeFigure}
  \caption{Basic Cell Shapes}
  \label{fig:CreateExplicitMeshesCellShapes}
\end{figure}

\begin{figure}[htb]
  \centering
  \includegraphics{images/ExplicitCellConnections}
  \caption{An example explicit mesh.}
  \label{fig:ExplicitMesh}
\end{figure}

The cells of an explicit mesh are defined with the following 3 arrays, which are depicted graphically in Figure \ref{fig:ExplicitMesh}.
\begin{description}
\item[Shapes] \index{explicit mesh!shapes}
  An array of ids identifying the shape of the cell.
  Each value is a \vtkm{UInt8} and should be set to one of the \vtkm{}\textcode{::}\textidentifier{CELL\_SHAPE\_*} constants.
  The shapes and their identifiers are shown in Figure \ref{fig:CreateExplicitMeshesCellShapes}.
  The size of this array is equal to the number of cells in the set.
\item[Connectivity] \index{explicit mesh!connectivity}
  An array that lists all the points that comprise each cell.
  Each entry in the array is a \vtkm{Id} giving the point id associated with a vertex of a cell.
  The points for each cell are given in a prescribed order for each shape, which is also shown in Figure \ref{fig:CreateExplicitMeshesCellShapes}.
  The point indices are stored consecutively from the first cell to the last.
\item[Offsets] \index{explicit mesh!offsets}
  An array of \vtkm{Id}s pointing to the index in the connectivity array where the points for a particular cell starts.
  The size of this array is equal to the number of cells in the set plus 1.
  The first entry is expected to be 0 (since the connectivity of the first cell is at the start of the connectivity array).
  The last entry, which does not correspond to any cell, should be the size of the connectivity array.
\end{description}

One important item that is missing from this list of arrays is a count of the number of indices associated with each cell.
This is not explicitly represented in \VTKm's mesh structure because it can be implicitly derived from the offsets array by subtracting consecutive entries.
However, it is usually the case when building an explicit mesh that you will have an array of these counts rather than the offsets.
It is for this reason that \VTKm contains mechanisms to build an explicit data set with a ``num indices'' arrays rather than an offsets array.

The \vtkmcont{DataSetBuilderExplicit} class can be used to create data sets with explicit meshes.
\textidentifier{DataSetBuilderExplicit} has several versions of a method named \classmember*{DataSetBuilderExplicit}{Create}.
Generally, these methods take the shapes, number of indices, and connectivity arrays as well as an array of point coordinates.
These arrays can be given in \textcode{std::vector} objects, and the data are copied into the \textidentifier{DataSet} created.

The following example creates a mesh like the one shown in
Figure~\ref{fig:ExplicitMesh}.

\vtkmlisting{Creating an explicit mesh with \textidentifier{DataSetBuilderExplicit}.}{CreateExplicitGrid.cxx}

Often it is awkward to build your own arrays and then pass them to
\textidentifier{DataSetBuilderExplicit}. There also exists an alternate
builder class named \vtkmcont{DataSetBuilderExplicitIterative} that allows
you to specify each cell and point one at a time rather than all at once.
This is done by calling one of the versions of \classmember*{DataSetBuilderExplicitIterative}{AddPoint} and one
of the versions of \classmember*{DataSetBuilderExplicitIterative}{AddCell} for each point and cell,
respectively. The next example also builds the mesh shown in
Figure~\ref{fig:ExplicitMesh} except this time using
\textidentifier{DataSetBuilderExplicitIterative}.

\vtkmlisting{Creating an explicit mesh with \textidentifier{DataSetBuilderExplicitIterative}.}{CreateExplicitGridIterative.cxx}

\subsection{Add Fields}

In addition to creating the geometric structure of a data set, it is
usually important to add fields to the data. Fields describe numerical data
associated with the topological elements in a cell. They often represent a
physical quantity (such as temperature, mass, or volume fraction) but can
also represent other information (such as indices or classifications).

The easiest way to define fields in a data set is to use the \classmember{DataSet}{AddPointField} and \classmember{DataSet}{AddCellField} methods.
Each of these methods take a requisite field name and the array with with field data.

Both \classmember*{DataSet}{AddPointField} and \classmember*{DataSet}{AddCellField} are overloaded to
accept arrays of data in different structures. Field arrays can be passed
as standard C arrays or as \textcode{std::vector}s, in which case the data
are copied. Field arrays can also be passed in a
\textidentifier{ArrayHandle} (introduced later in this book), in which case the data are not copied.

The following (somewhat contrived) example defines fields for a uniform
grid that identify which points and cells are on the boundary of the mesh.

\vtkmlisting{Adding fields to a \textidentifier{DataSet}.}{AddFieldData.cxx}

\index{data set!building|)}

\section{Cell Sets}
\label{sec:DataSets:CellSets}

\index{cell set|(}
\index{data set!cell set|see{cell set}}

A cell set determines the topological structure of the data in a data set.
Fundamentally, any cell set is a collection of cells, which typically (but
not always) represent some region in space. 3D cells are made up of
\index{point}\index{shape!point}\index{cell!point}points,
\index{edge}\index{shape!edge}\index{cell!edge}edges, and
\index{face}\index{shape!face}\index{cell!face}faces. (2D cells have only points and edges,
and 1D cells have only points.) Figure~\ref{fig:CellTopology} shows the
relationship between a cell's shape and these topological elements. The
arrangement of these points, edges, and faces is defined by the
\index{shape}\index{cell set!shape}\index{cell shape}\keyterm{shape} of the
cell, which prescribes a specific ordering of each. The basic cell shapes
provided by \VTKm are discussed in detail in
Section~\ref{sec:CellShapeTagsIds} starting on
page~\pageref{sec:CellShapeTagsIds}.

\begin{figure}[htb]
  \centering
  \includegraphics{images/CellConstituents}
  \caption{The relationship between a cell shape and its topological
    elements (points, edges, and faces).}
  \label{fig:CellTopology}
\end{figure}

There are multiple ways to express the connections of a cell set, each with
different benefits and restrictions. These different cell set types are
managed by different cell set classes in \VTKm. All \VTKm cell set classes
inherit from \vtkmcont{CellSet}. The two basic types of cell sets are
structured and explicit, and there are several variations of these types.

\subsection{Structured Cell Sets}

\index{cell set!structured|(}
\index{structured cell set|(}

A \vtkmcont{CellSetStructured} defines a 1-, 2-, or 3-dimensional grid of
points with lines, quadrilaterals, or hexahedra, respectively, connecting
them. The topology of a \textidentifier{CellSetStructured} is specified by
simply providing the dimensions, which is the number of points in the $i$,
$j$, and $k$ directions of the grid of points. The number of points is
implicitly $i \times j \times k$ and the number of cells is implicitly
$(i-1) \times (j-1) \times (k-1)$ (for 3D grids).
Figure~\ref{fig:CellSetStructured} demonstrates this arrangement.

\begin{figure}[htb]
  \centering
  \includegraphics{images/StructuredCellSet}
  \caption{The arrangement of points and cells in a 3D structured grid.}
  \label{fig:CellSetStructured}
\end{figure}

The big advantage of using \vtkmcont{CellSetStructured} to define a cell
set is that it is very space efficient because the entire topology can be
defined by the three integers specifying the dimensions. Also algorithms
can be optimized for \textidentifier{CellSetStructured}'s regular nature.
However, \textidentifier{CellSetStructured}'s strictly regular grid
structure also limits its applicability. A structured cell set can only be
a dense grid of lines, quadrilaterals, or hexahedra. It cannot represent
irregular data well.

Many data models in other software packages, such as the one for VTK, make
a distinction between uniform, rectilinear, and curvilinear grids. \VTKm's
cell sets do not. All three of these grid types are represented by
\textidentifier{CellSetStructured}. This is because in a \VTKm data set the
cell set and the coordinate system are defined independently and used
interchangeably. A structured cell set with uniform point coordinates makes
a uniform grid. A structured cell set with point coordinates defined
irregularly along coordinate axes makes a rectilinear grid. And a
structured cell set with arbitrary point coordinates makes a curvilinear
grid. The point coordinates are defined by the data set's coordinate system,
which is discussed in Section~\ref{sec:DataSets:CoordinateSystems} starting
on page~\pageref{sec:DataSets:CoordinateSystems}.

\index{structured cell set|)}
\index{cell set!structured|)}

\subsection{Explicit Cell Sets}
\label{sec:ExplicitCellSets}

\index{explicit cell set|(}
\index{cell set!explicit|(}

A \vtkmcont{CellSetExplicit} defines an irregular collection of cells.
The cells can be of different types and connected in arbitrary ways.
The types of cell sets are listed in Figure \ref{fig:ExplicitCellSetShapes}.
This is done by explicitly providing for each cell a sequence of points that defines the cell.

\begin{figure}[htb]
  \centering
  \input{CellShapeFigure}
  \caption{Basic Cell Shapes in a \textidentifier{CellSetExplicit}.}
  \label{fig:ExplicitCellSetShapes}
\end{figure}

An explicit cell set is defined with a minimum of three arrays.
The first array identifies the shape of each cell.
(Identifiers for cell shapes are shown in Figure \ref{fig:ExplicitCellSetShapes}.)
The second array has a sequence of point indices that make up each cell.
The third array identifies an offset into the second array where the point indices for each cell is found plus an extra entry at the end set to the size of the second array.
Figure~\ref{fig:CellSetExplicit} shows a simple example of an explicit cell set.

\begin{figure}[htb]
  \centering
  \includegraphics{images/ExplicitCellConnections}
  \caption{Example of cells in a \textidentifier{CellSetExplicit} and the
    arrays that define them.}
  \label{fig:CellSetExplicit}
\end{figure}

An explicit cell set can also identify the number of indices defined for each cell by subtracting consecutive entries in the offsets array.
It is often the case when creating a \textidentifier{CellSetExplicit} that you have an array containing the number of indices rather than the offsets.
Such an array can be converted to an offsets array that can be used with \textidentifier{CellSetExplicit} by using the \vtkmcont{ConvertNumComponentsToOffsets} convenience function.

\vtkmcont{CellSetExplicit} is a powerful representation for a cell set
because it can represent an arbitrary collection of cells. However, because
all connections must be explicitly defined,
\textidentifier{CellSetExplicit} requires a significant amount of memory to
represent the topology.

\index{cell set!single type|(}
\index{explicit cell set!single type|(}
\index{single type cell set|(}

An important specialization of an explicit cell set is
\vtkmcont{CellSetSingleType}. \textidentifier{CellSetSingleType} is an
explicit cell set constrained to contain cells that all have the same shape
and all have the same number of points. So for example if you are creating
a surface that you know will contain only triangles,
\textidentifier{CellSetSingleType} is a good representation for these data.

Using \textidentifier{CellSetSingleType} saves memory because the array of
cell shapes and the array of point counts no longer need to be stored.
\textidentifier{CellSetSingleType} also allows \VTKm to skip some
processing and other storage required for general explicit cell sets.

\index{single type cell set|)}
\index{explicit cell set!single type|)}
\index{cell set!single type|)}

\index{cell set!explicit|)}
\index{explicit cell set|)}

\subsection{Cell Set Permutations}

\index{permutation cell set|(}
\index{cell set!permutation|(}

A \vtkmcont{CellSetPermutation} rearranges the cells of one cell set to
create another cell set. This restructuring of cells is not done by copying
data to a new structure. Rather, \textidentifier{CellSetPermutation}
establishes a look-up from one cell structure to another. Cells are permuted
on the fly while algorithms are run.

A \textidentifier{CellSetPermutation} is established by providing a mapping
array that for every cell index provides the equivalent cell index in the
cell set being permuted. \textidentifier{CellSetPermutation} is most often
used to mask out cells in a data set so that algorithms will skip over
those cells when running.

\begin{didyouknow}
  Although \textidentifier{CellSetPermutation} can mask cells, it cannot
  mask points. All points from the original cell set are available in the
  permuted cell set regardless of whether they are used.
\end{didyouknow}

The following example uses \vtkmcont{CellSetPermutation} with a counting
array to expose every tenth cell. This provides a simple way to subsample a
data set.

\vtkmlisting{Subsampling a data set with \textidentifier{CellSetPermutation}.}{CreateCellSetPermutation.cxx}

\index{cell set!permutation|)}
\index{permutation cell set|)}

\subsection{Cell Set Extrude}
A \vtkmcont{CellSetExtrude} defines a 3-dimensional extruded mesh representation 
from 2-dimensional coordinates in the XZ-plane. This is done by providing 2-dimensional coordinates,
 the number of planes to extrude along the Y-axis, and whether the resulting wedge cellset
 representation should be a torus or a cylinder.
 
 \begin{figure}[htb]
  \centering
  \includegraphics[width=\textwidth,keepaspectratio]{images/ExtrudedCellSet}
  \caption{An example of an extruded wedge from XZ-plane coordinates. Six wedges are 
          extracted from three XZ-plane points.}
  \label{fig:CellSetExtruded}
\end{figure}

The extruded mesh is advantageous because it is represented on-the-fly as required, so no additional 
memory is required. In contrast other forms of cell sets, 
such as \vtkmcont{CellSetExplicit}, need to be explicitly constructed
by replicating the vertices and cells.  Figure~\ref{fig:CellSetExtruded} shows an
example of six wedges extruded from three 2-dimensional coordinates.

\fix{
  There is a removed section on dynamic cell sets here.
  This was at best in the wrong place.
  Assuming we move to multiplexer containers, we may be able to get by without going into any details.
}

%% \subsection{Dynamic Cell Sets}

%% \index{dynamic cell set|(}
%% \index{cell set!dynamic|(}

%% \vtkmcont{DataSet} must hold a \vtkmcont{CellSet} object, but it cannot know its specific type at compile time.
%% To manage storing \textidentifier{CellSet}s without knowing their types, \textidentifier{DataSet} actually holds a reference using \vtkmcont{DynamicCellSet}.
%% \textidentifier{DynamicCellSet} is a simple polymorphic container that stores a reference to a \vtkmcont{CellSet} of unknown type.

%% \textidentifier{DynamicCellSet} has a method named \classmember*{DynamicCellSet}{CastToBase} that
%% returns a const reference to the held cell set as the abstract
%% \textidentifier{CellSet} class. This can be used to easily access the
%% virtual methods in the \textidentifier{CellSet} interface. You can also
%% create a new instance of a cell set with the same type using the
%% \classmember{DynamicCellSet}{NewInstance} method.

%% When it comes to doing something useful with the \vtkmcont{CellSet}, the \textidentifier{DynamicCellSet} must cast the \vtkmcont{CellSet} to a known subclass.
%% The \classmember{DynamicCellSet}{IsType} method can be used to determine whether the cell set held in the dynamic cell set is of a given type.
%% If the cell set type is known, \classmember{DynamicCellSet}{Cast} can be used to safely downcast the cell set object, or \classmember{DynamicCellSet}{CopyTo} can be used to safely copy to a reference of the appropriate type.

%% When a typed version of the cell set stored in the
%% \textidentifier{DynamicCellSet} is needed but the type is not known, which
%% happens regularly in the internal workings of \VTKm, the
%% \classmember{DynamicCellSet}{CastAndCall} method can be used to make this transition.
%% \classmember*{DynamicCellSet}{CastAndCall} works by taking a functor and calls it with the
%% appropriately cast cell set object.

%% The \classmember*{DynamicCellSet}{CastAndCall} method works by attempting to cast to a known
%% set of types. This set of types used is defined by the macro
%% \vtkmmacro{VTKM\_DEFAULT\_CELL\_SET\_LIST}, which is declared in
%% \vtkmheader{vtkm/cont}{CellSetList.h}. This list can be overridden
%% globally by defining the \vtkmmacro{VTKM\_DEFAULT\_CELL\_SET\_LIST}
%% macro \emph{before} any \VTKm headers are included.

%% The set of types used in a \classmember*{DynamicCellSet}{CastAndCall} can also be changed only
%% for a particular instance of a dynamic cell set by calling its
%% \classmember*{DynamicCellSet}{ResetCellSetList}. This method takes a list of cell types and
%% returns a new variant array handle of a slightly different type that will
%% use this new list of cells for dynamic casting.

%% \index{cell set!dynamic|)}
%% \index{dynamic cell set|)}

%% \index{cell set|)}

\section{Fields}
\label{sec:DataSets:Fields}

\index{field|(}
\index{data set!field|see{field}}

A field on a data set provides a value on every point in space on the mesh.
Fields are often used to describe physical properties such as pressure,
temperature, mass, velocity, and much more. Fields are represented in a
\VTKm data set as an array where each value is associated with a particular
element type of a mesh (such as points or cells). This association of field
values to mesh elements and the structure of the cell set determines how
the field is interpolated throughout the space of the mesh.

Fields are manged by the \vtkmcont{Field} class.
The \textidentifier{Field} object internally holds a reference to an array in a type-agnostic way.
Filters and other \VTKm units will determine the type of the array and pull it out of the \textidentifier{Field}.

\index{range!field}\textidentifier{Field} has a convenience method named \classmember*{Field}{GetRange} that finds the range of values stored in the field array.
The returned value of \classmember*{Field}{GetRange} is an \textidentifier{ArrayHandle} containing \vtkm{Range} values.
The \textidentifier{ArrayHandle} will have as many values as components in the field.
So, for example, calling \classmember*{Field}{GetRange} on a scalar field will return an \textidentifier{ArrayHandle} with exactly 1 entry in it.
Calling \classmember*{Field}{GetRange} on a field of 3D vectors will return an \textidentifier{ArrayHandle} with exactly 3 entries corresponding to each of the components in the range.
Details on how to get data from an \textidentifier{ArrayHandle} them is given in Chapter \ref{chap:AccessingAllocatingArrays}.

\index{field|)}

\section{Coordinate Systems}
\label{sec:DataSets:CoordinateSystems}

\index{coordinate system|(}
\index{data set!coordinate system|see{coordinate system}}

A coordinate system determines the location of a mesh's elements in space.
The spatial location is described by providing a 3D vector at each point
that gives the coordinates there. The point coordinates can then be
interpolated throughout the mesh.

Coordinate systems are managed by the \vtkmcont{CoordinateSystem} class. In
actuality, a coordinate system is just a field with a special meaning, and
so the \textidentifier{CoordinateSystem} class inherits from the
\textidentifier{Field} class. \textidentifier{CoordinateSystem} constrains
the field to be associated with points and typically has 3D floating point
vectors for values.

In addition to all the methods provided by the \textidentifier{Field} superclass, the \textidentifier{CoordinateSystem} also provides a \classmember*{CoordinateSystem}{GetBounds} convenience method that returns a \vtkm{Bounds} object giving the spatial bounds of the coordinate system.

It is typical for a \textidentifier{DataSet} to have one coordinate system
defined, but it is possible to define multiple coordinate systems. This is
helpful when there are multiple ways to express coordinates. For example,
positions in geographic may be expressed as Cartesian coordinates or as
latitude-longitude coordinates. Both are valid and useful in different
ways.

It is also valid to have a \textidentifier{DataSet} with no coordinate
system. This is useful when the structure is not rooted in physical space.
For example, if the cell set is representing a graph structure, there might
not be any physical space that has meaning for the graph.

\index{coordinate system|)}


\section{Partitioned Data Sets}
\label{sec:DataSets:PartitionedDataSet}

\index{partitioned data set|(}
\index{data set!partitioned|see{partitioned data set}}

A partitioned data set, implemented with \vtkmcont{PartitionedDataSet}, comprises a set of \vtkmcont{DataSet} objects.
The \textidentifier{PartitionedDataSet} interface allows for adding, replacing, and querying \textidentifier{DataSet}s in its list with the following methods.

\begin{description}
\item[\classmember*{PartitionedDataSet}{GetNumberOfPartitions}]
  Returns the number of partitions stored in the \textidentifier{PartitionedDataSet}.
\item[\classmember*{PartitionedDataSet}{GetPartition}]
  Returns the \textidentifier{DataSet} at a given index.
\item[\classmember*{PartitionedDataSet}{GetPartitions}]
  Returns all of the \textidentifier{DataSet}s stored in the \textidentifier{PartitionedDataSet} in a \textcode{std::vector}.
\item[\classmember*{PartitionedDataSet}{AppendPartition}]
  Adds a given \textidentifier{DataSet} to the end of the list of partitions.
\item[\classmember*{PartitionedDataSet}{AppendPartitions}]
  Given a list of \textidentifier{DataSet} objects, appends this list to the end of the list of partitions.
  This list can be given as a \textcode{std::vector} or it can be an initializer list (declared in \textcode{\{ \}} curly braces).
\item[\classmember*{PartitionedDataSet}{InsertPartition}]
  Given an index and a \textidentifier{DataSet}, places the \textidentifier{DataSet} at the given index and pushes the remaining partitions after it.
\item[\classmember*{PartitionedDataSet}{ReplacePartition}]
  Given an index and a \textidentifier{DataSet}, replaces the partition at that index with the new \textidentifier{DataSet}.
\item[\classmember*{PartitionedDataSet}{GetField}]
  Retrieves a \vtkmcont{Field} object from the \textidentifier{DataSet} at a given index.
\end{description}

The following example creates a \vtkmcont{PartitionedDataSet} containing two uniform grid data sets.

\vtkmlisting{Creating a \textidentifier{PartitionedDataSet}.}{CreatePartitionedDataSet.cxx}

It is always possible to retrieve the independent blocks in a \textidentifier{PartitionedDataSet}, from which you can iterate and get information about the data.
However, \VTKm provides several helper functions to collect metadata information about the collection as a whole.

\begin{description}
\item[\vtkmcont{BoundsCompute}]
  Queries the bounds of all the \textidentifier{DataSet}s contained in the given \textidentifier{PartitionedDataSet} and returns a \vtkm{Bounds} object encompassing the conglomerate data.
\item[\vtkmcont{BoundsGlobalCompute}]
  An MPI version of \textidentifier{BoundsCompute} that also finds the bounds around the conglomerate data across all processes.
  All MPI processes must call this method.
\item[\vtkmcont{FieldRangeCompute}]
  Given a \textidentifier{PartitionedDataSet}, the name of a field, and (optionally) an association of the field, returns the minimum and maximum value of that field over all the contained blocks.
  The result is returned in a \textidentifier{ArrayHandle} of \vtkm{Range} objects in the same manner as the \vtkmcont{Field}[GetRange] method (see Section~\ref{sec:DataSets:Fields}).
\item[\vtkmcont{FieldRangeGlobalCompute}]
  An MPI version of \textidentifier{FieldRangeCompute} that also finds the field ranges over all blocks on all processes.
  All MPI processes must call this method.
\end{description}

The following example illustrates a spatial bounds query and a field range query on a \vtkmcont{PartitionedDataSet}.

\vtkmlisting{Queries on a \textidentifier{PartitionedDataSet}.}{QueryPartitionedDataSet.cxx}

\begin{didyouknow}
  The aforementioned functions for querying a \textidentifier{PartitionedDataSet} object also work on \textidentifier{DataSet} objects.
  This is particularly useful with the \textidentifier{BoundsGlobalCompute} and \textidentifier{FieldRangeGlobalCompute} to manage distributed parallel objects.
\end{didyouknow}

Filters can be executed on \textidentifier{PartitionedDataSet} objects in a similar way they are executed on \textidentifier{DataSet} objects.
In both cases, the \classmember*{Filter}{Execute} method is called on the filter giving data object as an argument.

\vtkmlisting{Applying a filter to multi block data.}{FilterPartitionedDataSet.cxx}

\index{partitioned data set|)}

\index{data set|)}
