.. _derived-quantities:

Derived Quantities
==================

Derived quantities are a way of operating on a collection of cells and
returning a set of values that is fewer in number than the number of cells --
for instance yt already knows about several.

Using Derived Quantities
------------------------

Every 3D data object (see :ref:`using-objects` and :ref:`philo-objects`)
provides a mechanism for access to derived quantities.  These can be accessed
via the ``quantities`` interface, like so:

.. code-block:: python

   pf = load("my_data")
   dd = pf.h.all_data()
   dd.quantities["AngularMomentumVector"]()

The following quantities are available via the ``quantities`` interface.

.. include:: _dq_docstrings.inc

Creating Derived Quantities
---------------------------

The basic idea is that you need to be able to operate both on a set of data,
and a set of sets of data.  (If this is not possible, the quantity needs to be
added with the ``force_unlazy`` option.)

Two functions are necessary.  One will operate on arrays of data, either fed
from each grid individually or fed from the entire data object at once.  The
second one takes the results of the first, either as lists of arrays or as
single arrays, and returns the final values.  For an example, we look at the
``TotalMass`` function:

.. code-block:: python

   def _TotalMass(data):
       baryon_mass = data["CellMassMsun"].sum()
       particle_mass = data["ParticleMassMsun"].sum()
       return baryon_mass, particle_mass
   def _combTotalMass(data, baryon_mass, particle_mass):
       return baryon_mass.sum() + particle_mass.sum()
   add_quantity("TotalMass", function=_TotalMass,
                combine_function=_combTotalMass, n_ret = 2)

Once the two functions have been defined, we then call :func:`add_quantity` to
tell it the function that defines the data, the collator function, and the
number of values that get passed between them.  In this case we return both the
particle and the baryon mass, so we have two total values passed from the main
function into the collator.
