Commits

Matthew Turk  committed ab1cd7a

First pass at YTEP for periodicity.

  • Participants
  • Parent commits 1cbf3d9

Comments (0)

Files changed (2)

File source/YTEPs/YTEP-0002.rst

 Status
 ------
 
-In Progress: A basic implementation has been created, but API needs to be
-decided upon as does the list of functions it will implement.
+In Progress: A basic implementation has been created, which now needs to be
+modified and changed in accordance with this YTEP.
 
 The code can be seen in ``yt/visualization/profile_plotter.py``, specifically
 the objects:

File source/YTEPs/YTEP-0006.rst

+YTEP-0006: Periodicity
+======================
+
+Periodicity needs to be dealt with in an explicit, rather than implicit,
+fashion.
+
+Abstract
+--------
+
+ * Created: January 10, 2013
+ * Author: Matthew Turk
+
+Periodicity in yt has been handled poorly in the past.  Some objects and fields
+have been set to be periodic by default, but not all.  This YTEP aims to define
+a mechanism by which fields and objects can query periodicity information and
+use it correctly.
+
+Status
+------
+
+Proposed.
+
+Project Management Links
+------------------------
+
+  * Mailing list discussion: http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/2012-December/002739.html
+  * Mailing list discussion: http://lists.spacepope.org/pipermail/yt-users-spacepope.org/2012-December/003194.html
+  * Issue: https://bitbucket.org/yt_analysis/yt/issue/484/fields-dont-know-about-periodic-boundary
+
+Detailed Description
+--------------------
+
+Periodicity is a tricky business.  By volume, the majority of simulations
+analyzed with yt are cosmology simulations, which are exclusively periodic.  So
+objects such as ellipsoids, fields such as radius, and so on have all evolved
+to select data or regard data as wrapping around the edges of simulation
+boundaries.
+
+However, all of these should only be periodic *when it makes sense*.  This
+means that we need to have a method of marking a simulation as periodic and a
+method for applying this periodicity.  For those situations where periodicity
+makes sense, it should either *always* be applied if the simulation is
+periodic, or *never* applied if it is not.  I believe we should allow
+simulations to be periodic in any one of the three axes, but not necessarily
+all simultaneously; this may be overly complex.  We explicitly do not support
+any type of domain-wrapping or boundary conditions more complex than simply
+wrapping around.
+
+Affected Regions
+----------------
+
++---------------------------+---------------------+---------------+
+| Region of the Code        | Type of Periodicity | Change?       |
++===========================+=====================+===============+
+| Light cone                | Implicit            | No            |
++---------------------------+---------------------+---------------+
+| Halo finding              | Implicit            | No            |
++---------------------------+---------------------+---------------+
+| Light ray                 | Implicit            | No            |
++---------------------------+---------------------+---------------+
+| EnzoFOF                   | Implicit            | No            |
++---------------------------+---------------------+---------------+
+| FOF                       | Implicit            | No            |
++---------------------------+---------------------+---------------+
+| Halo objects              | Implicit            | No            |
++---------------------------+---------------------+---------------+
+| Fixed Res Buffers         | Explicit            | Yes           |
++---------------------------+---------------------+---------------+
+| Multi-halo profiler       | Implicit            | No            |
++---------------------------+---------------------+---------------+
+| Radial column density     | Implicit            | Yes           |
++---------------------------+---------------------+---------------+
+| Periodic regions          | Explicit            | Yes           |
++---------------------------+---------------------+---------------+
+| Spheres                   | Implicit            | Yes           |
++---------------------------+---------------------+---------------+
+| Ellipsoids                | Implicit            | Yes           |
++---------------------------+---------------------+---------------+
+| Two-point functions       | Implicit            | Yes           |
++---------------------------+---------------------+---------------+
+| Clumps                    | Implicit            | Yes           |
++---------------------------+---------------------+---------------+
+| Boolean regions           | Implicit            | Yes           |
++---------------------------+---------------------+---------------+
+| AMR kD Tree               | Explicit            | Yes           |
++---------------------------+---------------------+---------------+
+| Domain decomp             | Implicit            | Yes           |
++---------------------------+---------------------+---------------+
+| Radius                    | Implicit            | Yes           |
++---------------------------+---------------------+---------------+
+| ParticleRadius            | Implicit            | Yes           |
++---------------------------+---------------------+---------------+
+| Covering grids            | Implicit            | Yes           |
++---------------------------+---------------------+---------------+
+
+New Method
+----------
+
+Two types of changes will be made.  The first is to remove implicit periodicity
+and replace it with a check on the periodicity of the simulation.  The second
+is to remove multiple definitions of objects or functions that operate either
+in periodic or non-periodic methods, and instead provide only one that
+self-distinguished.  Some operations, such as anything that operates on
+cosmological simulations (which I reluctantly consider halo finding to do) can
+assume periodicity.
+
+We need to take account of the following types of checks:
+
+ * Distance between two points
+ * Shortest path between two points (uncommon, can be special cased)
+ * Object inclusion/collision
+ * Selection of points
+
+We will make the following changes:
+
+ * Create a ``periodicity`` property on all ``StaticOutput`` objects.  This
+   will be a ``float64`` array of shape (3,) that contains either 0.0 or the
+   domain width around which positions should be wrapped.
+ * Remove all locally-defined periodicity functions in favor of
+   the function ``periodic_dist`` in ``yt/utilities/math_utils.py`` and
+   checking the ``periodicity`` attribute.  **Q: What other functions should be
+   defined?**
+ * Anything that applies periodic shifts to data for checks of inclusion should
+   apply them exclusively through the ``periodicity`` attribute.  For data
+   selectors, we will have a two-step process: the data object will need to
+   implement a ``check_periodicity`` function.
+ * Everything that relies on ``periodic_region`` should instead rely on
+   ``region`` which will include an option (default = True, which actually
+   means) to check periodicity.
+ * The ``periodic_region`` data object will, in 2.X, become a wrapper around
+   the basic region object.
+
+Backwards Compatibility
+-----------------------
+
+All operations that relied on implicit periodicity for datasets that cannot be
+identified as periodic will have different results.
+
+Old results for non-periodic datasets that were incorrect will become correct.