[yt-svn] commit/yt: chummels: Merged in chummels/yt/yt-3.0 (pull request #1119)
commits-noreply at bitbucket.org
commits-noreply at bitbucket.org
Sat Aug 2 05:08:11 PDT 2014
1 new commit in yt:
https://bitbucket.org/yt_analysis/yt/commits/2ad686b9cb30/
Changeset: 2ad686b9cb30
Branch: yt-3.0
User: chummels
Date: 2014-08-02 14:07:59
Summary: Merged in chummels/yt/yt-3.0 (pull request #1119)
Docs updates
Affected #: 22 files
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/helper_scripts/show_fields.py
--- a/doc/helper_scripts/show_fields.py
+++ b/doc/helper_scripts/show_fields.py
@@ -57,10 +57,11 @@
Field List
==========
-This is a list of many of the fields available in ``yt``. We have attempted to
+This is a list of many of the fields available in yt. We have attempted to
include most of the fields that are accessible through the plugin system,
however it is possible to generate many more permutations, particularly through
-vector operations.
+vector operations. For more information about the fields framework,
+see :ref:`fields`.
Try using the ``ds.field_list`` and ``ds.derived_field_list`` to view the
native and derived fields available for your dataset respectively. For example
@@ -73,6 +74,8 @@
for i in sorted(ds.field_list):
print i
+To figure out out what all of the field types here mean, see
+:ref:`known-field-types`.
"""
print header
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/analyzing/analysis_modules/halo_analysis.rst
--- a/doc/source/analyzing/analysis_modules/halo_analysis.rst
+++ b/doc/source/analyzing/analysis_modules/halo_analysis.rst
@@ -7,7 +7,7 @@
and using the halo mass function.
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
halo_transition
halo_catalogs
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/analyzing/analysis_modules/halo_catalogs.rst
--- a/doc/source/analyzing/analysis_modules/halo_catalogs.rst
+++ b/doc/source/analyzing/analysis_modules/halo_catalogs.rst
@@ -241,4 +241,4 @@
----------------------------------------
For a full example of how to use these methods together see
-:ref:`halo_analysis_example`.
+:ref:`halo-analysis-example`.
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/analyzing/analysis_modules/particle_trajectories.rst
--- a/doc/source/analyzing/analysis_modules/particle_trajectories.rst
+++ b/doc/source/analyzing/analysis_modules/particle_trajectories.rst
@@ -1,3 +1,5 @@
+.. _particle-trajectories:
+
Particle Trajectories
---------------------
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/analyzing/analysis_modules/synthetic_observation.rst
--- a/doc/source/analyzing/analysis_modules/synthetic_observation.rst
+++ b/doc/source/analyzing/analysis_modules/synthetic_observation.rst
@@ -5,13 +5,12 @@
from simulation data.
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
light_cone_generator
light_ray_generator
planning_cosmology_simulations
absorption_spectrum
- fitting_procedure
star_analysis
xray_emission_fields
sunyaev_zeldovich
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/analyzing/external_analysis.rst
--- a/doc/source/analyzing/external_analysis.rst
+++ b/doc/source/analyzing/external_analysis.rst
@@ -15,10 +15,10 @@
.. code-block:: python
- from yt.mods import *
+ import yt
import radtrans
- ds = load("DD0010/DD0010")
+ ds = yt.load("DD0010/DD0010")
rt_grids = []
for grid in ds.index.grids:
@@ -36,13 +36,13 @@
.. code-block:: python
- from yt.mods import *
+ import yt
import pop_synthesis
- ds = load("DD0010/DD0010")
- dd = ds.all_data()
- star_masses = dd["StarMassMsun"]
- star_metals = dd["StarMetals"]
+ ds = yt.load("DD0010/DD0010")
+ ad = ds.all_data()
+ star_masses = ad["StarMassMsun"]
+ star_metals = ad["StarMetals"]
pop_synthesis.CalculateSED(star_masses, star_metals)
@@ -94,11 +94,11 @@
There are several components to this analysis routine which we will have to
wrap.
- #. We have to wrap the creation of an instance of ``ParticleCollection``.
- #. We have to transform a set of NumPy arrays into pointers to doubles.
- #. We have to create a set of doubles into which ``calculate_axes`` will be
- placing the values of the axes it calculates.
- #. We have to turn the return values back into Python objects.
+#. We have to wrap the creation of an instance of ``ParticleCollection``.
+#. We have to transform a set of NumPy arrays into pointers to doubles.
+#. We have to create a set of doubles into which ``calculate_axes`` will be
+ placing the values of the axes it calculates.
+#. We have to turn the return values back into Python objects.
Each of these steps can be handled in turn, and we'll be doing it using Cython
as our interface code.
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/analyzing/fields.rst
--- a/doc/source/analyzing/fields.rst
+++ b/doc/source/analyzing/fields.rst
@@ -3,6 +3,8 @@
Fields in yt
============
+Fields are spatially-dependent quantities associated with a parent dataset.
+Examples of fields are gas density, gas temperature, particle mass, etc.
The fundamental way to query data in yt is to access a field, either in its raw
form (by examining a data container) or a processed form (derived quantities,
projections, and so on). "Field" is something of a loaded word, as it can
@@ -62,7 +64,7 @@
step.
How are fields implemented?
-+++++++++++++++++++++++++++
+---------------------------
There are two classes of fields in yt. The first are those fields that exist
external to yt, which are immutable and can be queried -- most commonly, these
@@ -90,22 +92,137 @@
For more information, see :ref:`creating-derived-fields`.
There is a third, borderline class of field in yt, as well. This is the
-"alias" type, where a field on disk (for example, ``Density``) is aliased into
-an internal yt-name (for example, ``density``). The aliasing process allows
-universally-defined derived fields to take advantage of internal names, and it
-also provides an easy way to address what units something should be returned
-in. If an aliased field is requested (and aliased fields will always be
-lowercase, with underscores separating words) it will be returned in CGS units
-(future versions will enable global defaults to be set for MKS and other unit
-systems), whereas if the underlying field is requested, it will not undergo any
-unit conversions from its natural units. (This rule is occasionally violated
-for fields which are mesh-dependent, specifically particle masses in some
-cosmology codes.)
+"alias" type, where a field on disk (for example, (frontend, ``Density``)) is
+aliased into an internal yt-name (for example, (``gas``, ``density``)). The
+aliasing process allows universally-defined derived fields to take advantage of
+internal names, and it also provides an easy way to address what units something
+should be returned in. If an aliased field is requested (and aliased fields
+will always be lowercase, with underscores separating words) it will be returned
+in CGS units (future versions will enable global defaults to be set for MKS and
+other unit systems), whereas if the underlying field is requested, it will not
+undergo any unit conversions from its natural units. (This rule is occasionally
+violated for fields which are mesh-dependent, specifically particle masses in
+some cosmology codes.)
+
+.. _known_field_types:
+
+Field types known to yt
+-----------------------
+
+yt knows of a few different field types:
+
+* frontend-name -- Mesh or fluid fields that exist on-disk default to having
+ the name of the frontend as their type name (e.g., ``enzo``, ``flash``,
+ ``pyne`` and so on). The units of these types are whatever units are
+ designated by the source frontend when it writes the data.
+* ``index`` -- This field type refers to characteristics of the mesh, whether
+ that mesh is defined by the simulation or internally by an octree indexing
+ of particle data. A few handy fields are ``x``, ``y``, ``z``, ``theta``,
+ ``phi``, ``radius``, ``dx``, ``dy``, ``dz`` and so on. Default units
+ are in CGS.
+* ``gas`` -- This is the usual default for simulation frontends for fluid
+ types. These fields are typically aliased to the frontend-specific mesh
+ fields for grid-based codes or to the deposit fields for particle-based
+ codes. Default units are in CGS.
+* particle type -- These are particle fields that exist on-disk as written
+ by individual frontends. If the frontend designates names for these particles
+ (i.e. particle type) those names are the field types.
+ Additionally, any particle unions or filters will be accessible as field
+ types. Examples of particle types are ``Stars``, ``DM``, ``io``, etc.
+ Like the front-end specific mesh or fluid fields, the units of these fields
+ are whatever was designated by the source frontend when written to disk.
+* ``io`` -- If a data frontend does not have a set of multiple particle types,
+ this is the default for all particles.
+* ``all`` -- This is a special particle field type that represents a
+ concatenation of all particle field types using :ref:`particle-unions`.
+* ``deposit`` -- This field type refers to the deposition of particles
+ (discrete data) onto a mesh, typically to compute smoothing kernels, local
+ density estimates, counts, and the like. See :ref:`deposited-particle-fields`
+ for more information.
+
+Field Plugins
+-------------
+
+Derived fields are organized via plugins. Inside yt are a number of field
+plugins, which take information about fields in a dataset and then construct
+derived fields on top of them. This allows them to take into account
+variations in naming system, units, data representations, and most importantly,
+allows only the fields that are relevant to be added. This system will be
+expanded in future versions to enable much deeper semantic awareness of the
+data types being analyzed by yt.
+
+The field plugin system works in this order:
+
+ * Available, inherent fields are identified by yt
+ * The list of enabled field plugins is iterated over. Each is called, and new
+ derived fields are added as relevant.
+ * Any fields which are not available, or which throw errors, are discarded.
+ * Remaining fields are added to the list of derived fields available for a
+ dataset
+ * Dependencies for every derived field are identified, to enable data
+ preloading
+
+Field plugins can be loaded dynamically, although at present this is not
+particularly useful. Plans for extending field plugins to dynamically load, to
+enable simple definition of common types (gradient, divergence, etc), and to
+more verbosely describe available fields, have been put in place for future
+versions.
+
+The field plugins currently available include:
+
+ * Angular momentum fields for particles and fluids
+ * Astrophysical fields, such as those related to cosmology
+ * Vector fields for fluid fields, such as gradients and divergences
+ * Particle vector fields
+ * Magnetic field-related fields
+ * Species fields, such as for chemistry species (yt can recognize the entire
+ periodic table in field names and construct ionization fields as need be)
+
+What fields are available?
+--------------------------
+
+We provide a full list of fields that yt recognizes by default at
+:ref:`field-list`. If you want to create additional custom derived fields,
+see :ref:`creating-derived-fields`.
+
+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
+---------------
+
+Naturally, particle fields contain properties of particles rather than
+grid cells. By examining the particle field in detail, you can see that
+each element of the field array represents a single particle, whereas in mesh
+fields each element represents a single mesh cell. This means that for the
+most part, operations cannot operate on both particle fields and mesh fields
+simultaneously in the same way, like filters (see :ref:`filtering-data`).
+However, many of the particle fields have corresponding mesh fields that
+can be populated by "depositing" the particle values onto a yt grid as
+described below.
.. _field_parameters:
Field Parameters
-++++++++++++++++
+----------------
Certain fields require external information in order to be calculated. For
example, the radius field has to be defined based on some point of reference
@@ -144,114 +261,16 @@
For a practical application of this, see :ref:`cookbook-radial-velocity`.
-Field types known to yt
-+++++++++++++++++++++++
-
-yt knows of a few different field types, by default.
-
- * ``index`` - this field type refers to characteristics of the mesh, whether
- that mesh is defined by the simulation or internally by an octree indexing
- of particle data. A few handy fields are ``x``, ``y``, ``z``, ``theta``,
- ``phi``, ``radius``, ``dx``, ``dy``, ``dz`` and so on.
- * ``gas`` - this is the usual default for simulation frontends for fluid
- types.
- * ``all`` - this is a special particle field type that represents a
- concatenation of all particle field types.
- * ``deposit`` - this field type refers to the deposition of particles
- (discrete data) onto a mesh, typically to compute smoothing kernels, local
- density estimates, counts, and the like.
- * ``io`` - if a data frontend does not have a set of particle types, this will
- be the default for particle types.
- * frontend-name - mesh or fluid fields that exist on-disk default to having
- the name of the frontend as their type name. (i.e., ``enzo``, ``flash``,
- ``pyne`` and so on.)
- * particle type - if the particle types in the file are affiliated with names
- (rather than just ``io``) they will be available as field types.
- Additionally, any particle unions or filters will be accessible as field
- types.
-
-Field Plugins
-+++++++++++++
-
-Derived fields are organized via plugins. Inside yt are a number of field
-plugins, which take information about fields in a dataset and then construct
-derived fields on top of them. This allows them to take into account
-variations in naming system, units, data representations, and most importantly,
-allows only the fields that are relevant to be added. This system will be
-expanded in future versions to enable much deeper semantic awareness of the
-data types being analyzed by yt.
-
-The field plugin system works in this order:
-
- * Available, inherent fields are identified by yt
- * The list of enabled field plugins is iterated over. Each is called, and new
- derived fields are added as relevant.
- * Any fields which are not available, or which throw errors, are discarded.
- * Remaining fields are added to the list of derived fields available for a
- dataset
- * Dependencies for every derived field are identified, to enable data
- preloading
-
-Field plugins can be loaded dynamically, although at present this is not
-particularly useful. Plans for extending field plugins to dynamically load, to
-enable simple definition of common types (gradient, divergence, etc), and to
-more verbosely describe available fields, have been put in place for future
-versions.
-
-The field plugins currently available include:
-
- * Angular momentum fields for particles and fluids
- * Astrophysical fields, such as those related to cosmology
- * Vector fields for fluid fields, such as gradients and divergences
- * Particle vector fields
- * Magnetic field-related fields
- * Species fields, such as for chemistry species (yt can recognize the entire
- periodic table in field names and construct ionization fields as need be)
-
-What fields are available?
-++++++++++++++++++++++++++
-
-.. 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
----------------
-
-Naturally, particle fields contain properties of particles rather than
-grid cells. Many of these fields have corresponding grid fields that
-can be populated by "depositing" the particle values onto a yt grid.
-
General Particle Fields
-+++++++++++++++++++++++
+-----------------------
Every particle will contain both a ``particle_position`` and ``particle_velocity``
that tracks the position and velocity (respectively) in code units.
-
.. _deposited-particle-fields:
Deposited Particle Fields
-+++++++++++++++++++++++++
+-------------------------
In order to turn particle (discrete) fields into fields that are deposited in
some regular, space-filling way (even if that space is empty, it is defined
@@ -269,25 +288,25 @@
somewhat outside the scope of this section. The default deposition types
available are:
- * ``count`` - this field counts the total number of particles of a given type
- in a given mesh zone. Note that because, in general, the mesh for particle
- datasets is defined by the number of particles in a region, this may not be
- the most useful metric. This may be made more useful by depositing particle
- data onto an :ref:`arbitrary-grid`.
- * ``density`` - this field takes the total sum of ``particle_mass`` in a given
- mesh field and divides by the volume.
- * ``mass`` - this field takes the total sum of ``particle_mass`` in each mesh
- zone.
- * ``cic`` - this field performs cloud-in-cell interpolation (see `Section 2.2
- <http://ta.twi.tudelft.nl/dv/users/Lemmens/MThesis.TTH/chapter4.html>`_ for more
- information) of the density of particles in a given mesh zone.
- * ``smoothed`` - this is a special deposition type. See discussion below for
- more information, in :ref:`sph-fields`.
+* ``count`` - this field counts the total number of particles of a given type
+ in a given mesh zone. Note that because, in general, the mesh for particle
+ datasets is defined by the number of particles in a region, this may not be
+ the most useful metric. This may be made more useful by depositing particle
+ data onto an :ref:`arbitrary-grid`.
+* ``density`` - this field takes the total sum of ``particle_mass`` in a given
+ mesh field and divides by the volume.
+* ``mass`` - this field takes the total sum of ``particle_mass`` in each mesh
+ zone.
+* ``cic`` - this field performs cloud-in-cell interpolation (see `Section 2.2
+ <http://ta.twi.tudelft.nl/dv/users/Lemmens/MThesis.TTH/chapter4.html>`_ for more
+ information) of the density of particles in a given mesh zone.
+* ``smoothed`` - this is a special deposition type. See discussion below for
+ more information, in :ref:`sph-fields`.
.. _sph-fields:
SPH Fields
-++++++++++
+----------
For gas particles from SPH simulations, each particle will typically carry
a field for the smoothing length ``h``, which is roughly equivalent to
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/developing/building_the_docs.rst
--- a/doc/source/developing/building_the_docs.rst
+++ b/doc/source/developing/building_the_docs.rst
@@ -1,8 +1,77 @@
+.. _documentation:
+
+Documentation
+=============
+
+.. _writing_documentation:
+
+How to Write Documentation
+--------------------------
+
+Writing documentation is one of the most important but often overlooked tasks
+for increasing yt's impact in the community. It is the way in which the
+world will understand how to use our code, so it needs to be done concisely
+and understandably. Typically, when a developer submits some piece of code
+with new functionality, she should also include documentation on how to use
+that functionality (as per :ref:`requirements-for-code-submission`).
+Depending on the nature of the code addition, this could be a new narrative
+docs section describing how the new code works and how to use it, it could
+include a recipe in the cookbook section, or it could simply be adding a note
+in the relevant docs text somewhere.
+
+The documentation exists in the main mercurial code repository for yt in the
+``doc`` directory (i.e. ``$YT_HG/doc/source`` where ``$YT_HG`` is the path of
+the yt mercurial repository). It is organized hierarchically into the main
+categories of:
+
+* Visualizing
+* Analyzing
+* Examining
+* Cookbook
+* Bootcamp
+* Developing
+* Reference
+* Help
+
+You will have to figure out where your new/modified doc fits into this, but
+browsing through the pre-built documentation is a good way to sort that out.
+
+All the source for the documentation is written in
+`Sphinx <http://sphinx-doc.org/>`_, which uses ReST for markup. ReST is very
+straightforward to markup in a text editor, and if you are new to it, we
+recommend just using other .rst files in the existing yt documentation as
+templates or checking out the
+`ReST reference documentation <http://sphinx-doc.org/rest.html>`_.
+
+New cookbook recipes (see :ref:`cookbook`) are very helpful for the community
+as they provide simple annotated recipes on how to use specific functionality.
+To add one, create a concise python script which demonstrates some
+functionality and pare it down to its minimum. Add some comment lines to
+describe what it is that you're doing along the way. Place this ``.py`` file
+in the ``source/cookbook/`` directory, and then link to it explicitly in one
+of the relevant ``.rst`` files in that directory (e.g. ``complex_plots.rst``,
+``cosmological_analysis.rst``, etc.), and add some description of what the script
+actually does. We recommend that you use one of the
+`sample data sets <http://yt-project.org/data>`_ in your recipe. When the full
+docs are built, each of the cookbook recipes are executed dynamically on
+a system which has access to all of the sample datasets. Any output images
+generated by your script will then be attached inline in the built documentation
+directly following your script.
+
+After you have made your modifications to the docs, you will want to make sure
+that they render the way you expect them to render. For more information on
+this, see the section on :ref:`docs_build`. Unless you're contributing cookbook
+recipes or notebooks which require a dynamical build, you can probably get
+away with just doing a 'quick' docs build.
+
+When you have completed your documentation additions, commit your changes
+to your repository and make a pull request in the same way you would contribute
+a change to the codebase, as described in the section on :ref:`sharing-changes`.
+
.. _docs_build:
-==========================
Building the Documentation
-==========================
+--------------------------
The yt documentation makes heavy use of the sphinx documentation automation
suite. Sphinx, written in python, was originally created for the documentation
@@ -14,8 +83,8 @@
build time by sphinx. We also use sphinx to run code snippets (e.g. the
cookbook and the notebooks) and embed resulting images and example data.
-Quick versus full documentation builds
---------------------------------------
+Quick versus Full Documentation Builds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Building the entire set of yt documentation is a laborious task, since you
need to have a large number of packages in order to successfully execute
@@ -31,8 +100,8 @@
to follow the instructions for building the ``full`` docs, so that you can
dynamically execute and render the cookbook recipes, the notebooks, etc.
-Building the docs (quick)
--------------------------
+Building the Docs (Quick)
+^^^^^^^^^^^^^^^^^^^^^^^^^
You will need to have the yt repository available on your computer, which
is done by default if you have yt installed. In addition, you need a
@@ -62,8 +131,8 @@
``$YT_HG/doc/build/html`` directory. You can now go there and open
up ``index.html`` or whatever file you wish in your web browser.
-Building the docs (full)
-------------------------
+Building the Docs (Full)
+^^^^^^^^^^^^^^^^^^^^^^^^
As alluded to earlier, building the full documentation is a bit more involved
than simply building the static documentation.
@@ -85,15 +154,15 @@
supplementary yt analysis modules installed. The following dependencies were
used to generate the yt documentation during the release of yt 2.6 in late 2013.
-- Sphinx_ 1.1.3
-- IPython_ 1.1
-- runipy_ (git hash f74458c2877)
-- pandoc_ 1.11.1
-- Rockstar halo finder 0.99.6
-- SZpack_ 1.1.1
-- ffmpeg_ 1.2.4 (compiled with libvpx support)
-- JSAnimation_ (git hash 1b95cb3a3a)
-- Astropy_ 0.2.5
+* Sphinx_ 1.1.3
+* IPython_ 1.1
+* runipy_ (git hash f74458c2877)
+* pandoc_ 1.11.1
+* Rockstar halo finder 0.99.6
+* SZpack_ 1.1.1
+* ffmpeg_ 1.2.4 (compiled with libvpx support)
+* JSAnimation_ (git hash 1b95cb3a3a)
+* Astropy_ 0.2.5
.. _SZpack: http://www.cita.utoronto.ca/~jchluba/Science_Jens/SZpack/SZpack.html
.. _Astropy: http://astropy.org/
@@ -130,8 +199,8 @@
will not delete the autogenerated API docs, so use :code:`make fullclean` to
delete those as well.
-Building the docs (hybrid)
---------------------------
+Building the Docs (Hybrid)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
It's also possible to create a custom sphinx build that builds a restricted set
of notebooks or scripts. This can be accomplished by editing the Sphinx
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/developing/debugdrive.rst
--- a/doc/source/developing/debugdrive.rst
+++ b/doc/source/developing/debugdrive.rst
@@ -1,9 +1,9 @@
.. _debug-drive:
-Debugging and Driving YT
-========================
+Debugging yt
+============
-There are several different convenience functions that allow you to control YT
+There are several different convenience functions that allow you to control yt
in perhaps unexpected and unorthodox manners. These will allow you to conduct
in-depth debugging of processes that may be running in parallel on multiple
processors, as well as providing a mechanism of signalling to yt that you need
@@ -20,8 +20,8 @@
.. _pastebin:
-The Pastebin
-------------
+Pastebin
+--------
A pastebin is a website where you can easily copy source code and error
messages to share with yt developers or your collaborators. At
@@ -47,24 +47,12 @@
The snippet will be output to the window, so output redirection can be used to
store it in a file.
-.. _error-reporting:
+Use the Python Debugger
+-----------------------
-Error Reporting with the Pastebin
-+++++++++++++++++++++++++++++++++
-
-If you are having troubles with yt, you can have it paste the error report
-to the pastebin by running your problematic script with the ``--paste`` option:
-
-.. code-block:: bash
-
- $ python2.7 some_problematic_script.py --paste
-
-The ``--paste`` option has to come after the name of the script. When the
-script dies and prints its error, it will also submit that error to the
-pastebin and return a URL for the error. When reporting your bug, include this
-URL and then the problem can be debugged more easily.
-
-For more information on asking for help, see `asking-for-help`.
+yt is almost entirely composed of python code, so it makes sense to use
+the python debugger as your first stop in trying to debug it:
+`https://docs.python.org/2/library/pdb.html`_
Signaling yt to Do Something
----------------------------
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/developing/developing.rst
--- a/doc/source/developing/developing.rst
+++ b/doc/source/developing/developing.rst
@@ -23,28 +23,28 @@
you're new to Mercurial, these three resources are pretty great for learning
the ins and outs:
- * http://hginit.com/
- * http://hgbook.red-bean.com/read/
- * http://mercurial.selenic.com/
+* `http://hginit.com/`_
+* `http://hgbook.red-bean.com/read/`_
+* `http://mercurial.selenic.com/`_
The commands that are essential for using mercurial include:
- * ``hg commit`` which commits changes in the working directory to the
- repository, creating a new "changeset object."
- * ``hg add`` which adds a new file to be tracked by mercurial. This does
- not change the working directory.
- * ``hg pull`` which pulls (from an optional path specifier) changeset
- objects from a remote source. The working directory is not modified.
- * ``hg push`` which sends (to an optional path specifier) changeset objects
- to a remote source. The working directory is not modified.
- * ``hg log`` which shows a log of all changeset objects in the current
- repository. Use ``-g`` to show a graph of changeset objects and their
- relationship.
- * ``hg update`` which (with an optional "revision" specifier) updates the
- state of the working directory to match a changeset object in the
- repository.
- * ``hg merge`` which combines two changesets to make a union of their lines
- of development. This updates the working directory.
+* ``hg commit`` which commits changes in the working directory to the
+ repository, creating a new "changeset object."
+* ``hg add`` which adds a new file to be tracked by mercurial. This does
+ not change the working directory.
+* ``hg pull`` which pulls (from an optional path specifier) changeset
+ objects from a remote source. The working directory is not modified.
+* ``hg push`` which sends (to an optional path specifier) changeset objects
+ to a remote source. The working directory is not modified.
+* ``hg log`` which shows a log of all changeset objects in the current
+ repository. Use ``-g`` to show a graph of changeset objects and their
+ relationship.
+* ``hg update`` which (with an optional "revision" specifier) updates the
+ state of the working directory to match a changeset object in the
+ repository.
+* ``hg merge`` which combines two changesets to make a union of their lines
+ of development. This updates the working directory.
Keep in touch, and happy hacking! We also provide `doc/coding_styleguide.txt`
and an example of a fiducial docstring in `doc/docstring_example.txt`. Please
@@ -87,26 +87,26 @@
<https://ytep.readthedocs.org/en/latest/YTEPs/YTEP-0008.html>`_ for more
detail.)
- * New Features
+* New Features
- * New unit tests (possibly new answer tests) (See :ref:`testing`)
- * Docstrings in the source code for the public API
- * Addition of new feature to the narrative documentation (See :ref:`writing_documentation`)
- * Addition of cookbook recipe (See :ref:`writing_documentation`)
- * Issue created on issue tracker, to ensure this is added to the changelog
+ * New unit tests (possibly new answer tests) (See :ref:`testing`)
+ * Docstrings in the source code for the public API
+ * Addition of new feature to the narrative documentation (See :ref:`writing_documentation`)
+ * Addition of cookbook recipe (See :ref:`writing_documentation`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
- * Extension or Breakage of API in Existing Features
+* Extension or Breakage of API in Existing Features
- * Update existing narrative docs and docstrings (See :ref:`writing_documentation`)
- * Update existing cookbook recipes (See :ref:`writing_documentation`)
- * Modify of create new unit tests (See :ref:`testing`)
- * Issue created on issue tracker, to ensure this is added to the changelog
+ * Update existing narrative docs and docstrings (See :ref:`writing_documentation`)
+ * Update existing cookbook recipes (See :ref:`writing_documentation`)
+ * Modify of create new unit tests (See :ref:`testing`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
- * Bug fixes
+* Bug fixes
- * Unit test is encouraged, to ensure breakage does not happen again in the
- future. (See :ref:`testing`)
- * Issue created on issue tracker, to ensure this is added to the changelog
+ * Unit test is encouraged, to ensure breakage does not happen again in the
+ future. (See :ref:`testing`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
When submitting, you will be asked to make sure that your changes meet all of
these requirements. They are pretty easy to meet, and we're also happy to help
@@ -122,22 +122,22 @@
walk you through any troubles you might have. Here are some suggestions
for using mercurial with yt:
- * Named branches are to be avoided. Try using bookmarks (``hg bookmark``) to
- track work. (`More <http://mercurial.selenic.com/wiki/Bookmarks>`_)
- * Make sure you set a username in your ``~/.hgrc`` before you commit any
- changes! All of the tutorials above will describe how to do this as one of
- the very first steps.
- * When contributing changes, you might be asked to make a handful of
- modifications to your source code. We'll work through how to do this with
- you, and try to make it as painless as possible.
- * Please avoid deleting your yt forks, as that eliminates the code review
- process from BitBucket's website.
- * In all likelihood, you only need one fork. To keep it in sync, you can
- sync from the website. (See Bitbucket's `Blog Post
- <http://blog.bitbucket.org/2013/02/04/syncing-and-merging-come-to-bitbucket/>`_
- about this.)
- * If you run into any troubles, stop by IRC (see :ref:`irc`) or the mailing
- list.
+* Named branches are to be avoided. Try using bookmarks (``hg bookmark``) to
+ track work. (`More <http://mercurial.selenic.com/wiki/Bookmarks>`_)
+* Make sure you set a username in your ``~/.hgrc`` before you commit any
+ changes! All of the tutorials above will describe how to do this as one of
+ the very first steps.
+* When contributing changes, you might be asked to make a handful of
+ modifications to your source code. We'll work through how to do this with
+ you, and try to make it as painless as possible.
+* Please avoid deleting your yt forks, as that eliminates the code review
+ process from BitBucket's website.
+* In all likelihood, you only need one fork. To keep it in sync, you can
+ sync from the website. (See Bitbucket's `Blog Post
+ <http://blog.bitbucket.org/2013/02/04/syncing-and-merging-come-to-bitbucket/>`_
+ about this.)
+* If you run into any troubles, stop by IRC (see :ref:`irc`) or the mailing
+ list.
.. _building-yt:
@@ -192,124 +192,59 @@
The simplest way to submit changes to yt is to do the following:
- * Build yt from the mercurial repository
- * Navigate to the root of the yt repository
- * Make some changes and commit them
- * Fork the `yt repository on BitBucket <https://bitbucket.org/yt_analysis/yt>`_
- * Push the changesets to your fork
- * Issue a pull request.
+* Build yt from the mercurial repository
+* Navigate to the root of the yt repository
+* Make some changes and commit them
+* Fork the `yt repository on BitBucket <https://bitbucket.org/yt_analysis/yt>`_
+* Push the changesets to your fork
+* Issue a pull request.
Here's a more detailed flowchart of how to submit changes.
- #. If you have used the installation script, the source code for yt can be
- found in ``$YT_DEST/src/yt-hg``. Alternatively see
- :ref:`source-installation` for instructions on how to build yt from the
- mercurial repository. (Below, in :ref:`reading-source`, we describe how to
- find items of interest.)
- #. Edit the source file you are interested in and
- test your changes. (See :ref:`testing` for more information.)
- #. Fork yt on BitBucket. (This step only has to be done once.) You can do
- this at: https://bitbucket.org/yt_analysis/yt/fork . Call this repository
- yt.
- #. Commit these changes, using ``hg commit``. This can take an argument
- which is a series of filenames, if you have some changes you do not want
- to commit.
- #. If your changes include new functionality or cover an untested area of the
- code, add a test. (See :ref:`testing` for more information.) Commit
- these changes as well.
- #. Push your changes to your new fork using the command::
+#. If you have used the installation script, the source code for yt can be
+ found in ``$YT_DEST/src/yt-hg``. Alternatively see
+ :ref:`source-installation` for instructions on how to build yt from the
+ mercurial repository. (Below, in :ref:`reading-source`, we describe how to
+ find items of interest.)
+#. Edit the source file you are interested in and
+ test your changes. (See :ref:`testing` for more information.)
+#. Fork yt on BitBucket. (This step only has to be done once.) You can do
+ this at: https://bitbucket.org/yt_analysis/yt/fork . Call this repository
+ yt.
+#. Commit these changes, using ``hg commit``. This can take an argument
+ which is a series of filenames, if you have some changes you do not want
+ to commit.
+#. If your changes include new functionality or cover an untested area of the
+ code, add a test. (See :ref:`testing` for more information.) Commit
+ these changes as well.
+#. Push your changes to your new fork using the command::
- hg push -r . https://bitbucket.org/YourUsername/yt/
+ hg push -r . https://bitbucket.org/YourUsername/yt/
- If you end up doing considerable development, you can set an alias in the
- file ``.hg/hgrc`` to point to this path.
- #. Issue a pull request at
- https://bitbucket.org/YourUsername/yt/pull-request/new
+ If you end up doing considerable development, you can set an alias in the
+ file ``.hg/hgrc`` to point to this path.
+#. Issue a pull request at
+ https://bitbucket.org/YourUsername/yt/pull-request/new
During the course of your pull request you may be asked to make changes. These
changes may be related to style issues, correctness issues, or even requesting
tests. The process for responding to pull request code review is relatively
straightforward.
- #. Make requested changes, or leave a comment indicating why you don't think
- they should be made.
- #. Commit those changes to your local repository.
- #. Push the changes to your fork::
+#. Make requested changes, or leave a comment indicating why you don't think
+ they should be made.
+#. Commit those changes to your local repository.
+#. Push the changes to your fork::
- hg push https://bitbucket.org/YourUsername/yt/
+ hg push https://bitbucket.org/YourUsername/yt/
- #. Your pull request will be automatically updated.
-
-.. _writing_documentation:
-
-How to Write Documentation
---------------------------
-
-Writing documentation is one of the most important but often overlooked tasks
-for increasing yt's impact in the community. It is the way in which the
-world will understand how to use our code, so it needs to be done concisely
-and understandably. Typically, when a developer submits some piece of code
-with new functionality, she should also include documentation on how to use
-that functionality (as per :ref:`requirements-for-code-submission`).
-Depending on the nature of the code addition, this could be a new narrative
-docs section describing how the new code works and how to use it, it could
-include a recipe in the cookbook section, or it could simply be adding a note
-in the relevant docs text somewhere.
-
-The documentation exists in the main mercurial code repository for yt in the
-``doc`` directory (i.e. ``$YT_HG/doc/source`` where ``$YT_HG`` is the path of
-the yt mercurial repository). It is organized hierarchically into the main
-categories of:
-
- * Visualizing
- * Analyzing
- * Examining
- * Cookbook
- * Bootcamp
- * Developing
- * Reference
- * Help
-
-You will have to figure out where your new/modified doc fits into this, but
-browsing through the pre-built documentation is a good way to sort that out.
-
-All the source for the documentation is written in
-`Sphinx <http://sphinx-doc.org/>`_, which uses ReST for markup. ReST is very
-straightforward to markup in a text editor, and if you are new to it, we
-recommend just using other .rst files in the existing yt documentation as
-templates or checking out the
-`ReST reference documentation <http://sphinx-doc.org/rest.html>`_.
-
-New cookbook recipes (see :ref:`cookbook`) are very helpful for the community
-as they provide simple annotated recipes on how to use specific functionality.
-To add one, create a concise python script which demonstrates some
-functionality and pare it down to its minimum. Add some comment lines to
-describe what it is that you're doing along the way. Place this ``.py`` file
-in the ``source/cookbook/`` directory, and then link to it explicitly in one
-of the relevant ``.rst`` files in that directory (e.g. ``complex_plots.rst``,
-``cosmological_analysis.rst``, etc.), and add some description of what the script
-actually does. We recommend that you use one of the
-`sample data sets <http://yt-project.org/data>`_ in your recipe. When the full
-docs are built, each of the cookbook recipes are executed dynamically on
-a system which has access to all of the sample datasets. Any output images
-generated by your script will then be attached inline in the built documentation
-directly following your script.
-
-After you have made your modifications to the docs, you will want to make sure
-that they render the way you expect them to render. For more information on
-this, see the section on :ref:`docs_build`. Unless you're contributing cookbook
-recipes or notebooks which require a dynamical build, you can probably get
-away with just doing a 'quick' docs build.
-
-When you have completed your documentation additions, commit your changes
-to your repository and make a pull request in the same way you would contribute
-a change to the codebase, as described in the section on :ref:`sharing-changes`.
+#. Your pull request will be automatically updated.
How To Get The Source Code For Editing
--------------------------------------
yt is hosted on BitBucket, and you can see all of the yt repositories at
-http://hg.yt-project.org/ . With the yt installation script you should have a
+`http://hg.yt-project.org/`_ . With the yt installation script you should have a
copy of Mercurial for checking out pieces of code. Make sure you have followed
the steps above for bootstrapping your development (to assure you have a
bitbucket account, etc.)
@@ -318,7 +253,7 @@
main yt repository on bitbucket. A fork is simply an exact copy of the main
repository (along with its history) that you will now own and can make
modifications as you please. You can create a personal fork by visiting the yt
-bitbucket webpage at https://bitbucket.org/yt_analysis/yt/ . After logging in,
+bitbucket webpage at `https://bitbucket.org/yt_analysis/yt/`_ . After logging in,
you should see an option near the top right labeled "fork". Click this option,
and then click the fork repository button on the subsequent page. You now have
a forked copy of the yt repository for your own personal modification.
@@ -380,54 +315,54 @@
code is contained in the yt subdirectory. This directory its self contains
the following subdirectories:
- ``frontends``
- This is where interfaces to codes are created. Within each subdirectory of
- yt/frontends/ there must exist the following files, even if empty:
+``frontends``
+ This is where interfaces to codes are created. Within each subdirectory of
+ yt/frontends/ there must exist the following files, even if empty:
- * ``data_structures.py``, where subclasses of AMRGridPatch, Dataset
- and AMRHierarchy are defined.
- * ``io.py``, where a subclass of IOHandler is defined.
- * ``fields.py``, where fields we expect to find in datasets are defined
- * ``misc.py``, where any miscellaneous functions or classes are defined.
- * ``definitions.py``, where any definitions specific to the frontend are
- defined. (i.e., header formats, etc.)
+ * ``data_structures.py``, where subclasses of AMRGridPatch, Dataset
+ and AMRHierarchy are defined.
+ * ``io.py``, where a subclass of IOHandler is defined.
+ * ``fields.py``, where fields we expect to find in datasets are defined
+ * ``misc.py``, where any miscellaneous functions or classes are defined.
+ * ``definitions.py``, where any definitions specific to the frontend are
+ defined. (i.e., header formats, etc.)
- ``fields``
- This is where all of the derived fields that ship with yt are defined.
+``fields``
+ This is where all of the derived fields that ship with yt are defined.
- ``geometry``
- This is where geometric helpler routines are defined. Handlers
- for grid and oct data, as well as helpers for coordinate transformations
- can be found here.
+``geometry``
+ This is where geometric helpler routines are defined. Handlers
+ for grid and oct data, as well as helpers for coordinate transformations
+ can be found here.
- ``visualization``
- This is where all visualization modules are stored. This includes plot
- collections, the volume rendering interface, and pixelization frontends.
+``visualization``
+ This is where all visualization modules are stored. This includes plot
+ collections, the volume rendering interface, and pixelization frontends.
- ``data_objects``
- All objects that handle data, processed or unprocessed, not explicitly
- defined as visualization are located in here. This includes the base
- classes for data regions, covering grids, time series, and so on. This
- also includes derived fields and derived quantities.
+``data_objects``
+ All objects that handle data, processed or unprocessed, not explicitly
+ defined as visualization are located in here. This includes the base
+ classes for data regions, covering grids, time series, and so on. This
+ also includes derived fields and derived quantities.
- ``analysis_modules``
- This is where all mechanisms for processing data live. This includes
- things like clump finding, halo profiling, halo finding, and so on. This
- is something of a catchall, but it serves as a level of greater
- abstraction that simply data selection and modification.
+``analysis_modules``
+ This is where all mechanisms for processing data live. This includes
+ things like clump finding, halo profiling, halo finding, and so on. This
+ is something of a catchall, but it serves as a level of greater
+ abstraction that simply data selection and modification.
- ``gui``
- This is where all GUI components go. Typically this will be some small
- tool used for one or two things, which contains a launching mechanism on
- the command line.
+``gui``
+ This is where all GUI components go. Typically this will be some small
+ tool used for one or two things, which contains a launching mechanism on
+ the command line.
- ``utilities``
- All broadly useful code that doesn't clearly fit in one of the other
- categories goes here.
+``utilities``
+ All broadly useful code that doesn't clearly fit in one of the other
+ categories goes here.
- ``extern``
- Bundled external modules (i.e. code that was not written by one of
- the yt authors but that yt depends on) lives here.
+``extern``
+ Bundled external modules (i.e. code that was not written by one of
+ the yt authors but that yt depends on) lives here.
If you're looking for a specific file or function in the yt source code, use
@@ -457,72 +392,72 @@
General Guidelines
++++++++++++++++++
- * In general, follow `PEP-8 <http://www.python.org/dev/peps/pep-0008/>`_ guidelines.
- * Classes are ConjoinedCapitals, methods and functions are
- ``lowercase_with_underscores.``
- * Use 4 spaces, not tabs, to represent indentation.
- * Line widths should not be more than 80 characters.
- * Do not use nested classes unless you have a very good reason to, such as
- requiring a namespace or class-definition modification. Classes should live
- at the top level. ``__metaclass__`` is exempt from this.
- * Do not use unnecessary parentheses in conditionals. ``if((something) and
- (something_else))`` should be rewritten as ``if something and
- something_else``. Python is more forgiving than C.
- * Avoid copying memory when possible. For example, don't do ``a =
- a.reshape(3,4)`` when ``a.shape = (3,4)`` will do, and ``a = a * 3`` should be
- ``np.multiply(a, 3, a)``.
- * In general, avoid all double-underscore method names: ``__something`` is
- usually unnecessary.
- * Doc strings should describe input, output, behavior, and any state changes
- that occur on an object. See the file `doc/docstring_example.txt` for a
- fiducial example of a docstring.
+* In general, follow `PEP-8 <http://www.python.org/dev/peps/pep-0008/>`_ guidelines.
+* Classes are ConjoinedCapitals, methods and functions are
+ ``lowercase_with_underscores.``
+* Use 4 spaces, not tabs, to represent indentation.
+* Line widths should not be more than 80 characters.
+* Do not use nested classes unless you have a very good reason to, such as
+ requiring a namespace or class-definition modification. Classes should live
+ at the top level. ``__metaclass__`` is exempt from this.
+* Do not use unnecessary parentheses in conditionals. ``if((something) and
+ (something_else))`` should be rewritten as ``if something and
+ something_else``. Python is more forgiving than C.
+* Avoid copying memory when possible. For example, don't do ``a =
+ a.reshape(3,4)`` when ``a.shape = (3,4)`` will do, and ``a = a * 3`` should be
+ ``np.multiply(a, 3, a)``.
+* In general, avoid all double-underscore method names: ``__something`` is
+ usually unnecessary.
+* Doc strings should describe input, output, behavior, and any state changes
+ that occur on an object. See the file `doc/docstring_example.txt` for a
+ fiducial example of a docstring.
API Guide
+++++++++
- * Do not import "*" from anything other than ``yt.funcs``.
- * Internally, only import from source files directly; instead of: ``from
- yt.visualization.api import SlicePlot`` do
- ``from yt.visualization.plot_window import SlicePlot``.
- * Numpy is to be imported as ``np``.
- * Do not use too many keyword arguments. If you have a lot of keyword
- arguments, then you are doing too much in ``__init__`` and not enough via
- parameter setting.
- * In function arguments, place spaces before commas. ``def something(a,b,c)``
- should be ``def something(a, b, c)``.
- * Don't create a new class to replicate the functionality of an old class --
- replace the old class. Too many options makes for a confusing user
- experience.
- * Parameter files external to yt are a last resort.
- * The usage of the ``**kwargs`` construction should be avoided. If they
- cannot be avoided, they must be explained, even if they are only to be
- passed on to a nested function.
- * Constructor APIs should be kept as *simple* as possible.
- * Variable names should be short but descriptive.
- * No global variables!
+* Do not import "*" from anything other than ``yt.funcs``.
+* Internally, only import from source files directly; instead of: ``from
+ yt.visualization.api import SlicePlot`` do
+ ``from yt.visualization.plot_window import SlicePlot``.
+* Numpy is to be imported as ``np``.
+* Do not use too many keyword arguments. If you have a lot of keyword
+ arguments, then you are doing too much in ``__init__`` and not enough via
+ parameter setting.
+* In function arguments, place spaces before commas. ``def something(a,b,c)``
+ should be ``def something(a, b, c)``.
+* Don't create a new class to replicate the functionality of an old class --
+ replace the old class. Too many options makes for a confusing user
+ experience.
+* Parameter files external to yt are a last resort.
+* The usage of the ``**kwargs`` construction should be avoided. If they
+ cannot be avoided, they must be explained, even if they are only to be
+ passed on to a nested function.
+* Constructor APIs should be kept as *simple* as possible.
+* Variable names should be short but descriptive.
+* No global variables!
Variable Names and Enzo-isms
++++++++++++++++++++++++++++
- * Avoid Enzo-isms. This includes but is not limited to:
+* Avoid Enzo-isms. This includes but is not limited to:
- + Hard-coding parameter names that are the same as those in Enzo. The
- following translation table should be of some help. Note that the
- parameters are now properties on a Dataset subclass: you access them
- like ``ds.refine_by`` .
+ + Hard-coding parameter names that are the same as those in Enzo. The
+ following translation table should be of some help. Note that the
+ parameters are now properties on a Dataset subclass: you access them
+ like ``ds.refine_by`` .
- - ``RefineBy `` => `` refine_by``
- - ``TopGridRank `` => `` dimensionality``
- - ``TopGridDimensions `` => `` domain_dimensions``
- - ``InitialTime `` => `` current_time``
- - ``DomainLeftEdge `` => `` domain_left_edge``
- - ``DomainRightEdge `` => `` domain_right_edge``
- - ``CurrentTimeIdentifier `` => `` unique_identifier``
- - ``CosmologyCurrentRedshift `` => `` current_redshift``
- - ``ComovingCoordinates `` => `` cosmological_simulation``
- - ``CosmologyOmegaMatterNow `` => `` omega_matter``
- - ``CosmologyOmegaLambdaNow `` => `` omega_lambda``
- - ``CosmologyHubbleConstantNow `` => `` hubble_constant``
+ - ``RefineBy `` => `` refine_by``
+ - ``TopGridRank `` => `` dimensionality``
+ - ``TopGridDimensions `` => `` domain_dimensions``
+ - ``InitialTime `` => `` current_time``
+ - ``DomainLeftEdge `` => `` domain_left_edge``
+ - ``DomainRightEdge `` => `` domain_right_edge``
+ - ``CurrentTimeIdentifier `` => `` unique_identifier``
+ - ``CosmologyCurrentRedshift `` => `` current_redshift``
+ - ``ComovingCoordinates `` => `` cosmological_simulation``
+ - ``CosmologyOmegaMatterNow `` => `` omega_matter``
+ - ``CosmologyOmegaLambdaNow `` => `` omega_lambda``
+ - ``CosmologyHubbleConstantNow `` => `` hubble_constant``
- + Do not assume that the domain runs from 0 to 1. This is not true
- everywhere.
+ + Do not assume that the domain runs from 0 to 1. This is not true
+ for many codes and datasets.
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/developing/intro.rst
--- a/doc/source/developing/intro.rst
+++ b/doc/source/developing/intro.rst
@@ -15,9 +15,9 @@
There are four main communication channels for yt:
- * We also have an IRC channel, on ``irc.freenode.net`` in ``#yt``, which can be a
- bit less on-topic than the mailing lists. You can connect through our web
- gateway without any special client, at http://yt-project.org/irc.html .
+ * We have an IRC channel, on ``irc.freenode.net`` in ``#yt``.
+ You can connect through our web
+ gateway without any special client, at `http://yt-project.org/irc.html`_.
*IRC is the first stop for conversation!*
* `yt-users <http://lists.spacepope.org/listinfo.cgi/yt-users-spacepope.org>`_
is a relatively high-traffic mailing list where people are encouraged to ask
@@ -60,8 +60,8 @@
to have more examples that show complex or advanced behavior -- and if you have
used such scripts to write a paper, that too would be an amazing contribution.
-Documentation and Screencasts
------------------------------
+Documentation
+-------------
The yt documentation -- which you are reading right now -- is constantly being
updated, and it is a task we would very much appreciate assistance with.
@@ -75,18 +75,6 @@
issue a pull request through the website for your new fork, and we can comment
back and forth and eventually accept your changes.
-One of the more interesting ways we are attempting to do lately is to add
-screencasts to the documentation -- these are recordings of people executing
-sessions in a terminal or in a web browser, showing off functionality and
-describing how to do various things. These provide a more dynamic and
-engaging way of demonstrating functionality and teaching methods.
-
-One easy place to record screencasts is with `Screencast-O-Matic
-<http://www.screencast-o-matic.com/>`_ but there are many to choose from. Once
-you have recorded it, let us know and be sure to add it to the
-`yt Vimeo group <http://vimeo.com/groups/ytgallery>`_. We'll then link to it
-from the documentation!
-
Gallery Images and Videos
-------------------------
@@ -96,9 +84,9 @@
email it to us and we'll add it to the `Gallery
<http://yt-project.org/gallery.html>`_.
-We're eager to show off the images you make with yt, so please feel free to
-drop `us <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_ a
-line and let us know if you've got something great!
+We're eager to show off the images and movies you make with yt, so please feel
+free to drop `us <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_
+a line and let us know if you've got something great!
Technical Contributions
-----------------------
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/developing/testing.rst
--- a/doc/source/developing/testing.rst
+++ b/doc/source/developing/testing.rst
@@ -1,6 +1,5 @@
.. _testing:
-=======
Testing
=======
@@ -46,8 +45,8 @@
.. code-block:: python
- >>> import yt
- >>> yt.run_nose()
+ import yt
+ yt.run_nose()
If you are developing new functionality, it is sometimes more convenient to use
the Nose command line interface, ``nosetests``. You can run the unit tests
@@ -79,36 +78,36 @@
document, as in some cases they belong to other packages. However, a few come
in handy:
- * :func:`yt.testing.fake_random_ds` provides the ability to create a random
- dataset, with several fields and divided into several different
- grids, that can be operated on.
- * :func:`yt.testing.assert_equal` can operate on arrays.
- * :func:`yt.testing.assert_almost_equal` can operate on arrays and accepts a
- relative allowable difference.
- * :func:`yt.testing.amrspace` provides the ability to create AMR grid
- structures.
- * :func:`~yt.testing.expand_keywords` provides the ability to iterate over
- many values for keywords.
+* :func:`~yt.testing.fake_random_ds` provides the ability to create a random
+ dataset, with several fields and divided into several different
+ grids, that can be operated on.
+* :func:`~yt.testing.assert_equal` can operate on arrays.
+* :func:`~yt.testing.assert_almost_equal` can operate on arrays and accepts a
+ relative allowable difference.
+* :func:`~yt.testing.amrspace` provides the ability to create AMR grid
+ structures.
+* :func:`~yt.testing.expand_keywords` provides the ability to iterate over
+ many values for keywords.
To create new unit tests:
- #. Create a new ``tests/`` directory next to the file containing the
- functionality you want to test. Be sure to add this new directory as a
- subpackage in the setup.py script located in the directory you're adding a
- new ``tests/`` folder to. This ensures that the tests will be deployed in
- yt source and binary distributions.
- #. Inside that directory, create a new python file prefixed with ``test_`` and
- including the name of the functionality.
- #. Inside that file, create one or more routines prefixed with ``test_`` that
- accept no arguments. These should ``yield`` a set of values of the form
- ``function``, ``arguments``. For example ``yield assert_equal, 1.0, 1.0``
- would evaluate that 1.0 equaled 1.0.
- #. Use ``fake_random_ds`` to test on datasets, and be sure to test for
- several combinations of ``nproc``, so that domain decomposition can be
- tested as well.
- #. Test multiple combinations of options by using the
- :func:`~yt.testing.expand_keywords` function, which will enable much
- easier iteration over options.
+#. Create a new ``tests/`` directory next to the file containing the
+ functionality you want to test. Be sure to add this new directory as a
+ subpackage in the setup.py script located in the directory you're adding a
+ new ``tests/`` folder to. This ensures that the tests will be deployed in
+ yt source and binary distributions.
+#. Inside that directory, create a new python file prefixed with ``test_`` and
+ including the name of the functionality.
+#. Inside that file, create one or more routines prefixed with ``test_`` that
+ accept no arguments. These should ``yield`` a set of values of the form
+ ``function``, ``arguments``. For example ``yield assert_equal, 1.0, 1.0``
+ would evaluate that 1.0 equaled 1.0.
+#. Use ``fake_random_ds`` to test on datasets, and be sure to test for
+ several combinations of ``nproc``, so that domain decomposition can be
+ tested as well.
+#. Test multiple combinations of options by using the
+ :func:`~yt.testing.expand_keywords` function, which will enable much
+ easier iteration over options.
For an example of how to write unit tests, look at the file
``yt/data_objects/tests/test_covering_grid.py``, which covers a great deal of
@@ -134,16 +133,16 @@
The very first step is to make a directory and copy over the data against which
you want to test. Currently, we test:
- * ``DD0010/moving7_0010`` (available in ``tests/`` in the yt distribution)
- * ``IsolatedGalaxy/galaxy0030/galaxy0030``
- * ``WindTunnel/windtunnel_4lev_hdf5_plt_cnt_0030``
- * ``GasSloshingLowRes/sloshing_low_res_hdf5_plt_cnt_0300``
- * ``TurbBoxLowRes/data.0005.3d.hdf5``
- * ``GaussianCloud/data.0077.3d.hdf5``
- * ``RadAdvect/plt00000``
- * ``RadTube/plt00500``
+* ``DD0010/moving7_0010`` (available in ``tests/`` in the yt distribution)
+* ``IsolatedGalaxy/galaxy0030/galaxy0030``
+* ``WindTunnel/windtunnel_4lev_hdf5_plt_cnt_0030``
+* ``GasSloshingLowRes/sloshing_low_res_hdf5_plt_cnt_0300``
+* ``TurbBoxLowRes/data.0005.3d.hdf5``
+* ``GaussianCloud/data.0077.3d.hdf5``
+* ``RadAdvect/plt00000``
+* ``RadTube/plt00500``
-These datasets are available at http://yt-project.org/data/.
+These datasets are available at `http://yt-project.org/data/`_.
Next, modify the file ``~/.yt/config`` to include a section ``[yt]``
with the parameter ``test_data_dir``. Set this to point to the
@@ -162,8 +161,8 @@
.. code-block:: python
- >>> import yt
- >>> yt.run_nose(run_answer_tests=True)
+ import yt
+ yt.run_nose(run_answer_tests=True)
If you have installed yt using ``python setup.py develop`` you can also
optionally invoke nose using the ``nosetests`` command line interface:
@@ -183,8 +182,8 @@
.. code-block:: python
- >>> import yt
- >>> yt.run_nose(run_answer_tests=True, answer_big_data=True)
+ import yt
+ yt.run_nose(run_answer_tests=True, answer_big_data=True)
or, in the base directory of the yt mercurial repository:
@@ -231,24 +230,24 @@
To write a new test:
- * Subclass ``AnswerTestingTest``
- * Add the attributes ``_type_name`` (a string) and ``_attrs``
- (a tuple of strings, one for each attribute that defines the test --
- see how this is done for projections, for instance)
- * Implement the two routines ``run`` and ``compare`` The first
- should return a result and the second should compare a result to an old
- result. Neither should yield, but instead actually return. If you need
- additional arguments to the test, implement an ``__init__`` routine.
- * Keep in mind that *everything* returned from ``run`` will be stored. So if
- you are going to return a huge amount of data, please ensure that the test
- only gets run for small data. If you want a fast way to measure something as
- being similar or different, either an md5 hash (see the grid values test) or
- a sum and std of an array act as good proxies. If you must store a large
- amount of data for some reason, try serializing the data to a string
- (e.g. using ``numpy.ndarray.dumps``), and then compressing the data stream
- using ``zlib.compress``.
- * Typically for derived values, we compare to 10 or 12 decimal places.
- For exact values, we compare exactly.
+* Subclass ``AnswerTestingTest``
+* Add the attributes ``_type_name`` (a string) and ``_attrs``
+ (a tuple of strings, one for each attribute that defines the test --
+ see how this is done for projections, for instance)
+* Implement the two routines ``run`` and ``compare`` The first
+ should return a result and the second should compare a result to an old
+ result. Neither should yield, but instead actually return. If you need
+ additional arguments to the test, implement an ``__init__`` routine.
+* Keep in mind that *everything* returned from ``run`` will be stored. So if
+ you are going to return a huge amount of data, please ensure that the test
+ only gets run for small data. If you want a fast way to measure something as
+ being similar or different, either an md5 hash (see the grid values test) or
+ a sum and std of an array act as good proxies. If you must store a large
+ amount of data for some reason, try serializing the data to a string
+ (e.g. using ``numpy.ndarray.dumps``), and then compressing the data stream
+ using ``zlib.compress``.
+* Typically for derived values, we compare to 10 or 12 decimal places.
+ For exact values, we compare exactly.
How to Add Data to the Testing Suite
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -257,26 +256,26 @@
The Enzo example in ``yt/frontends/enzo/tests/test_outputs.py`` is
considered canonical. Do these things:
- * Create a new directory, ``tests`` inside the frontend's directory.
+* Create a new directory, ``tests`` inside the frontend's directory.
- * Create a new file, ``test_outputs.py`` in the frontend's ``tests``
- directory.
+* Create a new file, ``test_outputs.py`` in the frontend's ``tests``
+ directory.
- * Create a new routine that operates similarly to the routines you can see
- in Enzo's outputs.
+* Create a new routine that operates similarly to the routines you can see
+ in Enzo's outputs.
- * This routine should test a number of different fields and data objects.
+ * This routine should test a number of different fields and data objects.
- * The test routine itself should be decorated with
- ``@requires_ds(file_name)`` This decorate can accept the argument
- ``big_data`` for if this data is too big to run all the time.
+ * The test routine itself should be decorated with
+ ``@requires_ds(file_name)`` This decorate can accept the argument
+ ``big_data`` for if this data is too big to run all the time.
- * There are ``small_patch_amr`` and ``big_patch_amr`` routines that
- you can yield from to execute a bunch of standard tests. This is where
- you should start, and then yield additional tests that stress the
- outputs in whatever ways are necessary to ensure functionality.
+ * There are ``small_patch_amr`` and ``big_patch_amr`` routines that
+ you can yield from to execute a bunch of standard tests. This is where
+ you should start, and then yield additional tests that stress the
+ outputs in whatever ways are necessary to ensure functionality.
- * **All tests should be yielded!**
+ * **All tests should be yielded!**
If you are adding to a frontend that has a few tests already, skip the first
two steps.
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/examining/low_level_inspection.rst
--- a/doc/source/examining/low_level_inspection.rst
+++ b/doc/source/examining/low_level_inspection.rst
@@ -230,6 +230,5 @@
directly as a fixed resolution array. This provides a means for bypassing the
yt method for generating plots, and allows the user the freedom to use
whatever interface they wish for displaying and saving their image data.
-The object for doing this is the aptly titled Fixed Resolution Buffer, and
-there is a full explanation for how to use it
-:ref:`here <fixed-resolution-buffers>`.
+You can use the :class:`~yt.visualization.fixed_resolution.FixedResolutionBuffer`
+to accomplish this as described in :ref:`fixed-resolution-buffers`.
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/help/index.rst
--- a/doc/source/help/index.rst
+++ b/doc/source/help/index.rst
@@ -1,6 +1,6 @@
.. _asking-for-help:
-What to do if you run into problems
+What to Do If You Run into Problems
===================================
If you run into problems with yt, there are a number of steps to follow
@@ -11,18 +11,18 @@
To summarize, here are the steps in order:
- #. Don’t panic and don’t give up
- #. Update to the latest version
- #. Search the yt documentation and mailing list archives
- #. Look at the yt source
- #. Isolate & document your problem
- #. Go on IRC and ask a question
- #. Ask the mailing list
- #. Submit a bug report
+#. Don’t panic and don’t give up
+#. Update to the latest version
+#. Search the yt documentation and mailing list archives
+#. Look at the yt source
+#. Isolate & document your problem
+#. Go on IRC and ask a question
+#. Ask the mailing list
+#. Submit a bug report
.. _dont-panic:
-Don't panic and don't give up
+Don't Panic and Don't Give up
-----------------------------
This may seem silly, but it's effective. While yt is a robust code with
@@ -34,7 +34,7 @@
.. _update-the-code:
-Try updating yt
+Try Updating yt
---------------
Sometimes the pace of development is pretty fast on yt, particularly in the
@@ -53,9 +53,35 @@
$ yt update --all
+.. _update_errors:
+
+Update Errors
+^^^^^^^^^^^^^
+
+If for some reason the ``update`` command fails with errors, or any attempt at
+loading yt either from the command line or from within python also fails, it
+may simply mean you need to rebuild the yt source (some of the c-code in yt
+needs to be rebuilt after major changes). You can do this by navigating to
+the root of the yt mercurial repository. If you installed with the all-in-one
+installer script, this is the ``yt-<machine>/src/yt-hg`` directory. Then
+execute these commands:
+
+.. code-block:: bash
+
+ $ python setup.py develop
+
+Now try running yt again with:
+
+.. code-block:: bash
+
+ $ yt --help
+
+If you continue to see errors, you should try contacting us via IRC or email
+but you may have to reinstall yt (see :ref:`getting-and-installing`).
+
.. _search-the-documentation:
-Search the documentation and mailing lists
+Search the Documentation and Mailing Lists
------------------------------------------
The documentation has a lot of the answers to everyday problems. This doesn't
@@ -84,7 +110,7 @@
.. _look-at-the-source:
-Look at the source code
+Look at the Source Code
-----------------------
We've done our best to make the source clean, and it is easily searchable from
@@ -125,7 +151,7 @@
.. _isolate_and_document:
-Isolate and document your problem
+Isolate and Document Your Problem
---------------------------------
As you gear up to take your question to the rest of the community, try to distill
@@ -133,15 +159,15 @@
script. This can help you (and us) to identify the basic problem. Follow
these steps:
- * Identify what it is that went wrong, and how you knew it went wrong.
- * Put your script, errors, and outputs online:
+* Identify what it is that went wrong, and how you knew it went wrong.
+* Put your script, errors, and outputs online:
- * ``$ yt pastebin script.py`` - pastes script.py online
- * ``$ yt upload_image image.png`` - pastes image online
+ * ``$ yt pastebin script.py`` - pastes script.py online
+ * ``$ yt upload_image image.png`` - pastes image online
- * Identify which version of the code you’re using.
+* Identify which version of the code you’re using.
- * ``$ yt version`` - provides version information, including changeset hash
+ * ``$ yt version`` - provides version information, including changeset hash
It may be that through the mere process of doing this, you end up solving
the problem!
@@ -162,7 +188,7 @@
.. _mailing-list:
-Ask the mailing list
+Ask the Mailing List
--------------------
If you still haven't yet found a solution, feel free to
@@ -183,7 +209,7 @@
.. _reporting-a-bug:
-How To report A bug
+How to Report a Bug
-------------------
If you have gone through all of the above steps, and you're still encountering
@@ -195,7 +221,6 @@
ticket in your stead. Remember to include the information
about your problem you identified in :ref:`this step <isolate_and_document>`.
-
Installation Issues
-------------------
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/index.rst
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -28,7 +28,7 @@
</p></td><td width="75%">
- <p class="linkdescr">Getting and Installing yt</p>
+ <p class="linkdescr">Getting, Installing, and Updating yt</p></td></tr><tr valign="top">
@@ -78,7 +78,7 @@
</p></td><td width="75%">
- <p class="linkdescr">Use analysis tools to extract results from your data</p>
+ <p class="linkdescr">Use analysis tools to extract results from your data</p></td></tr><tr valign="top">
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/installing.rst
--- a/doc/source/installing.rst
+++ b/doc/source/installing.rst
@@ -13,9 +13,9 @@
* If you do not have root access on your computer, are not comfortable managing
python packages, or are working on a supercomputer or cluster computer, you
- will probably want to use the bash installation script. This builds python,
- numpy, matplotlib, and yt from source to set up an isolated scientific python
- environment inside of a single folder in your home directory. See
+ will probably want to use the bash all-in-one installation script. This builds
+ python, numpy, matplotlib, and yt from source to set up an isolated scientific
+ python environment inside of a single folder in your home directory. See
:ref:`install-script` for more details.
* If you use the `Anaconda <https://store.continuum.io/cshop/anaconda/>`_ python
@@ -261,36 +261,6 @@
package install path. If you do not have write access for this location, you
might need to use ``sudo``.
-Switching to yt 2.x
-^^^^^^^^^^^^^^^^^^^
-
-With the release of version 3.0 of yt, development of the legacy yt 2.x series
-has been relegated to bugfixes. That said, we will continue supporting the 2.x
-series for the forseeable future. This makes it easy to use scripts written
-for older versions of yt without substantially updating them to support the
-new field naming or unit systems in yt version 3.
-
-Currently, the yt-2.x codebase is contained in a named branch in the yt
-mercurial repository. First, remove any extant installations of yt on your
-system:
-
-.. code-block:: bash
-
- pip uninstall yt
-
-To switch to yt-2.x, you will need to clone the mercurial repository as
-described in :ref:`source-installation`. Next, you will need to navigate to the
-mercurial repository, update to the `yt-2.x` branch, and recompile:
-
-.. code-block:: bash
-
- cd yt
- hg update yt-2.x
- python setup.py develop --user --prefix=
-
-You can check which version of yt you have installed by invoking ``yt version``
-at the command line.
-
Keeping yt Updated via Mercurial
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -327,7 +297,76 @@
If you get an error, follow the instructions it gives you to debug the problem.
Do not hesitate to :ref:`contact us <asking-for-help>` so we can help you
-figure it out.
+figure it out. There is also information at :ref:`update-errors`.
If you like, this might be a good time to run the test suite, see :ref:`testing`
for more details.
+
+.. _switching-between-yt-versions:
+
+Switching between yt-2.x and yt-3.x
+-----------------------------------
+
+With the release of version 3.0 of yt, development of the legacy yt 2.x series
+has been relegated to bugfixes. That said, we will continue supporting the 2.x
+series for the forseeable future. This makes it easy to use scripts written
+for older versions of yt without substantially updating them to support the
+new field naming or unit systems in yt version 3.
+
+Currently, the yt-2.x codebase is contained in a named branch in the yt
+mercurial repository. Thus, depending on the method you used to install
+yt, there are different instructions for switching versions.
+
+If You Installed yt Using the Installer Script
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You already have the mercurial repository, so you simply need to switch
+which version you're using. Navigate to the root of the yt mercurial
+repository, update to the desired version, and rebuild the source (some of the
+c code requires a compilation step for big changes like this):
+
+.. code-block:: bash
+
+ cd yt-<machine>/src/yt-hg
+ hg update <desired-version>
+ python setup.py develop
+
+Valid versions to jump to are:
+
+* ``yt`` -- The latest *dev* changes in yt-3.x (can be unstable)
+* ``stable`` -- The latest stable release of yt-3.x
+* ``yt-2.x`` -- The latest stable release of yt-2.x
+
+You can check which version of yt you have installed by invoking ``yt version``
+at the command line. If you encounter problems, see :ref:`update-errors`.
+
+If You Installed yt Using from Source or Using pip
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have installed python via ``pip``, remove
+any extant installations of yt on your system and clone the source mercurial
+repository of yt as described in :ref:`source-installation`.
+
+.. code-block:: bash
+
+ pip uninstall yt
+ hg clone https://bitbucket.org/yt_analysis/yt
+
+Now, to switch between versions, you need to navigate to the root of
+the mercurial yt repository. Use mercurial to
+update to the appropriate version and recompile.
+
+.. code-block:: bash
+
+ cd yt
+ hg update <desired-version>
+ python setup.py install --user --prefix=
+
+Valid versions to jump to are:
+
+* ``yt`` -- The latest *dev* changes in yt-3.x (can be unstable)
+* ``stable`` -- The latest stable release of yt-3.x
+* ``yt-2.x`` -- The latest stable release of yt-2.x
+
+You can check which version of yt you have installed by invoking ``yt version``
+at the command line. If you encounter problems, see :ref:`update-errors`.
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/reference/api/api.rst
--- a/doc/source/reference/api/api.rst
+++ b/doc/source/reference/api/api.rst
@@ -87,6 +87,7 @@
~yt.data_objects.selection_data_containers.YTSphereBase
~yt.data_objects.selection_data_containers.YTEllipsoidBase
~yt.data_objects.selection_data_containers.YTCutRegionBase
+ ~yt.data_objects.grid_patch.AMRGridPatch
Construction Objects
++++++++++++++++++++
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/reference/command-line.rst
--- a/doc/source/reference/command-line.rst
+++ b/doc/source/reference/command-line.rst
@@ -216,7 +216,7 @@
By running the ``pastebin_grab`` subcommand with a pastebin number
(e.g. 1768), it will grab the contents of that pastebin
(e.g. the website http://paste.yt-project.org/show/1768 ) and send it to
-STDOUT for local use. For more details see the :ref:`pastebin` section.
+STDOUT for local use. See :ref:`pastebin` for more information.
.. code-block:: bash
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/visualizing/streamlines.rst
--- a/doc/source/visualizing/streamlines.rst
+++ b/doc/source/visualizing/streamlines.rst
@@ -8,7 +8,8 @@
velocity flow or magnetic field lines, they can be defined to follow
any three-dimensional vector field. Once an initial condition and
total length of the streamline are specified, the streamline is
-uniquely defined.
+uniquely defined. Relatedly, yt also has the ability to follow
+:ref:`particle-trajectories`.
Method
------
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 doc/source/yt3differences.rst
--- a/doc/source/yt3differences.rst
+++ b/doc/source/yt3differences.rst
@@ -9,6 +9,31 @@
minimize disruption to existing scripts, but necessarily things will be
different in some ways.
+Updating to yt 3.0 from Old Versions
+------------------------------------
+
+First off, you need to update your version of yt to yt 3.0. If you're
+installing yt for the first time, please visit :ref:`getting-and-installing-yt`.
+If you already have a version of yt installed, you should just need one
+command:
+
+.. code-block:: bash
+
+ $ yt update --all
+
+This will update yt to the most recent version and rebuild the source base.
+If you installed using the installer script, it will assure you have all of the
+latest dependencies as well. This step may take a few minutes. To test
+to make sure yt is running, try:
+
+.. code-block:: bash
+
+ $ yt --help
+
+If you receive no errors, then you are ready to go. If you have
+an error, then consult :ref:`update-errors` for solutions. We also
+provide instructions for :ref:`switching-between-yt-versions`.
+
Cheat Sheet
-----------
@@ -129,7 +154,7 @@
Preliminary support for non-cartesian coordinates has been added. We expect
this to be considerably solidified and expanded in yt 3.1.
-Reworked import system
+Reworked Import System
^^^^^^^^^^^^^^^^^^^^^^
It's now possible to import all yt functionality using ``import yt``. Rather
@@ -176,15 +201,15 @@
ds = yt.load("MyData")
ds.setup_deprecated_fields()
-This sets up aliases from the old names to the new. See :ref:`fields` for
-more information.
+This sets up aliases from the old names to the new. See :ref:`fields` and
+:ref:`field-list` for more information.
Units of Fields
^^^^^^^^^^^^^^^
Fields now are all subclasses of NumPy arrays, the ``YTArray``, which carries
along with it units. This means that if you want to manipulate fields, you
-have to modify them in a unitful way.
+have to modify them in a unitful way. See :ref:`units`.
Parameter Files are Now Datasets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -244,7 +269,8 @@
^^^^^^^^^^^^^^^^
All data objects now accept an explicit list of ``field_parameters`` rather
-than accepting ``kwargs`` and supplying them to field parameters.
+than accepting ``kwargs`` and supplying them to field parameters. See
+:ref:`field-parameters`.
Object Renaming
^^^^^^^^^^^^^^^
@@ -253,7 +279,8 @@
removing ``AMR`` from the prefix or replacing it with ``YT``. All names of
objects remain the same for the purposes of selecting data and creating them;
i.e., ``sphere`` objects are still called ``sphere`` - you can access create one
-via ``ds.sphere``. For a detailed description and index see :ref:`available-objects`.
+via ``ds.sphere``. For a detailed description and index see
+:ref:`available-objects`.
Boolean Regions
^^^^^^^^^^^^^^^
@@ -279,3 +306,9 @@
This will "spatially" chunk the ``obj`` object and print out all the grids
included.
+
+Halo Catalogs
+^^^^^^^^^^^^^
+
+The ``Halo Profiler`` infrastructure has been fundamentally rewritten and now
+exists using the ``Halo Catalog`` framework. See :ref:`halo-analysis`.
diff -r 9701602a49cf2aa538b53570bb9038bc1ef441e4 -r 2ad686b9cb30292efbadf4d0f0cf3d18961537f2 yt/utilities/command_line.py
--- a/yt/utilities/command_line.py
+++ b/yt/utilities/command_line.py
@@ -388,7 +388,7 @@
yt_provider = pkg_resources.get_provider("yt")
path = os.path.dirname(yt_provider.module_path)
if not os.path.isdir(os.path.join(path, ".hg")): return None
- version = _get_hg_version(path)[:12]
+ version = _get_hg_version(path)
return version
# This code snippet is modified from Georg Brandl
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