[yt-svn] commit/yt: ngoldbaum: Merged in chummels/yt/yt-3.0 (pull request #1087)
commits-noreply at bitbucket.org
commits-noreply at bitbucket.org
Tue Jul 29 13:16:41 PDT 2014
1 new commit in yt:
https://bitbucket.org/yt_analysis/yt/commits/76f1cf5a7f78/
Changeset: 76f1cf5a7f78
Branch: yt-3.0
User: ngoldbaum
Date: 2014-07-29 22:16:31
Summary: Merged in chummels/yt/yt-3.0 (pull request #1087)
Docs Objects Update
Affected #: 26 files
diff -r b2a39372ea82bfa7a22b78af7fddfe6137073a8c -r 76f1cf5a7f78987525c183db3d64a0096a5a21f3 doc/source/analyzing/_dq_docstrings.inc
--- a/doc/source/analyzing/_dq_docstrings.inc
+++ /dev/null
@@ -1,94 +0,0 @@
-
-
-.. function:: angular_momentum_vector()
-
- (This is a proxy for :func:`~yt.data_objects.derived_quantities.AngularMomentumVector`.)
- This function returns the mass-weighted average angular momentum vector.
-
-
-.. function:: bulk_velocity():
-
- (This is a proxy for :func:`~yt.data_objects.derived_quantities.BulkVelocity`.)
- This function returns the mass-weighted average velocity in the object.
-
-
-.. function:: center_of_mass(use_cells=True, use_particles=False):
-
- (This is a proxy for :func:`~yt.data_objects.derived_quantities.CenterOfMass`.)
- This function returns the location of the center
- of mass. By default, it computes of the *non-particle* data in the object.
-
- Parameters
- ----------
-
- use_cells : bool
- If True, will include the cell mass (default: True)
- use_particles : bool
- if True, will include the particles in the object (default: False)
-
-
-
-.. function:: extrema(fields, non_zero=False, filter=None):
-
- (This is a proxy for :func:`~yt.data_objects.derived_quantities.Extrema`.)
- This function returns the extrema of a set of fields
-
- :param fields: A field name, or a list of field names
- :param filter: a string to be evaled to serve as a data filter.
-
-
-.. function:: max_location(field):
-
- (This is a proxy for :func:`~yt.data_objects.derived_quantities.max_location`.)
- This function returns the location of the maximum of a set
- of fields.
-
-
-.. function:: min_location(field):
-
- (This is a proxy for :func:`~yt.data_objects.derived_quantities.MinLocation`.)
- This function returns the location of the minimum of a set
- of fields.
-
-
-
-.. function:: spin_parameter(use_gas=True, use_particles=True):
-
- (This is a proxy for :func:`~yt.data_objects.derived_quantities.SpinParameter`.)
- This function returns the spin parameter for the baryons, but it uses
- the particles in calculating enclosed mass.
-
-
-.. function:: total_mass():
-
- (This is a proxy for :func:`~yt.data_objects.derived_quantities.TotalMass`.)
- This function takes no arguments and returns the sum of cell masses and
- particle masses in the object.
-
-
-.. function:: total_quantity(fields):
-
- (This is a proxy for :func:`~yt.data_objects.derived_quantities.TotalQuantity`.)
- This function sums up a given field over the entire region
-
- :param fields: The fields to sum up
-
-
-
-.. function:: weighted_average_quantity(field, weight):
-
- (This is a proxy for :func:`~yt.data_objects.derived_quantities.WeightedAverageQuantity`.)
- This function returns an averaged quantity.
-
- :param field: The field to average
- :param weight: The field to weight by
-
-.. function:: weighted_variance(field, weight):
-
- (This is a proxy for :func:`~yt.data_objects.derived_quantities.WeightedVariance`.)
- This function returns the variance of a field.
-
- :param field: The target field
- :param weight: The field to weight by
-
- Returns the weighted variance and the weighted mean.
diff -r b2a39372ea82bfa7a22b78af7fddfe6137073a8c -r 76f1cf5a7f78987525c183db3d64a0096a5a21f3 doc/source/analyzing/_obj_docstrings.inc
--- a/doc/source/analyzing/_obj_docstrings.inc
+++ /dev/null
@@ -1,150 +0,0 @@
-
-
-.. class:: boolean(self, regions, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRBooleanRegionBase`.)
-
-
-.. class:: covering_grid(self, level, left_edge, dims, fields=None, ds=None, num_ghost_zones=0, use_pbar=True, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRCoveringGridBase`.)
-
-
-.. class:: cut_region(self, base_region, field_cuts, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.InLineExtractedRegionBase`.)
-
-
-.. class:: cutting(self, normal, center, fields=None, node_name=None, north_vector=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRCuttingPlaneBase`.)
-
-
-.. class:: disk(self, center, normal, radius, height, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRCylinderBase`.)
-
-
-.. class:: ellipsoid(self, center, A, B, C, e0, tilt, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMREllipsoidBase`.)
-
-
-.. class:: extracted_region(self, base_region, indices, force_refresh=True, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.ExtractedRegionBase`.)
-
-
-.. class:: fixed_res_cutting(self, normal, center, width, dims, fields=None, node_name=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRFixedResCuttingPlaneBase`.)
-
-
-.. class:: fixed_res_proj(self, axis, level, left_edge, dims, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRFixedResProjectionBase`.)
-
-
-.. class:: grid_collection(self, center, grid_list, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRGridCollectionBase`.)
-
-
-.. class:: grid_collection_max_level(self, center, max_level, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRMaxLevelCollectionBase`.)
-
-
-.. class:: inclined_box(self, origin, box_vectors, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRInclinedBoxBase`.)
-
-
-.. class:: ortho_ray(self, axis, coords, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMROrthoRayBase`.)
-
-
-.. class:: overlap_proj(self, axis, field, weight_field=None, max_level=None, center=None, ds=None, source=None, node_name=None, field_cuts=None, preload_style='level', serialize=True, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRProjBase`.)
-
-
-.. class:: periodic_region(self, center, left_edge, right_edge, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRPeriodicRegionBase`.)
-
-
-.. class:: periodic_region_strict(self, center, left_edge, right_edge, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRPeriodicRegionStrictBase`.)
-
-
-.. class:: proj(self, axis, field, weight_field=None, max_level=None, center=None, ds=None, source=None, node_name=None, field_cuts=None, preload_style=None, serialize=True, style='integrate', **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRQuadTreeProjBase`.)
-
-
-.. class:: ray(self, start_point, end_point, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRRayBase`.)
-
-
-.. class:: region(self, center, left_edge, right_edge, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRRegionBase`.)
-
-
-.. class:: region_strict(self, center, left_edge, right_edge, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRRegionStrictBase`.)
-
-
-.. class:: slice(self, axis, coord, fields=None, center=None, ds=None, node_name=False, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRSliceBase`.)
-
-
-.. class:: smoothed_covering_grid(self, *args, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRSmoothedCoveringGridBase`.)
-
-
-.. class:: sphere(self, center, radius, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRSphereBase`.)
-
-
-.. class:: streamline(self, positions, length=1.0, fields=None, ds=None, **field_parameters):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRStreamlineBase`.)
-
-
-.. class:: surface(self, data_source, surface_field, field_value):
-
- For more information, see :ref:`physical-object-api`
- (This is a proxy for :class:`~yt.data_objects.data_containers.AMRSurfaceBase`.)
diff -r b2a39372ea82bfa7a22b78af7fddfe6137073a8c -r 76f1cf5a7f78987525c183db3d64a0096a5a21f3 doc/source/analyzing/creating_derived_fields.rst
--- a/doc/source/analyzing/creating_derived_fields.rst
+++ /dev/null
@@ -1,209 +0,0 @@
-.. _creating-derived-fields:
-
-Creating Derived Fields
-=======================
-
-One of the more powerful means of extending ``yt`` is through the usage of derived
-fields. These are fields that describe a value at each cell in a simulation.
-
-Defining a New Field
---------------------
-
-So once a new field has been conceived of, the best way to create it is to
-construct a function that performs an array operation -- operating on a
-collection of data, neutral to its size, shape, and type. (All fields should
-be provided as 64-bit floats.)
-
-A simple example of this is the pressure field, which demonstrates the ease of
-this approach.
-
-.. code-block:: python
-
- import yt
-
- def _pressure(field, data):
- return (data.ds.gamma - 1.0) * \
- data["density"] * data["thermal_energy"]
-
-Note that we do a couple different things here. We access the "gamma"
-parameter from the dataset, we access the "density" field and we access
-the "thermal_energy" field. "thermal_energy" is, in fact, another derived field!
-("thermal_energy" deals with the distinction in storage of energy between dual
-energy formalism and non-DEF.) We don't do any loops, we don't do any
-type-checking, we can simply multiply the three items together.
-
-Once we've defined our function, we need to notify ``yt`` that the field is
-available. The :func:`add_field` function is the means of doing this; it has a
-number of fairly specific parameters that can be passed in, but here we'll only
-look at the most basic ones needed for a simple scalar baryon field.
-
-.. code-block:: python
-
- yt.add_field("pressure", function=_pressure, units="dyne/cm**2")
-
-We feed it the name of the field, the name of the function, and the
-units. Note that the units parameter is a "raw" string, in the format that ``yt`` uses
-in its `symbolic units implementation <units>`_ (e.g., employing only unit names, numbers,
-and mathematical operators in the string, and using ``"**"`` for exponentiation). We suggest
-that you name the function that creates a derived field with the intended field name prefixed
-by a single underscore, as in the ``_pressure`` example above.
-
-:func:`add_field` can be invoked in two other ways. The first is by the function
-decorator :func:`derived_field`. The following code is equivalent to the previous
-example:
-
-.. code-block:: python
-
- from yt import derived_field
-
- @derived_field(name="pressure", units="dyne/cm**2")
- def _pressure(field, data):
- return (data.ds.gamma - 1.0) * \
- data["density"] * data["thermal_energy"]
-
-The :func:`derived_field` decorator takes the same arguments as :func:`add_field`,
-and is often a more convenient shorthand in cases where you want to quickly set up
-a new field.
-
-Defining derived fields in the above fashion must be done before a dataset is loaded,
-in order for the dataset to recognize it. If you want to set up a derived field after you
-have loaded a dataset, or if you only want to set up a derived field for a particular
-dataset, there is an :meth:`add_field` method that hangs off dataset objects. The calling
-syntax is the same:
-
-.. code-block:: python
-
- ds = yt.load("GasSloshing/sloshing_nomag2_hdf5_plt_cnt_0100")
- ds.add_field("pressure", function=_pressure, units="dyne/cm**2")
-
-If you find yourself using the same custom-defined fields over and over, you
-should put them in your plugins file as described in :ref:`plugin-file`.
-
-A More Complicated Example
---------------------------
-
-But what if we want to do something a bit more fancy? Here's an example of getting
-parameters from the data object and using those to define the field;
-specifically, here we obtain the ``center`` and ``bulk_velocity`` parameters
-and use those to define a field for radial velocity (there is already a ``"radial_velocity"``
-field in ``yt``, but we create this one here just as a transparent and simple example).
-
-.. code-block:: python
-
- from yt.fields.api import ValidateParameter
- import numpy as np
-
- def _my_radial_velocity(field, data):
- if data.has_field_parameter("bulk_velocity"):
- bv = data.get_field_parameter("bulk_velocity").in_units("cm/s")
- else:
- bv = data.ds.arr(np.zeros(3), "cm/s")
- xv = data["gas","velocity_x"] - bv[0]
- yv = data["gas","velocity_y"] - bv[1]
- zv = data["gas","velocity_z"] - bv[2]
- center = data.get_field_parameter('center')
- x_hat = data["x"] - center[0]
- y_hat = data["y"] - center[1]
- z_hat = data["z"] - center[2]
- r = np.sqrt(x_hat*x_hat+y_hat*y_hat+z_hat*z_hat)
- x_hat /= r
- y_hat /= r
- z_hat /= r
- return xv*x_hat + yv*y_hat + zv*z_hat
- yt.add_field("my_radial_velocity",
- function=_my_radial_velocity,
- units="cm/s",
- take_log=False,
- validators=[ValidateParameter('center'),
- ValidateParameter('bulk_velocity')])
-
-Note that we have added a few parameters below the main function; we specify
-that we do not wish to display this field as logged, that we require both
-``bulk_velocity`` and ``center`` to be present in a given data object we wish
-to calculate this for, and we say that it should not be displayed in a
-drop-down box of fields to display. This is done through the parameter
-*validators*, which accepts a list of :class:`FieldValidator` objects. These
-objects define the way in which the field is generated, and when it is able to
-be created. In this case, we mandate that parameters *center* and
-*bulk_velocity* are set before creating the field. These are set via
-:meth:`~yt.data_objects.data_containers.set_field_parameter`, which can
-be called on any object that has fields:
-
-.. code-block:: python
-
- ds = yt.load("GasSloshing/sloshing_nomag2_hdf5_plt_cnt_0100")
- sp = ds.sphere("max", (200.,"kpc"))
- sp.set_field_parameter("bulk_velocity", yt.YTArray([-100.,200.,300.], "km/s"))
-
-In this case, we already know what the *center* of the sphere is, so we do not set it. Also,
-note that *center* and *bulk_velocity* need to be :class:`YTArray` objects with units.
-
-Other examples for creating derived fields can be found in the cookbook recipes
-:ref:`cookbook-simple-derived-fields` and :ref:`cookbook-complex-derived-fields`.
-
-.. _derived-field-options:
-
-Field Options
--------------
-
-The arguments to :func:`add_field` are passed on to the constructor of :class:`DerivedField`.
-There are a number of options available, but the only mandatory ones are ``name``,
-``units``, and ``function``.
-
- ``name``
- This is the name of the field -- how you refer to it. For instance,
- ``pressure`` or ``magnetic_field_strength``.
- ``function``
- This is a function handle that defines the field
- ``units``
- This is a string that describes the units. Powers must be in
- Python syntax (``**`` instead of ``^``).
- ``display_name``
- This is a name used in the plots, for instance ``"Divergence of
- Velocity"``. If not supplied, the ``name`` value is used.
- ``take_log``
- This is *True* or *False* and describes whether the field should be logged
- when plotted.
- ``particle_type``
- Is this field a *particle* field?
- ``validators``
- (*Advanced*) This is a list of :class:`FieldValidator` objects, for instance to mandate
- spatial data.
- ``display_field``
- (*Advanced*) Should this field appear in the dropdown box in Reason?
- ``not_in_all``
- (*Advanced*) If this is *True*, the field may not be in all the grids.
- ``output_units``
- (*Advanced*) For fields that exist on disk, which we may want to convert to other
- fields or that get aliased to themselves, we can specify a different
- desired output unit than the unit found on disk.
-
-Units for Cosmological Datasets
--------------------------------
-
-``yt`` has additional capabilities to handle the comoving coordinate system used
-internally in cosmological simulations. Simulations that use comoving
-coordinates, all length units have three other counterparts correspoding to
-comoving units, scaled comoving units, and scaled proper units. In all cases
-'scaled' units refer to scaling by the reduced Hubble parameter - i.e. the length
-unit is what it would be in a universe where Hubble's parameter is 100 km/s/Mpc.
-
-To access these different units, yt has a common naming system. Scaled units are denoted by
-dividing by the scaled Hubble parameter ``h`` (which is in itself a unit). Comoving
-units are denoted by appending ``cm`` to the end of the unit name.
-
-Using the parsec as an example,
-
-``pc``
- Proper parsecs, :math:`\rm{pc}`.
-
-``pccm``
- Comoving parsecs, :math:`\rm{pc}/(1+z)`.
-
-``pccm/h``
- Comoving parsecs normalized by the scaled hubble constant, :math:`\rm{pc}/h/(1+z)`.
-
-``pc/h``
- Proper parsecs, normalized by the scaled hubble constant, :math:`\rm{pc}/h`.
-
-Further examples of this functionality are shown in :ref:`comoving_units_and_code_units`.
diff -r b2a39372ea82bfa7a22b78af7fddfe6137073a8c -r 76f1cf5a7f78987525c183db3d64a0096a5a21f3 doc/source/analyzing/fields.rst
--- a/doc/source/analyzing/fields.rst
+++ b/doc/source/analyzing/fields.rst
@@ -169,6 +169,27 @@
.. include reference here once it's done
+The full list of fields available for a dataset can be found as
+the attribute ``field_list`` for native, on-disk fields and ``derived_field_list``
+for derived fields (``derived_field_list`` is a superset of ``field_list``).
+You can view these lists by examining a dataset like this:
+
+.. code-block:: python
+
+ ds = yt.load("my_data")
+ print ds.field_list
+ print ds.derived_field_list
+
+By using the ``field_info()`` class, one can access information about a given
+field, like its default units or the source code for it.
+
+.. code-block:: python
+
+ ds = yt.load("my_data")
+ ds.index
+ print ds.field_info["gas", "pressure"].get_units()
+ print ds.field_info["gas", "pressure"].get_source()
+
Particle Fields
---------------
@@ -190,4 +211,3 @@
a field for the smoothing length ``h``, which is roughly equivalent to
``(m/\rho)^{1/3}``, where ``m`` and ``rho`` are the particle mass and density
respectively. This can be useful for doing neighbour finding.
-
diff -r b2a39372ea82bfa7a22b78af7fddfe6137073a8c -r 76f1cf5a7f78987525c183db3d64a0096a5a21f3 doc/source/analyzing/filtering.rst
--- a/doc/source/analyzing/filtering.rst
+++ b/doc/source/analyzing/filtering.rst
@@ -75,6 +75,8 @@
print 'Density of "overpressure and fast" data: ad["density"][overpressure_and_fast] = \n%s' % \
ad['density'][overpressure_and_fast]
+.. _cut-regions:
+
Cut Regions
^^^^^^^^^^^
@@ -84,6 +86,9 @@
.. notebook:: mesh_filter.ipynb
+Cut regions can also operator on particle fields, but a single cut region object
+cannot operate on both particle fields and mesh fields at the same time.
+
.. _filtering-particles:
Filtering Particle Fields
@@ -144,7 +149,8 @@
spheres, regions (3D prisms), ellipsoids, disks, and rays. The `all_data`
object which gets used throughout this documentation section is an example of
a geometric object, but it defaults to including all the data in the dataset
-volume.
+volume. To see all of the geometric objects available, see
+:ref:`available-objects`.
Consult the object documentation section for all of the different objects
one can use, but here is a simple example using a sphere object to filter
diff -r b2a39372ea82bfa7a22b78af7fddfe6137073a8c -r 76f1cf5a7f78987525c183db3d64a0096a5a21f3 doc/source/analyzing/index.rst
--- a/doc/source/analyzing/index.rst
+++ b/doc/source/analyzing/index.rst
@@ -6,13 +6,12 @@
.. toctree::
:maxdepth: 2
+ fields
objects
units/index
- fields
- creating_derived_fields
filtering
generating_processed_data
time_series_analysis
+ parallel_computation
external_analysis
- parallel_computation
analysis_modules/index
diff -r b2a39372ea82bfa7a22b78af7fddfe6137073a8c -r 76f1cf5a7f78987525c183db3d64a0096a5a21f3 doc/source/analyzing/objects.rst
--- a/doc/source/analyzing/objects.rst
+++ b/doc/source/analyzing/objects.rst
@@ -1,136 +1,340 @@
-.. _using-objects:
+.. _data-objects:
-Using and Manipulating Objects and Fields
-=========================================
+Data Objects
+============
+
+What are Data Objects in yt?
+----------------------------
+
+Data objects (also called *Data Containers*) are used in yt as convenience
+structures for grouping data in logical ways that make sense in the context
+of the dataset as a whole. Some of the data objects are geometrical groupings
+of data (e.g. sphere, box, cylinder, etc.). Others represent
+data products derived from your dataset (e.g. slices, streamlines, surfaces).
+Still other data objects group multiple objects together or filter them
+(e.g. data collection, cut region).
To generate standard plots, objects rarely need to be directly constructed.
However, for detailed data inspection as well as hand-crafted derived data,
objects can be exceptionally useful and even necessary.
-.. _types_of_fields:
-
-What Types of Fields are There?
+How to Create and Use an Object
-------------------------------
-``yt`` makes a distinction between two types of fields.
-
- * Fields it might expect to find on disk
- * Fields it has to generate in memory
-
-With the 2.3 release of ``yt``, the distinction between these has become more
-clear. This enables much better specification of which fields are expected to
-exist, and to provide fallbacks for calculating them. For instance you can now
-say, "temperature" might exist, but if it doesn't, here's how you calculate it.
-This also provides easier means of translating fields between different
-frontends. For instance, FLASH may refer to the temperature field as "temp"
-while Enzo calls it "temperature". Translator functions ensure that any
-derived field relying on "temp" or "temperature" works with both output types.
-
-When a field is requested, the dataset object first looks to see if that field
-exists on disk. If it does not, it then queries the list of code-specific
-derived fields. If it finds nothing there, it then defaults to examining the
-global set of derived fields.
-
-To add a derived field, which is not expected to necessarily exist on disk, use
-the standard construction:
+To create an object, you usually only need a loaded dataset, the name of
+the object type, and the relevant parameters for your object. Here is a common
+example for creating a ``Region`` object that covers all of your data volume.
.. code-block:: python
- add_field("specific_thermal_energy", function=_specific_thermal_energy,
- units="ergs/g")
+ import yt
+ ds = yt.load("RedshiftOutput0005")
+ ad = ds.all_data()
-where ``_specific_thermal_energy`` is a python function that defines the field.
-
-.. _accessing-fields:
-
-Accessing Fields in Objects
----------------------------
-
-``yt`` utilizes load-on-demand objects to represent physical regions in space.
-(see :ref:`how-yt-thinks-about-data`.) Data objects in ``yt`` all respect the following
-protocol for accessing data:
+Alternatively, we could create a sphere object of radius 1 kpc on location
+[0.5, 0.5, 0.5]:
.. code-block:: python
- my_object["density"]
+ import yt
+ ds = yt.load("RedshiftOutput0005")
+ sp = ds.sphere([0.5, 0.5, 0.5], (1, 'kpc'))
-where ``"density"`` can be any field name and ``"my_object"`` any one of
-the possible data containers listed at :ref:`available-objects`. For
-example, if we wanted to look at the temperature of cells within a
-spherical region of radius 10 kpc, centered at [0.5, 0.5, 0.5] in our
-simulation box, we would create a sphere object with:
+After an object has been created, it can be used as a data_source to certain
+tasks like ``ProjectionPlot`` (see
+:class:`~yt.visualization.plot_window.ProjectionPlot`), one can compute the
+bulk quantities associated with that object (see :ref:`derived-quantities`),
+or the data can be examined directly. For example, if you want to figure out
+the temperature at all indexed locations in the central sphere of your
+dataset you could:
.. code-block:: python
- sp = ds.sphere([0.5, 0.5, 0.5], 10.0/ds['kpc'])
+ import yt
+ ds = yt.load("RedshiftOutput0005")
+ sp = ds.sphere([0.5, 0.5, 0.5], (1, 'kpc'))
-and then look at the temperature of its cells within it via:
-
-.. code-block:: python
-
+ # Show all temperature values
print sp["temperature"]
-Information about how to create a new type of object can be found in
-:ref:`creating-objects`. The field is returned as a single, flattened
-array without spatial information. The best mechanism for
-manipulating spatial data is the :class:`~yt.data_objects.data_containers.AMRCoveringGridBase` object.
-
-The full list of fields that are available can be found as a property of the
-Hierarchy or Static Output object that you wish to access. This property is
-calculated every time the object is instantiated. The full list of fields that
-have been identified in the output file, which need no processing (besides unit
-conversion) are in the property ``field_list`` and the full list of
-potentially-accessible derived fields is available in the property
-``derived_field_list``. You can see these by examining the two properties:
-
-.. code-block:: python
-
- ds = yt.load("my_data")
- print ds.field_list
- print ds.derived_field_list
-
-When a field is added, it is added to a container that hangs off of the
-dataset, as well. All of the field creation options
-(:ref:`derived-field-options`) are accessible through this object:
-
-.. code-block:: python
-
- ds = yt.load("my_data")
- print ds.field_info["pressure"].get_units()
-
-This is a fast way to examine the units of a given field, and additionally you
-can use :meth:`yt.utilities.pydot.get_source` to get the source code:
-
-.. code-block:: python
-
- field = ds.field_info["pressure"]
- print field.get_source()
+ # Print things in a more human-friendly manner: one temperature at a time
+ print "(x, y, z) Temperature"
+ print "-----------------------"
+ for i in range(sp["temperature"].size):
+ print "(%f, %f, %f) %f" % (sp["x"][i], sp["y"][i], sp["z"][i], sp["temperature"][i])
.. _available-objects:
Available Objects
-----------------
-Objects are instantiated by direct access of a index. Each of the objects
-that can be generated by a index are in fact fully-fledged data objects
-respecting the standard protocol for interaction.
+As noted above, there are numerous types of objects. Here we group them
+into:
-The following objects are available, all of which hang off of the index
-object. To access them, you would do something like this (as for a
-:class:`region`):
+* *Geometric Objects* - Data is selected based on spatial shapes in the dataset
+* *Filtering Objects* - Data is selected based on other field criteria
+* *Collection Objects* - Multiple objects grouped together
+* *Construction Objects* - Objects represent some sort of data product
+constructed by additional analysis
+
+If you want to create your own custom data object type, see
+:ref:`creating-objects`.
+
+Geometric Objects
+^^^^^^^^^^^^^^^^^
+
+For 0D, 1D, and 2D geometric objects, if the extent of the object
+intersects a grid cell, then the cell is included in the object; however,
+for 3D objects the *center* of the cell must be within the object in order
+for the grid cell to be incorporated.
+
+0D Objects
+""""""""""
+
+**Point**
+ | Class :class:`~yt.data_objects.data_containers.YTPointBase`
+ | Usage: ``point(coord, ds=None, field_parameters=None)``
+ | A point defined by a single cell at specified coordinates.
+
+1D Objects
+""""""""""
+
+**Ray (Axis-Aligned)**
+ | Class :class:`~yt.data_objects.data_containers.YTOrthoRayBase`
+ | Usage: ``ortho_ray(axis, coord, ds=None, field_parameters=None)``
+ | A line (of data cells) stretching through the full domain
+ aligned with one of the x,y,z axes. Defined by an axis and a point
+ to be intersected.
+
+**Ray (Arbitrarily-Aligned)**
+ | Class :class:`~yt.data_objects.data_containers.YTRayBase`
+ | Usage: ``ray(start_coord, end_coord, ds=None, field_parameters=None)``
+ | A line (of data cells) defined by arbitrary start and end coordinates.
+
+2D Objects
+""""""""""
+
+**Slice (Axis-Aligned)**
+ | Class :class:`~yt.data_objects.data_containers.YTSliceBase`
+ | Usage: ``slice(axis, coord, center=None, ds=None, field_parameters=None)``
+ | A plane normal to one of the axes and intersecting a particular
+ coordinate.
+
+**Slice (Arbitrarily-Aligned)**
+ | Class :class:`~yt.data_objects.data_containers.YTCuttingPlaneBase`
+ | Usage: ``cutting(normal, coord, north_vector=None, ds=None, field_parameters=None)``
+ | A plane normal to a specified vector and intersecting a particular
+ coordinate.
+
+3D Objects
+""""""""""
+
+**All Data**
+ | Class :fun:`~yt.data_objects.static_output.Dataset.all_data`
+ | Usage: ``all_data(find_max=False)``
+ | ``all_data()`` is a wrapper on the Box Region class which defaults to
+ creating a Region covering the entire dataset domain. It is effectively
+ ``ds.region(ds.domain_center, ds.domain_left_edge, ds.domain_right_edge)``.
+
+**Box Region**
+ | Class :class:`~yt.data_objects.data_containers.YTRegionBase`
+ | Usage: ``region(center, left_edge, right_edge, fields=None, ds=None, field_parameters=None)``
+ | Alternatively: ``box(left_edge, right_edge, fields=None, ds=None, field_parameters=None)``
+ | A box-like region aligned with the grid axis orientation. It is
+ defined by a left_edge, a right_edge, and a center. The left_edge
+ and right_edge are the minimum and maximum bounds in the three axes
+ respectively. The center is arbitrary and must only be contained within
+ the left_edge and right_edge. By using the ``box`` wrapper, the center
+ is assumed to be the midpoint between the left and right edges.
+
+**Disk/Cylinder**
+ | Class: :class:`~yt.data_objects.data_containers.YTDiskBase`
+ | Usage: ``disk(center, normal, radius, height, fields=None, ds=None, field_parameters=None)``
+ | A cylinder defined by a point at the center of one of the circular bases,
+ a normal vector to it defining the orientation of the length of the
+ cylinder, and radius and height values for the cylinder's dimensions.
+
+**Ellipsoid**
+ | Class :class:`~yt.data_objects.data_containers.YTEllipsoidBase`
+ | Usage: ``ellipsoid(center, semi_major_axis_length, semi_medium_axis_length, semi_minor_axis_length, semi_major_vector, tilt, fields=None, ds=None, field_parameters=None)``
+ | An ellipsoid with axis magnitudes set by semi_major_axis_length,
+ semi_medium_axis_length, and semi_minor_axis_length. semi_major_vector
+ sets the direction of the semi_major_axis. tilt defines the orientation
+ of the semi-medium and semi_minor axes.
+
+**Sphere**
+ | Class :class:`~yt.data_objects.data_containers.YTSphereBase`
+ | Usage: ``sphere(center, radius, ds=None, field_parameters=None)``
+ | A sphere defined by a central coordinate and a radius.
+
+
+Filtering and Collection Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+See also the section on :ref:`filtering-data`.
+
+**Boolean Regions**
+ | **Note: not yet implemented in yt 3.0**
+ | Usage: ``boolean()``
+ See :ref:`boolean-data-objects`.
+
+**Filter**
+ | Class :class:`~yt.data_objects.data_containers.YTCutRegionBase`
+ | Usage: ``cut_region(base_object, conditionals, ds=None, field_parameters=None)``
+ | A ``cut_region`` is a filter which can be applied to any other data
+ object. The filter is defined by the conditionals present, which
+ apply cuts to the data in the object. A ``cut_region`` will work
+ for either particle fields or mesh fields, but not on both simulaneously.
+ For more detailed information and examples, see :ref:`cut-regions`.
+
+**Collection of Data Objects**
+ | Class :class:`~yt.data_objects.data_containers.YTDataCollectionBase`
+ | Usage: ``data_collection(center, obj_list, ds=None, field_parameters=None)``
+ | A ``data_collection`` is a list of data objects that can be
+ sampled and processed as a whole in a single data object.
+
+Construction Objects
+^^^^^^^^^^^^^^^^^^^^
+
+**Fixed-Resolution Region**
+ | Class :class:`~yt.data_objects.data_containers.YTCoveringGridBase`
+ | Usage: ``covering_grid(level, left_edge, dimensions, fields=None, ds=None, num_ghost_zones=0, use_pbar=True, field_parameters=None)``
+ | A 3D region with all data extracted to a single, specified resolution.
+ See :ref:`examining-grid-data-in-a-fixed-resolution-array`.
+
+**Fixed-Resolution Region with Smoothing**
+ | Class :class:`~yt.data_objects.data_containers.YTSmoothedCoveringGridBase`
+ | Usage: ``smoothed_covering_grid(level, left_edge, dimensions, fields=None, ds=None, num_ghost_zones=0, use_pbar=True, field_parameters=None)``
+ | A 3D region with all data extracted and interpolated to a single,
+ specified resolution. Identical to covering_grid, except that it
+ interpolates as necessary from coarse regions to fine. See
+ :ref:`examining-grid-data-in-a-fixed-resolution-array`.
+
+**Fixed-Resolution Region for Particle Deposition**
+ | Class :class:`~yt.data_objects.data_containers.YTArbitraryGridBase`
+ | Usage: ``arbitrary_grid(left_edge, right_edge, dimensions, ds=None, field_parameters=None)``
+ | When particles are deposited on to mesh fields, they use the existing
+ mesh structure, but this may have too much or too little resolution
+ relative to the particle locations (or it may not exist at all!). An
+ `arbitrary_grid` provides a means for generating a new independent mesh
+ structure for particle deposition. See :ref:`arbitrary-grid` for more
+ information.
+
+**Projection**
+ | Class :class:`~yt.data_objects.data_containers.YTQuadTreeProjBase`
+ | Usage: ``proj(field, axis, weight_field=None, center=None, ds=None, data_source=None, style="integrate", field_parameters=None)``
+ | A 2D projection of a 3D volume along one of the axis directions.
+ By default, this is a line integral through the entire simulation volume
+ (although it can be a subset of that volume specified by a data object
+ with the ``data_source`` keyword). Alternatively, one can specify
+ a weight_field and different ``style`` values to change the nature
+ of the projection outcome. See :ref:`projection-types` for more information.
+
+**Streamline**
+ | Class :class:`~yt.data_objects.data_containers.YTStreamlineBase`
+ | Usage: ``streamline(coord_list, length, fields=None, ds=None, field_parameters=None)``
+ | A ``streamline`` can be traced out by identifying a starting coordinate (or
+ list of coordinates) and allowing it to trace a vector field, like gas
+ velocity. See :ref:`streamlines` for more information.
+
+**Surface**
+ | Class :class:`~yt.data_objects.data_containers.YTSurfaceBase`
+ | Usage: ``surface(data_source, field, field_value)``
+ | The surface defined by all an isocontour in any mesh field. An existing
+ data object must be provided as the source, as well as a mesh field
+ and the value of the field which you desire the isocontour. See
+ :ref:`extracting-isocontour-information`.
+
+.. _derived-quantities:
+
+Processing Objects: Derived Quantities
+--------------------------------------
+
+Derived quantities are a way of calculating some bulk quantities associated
+with all of the grid cells contained in a data object.
+Derived quantities can be accessed via the ``quantities`` interface.
+Here is an example of how to get the angular momentum vector calculated from
+all the cells contained in a sphere at the center of our dataset.
.. code-block:: python
- import yt
- ds = yt.load("RedshiftOutput0005")
- reg = ds.region([0.5, 0.5, 0.5], [0.0, 0.0, 0.0], [1.0, 1.0, 1.0])
+ ds = load("my_data")
+ sp = ds.sphere('c', (10, 'kpc'))
+ print ad.quantities.angular_momentum_vector()
-.. include:: _obj_docstrings.inc
+Available Derived Quantities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Angular Momentum Vector**
+ | Class :class:`~yt.data_objects.derived_quantities.AngularMomentumVector`
+ | Usage: ``angular_momentum_vector(use_gas=True, use_particles=True)``
+ | The mass-weighted average angular momentum vector of the particles, gas,
+ or both.
+
+**Bulk Velocity**
+ | Class :class:`~yt.data_objects.derived_quantities.BulkVelocity`
+ | Usage: ``bulk_velocity(use_gas=True, use_particles=True)``
+ | The mass-weighted average velocity of the particles, gas, or both.
+
+**Center of Mass**
+ | Class :class:`~yt.data_objects.derived_quantities.CenterOfMass`
+ | Usage: ``center_of_mass(use_cells=True, use_particles=False)``
+ | The location of the center of mass. By default, it computes of
+ the *non-particle* data in the object, but it can be used on
+ particles, gas, or both.
+
+**Extrema**
+ | Class :class:`~yt.data_objects.derived_quantities.Extrema`
+ | Usage: ``extrema(fields, non_zero=False)``
+ | The extrema of a field or list of fields.
+
+**Maximum Location**
+ | Class :class:`~yt.data_objects.derived_quantities.max_location`
+ | Usage: ``max_location(fields)``
+ | The maximum of a field or list of fields as well
+ as the x,y,z location of that maximum.
+
+**Minimum Location**
+ | Class :class:`~yt.data_objects.derived_quantities.min_location`
+ | Usage: ``min_location(fields)``
+ | The minimum of a field or list of fields as well
+ as the x,y,z location of that minimum.
+
+**Spin Parameter**
+ | Class :class:`~yt.data_objects.derived_quantities.SpinParameter`
+ | Usage: ``spin_parameter(use_gas=True, use_particles=True)``
+ | The spin parameter for the baryons using the particles, gas, or both.
+
+**Total Mass**
+ | Class :class:`~yt.data_objects.derived_quantities.TotalMass`
+ | Usage: ``total_mass()``
+ | The total mass of the object as a tuple of (total gas, total particle)
+ mass.
+
+**Total of a Field**
+ | Class :class:`~yt.data_objects.derived_quantities.TotalQuantity`
+ | Usage: ``total_quantity(fields)``
+ | The sum of a given field (or list of fields) over the entire object.
+
+**Weighted Average of a Field**
+ | Class :class:`~yt.data_objects.derived_quantities.WeightedAverageQuantity`
+ | Usage: ``weighted_average_quantity(fields, weight)``
+ | The weighted average of a field (or list of fields)
+ over an entire data object. If you want an unweighted average,
+ then set your weight to be the field: ``ones``.
+
+**Weighted Variance of a Field**
+ | Class :class:`~yt.data_objects.derived_quantities.WeightedVariance`
+ | Usage: ``weighted_variance(fields, weight)``
+ | The weighted variance of a field (or list of fields)
+ over an entire data object and the weighted mean.
+ If you want an unweighted variance, then
+ set your weight to be the field: ``ones``.
.. _arbitrary-grid:
-Arbitrary Grids
----------------
+Arbitrary Grids Objects for Particle Deposition
+-----------------------------------------------
The covering grid and smoothed covering grid objects mandate that they be
exactly aligned with the mesh. This is a
@@ -195,102 +399,10 @@
Please see the :ref:`cookbook` for some examples of how to use the boolean
data object.
-.. _derived-quantities:
-
-Processing Objects: 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 --
-yt already knows about several. Every 3D data object (see
-:ref:`using-objects`) provides a mechanism for access to derived quantities.
-These can be accessed via the ``quantities`` interface, like so:
-
-.. code-block:: python
-
- ds = load("my_data")
- dd = ds.all_data()
- dd.quantities.angular_momentum_vector()
-
-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["cell_mass"].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.
-
-.. _field_cuts:
-
-Cutting Objects by Field Values
--------------------------------
-
-Data objects can be cut by their field values using the ``cut_region``
-method. For example, this could be used to compute the total gas mass within
-a certain temperature range, as in the following example.
-
-.. notebook-cell::
-
- import yt
- ds = yt.load("enzo_tiny_cosmology/DD0046/DD0046")
- ad = ds.all_data()
- total_mass = ad.quantities.total_quantity('cell_mass')
- # now select only gas with 1e5 K < T < 1e7 K.
- new_region = ad.cut_region(['obj["temperature"] > 1e5',
- 'obj["temperature"] < 1e7'])
- cut_mass = new_region.quantities.total_quantity('cell_mass')
- print "The fraction of mass in this temperature range is %f." % \
- (cut_mass / total_mass)
-
-The ``cut_region`` function generates a new object containing only the cells
-that meet all of the specified criteria. The sole argument to ``cut_region``
-is a list of strings, where each string is evaluated with an ``eval``
-statement. ``eval`` is a native Python function that evaluates a string as
-a Python expression. Any type of data object can be cut with ``cut_region``.
-Objects generated with ``cut_region`` can be used in the same way as all
-other data objects. For example, a cut region can be visualized by giving
-it as a data_source to a projection.
-
-.. python-script::
-
- import yt
- ds = yt.load("enzo_tiny_cosmology/DD0046/DD0046")
- ad = ds.all_data()
- new_region = ad.cut_region(['obj["density"] > 1e-29'])
- plot = yt.ProjectionPlot(ds, "x", "density", weight_field="density",
- data_source=new_region)
- plot.save()
-
.. _extracting-connected-sets:
-Connected Sets
---------------
+Connected Sets and Clump Finding
+--------------------------------
The underlying machinery used in :ref:`clump_finding` is accessible from any
data object. This includes the ability to obtain and examine topologically
@@ -318,30 +430,6 @@
contains :class:`~yt.data_objects.data_containers.AMRExtractedRegionBase`
objects. These can be queried just as any other data object.
-.. _extracting-isocontour-information:
-
-Extracting Isocontour Information
----------------------------------
-
-``yt`` contains an implementation of the `Marching Cubes
-<http://en.wikipedia.org/wiki/Marching_cubes>`_ algorithm, which can operate on
-3D data objects. This provides two things. The first is to identify
-isocontours and return either the geometry of those isocontours or to return
-another field value sampled along that isocontour. The second piece of
-functionality is to calculate the flux of a field over an isocontour.
-
-Note that these isocontours are not guaranteed to be topologically connected.
-In fact, inside a given data object, the marching cubes algorithm will return
-all isocontours, not just a single connected one. This means if you encompass
-two clumps of a given density in your data object and extract an isocontour at
-that density, it will include both of the clumps.
-
-To extract geometry or sample a field, call
-:meth:`~yt.data_objects.data_containers.AMR3DData.extract_isocontours`. To
-calculate a flux, call
-:meth:`~yt.data_objects.data_containers.AMR3DData.calculate_isocontour_flux`.
-both of these operations will run in parallel.
-
.. _object-serialization:
Storing and Loading Objects
@@ -361,16 +449,14 @@
has a separate set of serialization operations for 2D objects such as
projections.
-.. _parameter_file_serialization:
-
-``yt`` will save out 3D objects to disk under the presupposition that the
+``yt`` will save out objects to disk under the presupposition that the
construction of the objects is the difficult part, rather than the generation
of the data -- this means that you can save out an object as a description of
how to recreate it in space, but not the actual data arrays affiliated with
that object. The information that is saved includes the dataset off of
which the object "hangs." It is this piece of information that is the most
-difficult; the object, when reloaded, must be able to reconstruct a parameter
-file from whatever limited information it has in the save file.
+difficult; the object, when reloaded, must be able to reconstruct a dataset
+from whatever limited information it has in the save file.
To do this, ``yt`` is able to identify datasets based on a "hash"
generated from the base file name, the "CurrentTimeIdentifier", and the
@@ -379,45 +465,19 @@
conjunction they should be uniquely identifying. (This process is all done in
:mod:`~yt.utilities.ParameterFileStorage` via :class:`~yt.utilities.ParameterFileStorage.ParameterFileStore`.)
-To save an object, you can either save it in the ``.yt`` file affiliated with
-the index or as a standalone file. For instance, using
-:meth:`~yt.data_objects.index.save_object` we can save a sphere.
+You can save objects to an output file using the function
+:meth:`~yt.data_objects.index.save_object`:
.. code-block:: python
import yt
ds = yt.load("my_data")
- sp = ds.sphere([0.5, 0.5, 0.5], 10.0/ds['kpc'])
+ sp = ds.sphere([0.5, 0.5, 0.5], (10.0, 'kpc'))
+ sp.save_object("sphere_name", "save_file.cpkl")
- ds.save_object(sp, "sphere_to_analyze_later")
-
-
-In a later session, we can load it using
-:meth:`~yt.data_objects.index.load_object`:
-
-.. code-block:: python
-
- import yt
-
- ds = yt.load("my_data")
- sphere_to_analyze = ds.load_object("sphere_to_analyze_later")
-
-Additionally, if we want to store the object independent of the ``.yt`` file,
-we can save the object directly:
-
-.. code-block:: python
-
- import yt
-
- ds = yt.load("my_data")
- sp = ds.sphere([0.5, 0.5, 0.5], 10.0/ds['kpc'])
-
- sp.save_object("my_sphere", "my_storage_file.cpkl")
-
-This will store the object as ``my_sphere`` in the file
-``my_storage_file.cpkl``, which will be created or accessed using the standard
-python module :mod:`shelve`. Note that if a filename is not supplied, it will
-be saved via the index, as above.
+This will store the object as ``sphere_name`` in the file
+``save_file.cpkl``, which will be created or accessed using the standard
+python module :mod:`shelve`.
To re-load an object saved this way, you can use the shelve module directly:
@@ -425,17 +485,12 @@
import yt
import shelve
+ ds = yt.load("my_data")
+ saved_fn = shelve.open("save_file.cpkl")
+ ds, sp = saved_fn["sphere_name"]
- ds = yt.load("my_data") # not necessary if storeparameterfiles is on
-
- obj_file = shelve.open("my_storage_file.cpkl")
- ds, obj = obj_file["my_sphere"]
-
-If you have turned on ``storeparameterfiles`` in your configuration,
-you won't need to load the parameterfile again, as the load process
-will actually do that for you in that case. Additionally, we can
-store multiple objects in a single shelve file, so we have to call the
-sphere by name.
+Additionally, we can store multiple objects in a single shelve file, so we
+have to call the sphere by name.
.. note:: It's also possible to use the standard :mod:`cPickle` module for
loading and storing objects -- so in theory you could even save a
@@ -443,4 +498,3 @@
This method works for clumps, as well, and the entire clump index will be
stored and restored upon load.
-
diff -r b2a39372ea82bfa7a22b78af7fddfe6137073a8c -r 76f1cf5a7f78987525c183db3d64a0096a5a21f3 doc/source/analyzing/units/2)_Data_Selection_and_fields.ipynb
--- a/doc/source/analyzing/units/2)_Data_Selection_and_fields.ipynb
+++ /dev/null
@@ -1,462 +0,0 @@
-{
- "metadata": {
- "name": "",
- "signature": "sha256:2faff88abc93fe2bc9d91467db786a8b69ec3ece6783a7055942ecc7c47a0817"
- },
- "nbformat": 3,
- "nbformat_minor": 0,
- "worksheets": [
- {
- "cells": [
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "In the past, querying a data object with a field name returned a NumPy `ndarray` . In the new unit system, data object queries will return a `YTArray`, a subclass of `ndarray` that preserves all of the nice properties of `ndarray`, including broadcasting, deep and shallow copies, and views. "
- ]
- },
- {
- "cell_type": "heading",
- "level": 3,
- "metadata": {},
- "source": [
- "Selecting data from an object"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "`YTArray` is 'unit-aware'. Let's show how this works in practice using a sample Enzo dataset:"
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "import yt\n",
- "ds = yt.load('IsolatedGalaxy/galaxy0030/galaxy0030')\n",
- " \n",
- "dd = ds.all_data()\n",
- "maxval, maxloc = ds.find_max('density')\n",
- "\n",
- "dens = dd['density']"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "print maxval"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "print dens"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "mass = dd['cell_mass']\n",
- "\n",
- "print \"Cell Masses in CGS: \\n\", mass, \"\\n\"\n",
- "print \"Cell Masses in MKS: \\n\", mass.in_mks(), \"\\n\"\n",
- "print \"Cell Masses in Solar Masses: \\n\", mass.in_units('Msun'), \"\\n\"\n",
- "print \"Cell Masses in code units: \\n\", mass.in_units('code_mass'), \"\\n\""
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "dx = dd['dx']\n",
- "print \"Cell dx in code units: \\n\", dx, \"\\n\"\n",
- "print \"Cell dx in centimeters: \\n\", dx.in_cgs(), \"\\n\"\n",
- "print \"Cell dx in meters: \\n\", dx.in_units('m'), \"\\n\"\n",
- "print \"Cell dx in megaparsecs: \\n\", dx.in_units('Mpc'), \"\\n\""
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "heading",
- "level": 3,
- "metadata": {},
- "source": [
- "Unit conversions"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "YTArray defines several user-visible member functions that allow data to be converted from one unit system to another:\n",
- "\n",
- "* `in_units`\n",
- "* `in_cgs`\n",
- "* `in_mks`\n",
- "* `convert_to_units`\n",
- "* `convert_to_cgs`\n",
- "* `convert_to_mks`"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The first method, `in_units`, returns a copy of the array in the units denoted by a string argument:"
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "print dd['density'].in_units('Msun/pc**3')"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "`in_cgs` and `in_mks` return a copy of the array converted CGS and MKS units, respectively:"
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "print (dd['pressure'])\n",
- "print (dd['pressure']).in_cgs()\n",
- "print (dd['pressure']).in_mks()"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "The next two methods do in-place conversions:"
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "dens = dd['density']\n",
- "print dens\n",
- "\n",
- "dens.convert_to_units('Msun/pc**3')\n",
- "print dens"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "One possibly confusing wrinkle when using in-place conversions is if you try to query `dd['density']` again, you'll find that it has been converted to solar masses per cubic parsec:"
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "print dd['density']\n",
- "\n",
- "dens.convert_to_units('g/cm**3')\n",
- "\n",
- "print dens"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Since the unit metadata is preserved and the array values are still correct in the new unit system, all numerical operations will still be correct.\n",
- "\n",
- "One of the nicest aspects of this new unit system is that the symbolic algebra for mathematical operations on data with units is performed automatically by sympy. This example shows how we can construct a field with density units from two other fields that have units of mass and volume:"
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "print dd['cell_mass']\n",
- "print dd['cell_volume'].in_units('cm**3')\n",
- "\n",
- "print (dd['cell_mass']/dd['cell_volume']).in_cgs()"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "heading",
- "level": 3,
- "metadata": {},
- "source": [
- "Working with views and converting to ndarray"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "There are two ways to convert the data into a numpy array. The most straightforward and safe way to do this is to create a copy of the array data. The following cell demonstrates four equivalent ways of doing this, in increasing degree of terseness."
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "import numpy as np\n",
- "\n",
- "dens = dd['cell_mass']\n",
- "\n",
- "print dens.to_ndarray()\n",
- "print np.array(dens)\n",
- "print dens.value\n",
- "print dens.v"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Since we have a copy of the data, we can mess with it however we wish without disturbing the original data returned by the yt data object."
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Another way to touch the raw array data is to get a _view_. A numpy view is a lightweight array interface to a memory buffer. There are four ways to create views of YTArray instances:"
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "print dd['cell_mass'].ndarray_view()\n",
- "print dd['cell_mass'].view(np.ndarray)\n",
- "print dd['cell_mass'].ndview\n",
- "print dd['cell_mass'].d"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "When working with views, rememeber that you are touching the raw array data and no longer have any of the unit checking provided by the unit system. This can be useful where it might be more straightforward to treat the array as if it didn't have units but without copying the data."
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "density_values = dd['density'].d\n",
- "density_values[0:10] = 0\n",
- "\n",
- "# The original array was updated\n",
- "print dd['density']"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "heading",
- "level": 3,
- "metadata": {},
- "source": [
- "Round-Trip Conversions to and from AstroPy's Units System"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Finally, a `YTArray` or `YTQuantity` may be converted to an [AstroPy quantity](http://astropy.readthedocs.org/en/latest/units/), which is a NumPy array or a scalar associated with units from AstroPy's units system. You may use this facility if you have AstroPy installed. "
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Some examples of converting from AstroPy units to yt:"
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "from astropy import units as u\n",
- "from yt import YTQuantity, YTArray\n",
- "\n",
- "x = 42.0 * u.meter\n",
- "y = YTQuantity.from_astropy(x) "
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "print x, type(x)\n",
- "print y, type(y)"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "a = np.random.random(size=10) * u.km/u.s\n",
- "b = YTArray.from_astropy(a)"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "print a, type(a)\n",
- "print b, type(b)"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "It also works the other way around, converting a `YTArray` or `YTQuantity` to an AstroPy quantity via the method `to_astropy`. For arrays:"
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "temp = dd[\"temperature\"]\n",
- "atemp = temp.to_astropy()"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "print temp, type(temp)\n",
- "print atemp, type(atemp)"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "and quantities:"
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "from yt.utilities.physical_constants import kboltz\n",
- "kb = kboltz.to_astropy()"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "print kboltz, type(kboltz)\n",
- "print kb, type(kb)"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "As a sanity check, you can show that it works round-trip:"
- ]
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "k1 = kboltz.to_astropy()\n",
- "k2 = YTQuantity.from_astropy(kb)\n",
- "print k1 == k2"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- },
- {
- "cell_type": "code",
- "collapsed": false,
- "input": [
- "c = YTArray.from_astropy(a)\n",
- "d = c.to_astropy()\n",
- "print a == d"
- ],
- "language": "python",
- "metadata": {},
- "outputs": []
- }
- ],
- "metadata": {}
- }
- ]
-}
\ No newline at end of file
This diff is so big that we needed to truncate the remainder.
Repository URL: https://bitbucket.org/yt_analysis/yt/
--
This is a commit notification from bitbucket.org. You are receiving
this because you have the service enabled, addressing the recipient of
this email.
More information about the yt-svn
mailing list