Introduction to yt

Herein, we present a brief introduction to yt’s capabilities and infrastructure with numerous links to relevant portions of the documentation on each topic. It is our hope that readers will not only gain insight to what can be done with yt, but also they will learn how to think in yt to solve science questions, learn some of the yt jargon, and figure out where to go in the docs for help.

Fields

yt is an analysis toolkit operating on multidimensional datasets for a variety of data formats. It represents quantities varying over a multidimensional space as fields such as gas density, gas temperature, etc. Many fields are defined when yt loads the external dataset into “native fields” as defined by individual frontends for each code format. However, yt additionally creates many “derived fields” by manipulating and combining native fields. yt comes with a large existing set of derived fields, but you can also create your own.

Objects

Central to yt’s infrastructure are data objects, which act as a means of filtering data based on spatial location (e.g. lines, spheres, boxes, cylinders), based on field values (e.g. all gas > 10^6 K), or for constructing new data products (e.g. projections, slices, isosurfaces). Furthermore, yt can calculate the bulk quantities associated with these data objects (e.g. total mass, bulk velocity, angular momentum).

General Analysis

The documentation section on analyzing data has a full description of fields, data objects, and filters. It also includes an explanation of how the units system works to tag every individual field and quantity with a physical unit (e.g. cm, AU, kpc, Mpc, etc.), and it describes ways of analyzing multiple chronological data outputs from the same underlying dataset known as time series. Lastly, it includes information on how to enable yt to operate in parallel over multiple processors simultaneously.

Datasets can be analyzed by simply examining raw source data, or they can be processed in a number of ways to extract relevant information and to explore the data including visualizing data.

Visualization

yt provides many tools for visualizing data, and herein we highlight a few of them. yt can create slice plots, wherein a three-dimensional volume (or any of the data objects) is sliced by a plane to return the two-dimensional field data intersected by that plane. Similarly, yt can generate line queries (i.e. rays) of a single line intersecting a three-dimensional dataset. Projection plots are generated by projecting a three-dimensional volume into two dimensions either by summing or integrating the field along each pixel’s line of sight with or without a weighting field. Slices, projections, and rays can be made to align with the primary axes of the simulation (e.g. x,y,z) or at any arbitrary angle throughout the volume. For these operations, a number of “callbacks” exist that will annotate your figures with field contours, velocity vectors, particle and halo positions, streamlines, simple shapes, and text.

yt can examine correlations between two or three fields simultaneously with profile plots and phase plots. By querying field data for two separate fields at each position in your dataset or data object, yt can show the relationship between those two fields in a profile plot (e.g. average gas density as a function radius). Similarly, a phase plot correlates two fields as described above, but it weights those fields by a third field. Phase plots commonly use mass as the weighting field and are oftentimes used to relate gas density and temperature.

More advanced visualization functionality in yt includes generating streamlines to track the velocity flow in your datasets, creating photorealistic isocontour images of your data called volume renderings, and visualizing isosurfaces in an external interactive tool. yt even has a special web-based tool for exploring your data with a google-maps-like interface.

Executing and Scripting yt

yt is written almost entirely in python and it functions as a library that you can import into your python scripts. There is full docstring documentation for all of the major classes and functions in the API docs. yt has support for running in IPython and for running IPython notebooks for fully interactive sessions both locally and on remote supercomputers. yt also has a number of ways it can be executed at the command line for simple tasks like automatically loading a dataset, updating the yt sourcecode, starting an IPython notebook, or uploading scripts and images to public locations. There is an optional yt configuration file you can modify for controlling local settings like color, logging, output settings. There is also an optional yt plugin file you can create to automatically load certain datasets, custom derived fields, derived quantities, and more.

Cookbook and Quickstart

yt contains a number of example recipes for demonstrating simple and complex tasks in the cookbook including many of the topics discussed above. The cookbook also contains more lengthy notebooks to demonstrate more sophisticated machinery on a variety of topics. If you’re new to yt and you just want to see a broad demonstration of some of the things yt can do, check out the yt quickstart.

Developing in yt

yt is an open source development project, with only scientist-developers like you to support it, add code, add documentation, etc. As such, we welcome members of the public to join our community by contributing code, bug reports, documentation, and helping to support the code in a number of ways. Sooner or later, you’ll want to add your own derived field, data object, code frontend or make yt compatible with an external code. We have detailed instructions on how to contribute code documentation, and tests, and how to debug this code.

Getting Help

We have all been there, where something is going wrong and we cannot understand why. Check out our frequently asked questions and the documentation section What to do if you run into problems to get solutions for your problems.

Getting Started

We have detailed installation instructions and support for a number of platforms including Unix, Linux, MacOS, and Windows. If you are new to yt, check out the yt Quickstart and the cookbook for a demonstration of yt’s capabilities. If you previously used yt version 2, check out our guide on how to make your scripts work in yt 3. So what are you waiting for? Good luck and welcome to the yt community.