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 :ref:`running in IPython and for running
IPython notebooks <interactive-prompt>` 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.
