[Yt-svn] yt-commit r1007 - in branches/yt-1.0/doc/source: . cookbook extending modules/lagos modules/raven quick_guide tour tutorial
mturk at wrangler.dreamhost.com
mturk at wrangler.dreamhost.com
Sat Dec 13 19:29:31 PST 2008
Author: mturk
Date: Sat Dec 13 19:29:29 2008
New Revision: 1007
URL: http://yt.spacepope.org/changeset/1007
Log:
Deleted the old tutorial and parallel analysis section, added a new 'tour' of
yt. Also added contribution guide, some more helpful stuff to the index, and
so on.
Added:
branches/yt-1.0/doc/source/contribution.rst
branches/yt-1.0/doc/source/tour/
branches/yt-1.0/doc/source/tour/code_objects.rst
branches/yt-1.0/doc/source/tour/index.rst
branches/yt-1.0/doc/source/tour/physical_objects.rst
branches/yt-1.0/doc/source/tour/plots.rst
branches/yt-1.0/doc/source/tour/reduced_objects.rst
Removed:
branches/yt-1.0/doc/source/extending/analyzing_in_parallel.rst
branches/yt-1.0/doc/source/tutorial/
Modified:
branches/yt-1.0/doc/source/cookbook/making_profiles.rst
branches/yt-1.0/doc/source/extending/index.rst
branches/yt-1.0/doc/source/faq.rst
branches/yt-1.0/doc/source/getting_started.rst
branches/yt-1.0/doc/source/index.rst
branches/yt-1.0/doc/source/intro.rst
branches/yt-1.0/doc/source/modules/lagos/basedatatypes.rst
branches/yt-1.0/doc/source/modules/raven/plotcollection.rst
branches/yt-1.0/doc/source/quick_guide/index.rst
Added: branches/yt-1.0/doc/source/contribution.rst
==============================================================================
--- (empty file)
+++ branches/yt-1.0/doc/source/contribution.rst Sat Dec 13 19:29:29 2008
@@ -0,0 +1,47 @@
+Contributing Code
+=================
+
+``yt`` is designed to be a contribu
+
+Bug Fixes
+---------
+
+If you have simple bug fixes, please feel free to attach them to a ticket on
+the `bug tracker <http://yt.enzotools.org/newticket/>`_ (you might have to
+`register <http://yt.enzotools.org/register>`_ first) or to email them to one
+of the developers directly. We're always happy to hear about the things we've
+done wrong, and how you've fixed them!
+
+Licensing
+---------
+
+All contributed code must be GPL-compatible; we ask that you consider licensing
+under the GPL version 3, but we will consider submissions of code that are
+BSD-like licensed as well. If you'd rather not license in this manner, but
+still want to contribute, just drop me a line and I'll put a link on the main
+wiki page to wherever you like!
+
+Fields and Extensions
+---------------------
+
+``yt`` comes with a bunch of derived fields. However, if you have constructed
+some that add interesting analysis quantities, please feel free to send them to
+one of the developers!
+
+Additionally, if you have a sub-module that extends ``yt`` in a fun or exciting
+way, we'd be very happy to include it. Recently we've added light cone
+generators, halo profilers, and work is even ongoing on a parallel halo finder!
+
+.. _free_repo_space:
+
+Analysis Code and Examples
+--------------------------
+
+Because ``yt`` can be a bit difficult to become fully acquainted with, we
+encourage you to share your analysis scripts. Specifically, we will provide
+you with free repository space to store any analysis scripts that went into the
+writing of a paper. Through this, we hope to build up a library not only of
+usage-cases, but of real-world examples of plot generation and data analysis.
+
+If you are interested in submitting your scripts, please contact Matt Turk at
+``matthewturk at gmail.com``.
Modified: branches/yt-1.0/doc/source/cookbook/making_profiles.rst
==============================================================================
--- branches/yt-1.0/doc/source/cookbook/making_profiles.rst (original)
+++ branches/yt-1.0/doc/source/cookbook/making_profiles.rst Sat Dec 13 19:29:29 2008
@@ -1,3 +1,5 @@
+.. _making_profiles:
+
Making Profiles
===============
Modified: branches/yt-1.0/doc/source/extending/index.rst
==============================================================================
--- branches/yt-1.0/doc/source/extending/index.rst (original)
+++ branches/yt-1.0/doc/source/extending/index.rst Sat Dec 13 19:29:29 2008
@@ -12,4 +12,3 @@
creating_datatypes
creating_derived_quantities
creating_derived_fields
- analyzing_in_parallel
Modified: branches/yt-1.0/doc/source/faq.rst
==============================================================================
--- branches/yt-1.0/doc/source/faq.rst (original)
+++ branches/yt-1.0/doc/source/faq.rst Sat Dec 13 19:29:29 2008
@@ -37,7 +37,7 @@
In the book `Snow Crash <http://en.wikipedia.org/wiki/Snow_Crash>`_, yt is
Uncle Enzo's messenger. Lagos is the keeper of the data, Raven is a master
-slicer, and so on.
+slicer, and so on. It's likely that this will get changed in the future.
Are there any restrictions on my use of yt?
-------------------------------------------
@@ -50,6 +50,9 @@
Additionally, if you use yt in a paper, I'd love it if you'd drop me a line to
let me know.
+.. _units:
+.. _derived fields:
+
How do I know what the units returned are?
------------------------------------------
@@ -70,6 +73,8 @@
all of the versions of Enzo I have used or encountered, and the newest public
release is a target platform.
+.. _data_serialization:
+
What are all these .yt files?
-----------------------------
@@ -90,12 +95,16 @@
such cases, it is recommended that the parameter 'serialize' in the section
'lagos' of your configuration file is set to 'False'.
+.. _contributing:
+
How can I help?
---------------
If you find a bug, report it. If you do something cool, write it up. If you
find a place to improve the code, send in a patch.
+.. _help:
+
Something has gone wrong. What do I do?
----------------------------------------
Modified: branches/yt-1.0/doc/source/getting_started.rst
==============================================================================
--- branches/yt-1.0/doc/source/getting_started.rst (original)
+++ branches/yt-1.0/doc/source/getting_started.rst Sat Dec 13 19:29:29 2008
@@ -43,6 +43,9 @@
Binary Packages
===============
+Currently binary packages are only supplied for OSX. See the download page on
+the Wiki for up-to-date links.
+
Installing From Source
======================
@@ -61,13 +64,37 @@
any changes in the source directory will be included the next time you
import yt!
-Prerequisites for yt
---------------------
+There are several variabels you can set inside this script.
-A driving factor in the development of yt over the months leading to release
-1.0 has been the reduction of dependencies. To that extent, only a few
-packages are required for the base usage, and a GUI toolkit if you are going to use
-the graphical user interface, Reason.
+ ``DEST_DIR``
+ This is the location to which all source code will be downloaded and
+ resulting built libraries installed.
+ ``HDF5_DIR``
+ If you wish to link against existing HDF5 (*shared*) libraries, put the
+ root path to the installation here.
+ ``INST_WXPYTHON``
+ This is a boolean, set to 0 or 1, that governs whether or not wxPython
+ should be installed.
+ ``INST_ZLIB``
+ This is a boolean, set to 0 or 1, that governs whether or not zlib
+ should be installed.
+ ``YT_DIR``
+ If you've got a source checkout of YT somewhere else, point to it with
+ this!
+
+.. warning:: If you run into problems, particularly anything involving
+ ``-fPIC``, it is likely that there's a problem with static libraries.
+ Try asking the installer script to install HDF5 and ZLIB.
+
+Installing by Hand
+------------------
+
+If you've ever installed a python package by hand before, YT should be easy to
+install. You will need to install the prequisites first. A driving factor in
+the development of yt over the months leading to release 1.0 has been the
+reduction of dependencies. To that extent, only a few packages are required
+for the base usage, and a GUI toolkit if you are going to use the graphical
+user interface, Reason.
* `Python <http://python.org/>`_, at least version 2.4, but preferably 2.5 or
2.6.
@@ -85,3 +112,11 @@
elsewhere. You may also consider installing the
`Enthought Python Distribution <http://www.enthought.com/products/epd.php>`_,
which includes all of the necessary packages.
+
+Once these dependencies have been met, YT can be installed in the standard
+manner:
+
+.. code-block:: bash
+
+ cd yt/
+ python2.5 setup.py install --prefix=/some/where/
Modified: branches/yt-1.0/doc/source/index.rst
==============================================================================
--- branches/yt-1.0/doc/source/index.rst (original)
+++ branches/yt-1.0/doc/source/index.rst Sat Dec 13 19:29:29 2008
@@ -4,6 +4,14 @@
yt is a toolkit designed to analyze, manage and plot adaptive mesh refinement
data from the Enzo code.
+If you use ``yt`` in a paper, I highly encourage you to read about our policy
+on :ref:`free repository space<free_repo_space>` for analysis code!
+
+Below you'll find the table of contents. There's a super-quick-start guide to
+interactive data analysis, a tour of the objects and methodology of ``yt``, a
+short cookbook, a guide extending, and -- perhaps most important of all -- a
+guide to the classes and functions available!
+
Contents:
.. toctree::
@@ -12,9 +20,10 @@
intro
getting_started
quick_guide/index
- tutorial/index
+ tour/index
cookbook/index
extending/index
+ contribution
faq
modules/index
Modified: branches/yt-1.0/doc/source/intro.rst
==============================================================================
--- branches/yt-1.0/doc/source/intro.rst (original)
+++ branches/yt-1.0/doc/source/intro.rst Sat Dec 13 19:29:29 2008
@@ -24,7 +24,7 @@
dependencies have been reduced, and thus its installation made significantly easier.
In 2008, yt was extended by Jeff Oishi to include support for the Orion code.
-Additionally, it was selected for inclusion in the next public release of the
+Additionally, it was selected for inclusion in the 1.5 release of the
Enzo code.
What yt is and is not
@@ -54,7 +54,7 @@
* Identification of topologically-connected sets in arbitrary fields
* Projections, orthogonal slices, oblique slices
* Axially-aligned rays
- * Memory-conserving 1-, 2- and 3-D profiles of arbitrary fields.
+ * Memory-conserving 1-, 2- and 3-D profiles of arbitrary fields and objects.
* Halo-finding (HOP) algorithm with full particle information and sphere access
* `PyTables <http://www.pytables.org/>`_, the data-storage backend for
marshalling of data.
@@ -100,3 +100,21 @@
* Source code availability: **FULL**.
* Portability: **YES**.
+How do I cite yt?
+-----------------
+
+If you use some of the advanced features of yt and would like to cite it in
+a publication, you should feel free to cite the
+`Proceedings Paper <http://conference.scipy.org/proceedings/SciPy2008/paper_11>`_
+with the following BibTeX entry: ::
+
+ @InProceedings{SciPyProceedings_46,
+ author = {Matthew Turk},
+ title = {Analysis and Visualization of Multi-Scale Astrophysical
+ Simulations Using Python and NumPy},
+ booktitle = {Proceedings of the 7th Python in Science Conference},
+ pages = {46 - 50},
+ address = {Pasadena, CA USA},
+ year = {2008},
+ editor = {Ga\"el Varoquaux and Travis Vaught and Jarrod Millman},
+ }
Modified: branches/yt-1.0/doc/source/modules/lagos/basedatatypes.rst
==============================================================================
--- branches/yt-1.0/doc/source/modules/lagos/basedatatypes.rst (original)
+++ branches/yt-1.0/doc/source/modules/lagos/basedatatypes.rst Sat Dec 13 19:29:29 2008
@@ -19,8 +19,8 @@
.. currentmodule:: yt.lagos
-Base Containers
----------------
+Base Classes
+------------
.. autoclass:: yt.lagos.EnzoData
:members:
@@ -43,6 +43,11 @@
.. autoclass:: yt.lagos.FakeGridForParticles
:members:
+.. _data_objects:
+
+Physical Objects
+================
+
1D Data Containers
------------------
@@ -99,6 +104,8 @@
:members:
:show-inheritance:
+.. _derived_quantities:
+
Derived Quantities
------------------
Modified: branches/yt-1.0/doc/source/modules/raven/plotcollection.rst
==============================================================================
--- branches/yt-1.0/doc/source/modules/raven/plotcollection.rst (original)
+++ branches/yt-1.0/doc/source/modules/raven/plotcollection.rst Sat Dec 13 19:29:29 2008
@@ -13,6 +13,8 @@
.. autoclass:: yt.raven.PlotCollection
:members:
+.. _callbacks:
+
Plot Modification Callbacks
---------------------------
Modified: branches/yt-1.0/doc/source/quick_guide/index.rst
==============================================================================
--- branches/yt-1.0/doc/source/quick_guide/index.rst (original)
+++ branches/yt-1.0/doc/source/quick_guide/index.rst Sat Dec 13 19:29:29 2008
@@ -46,6 +46,8 @@
And then in the variable ``v`` we have the value of the most dense cell, and in
``c`` we have the location of that point.
+.. _quick_making_plots:
+
Making Plots
------------
Added: branches/yt-1.0/doc/source/tour/code_objects.rst
==============================================================================
--- (empty file)
+++ branches/yt-1.0/doc/source/tour/code_objects.rst Sat Dec 13 19:29:29 2008
@@ -0,0 +1,128 @@
+Code Objects
+============
+
+Unfortunately, this name is a bit misleading, because in a sense, everything is
+a code object! But what it's meant to convey is that there are some objects
+that are *native* to the AMR code that output them -- for Enzo, this would be
+things like grid patches, the hierarchy, the parameter file, and a couple more
+supplemental files that don't show up in analysis very often.
+
+For the most part, ``yt`` will abstract these objects away -- there's no reason
+the user (you & me!) should have to know anything about grids if they don't
+*have* to. But, at the same time, you should be able to dig as deep as you
+want into the internals of the AMR code, and what it outputs.
+
+Let's start with the structure of the data. We can think about this in terms
+of the *parameters* that describe the simulation, the *hierarchy* of grid
+patches inside that simulation, and then the *grid patches* themselves.
+
+Parameter Files
+---------------
+
+This is the most primitive and isolated means of examining data output from the
+code, and it's also the jumping point for analyzing and plotting of any data
+from a simulation -- this is your entry point inside ``yt``. These particular
+objects are meant to be very 'cheap' -- they're meant to be quick to
+instantiate, so that you can, for instance, very rapidly identify which output
+you want to examine in a script. The class name is :class:`EnzoStaticOutput`.
+
+For example, here's a snippet from my own research. It uses a python module
+called ``glob`` to do wildcard filename matching, and then it checks to see if
+the time a given output was made at was greater than 200 million years, and if
+so, it quits the loop, and then the script can process the file in whatever way.
+
+.. code-block:: python
+
+ from yt.mods import *
+ import glob
+
+ for fn in glob.glob("DataDump*"):
+ pf = EnzoStaticOutput(fn)
+ if pf["InitialTime"] * pf["years"] >= 2e8: break
+
+This particular snippet also brings up the point that the parameter file
+encompasses all of the units associated with a given output file. It will do
+its best to figure out how to convert between code quantities -- things like
+time, energy, density, velocity -- and cgs quantities.
+
+As a note, the parameter file actually has the ability to handle a couple other
+code objects -- the cooling table and the rate table. Right now the means of
+processing this information is not terribly standardized, but please feel free
+to experiment with the ``cool_rates`` and ``cool_rates`` objects.
+
+Hierarchy
+---------
+
+With the hierarchy, we begin to delve a bit deeper into the workings of both
+``yt`` and the AMR code. This will parse the hiearchy file and instantiate all
+of the grid objects inside python. Unfortunately, with a large number of
+grids, this can take some time. (Efforts are under way to reduce this time,
+but it's an unfortunate tradeoff between flexibility and speed. Typically it
+doesn't feel sluggish unless you are instantiating more than 50,000 grid
+patches.) This class is :class:`EnzoHierarchyType`, but you will only need to
+access it as a property of an :class:`EnzoStaticOutput` called ``h``:
+
+.. code-block:: python
+
+ my_hierarchy = pf.h
+ my_hierarchy.print_stats()
+
+This will access the hierarchy, assign it to a local variable (not strictly
+necessary!) and then print out statistics about the simulation -- the number of
+levels, the number of grids on a level, the number of total cells, and some
+information about the finest grid cell. The hierarchy does have one very
+important function called ``find_max`` -- this function will dig through the
+top couple levels of a simulation and attempt to find the maximum point of a
+given field, and then it returns the value and the center point to you.
+(There's an example down below.)
+
+Because the hierarchy contains all of the grids (in an array called ``grids``),
+it can operate on the information about those grids very easily. Additionally,
+it acts as a means of generating the next level of objects, as well; in a
+sense, the hierarchy acts as gatekeeper to the grid patches as well as to the
+data in the simulation.
+
+In the next section, we'll talk about some of these 'physical' objects, and how
+you can use them to examine data in simulations.
+
+Grids
+-----
+
+Inside a simulation, the data is first divided up into grid patches, which are
+subdivided into cells, associated with each of which is a set of data points.
+The grid patches may trace physical objects, but the distribution of grid
+patches is governed not only by hydrodynamic structure but can also be
+influenced by processor arrangement and topology. As such, these are thought
+of a code objects rather than physical objects. However, despite that
+categorization, the data returned to you when accessed through a grid is in cgs
+units, as to allow better and more meaningful analysis. This class is the
+:class:`EnzoGridBase`.
+
+You should not have to instantiate grid objects yourself -- they are
+automatically created by the hierarchy, and stored in an array called
+``grids``:
+
+.. code-block:: python
+
+ print my_hierarchy.grids[0].LeftEdge
+
+Note that while the grids are indexed-by-one by Enzo in ``yt`` they are
+indexed-by-zero in the grids array!
+
+Usage of Code Objects
+---------------------
+
+For the most part, you should interact with the code objects in only a few
+ways. If ``yt`` has done its job correctly, you won't have to interact with
+the grids individually or with the hierarchy except to create objects.
+Typically you will do something like:
+
+.. code-block:: python
+
+ pf = EnzoStaticOutput("DataDump0019.dir/DataDump0019")
+ v, c = pf.h.find_max("Density")
+ sphere = pf.h.sphere(c, 100.0/pf['au'])
+
+We now have a sphere (see the next section) centered at the point of maximum
+density in the simulation. At this point, we should be able to mostly
+disregard the code objects, and operate exclusively on the sphere.
Added: branches/yt-1.0/doc/source/tour/index.rst
==============================================================================
--- (empty file)
+++ branches/yt-1.0/doc/source/tour/index.rst Sat Dec 13 19:29:29 2008
@@ -0,0 +1,41 @@
+A Tour of yt
+============
+
+There's a lot inside yt. This section is designed to give you an idea of
+what's there, what you can do with it, and how to think about the yt
+environment.
+
+You will be served best by thinking about doing things with yt by thinking in
+objects; we'll start by talking about how to access different types of objects
+that are put on the disk by the AMR code, then we'll talk about how to select
+subsections of a set of output based on physical quantities or other
+characteristics, and then a bit about how to perform data reduction to
+transform those objects into profiles, phase-space distributions, images, and
+so on. So this leads to a clear set of categories for different 'objects'
+inside the yt-domain.
+
+ Code Objects
+ These are objects that are on the disk, that the AMR code knows about --
+ things like grids, data dumps, the grid hierarchy and so on and so forth.
+ Physical Objects
+ These are objects like spheres, rectangular prisms, slices, and so on.
+ These are collections of related data, and these associations are not
+ necessarily associated with arrangement inside a code object.
+ Reduced Objects
+ These are objects where some set of data has been reduced into a more
+ tractable format. Histograms, 1-D profiles, averages and so on are all
+ members of this category.
+ Plots
+ Plots stand somewhat outside this category, because the plotting interface
+ accepts information about what you want to see, then goes out and fetches
+ it as appropriate from the correct types of objects.
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ code_objects
+ physical_objects
+ reduced_objects
+ plots
Added: branches/yt-1.0/doc/source/tour/physical_objects.rst
==============================================================================
--- (empty file)
+++ branches/yt-1.0/doc/source/tour/physical_objects.rst Sat Dec 13 19:29:29 2008
@@ -0,0 +1,40 @@
+Physical Objects
+================
+
+Assuming the simulation ran correctly, and debugging doesn't need to occur, the
+primary means of interaction with simulation output should be through
+physically meaningful objects. Specifically, rather than viewing a collection
+of points in a single grid patch, one should be able to obtain and manipulate
+collections of points inside spheres, disks, 'clumps' and so forth. To
+facilitate that, ``yt`` provides means of obtaining objects.
+
+Creating Objects
+----------------
+
+These objects are all created from the hierarchy object; for instance, to
+obtain a sphere centered at ``(0.3, 0.5, 0.8)`` with a radius of one
+megaparsec, you could do:
+
+.. code-block:: python
+
+ sp = pf.h.sphere([0.3,0.5,0.8], 1.0/pf['mpc'])
+
+The variable ``sp`` is now an object that can be examined, manipulated and
+analyzed. There are several different objects available -- for more
+information, see :ref:`data_objects`.
+
+Means of Interactions
+---------------------
+
+These objects have several means of interactions, but the most primitive is
+simply to obtain all of the data that is contained in a given object.
+
+.. code-block:: python
+
+ print sp["CellMassMsun"].sum()
+
+This accesses every cell located within the sphere, calculates its mass in
+solar masses, and prints the sum. The actual array of data is a NumPy array;
+these have a number of methods, of which ``sum`` is but one -- for more
+information, see the NumPy documentation. (Additionally, you can just call
+``help`` on the array: ``help(sp["CellMassMsun"])`` .)
Added: branches/yt-1.0/doc/source/tour/plots.rst
==============================================================================
--- (empty file)
+++ branches/yt-1.0/doc/source/tour/plots.rst Sat Dec 13 19:29:29 2008
@@ -0,0 +1,85 @@
+Plots
+=====
+
+Through the plotting interface, you can have ``yt`` automatically generate many
+of the analysis objects available to you!
+
+The primary plotting interface is through a :class:`PlotCollection`
+instantiated with a given parameter file and (optionally) a center. See
+:ref:`quick_making_plots` for a brief example of how to generate a
+:class:`PlotCollection`.
+
+Two-Dimensional Images
+----------------------
+
+Whenever a two-dimensional image is created, the plotting object first
+obtains the necessary data at the *highest resolution*. Every time an image is
+requested of it -- for instance, when the width or field is changed -- this
+high-resolution data is then pixelized and placed in a buffer of fixed size.
+
+Slices are axially-aligned images of data selected at a fixed point on an axis;
+these are the fastest type of two-dimensional image, as only the correct
+coordinate data is read from disk and then plotted.
+
+Cutting planes are oblique slices, aligned with a given normal vector. These
+can be used for face-on images of disks and other objects, as well as a
+rotational slices. They work just like slices in other ways, but they tend to
+be a bit slower.
+
+Projections are closer in style to profiles than slices. They can exist either
+as a summation of the data along every possible ray through the simulation, or
+an average value along every possible ray. If a *weight_field* is provided,
+then the data returned is an average; typically you will want to weight with
+``Density``. If you do not supply a *weight_field* then the returned data is a
+column sum. These fields are stored in between invocations -- this allows for
+speedier access to a relatively slow process!
+
+.. _profiles_and_phase_plots:
+
+Profiles and Phase Plots
+------------------------
+
+Profiles and phase plots provide identical API to the generation of profiles
+themselves, but with a couple convenience interfaces. You can have the plot
+collection generate a sphere automatically for either one:
+
+.. code-block:: python
+
+ pc.add_phase_sphere(100.0, 'au', ["Density", "Temperature", "CellMassMsun"],
+ weight = None)
+
+This will generate a sphere, a phase plot, and then return to you the plot
+object.
+
+Interactive Plotting
+--------------------
+
+Thanks to the pylab interface in Matplotlib, we have an interactive plot
+collection available for usage within ``IPython``. Instead of
+:class:`PlotCollection`, use :class:`PlotCollectionInteractive` -- this will
+generate automatically updating GUI windows with the plots inside them.
+
+Callbacks
+---------
+
+Callbacks are means of adding things on top of existing plots -- like vectors,
+overplotted lines, and so on and so forth. They have to be added to the plot
+objects themselves, rather than the :class:`PlotCollection`. You can add them like so:
+
+.. code-block:: python
+
+ p = pc.add_slice("Density", 0)
+ p.add_callback(GridBoundaryCallback())
+
+Each Callback has to be instantiated, and then added. You can also access the
+plot objects inside the PlotCollection directly:
+
+.. code-block:: python
+
+ pc.add_slice("Density", 0)
+ pc.plots[-1].add_callback(GridBoundaryCallback())
+
+Note that if you are plotting interactively, the PlotCollection will need to
+have ``redraw`` called on it.
+
+For more information about Callbacks, see the :ref:`API reference <callbacks>` .
Added: branches/yt-1.0/doc/source/tour/reduced_objects.rst
==============================================================================
--- (empty file)
+++ branches/yt-1.0/doc/source/tour/reduced_objects.rst Sat Dec 13 19:29:29 2008
@@ -0,0 +1,54 @@
+Reduced Objects
+===============
+
+Once a physically meaningful collection of data has been selected, often
+analysis needs to be conducted that reduces that object to some smaller set of
+numbers, often numbers that can be plotted or included in a paper. As such,
+``yt`` includes facilities for doing such things!
+
+Derived Quantities
+------------------
+
+Derived quantities are the 'simple numbers' you can get out of objects -- this
+includes things like (baryon) spin parameter, the angular momentum vector, the
+gravitational boundedness of a given physical object and so forth. More
+information, including a list of quantities, can be found in
+:ref:`derived_quantities`. These get called in an admittedly slightly awkward
+way, but that is because they can also accept parameters:
+
+.. code-block:: python
+
+ is_bound = my_sphere.quantities["IsBound"]()
+ L_vec = my_sphere.quantities["AngularMomentumVector"]()
+
+Some return booleans, others return arrays, and some just return numbers.
+
+Profiles
+--------
+
+The idea of a profile is rather more like an n-dimensional histogram with an
+arbitrary weighting. There are only a few things to keep in mind here -- the
+profiles will truncate any points that do not fall within their boundaries (if
+you do not specify boundaries, they will auto-select them to include all
+points) and the value in a given bin is governed by the value of the 'weight.'
+If the 'weight' is set to ``None``, then the values in a given bin are simply
+added; typically it is set to ``CellMassMsun`` which will multiply each value
+by the mass in its cell, sum, and then divide by the total mass in that bin.
+
+Typically 1-D profiles are generated either as 'radial profiles' or
+'probability distribution functions' and 2-D profiles are thought of as phase
+plots. A common usage pattern is to generate a phase plot of mass in a bin in
+the plane of two quantities, then overplot the 1-D profile with a weighted
+average. In this way, the spread in a quantity as well as its average value
+can be displayed simultaneously.
+
+You can generate these profiles yourself, but because their API is completely
+exposed by the :class:`PlotCollection` object, you rarely need to. But, if you
+are determined to, see :ref:`making_profiles`. Otherwise, check out
+:ref:`profiles_and_phase_plots`.
+
+Projections
+-----------
+
+Projections are, in a sense, a means of casting rays through the simulational
+volume.
More information about the yt-svn
mailing list