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) or you can 
:ref:`define your own <creating_derived_quantities>`.

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>` and employing :ref:`topic-specific 
analysis modules <analysis-modules>`.  

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>`.

Topic-Specific Analysis Modules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Beyond visualization and general analysis tools, yt contains a number 
of :ref:`topic-specific analysis modules <analysis-modules>` for processing
datasets.  These analysis modules operate somewhat autonomous and oftentimes
use external libraries or codes.  While they are installed with yt, they are 
not loaded by default in every session so you have to call them specifically.
Examples include :ref:`halo analysis <halo-analysis>` (including 
:ref:`halo finding <halo_finding>`, :ref:`merger trees <merger_tree>`, 
:ref:`halo mass functions <halo_mass_function>`), :ref:`synthetic observations 
<synthetic-observations>` (including :ref:`cosmological light cones 
<light-cone-generator>`, :ref:`cosmological light rays <light-ray-generator>`, 
:ref:`synthetic absorption spectra <absorption_spectrum>`, :ref:`spectral 
emission distributions (SEDS) <synthetic_spectrum>`, :ref:`star formation 
rates <star_analysis>`, :ref:`synthetic x-ray obserservations 
<xray_emission_fields>`, and :ref:`synthetic sunyaev-zeldovich effect 
observations <sunyaev-zeldovich>`), :ref:`two-point correlations functions 
<two_point_functions>`, :ref:`identification of overdensities in arbitrary 
fields (clump finding) <clump_finding>`, :ref:`tracking particle trajectories 
<particle-trajectories>`, and exporting data to external radiative transfer 
codes (e.g. :ref:`Sunrise <sunrise_export>` and :ref:`RadMC-3D 
<radmc3d_export>`).

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:`derived 
quantity <creating_derived_quantities>`, :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 <getting-and-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.
