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. .. contents:: :depth: 2 :local: :backlinks: none Fields ^^^^^^ yt is an analysis toolkit operating on multidimensional datasets for :ref:`a variety of data formats <code-support>`. It represents quantities varying over a multidimensional space as :ref:`fields <fields>` such as gas density, gas temperature, etc. Many fields are defined when yt :ref:`loads the external dataset <examining-data>` 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 :ref:`set of derived fields <field-list>`, but you can also :ref:`create your own <creating-derived-fields>`. Objects ^^^^^^^ Central to yt's infrastructure are :ref:`data objects <data-objects>`, which act as a means of :ref:`filtering data <filtering-data>` based on :ref:`spatial location <geometric-objects>` (e.g. lines, spheres, boxes, cylinders), based on :ref:`field values <collection-objects>` (e.g. all gas > 10^6 K), or for :ref:`constructing new data products <construction-objects>` (e.g. projections, slices, isosurfaces). Furthermore, yt can calculate the :ref:`bulk quantities <derived-quantities>` associated with these data objects (e.g. total mass, bulk velocity, angular momentum). General Analysis ^^^^^^^^^^^^^^^^ The documentation section on :ref:`analyzing data <analyzing>` has a full description of :ref:`fields <fields>`, :ref:`data objects <data-objects>`, and :ref:`filters <filtering-data>`. It also includes an explanation of how the :ref:`units system <units>` 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 :ref:`time series <time-series-analysis>`. Lastly, it includes information on how to enable yt to operate :ref:`in parallel over multiple processors simultaneously <parallel-computation>`. Datasets can be analyzed by simply :ref:`examining raw source data <low-level-data-inspection>`, or they can be processed in a number of ways to extract relevant information and to explore the data including :ref:`visualizing data <visualizing>`. Visualization ^^^^^^^^^^^^^ yt provides many tools for :ref:`visualizing data <visualizing>`, and herein we highlight a few of them. yt can create :ref:`slice plots <slice-plots>`, wherein a three-dimensional volume (or any of the :ref:`data objects <data-objects>`) is *sliced* by a plane to return the two-dimensional field data intersected by that plane. Similarly, yt can generate :ref:`line queries (i.e. rays) <generating-line-queries>` of a single line intersecting a three-dimensional dataset. :ref:`Projection plots <projection-plots>` are generated by projecting a three-dimensional volume into two dimensions either :ref:`by summing or integrating <projection-types>` 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 :ref:`"callbacks" <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 :ref:`profile plots <how-to-make-1d-profiles>` and :ref:`phase plots <how-to-make-2d-profiles>`. By querying field data for two separate fields at each position in your dataset or :ref:`data object <data-objects>`, yt can show the relationship between those two fields in a :ref:`profile plot <how-to-make-1d-profiles>` (e.g. average gas density as a function radius). Similarly, a :ref:`phase plot <how-to-make-2d-profiles>` 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 :ref:`streamlines <streamlines>` to track the velocity flow in your datasets, creating photorealistic isocontour images of your data called :ref:`volume renderings <volume_rendering>`, and :ref:`visualizing isosurfaces in an external interactive tool <surfaces>`. yt even has a special web-based tool for exploring your data with a :ref:`google-maps-like interface <mapserver>`. 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 :ref:`API docs <api-reference>`. 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 :ref:`executed at the command line <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 :ref:`yt configuration file <configuration-file>` you can modify for controlling local settings like color, logging, output settings. There is also an optional :ref:`yt plugin file <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 :ref:`the cookbook <cookbook>` including many of the topics discussed above. The cookbook also contains :ref:`more lengthy notebooks <example-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 :ref:`yt quickstart <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 :ref:`our community <who-is-yt>` by contributing code, bug reports, documentation, and helping to :ref:`support the code in a number of ways <getting-involved>`. Sooner or later, you'll want to :ref:`add your own derived field <creating-derived-fields>`, :ref:`data object <creating-objects>`, :ref:`code frontend <creating_frontend>` or :ref:`make yt compatible with an external code <external-analysis-tools>`. We have detailed instructions on how to :ref:`contribute code <contributing-code>` :ref:`documentation <documentation>`, and :ref:`tests <testing>`, and how to :ref:`debug this code <debug-drive>`. Getting Help ^^^^^^^^^^^^ We have all been there, where something is going wrong and we cannot understand why. Check out our :ref:`frequently asked questions <faq>` and the documentation section :ref:`asking-for-help` to get solutions for your problems. Getting Started ^^^^^^^^^^^^^^^ We have detailed :ref:`installation instructions <installing-yt>` and support for a number of platforms including Unix, Linux, MacOS, and Windows. If you are new to yt, check out the :ref:`yt Quickstart <quickstart>` and the :ref:`cookbook <cookbook>` for a demonstration of yt's capabilities. If you previously used yt version 2, check out our guide on :ref:`how to make your scripts work in yt 3 <yt3differences>`. So what are you waiting for? Good luck and welcome to the yt community.
