17.geometry_and_indexing.md

Indexing and Geometry

yt is designed for analysis and visualization of datasets that describe "natural" or "physical" phenomena; more generally, yt is designed to analyze data that can be characterized by a metric of some type. The most common use case, by far, is that of data that is described in a Cartesian space, by the orthogonal axes of x, y and z. However, for reasons related to naturalness of coordinate systems and relevance to physical phenomena, datasets are also frequently organized in other coordinate systems, such as cylindrical polar ($r$, $z$ and $\theta$), spherical ($r$, $\theta$ and $\phi$) and variants such as geographic (latitude, longitude and altitude).

Importantly, however, yt distinguishes between the coordinate space a dataset describes and the natural or index space by which its organization is described. This distinction is the most relevant among datasets and data formats where the organization is implicit, rather than explicit; for instance, in a grid patch dataset, data variable locations are often only specified implicitly. For a grid volume that covers a given region, the relationship between the "index" value of a cell (for instance, $i,j,k$) and its position in space (for instance, $x, y, z$ or $r, \theta, \phi$) requires transformation between a logically-Cartesian decomposition of the space and the potentially-non Cartesian space that it represents.

In Figure @fig:coordinate_space we demonstrate one possible mapping. We note that the specific data layout is not optimized for IO throughput, and is unlikely to be exactly replicated in real world formats. In this case, the data points may be laid out sequentially on disk (or in memory) and a mapping function translates these into position and extent in the coordinate system, here cylindrical coordinates. For instance, there may be a cell that spans $r$ from 0.375 to 0.5 and $\theta$ from 45.0 to 52.5, which is defined by the array values defined in cell 1, 4.

{#fig:coordinate_space}

<script> document.addEventListener("SVGLoaded", function(event) { d3.selectAll("svg#index_coord_figure .cell").classed("active"); d3.selectAll("svg#index_coord_figure .cell") .on("mouseover", (event) => { dataset = event.target.dataset; d3.select("#coordinate_info_r").text(dataset["r-0"] + " to " + dataset["r-1"]); d3.select("#coordinate_info_theta").text(dataset["theta-0"] + " to " + dataset["theta-1"]); d3.select("#coordinate_info_ij").text(dataset["cellI"] + ", " + dataset["cellJ"]); d3.selectAll("svg#index_coord_figure .cell").classed("highlighted", (d, i, n) => (n[i].dataset["cell"] == dataset["cell"])); }); }); </script>

Abstraction of Coordinate Systems {#sec:abstraction-coordinates}

yt provides a system for defining relationships between index-space and coordinate-space. During instantiation of a Dataset object, a helper object (coordinates, a subclass of CoordinateHandler) is created. This helper object tracks the correspondence between numerical axes and spatial axes (for instance, even in some Cartesian datasets, axis 0 corresponds to $z$ rather than $x$), the names of axes, and the transformation and pixelization methods for visualization. In addition to these helper functions, the coordinate handler provides definitions for derived fields that describe local cell width (and orthogonal path length), positions in coordinate space as computed by index space coordinates, volumes, and surface areas. These coordinate handlers also provide transformations between different spaces, albeit using the somewhat undesirable method of conversion to reference cartesian frames and subsequent conversion to local coordinate frames.

At present, coordinate spaces are defined in the spaces enumerated in Table @tbl:coord-systems. While these are representative of the most common spatial representations, additional representations (such as those that include a non-trivial mapping between coordinates and index values) are possible to implement.

Coordinate system	Axes
Cartesian coordinates	$x, y, z$
Cylindrical polar coordinates	$r, \theta \in [0, 2 \pi], z$
Spherical coordinates	$r, \theta, \phi$
Geographic coordinates	latitude $\in [0, 180]$, longitude $\in [0, 360]$, altitude
Internal geographic coordinates	latitude, longitude, depth
Spectral cube	Image $x$, Image $y$ and $\nu$

Table: Extant coordinate systems; in all cases, value ranges should be taken to describe extent rather than specific boundary points. {#tbl:coord-systems}

Future developments may involve code generation for arbitrary coordinate systems, using SymPy or other libraries. Independent of the visualization methods (which can often be reused), the development of coordinate systems is largely rote, applying straightforward mathematics to construct derived field definitions. As such, using mechanisms in SymPy for construction of relationships between coordinate systems may be a feasible method of developing code-generation for coordinate system handlers in yt.