[yt-svn] commit/yt: xarthisius: Merged in brittonsmith/yt (pull request #2277)
commits-noreply at bitbucket.org
commits-noreply at bitbucket.org
Sat Jul 16 08:54:16 PDT 2016
1 new commit in yt:
https://bitbucket.org/yt_analysis/yt/commits/baec4945cd28/
Changeset: baec4945cd28
Branch: yt
User: xarthisius
Date: 2016-07-16 15:53:49+00:00
Summary: Merged in brittonsmith/yt (pull request #2277)
Better docs for working with halo catalog datasets (closes Issue #1221)
Affected #: 8 files
diff -r 77c1b9653da76332bfe6baccb489f1973ee3c0b1 -r baec4945cd28a161c1b7b42c63840c9626da7174 doc/source/analyzing/analysis_modules/ellipsoid_analysis.rst
--- a/doc/source/analyzing/analysis_modules/ellipsoid_analysis.rst
+++ b/doc/source/analyzing/analysis_modules/ellipsoid_analysis.rst
@@ -4,10 +4,9 @@
=======================
.. sectionauthor:: Geoffrey So <gso at physics.ucsd.edu>
-.. warning:: This is my first attempt at modifying the yt source code,
- so the program may be bug ridden. Please send yt-dev an email and
- address to Geoffrey So if you discover something wrong with this
- portion of the code.
+.. warning:: This functionality is currently broken and needs to
+ be updated to make use of the :ref:`halo_catalog` framework.
+ Anyone interested in doing so should contact the yt-dev list.
Purpose
-------
diff -r 77c1b9653da76332bfe6baccb489f1973ee3c0b1 -r baec4945cd28a161c1b7b42c63840c9626da7174 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
@@ -3,14 +3,16 @@
Halo Analysis
=============
-Using halo catalogs, understanding the different halo finding methods,
-and using the halo mass function.
+This section covers halo finding, performing extra analysis on halos,
+and the halo mass function calculator. If you already have halo
+catalogs and simply want to load them into yt, see
+:ref:`halo-catalog-data`.
.. toctree::
:maxdepth: 2
+ halo_catalogs
+ halo_mass_function
halo_transition
- halo_catalogs
- halo_finders
- halo_mass_function
halo_merger_tree
+ ellipsoid_analysis
diff -r 77c1b9653da76332bfe6baccb489f1973ee3c0b1 -r baec4945cd28a161c1b7b42c63840c9626da7174 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
@@ -1,28 +1,42 @@
.. _halo_catalog:
-Halo Catalogs
-=============
+Halo Finding and Analysis
+=========================
-Creating Halo Catalogs
-----------------------
+In yt-3.x, halo finding and analysis are combined into a single
+framework called the
+:class:`~yt.analysis_modules.halo_analysis.halo_catalog.HaloCatalog`.
+This framework is substantially different from the halo analysis
+machinery available in yt-2.x and is entirely backward incompatible.
+For a direct translation of various halo analysis tasks using yt-2.x
+to yt-3.x, see :ref:`halo-transition`.
-In yt 3.0, operations relating to the analysis of halos (halo finding,
-merger tree creation, and individual halo analysis) are all brought
-together into a single framework. This framework is substantially
-different from the halo analysis machinery available in yt-2.x and is
-entirely backward incompatible.
-For a direct translation of various halo analysis tasks using yt-2.x
-to yt-3.0 please see :ref:`halo-transition`.
+.. _halo_catalog_finding:
-A catalog of halos can be created from any initial dataset given to halo
-catalog through data_ds. These halos can be found using friends-of-friends,
-HOP, and Rockstar. The finder_method keyword dictates which halo finder to
-use. The available arguments are :ref:`fof`, :ref:`hop`, and :ref:`rockstar`.
-For more details on the relative differences between these halo finders see
-:ref:`halo_finding`.
+Halo Finding
+------------
-The class which holds all of the halo information is the
-:class:`~yt.analysis_modules.halo_analysis.halo_catalog.HaloCatalog`.
+If you already have a halo catalog, either produced by one of the methods
+below or in a format described in :ref:`halo-catalog-data`, and want to
+perform further analysis, skip to :ref:`halo_catalog_analysis`.
+
+Three halo finding methods exist within yt. These are:
+
+* :ref:`fof`: a basic friend-of-friends algorithm (e.g. `Efstathiou et al. (1985)
+ <http://adsabs.harvard.edu/abs/1985ApJS...57..241E>`_)
+* :ref:`hop`: `Eisenstein and Hut (1998)
+ <http://adsabs.harvard.edu/abs/1998ApJ...498..137E>`_.
+* :ref:`rockstar`: a 6D phase-space halo finder developed by Peter Behroozi that
+ scales well and does substructure finding (`Behroozi et al.
+ 2011 <http://adsabs.harvard.edu/abs/2011arXiv1110.4372B>`_)
+
+Halo finding is performed through the creation of a
+:class:`~yt.analysis_modules.halo_analysis.halo_catalog.HaloCatalog`
+object. The dataset on which halo finding is to be performed should
+be loaded and given to the
+:class:`~yt.analysis_modules.halo_analysis.halo_catalog.HaloCatalog`
+along with the ``finder_method`` keyword to specify the method to be
+used.
.. code-block:: python
@@ -31,28 +45,187 @@
data_ds = yt.load('Enzo_64/RD0006/RedshiftOutput0006')
hc = HaloCatalog(data_ds=data_ds, finder_method='hop')
+ hc.create()
-A halo catalog may also be created from already run rockstar outputs.
-This method is not implemented for previously run friends-of-friends or
-HOP finders. Even though rockstar creates one file per processor,
-specifying any one file allows the full catalog to be loaded. Here we
-only specify the file output by the processor with ID 0. Note that the
-argument for supplying a rockstar output is `halos_ds`, not `data_ds`.
+The ``finder_method`` options should be given as "fof", "hop", or
+"rockstar". Each of these methods has their own set of keyword
+arguments to control functionality. These can specified in the form
+of a dictinoary using the ``finder_kwargs`` keyword.
.. code-block:: python
- halos_ds = yt.load(path+'rockstar_halos/halos_0.0.bin')
- hc = HaloCatalog(halos_ds=halos_ds)
+ import yt
+ from yt.analysis_modules.halo_analysis.api import HaloCatalog
-Although supplying only the binary output of the rockstar halo finder
-is sufficient for creating a halo catalog, it is not possible to find
-any new information about the identified halos. To associate the halos
-with the dataset from which they were found, supply arguments to both
-halos_ds and data_ds.
+ data_ds = yt.load('Enzo_64/RD0006/RedshiftOutput0006')
+ hc = HaloCatalog(data_ds=data_ds, finder_method='fof',
+ finder_kwargs={"ptype": "stars",
+ "padding": 0.02})
+ hc.create()
+
+For a full list of keywords for each halo finder, see
+:class:`~yt.analysis_modules.halo_finding.halo_objects.FOFHaloFinder`,
+:class:`~yt.analysis_modules.halo_finding.halo_objects.HOPHaloFinder`,
+and
+:class:`~yt.analysis_modules.halo_finding.rockstar.rockstar.RockstarHaloFinder`.
+
+FOF
+^^^
+
+This is a basic friends-of-friends algorithm. See
+`Efstathiou et al. (1985)
+<http://adsabs.harvard.edu/abs/1985ApJS...57..241E>`_ for more
+details as well as
+:class:`~yt.analysis_modules.halo_finding.halo_objects.FOFHaloFinder`.
+
+HOP
+^^^
+
+The version of HOP used in yt is an upgraded version of the
+`publicly available HOP code
+<http://cmb.as.arizona.edu/~eisenste/hop/hop.html>`_. Support
+for 64-bit floats and integers has been added, as well as
+parallel analysis through spatial decomposition. HOP builds
+groups in this fashion:
+
+#. Estimates the local density at each particle using a
+ smoothing kernel.
+
+#. Builds chains of linked particles by 'hopping' from one
+ particle to its densest neighbor. A particle which is
+ its own densest neighbor is the end of the chain.
+
+#. All chains that share the same densest particle are
+ grouped together.
+
+#. Groups are included, linked together, or discarded
+ depending on the user-supplied over density
+ threshold parameter. The default is 160.0.
+
+See the `HOP method paper
+<http://adsabs.harvard.edu/abs/1998ApJ...498..137E>`_ for
+full details as well as
+:class:`~yt.analysis_modules.halo_finding.halo_objects.HOPHaloFinder`.
+
+Rockstar
+^^^^^^^^
+
+Rockstar uses an adaptive hierarchical refinement of friends-of-friends
+groups in six phase-space dimensions and one time dimension, which
+allows for robust (grid-independent, shape-independent, and noise-
+resilient) tracking of substructure. The code is prepackaged with yt,
+but also `separately available <https://bitbucket.org/gfcstanford/rockstar>`_. The lead
+developer is Peter Behroozi, and the methods are described in `Behroozi
+et al. 2011 <http://arxiv.org/abs/1110.4372>`_.
+In order to run the Rockstar halo finder in yt, make sure you've
+:ref:`installed it so that it can integrate with yt <rockstar-installation>`.
+
+At the moment, Rockstar does not support multiple particle masses,
+instead using a fixed particle mass. This will not affect most dark matter
+simulations, but does make it less useful for finding halos from the stellar
+mass. In simulations where the highest-resolution particles all have the
+same mass (ie: zoom-in grid based simulations), one can set up a particle
+filter to select the lowest mass particles and perform the halo finding
+only on those. See the this cookbook recipe for an example:
+:ref:`cookbook-rockstar-nested-grid`.
+
+To run the Rockstar Halo finding, you must launch python with MPI and
+parallelization enabled. While Rockstar itself does not require MPI to run,
+the MPI libraries allow yt to distribute particle information across multiple
+nodes.
+
+.. warning:: At the moment, running Rockstar inside of yt on multiple compute nodes
+ connected by an Infiniband network can be problematic. Therefore, for now
+ we recommend forcing the use of the non-Infiniband network (e.g. Ethernet)
+ using this flag: ``--mca btl ^openib``.
+ For example, here is how Rockstar might be called using 24 cores:
+ ``mpirun -n 24 --mca btl ^openib python ./run_rockstar.py --parallel``.
+
+The script above configures the Halo finder, launches a server process which
+disseminates run information and coordinates writer-reader processes.
+Afterwards, it launches reader and writer tasks, filling the available MPI
+slots, which alternately read particle information and analyze for halo
+content.
+
+The RockstarHaloFinder class has these options that can be supplied to the
+halo catalog through the ``finder_kwargs`` argument:
+
+* ``dm_type``, the index of the dark matter particle. Default is 1.
+* ``outbase``, This is where the out*list files that Rockstar makes should be
+ placed. Default is 'rockstar_halos'.
+* ``num_readers``, the number of reader tasks (which are idle most of the
+ time.) Default is 1.
+* ``num_writers``, the number of writer tasks (which are fed particles and
+ do most of the analysis). Default is MPI_TASKS-num_readers-1.
+ If left undefined, the above options are automatically
+ configured from the number of available MPI tasks.
+* ``force_res``, the resolution that Rockstar uses for various calculations
+ and smoothing lengths. This is in units of Mpc/h.
+ If no value is provided, this parameter is automatically set to
+ the width of the smallest grid element in the simulation from the
+ last data snapshot (i.e. the one where time has evolved the
+ longest) in the time series:
+ ``ds_last.index.get_smallest_dx() * ds_last['Mpch']``.
+* ``total_particles``, if supplied, this is a pre-calculated
+ total number of dark matter
+ particles present in the simulation. For example, this is useful
+ when analyzing a series of snapshots where the number of dark
+ matter particles should not change and this will save some disk
+ access time. If left unspecified, it will
+ be calculated automatically. Default: ``None``.
+* ``dm_only``, if set to ``True``, it will be assumed that there are
+ only dark matter particles present in the simulation.
+ This option does not modify the halos found by Rockstar, however
+ this option can save disk access time if there are no star particles
+ (or other non-dark matter particles) in the simulation. Default: ``False``.
+
+Rockstar dumps halo information in a series of text (halo*list and
+out*list) and binary (halo*bin) files inside the ``outbase`` directory.
+We use the halo list classes to recover the information.
+
+Inside the ``outbase`` directory there is a text file named ``datasets.txt``
+that records the connection between ds names and the Rockstar file names.
+
+Installing Rockstar
+"""""""""""""""""""
+
+Because of changes in the Rockstar API over time, yt only currently works with
+a slightly older version of Rockstar. This version of Rockstar has been
+slightly patched and modified to run as a library inside of yt. By default it
+is not installed with yt, but installation is very easy. The
+:ref:`install-script` used to install yt from source has a line:
+``INST_ROCKSTAR=0`` that must be changed to ``INST_ROCKSTAR=1``. You can
+rerun this installer script over the top of an existing installation, and
+it will only install components missing from the existing installation.
+You can do this as follows. Put your freshly modified install_script in
+the parent directory of the yt installation directory (e.g. the parent of
+``$YT_DEST``, ``yt-x86_64``, ``yt-i386``, etc.), and rerun the installer:
+
+.. code-block:: bash
+
+ cd $YT_DEST
+ cd ..
+ vi install_script.sh // or your favorite editor to change INST_ROCKSTAR=1
+ bash < install_script.sh
+
+This will download Rockstar and install it as a library in yt.
+
+.. _halo_catalog_analysis:
+
+Extra Halo Analysis
+-------------------
+
+As a reminder, all halo catalogs created by the methods outlined in
+:ref:`halo_catalog_finding` as well as those in the formats discussed in
+:ref:`halo-catalog-data` can be loaded in to yt as first-class datasets.
+Once a halo catalog has been created, further analysis can be performed
+by providing both the halo catalog and the original simulation dataset to
+the
+:class:`~yt.analysis_modules.halo_analysis.halo_catalog.HaloCatalog`.
.. code-block:: python
- halos_ds = yt.load(path+'rockstar_halos/halos_0.0.bin')
+ halos_ds = yt.load('rockstar_halos/halos_0.0.bin')
data_ds = yt.load('Enzo_64/RD0006/RedshiftOutput0006')
hc = HaloCatalog(data_ds=data_ds, halos_ds=halos_ds)
@@ -60,24 +233,28 @@
associated with either dataset, to control the spatial region in
which halo analysis will be performed.
-Analysis Using Halo Catalogs
-----------------------------
-
-Analysis is done by adding actions to the
+The :class:`~yt.analysis_modules.halo_analysis.halo_catalog.HaloCatalog`
+allows the user to create a pipeline of analysis actions that will be
+performed on all halos in the existing catalog. The analysis can be
+performed in parallel with separate processors or groups of processors
+being allocated to perform the entire pipeline on individual halos.
+The pipeline is setup by adding actions to the
:class:`~yt.analysis_modules.halo_analysis.halo_catalog.HaloCatalog`.
Each action is represented by a callback function that will be run on
each halo. There are four types of actions:
-* Filters
-* Quantities
-* Callbacks
-* Recipes
+* :ref:`halo_catalog_filters`
+* :ref:`halo_catalog_quantities`
+* :ref:`halo_catalog_callbacks`
+* :ref:`halo_catalog_recipes`
A list of all available filters, quantities, and callbacks can be found in
:ref:`halo_analysis_ref`.
All interaction with this analysis can be performed by importing from
halo_analysis.
+.. _halo_catalog_filters:
+
Filters
^^^^^^^
@@ -118,6 +295,8 @@
# ... Later on in your script
hc.add_filter("my_filter")
+.. _halo_catalog_quantities:
+
Quantities
^^^^^^^^^^
@@ -176,6 +355,8 @@
# ... Anywhere after "my_quantity" has been called
hc.add_callback("print_quantity")
+.. _halo_catalog_callbacks:
+
Callbacks
^^^^^^^^^
@@ -214,6 +395,8 @@
# ... Later on in your script
hc.add_callback("my_callback")
+.. _halo_catalog_recipes:
+
Recipes
^^^^^^^
@@ -258,8 +441,8 @@
object as the first argument, recipe functions should take a ``HaloCatalog``
object as the first argument.
-Running Analysis
-----------------
+Running the Pipeline
+--------------------
After all callbacks, quantities, and filters have been added, the
analysis begins with a call to HaloCatalog.create.
@@ -290,7 +473,7 @@
A :class:`~yt.analysis_modules.halo_analysis.halo_catalog.HaloCatalog`
saved to disk can be reloaded as a yt dataset with the
-standard call to load. Any side data, such as profiles, can be reloaded
+standard call to ``yt.load``. Any side data, such as profiles, can be reloaded
with a ``load_profiles`` callback and a call to
:func:`~yt.analysis_modules.halo_analysis.halo_catalog.HaloCatalog.load`.
@@ -303,8 +486,8 @@
filename="virial_profiles")
hc.load()
-Worked Example of Halo Catalog in Action
-----------------------------------------
+Halo Catalog in Action
+----------------------
For a full example of how to use these methods together see
:ref:`halo-analysis-example`.
diff -r 77c1b9653da76332bfe6baccb489f1973ee3c0b1 -r baec4945cd28a161c1b7b42c63840c9626da7174 doc/source/analyzing/analysis_modules/halo_finders.rst
--- a/doc/source/analyzing/analysis_modules/halo_finders.rst
+++ /dev/null
@@ -1,231 +0,0 @@
-.. _halo_finding:
-
-Halo Finding
-============
-
-There are three methods of finding particle haloes in yt. The
-default method is called HOP, a method described
-in `Eisenstein and Hut (1998)
-<http://adsabs.harvard.edu/abs/1998ApJ...498..137E>`_. A basic
-friends-of-friends (e.g. `Efstathiou et al. (1985)
-<http://adsabs.harvard.edu/abs/1985ApJS...57..241E>`_) halo
-finder is also implemented. Finally Rockstar (`Behroozi et a.
-(2011) <http://adsabs.harvard.edu/abs/2011arXiv1110.4372B>`_) is
-a 6D-phase space halo finder developed by Peter Behroozi that
-excels in finding subhalos and substrcture, but does not allow
-multiple particle masses.
-
-.. _hop:
-
-HOP
----
-
-The version of HOP used in yt is an upgraded version of the
-`publicly available HOP code
-<http://cmb.as.arizona.edu/~eisenste/hop/hop.html>`_. Support
-for 64-bit floats and integers has been added, as well as
-parallel analysis through spatial decomposition. HOP builds
-groups in this fashion:
-
-#. Estimates the local density at each particle using a
- smoothing kernel.
-
-#. Builds chains of linked particles by 'hopping' from one
- particle to its densest neighbor. A particle which is
- its own densest neighbor is the end of the chain.
-
-#. All chains that share the same densest particle are
- grouped together.
-
-#. Groups are included, linked together, or discarded
- depending on the user-supplied over density
- threshold parameter. The default is 160.0.
-
-Please see the `HOP method paper
-<http://adsabs.harvard.edu/abs/1998ApJ...498..137E>`_ for
-full details and the
-:class:`~yt.analysis_modules.halo_finding.halo_objects.HOPHaloFinder`
-documentation.
-
-.. _fof:
-
-FOF
----
-
-A basic friends-of-friends halo finder is included. See the
-:class:`~yt.analysis_modules.halo_finding.halo_objects.FOFHaloFinder`
-documentation.
-
-.. _rockstar:
-
-Rockstar Halo Finding
----------------------
-
-Rockstar uses an adaptive hierarchical refinement of friends-of-friends
-groups in six phase-space dimensions and one time dimension, which
-allows for robust (grid-independent, shape-independent, and noise-
-resilient) tracking of substructure. The code is prepackaged with yt,
-but also `separately available <https://bitbucket.org/gfcstanford/rockstar>`_. The lead
-developer is Peter Behroozi, and the methods are described in `Behroozi
-et al. 2011 <http://arxiv.org/abs/1110.4372>`_.
-In order to run the Rockstar halo finder in yt, make sure you've
-:ref:`installed it so that it can integrate with yt <rockstar-installation>`.
-
-At the moment, Rockstar does not support multiple particle masses,
-instead using a fixed particle mass. This will not affect most dark matter
-simulations, but does make it less useful for finding halos from the stellar
-mass. In simulations where the highest-resolution particles all have the
-same mass (ie: zoom-in grid based simulations), one can set up a particle
-filter to select the lowest mass particles and perform the halo finding
-only on those. See the this cookbook recipe for an example:
-:ref:`cookbook-rockstar-nested-grid`.
-
-To run the Rockstar Halo finding, you must launch python with MPI and
-parallelization enabled. While Rockstar itself does not require MPI to run,
-the MPI libraries allow yt to distribute particle information across multiple
-nodes.
-
-.. warning:: At the moment, running Rockstar inside of yt on multiple compute nodes
- connected by an Infiniband network can be problematic. Therefore, for now
- we recommend forcing the use of the non-Infiniband network (e.g. Ethernet)
- using this flag: ``--mca btl ^openib``.
- For example, here is how Rockstar might be called using 24 cores:
- ``mpirun -n 24 --mca btl ^openib python ./run_rockstar.py --parallel``.
-
-The script above configures the Halo finder, launches a server process which
-disseminates run information and coordinates writer-reader processes.
-Afterwards, it launches reader and writer tasks, filling the available MPI
-slots, which alternately read particle information and analyze for halo
-content.
-
-The RockstarHaloFinder class has these options that can be supplied to the
-halo catalog through the ``finder_kwargs`` argument:
-
-* ``dm_type``, the index of the dark matter particle. Default is 1.
-* ``outbase``, This is where the out*list files that Rockstar makes should be
- placed. Default is 'rockstar_halos'.
-* ``num_readers``, the number of reader tasks (which are idle most of the
- time.) Default is 1.
-* ``num_writers``, the number of writer tasks (which are fed particles and
- do most of the analysis). Default is MPI_TASKS-num_readers-1.
- If left undefined, the above options are automatically
- configured from the number of available MPI tasks.
-* ``force_res``, the resolution that Rockstar uses for various calculations
- and smoothing lengths. This is in units of Mpc/h.
- If no value is provided, this parameter is automatically set to
- the width of the smallest grid element in the simulation from the
- last data snapshot (i.e. the one where time has evolved the
- longest) in the time series:
- ``ds_last.index.get_smallest_dx() * ds_last['Mpch']``.
-* ``total_particles``, if supplied, this is a pre-calculated
- total number of dark matter
- particles present in the simulation. For example, this is useful
- when analyzing a series of snapshots where the number of dark
- matter particles should not change and this will save some disk
- access time. If left unspecified, it will
- be calculated automatically. Default: ``None``.
-* ``dm_only``, if set to ``True``, it will be assumed that there are
- only dark matter particles present in the simulation.
- This option does not modify the halos found by Rockstar, however
- this option can save disk access time if there are no star particles
- (or other non-dark matter particles) in the simulation. Default: ``False``.
-
-Rockstar dumps halo information in a series of text (halo*list and
-out*list) and binary (halo*bin) files inside the ``outbase`` directory.
-We use the halo list classes to recover the information.
-
-Inside the ``outbase`` directory there is a text file named ``datasets.txt``
-that records the connection between ds names and the Rockstar file names.
-
-For more information, see the
-:class:`~yt.analysis_modules.halo_finding.halo_objects.RockstarHalo` and
-:class:`~yt.analysis_modules.halo_finding.halo_objects.Halo` classes.
-
-.. _parallel-hop-and-fof:
-
-Parallel HOP and FOF
---------------------
-
-Both the HOP and FoF halo finders can run in parallel using simple
-spatial decomposition. In order to run them in parallel it is helpful
-to understand how it works. Below in the first plot (i) is a simplified
-depiction of three haloes labeled 1,2 and 3:
-
-.. image:: _images/ParallelHaloFinder.png
- :width: 500
-
-Halo 3 is twice reflected around the periodic boundary conditions.
-
-In (ii), the volume has been sub-divided into four equal subregions,
-A,B,C and D, shown with dotted lines. Notice that halo 2 is now in
-two different subregions, C and D, and that halo 3 is now in three,
-A, B and D. If the halo finder is run on these four separate subregions,
-halo 1 is be identified as a single halo, but haloes 2 and 3 are split
-up into multiple haloes, which is incorrect. The solution is to give
-each subregion padding to oversample into neighboring regions.
-
-In (iii), subregion C has oversampled into the other three regions,
-with the periodic boundary conditions taken into account, shown by
-dot-dashed lines. The other subregions oversample in a similar way.
-
-The halo finder is then run on each padded subregion independently
-and simultaneously. By oversampling like this, haloes 2 and 3 will
-both be enclosed fully in at least one subregion and identified
-completely.
-
-Haloes identified with centers of mass inside the padded part of a
-subregion are thrown out, eliminating the problem of halo duplication.
-The centers for the three haloes are shown with stars. Halo 1 will
-belong to subregion A, 2 to C and 3 to B.
-
-To run with parallel halo finding, you must supply a value for
-padding in the finder_kwargs argument. The ``padding`` parameter
-is in simulation units and defaults to 0.02. This parameter is how
-much padding is added to each of the six sides of a subregion.
-This value should be 2x-3x larger than the largest expected halo
-in the simulation. It is unlikely, of course, that the largest
-object in the simulation will be on a subregion boundary, but there
-is no way of knowing before the halo finder is run.
-
-.. code-block:: python
-
- import yt
- from yt.analysis_modules.halo_analysis.api import *
- ds = yt.load("data0001")
-
- hc = HaloCatalog(data_ds = ds, finder_method = 'hop', finder_kwargs={'padding':0.02})
- # --or--
- hc = HaloCatalog(data_ds = ds, finder_method = 'fof', finder_kwargs={'padding':0.02})
-
-In general, a little bit of padding goes a long way, and too much
-just slows down the analysis and doesn't improve the answer (but
-doesn't change it). It may be worth your time to run the parallel
-halo finder at a few paddings to find the right amount, especially
-if you're analyzing many similar datasets.
-
-.. _rockstar-installation:
-
-Rockstar Installation
----------------------
-
-Because of changes in the Rockstar API over time, yt only currently works with
-a slightly older version of Rockstar. This version of Rockstar has been
-slightly patched and modified to run as a library inside of yt. By default it
-is not installed with yt, but installation is very easy. The
-:ref:`install-script` used to install yt from source has a line:
-``INST_ROCKSTAR=0`` that must be changed to ``INST_ROCKSTAR=1``. You can
-rerun this installer script over the top of an existing installation, and
-it will only install components missing from the existing installation.
-You can do this as follows. Put your freshly modified install_script in
-the parent directory of the yt installation directory (e.g. the parent of
-``$YT_DEST``, ``yt-x86_64``, ``yt-i386``, etc.), and rerun the installer:
-
-.. code-block:: bash
-
- cd $YT_DEST
- cd ..
- vi install_script.sh // or your favorite editor to change INST_ROCKSTAR=1
- bash < install_script.sh
-
-This will download Rockstar and install it as a library in yt. You should now
-be able to use Rockstar and yt together.
diff -r 77c1b9653da76332bfe6baccb489f1973ee3c0b1 -r baec4945cd28a161c1b7b42c63840c9626da7174 doc/source/analyzing/analysis_modules/halo_transition.rst
--- a/doc/source/analyzing/analysis_modules/halo_transition.rst
+++ b/doc/source/analyzing/analysis_modules/halo_transition.rst
@@ -1,11 +1,12 @@
.. _halo-transition:
-Getting up to Speed with Halo Analysis in yt-3.0
-================================================
+Transitioning From yt-2 to yt-3
+===============================
If you're used to halo analysis in yt-2.x, heres a guide to
how to update your analysis pipeline to take advantage of
-the new halo catalog infrastructure.
+the new halo catalog infrastructure. If you're starting
+from scratch, see :ref:`halo_catalog`.
Finding Halos
-------------
diff -r 77c1b9653da76332bfe6baccb489f1973ee3c0b1 -r baec4945cd28a161c1b7b42c63840c9626da7174 doc/source/analyzing/analysis_modules/index.rst
--- a/doc/source/analyzing/analysis_modules/index.rst
+++ b/doc/source/analyzing/analysis_modules/index.rst
@@ -19,4 +19,3 @@
two_point_functions
clump_finding
particle_trajectories
- ellipsoid_analysis
diff -r 77c1b9653da76332bfe6baccb489f1973ee3c0b1 -r baec4945cd28a161c1b7b42c63840c9626da7174 doc/source/examining/loading_data.rst
--- a/doc/source/examining/loading_data.rst
+++ b/doc/source/examining/loading_data.rst
@@ -1357,24 +1357,91 @@
a bounding box, field specification, and units as are done for standard
Gadget outputs. See :ref:`loading-gadget-data` for more information.
-.. _loading-pyne-data:
+.. _halo-catalog-data:
Halo Catalog Data
-----------------
yt has support for reading halo catalogs produced by Rockstar and the inline
FOF/SUBFIND halo finders of Gadget and OWLS. The halo catalogs are treated as
-particle datasets where each particle represents a single halo. Member particles
-for individual halos can be accessed through halo data containers. Further halo
-analysis can be performed using :ref:`halo_catalog`.
+particle datasets where each particle represents a single halo. For example,
+this means that the `particle_mass` field refers to the mass of the halos. For
+Gadget FOF/SUBFIND catalogs, the member particles for a given halo can be
+accessed by creating `halo` data containers. See :ref:`halo_containers` for
+more information.
-In the case where halo catalogs are written to multiple files, one must only
-give the path to one of them.
+If you have access to both the halo catalog and the simulation snapshot from
+the same redshift, additional analysis can be performed for each halo using
+:ref:`halo_catalog`.
+
+.. _rockstar:
+
+Rockstar
+^^^^^^^^
+
+Rockstar halo catalogs are loaded by providing the path to one of the .bin files.
+In the case where multiple files were produced, one need only provide the path
+to a single one of them. The field type for all fields is "halos". Some fields
+of note available from Rockstar are:
+
++----------------+---------------------------+
+| Rockstar field | yt field name |
++================+===========================+
+| halo id | particle_identifier |
++----------------+---------------------------+
+| virial mass | particle_mass |
++----------------+---------------------------+
+| virial radius | virial_radius |
++----------------+---------------------------+
+| halo position | particle_position_(x,y,z) |
++----------------+---------------------------+
+| halo velocity | particle_velocity_(x,y,z) |
++----------------+---------------------------+
+
+Numerous other Rockstar fields exist. To see them, check the field list by
+typing `ds.field_list` for a dataset loaded as `ds`. Like all other datasets,
+fields must be accessed through :ref:`Data-objects`.
+
+.. code-block:: python
+
+ import yt
+ ds = yt.load("rockstar_halos/halos_0.0.bin")
+ ad = ds.all_data()
+ # halo masses
+ print(ad["halos", "particle_mass"])
+ # halo radii
+ print(ad["halos", "virial_radius"])
+
+.. _gadget_fof:
Gadget FOF/SUBFIND
^^^^^^^^^^^^^^^^^^
-The two field types for GadgetFOF data are "Group" (FOF) and "Subhalo" (SUBFIND).
+Gadget FOF/SUBFIND halo catalogs work in the same way as those created by
+:ref:`rockstar`, except there are two field types: `FOF` for friend-of-friends
+groups and `Subhalo` for halos found with the SUBFIND substructure finder.
+Also like Rockstar, there are a number of fields specific to these halo
+catalogs.
+
++-------------------+---------------------------+
+| FOF/SUBFIND field | yt field name |
++===================+===========================+
+| halo id | particle_identifier |
++-------------------+---------------------------+
+| halo mass | particle_mass |
++-------------------+---------------------------+
+| halo position | particle_position_(x,y,z) |
++-------------------+---------------------------+
+| halo velocity | particle_velocity_(x,y,z) |
++-------------------+---------------------------+
+| num. of particles | particle_number |
++-------------------+---------------------------+
+| num. of subhalos | subhalo_number (FOF only) |
++-------------------+---------------------------+
+
+Many other fields exist, especially for SUBFIND subhalos. Check the field
+list by typing `ds.field_list` for a dataset loaded as `ds`. Like all
+other datasets, fields must be accessed through :ref:`Data-objects`.
.. code-block:: python
@@ -1400,6 +1467,11 @@
# x component of the spin
print(ad["Subhalo", "SubhaloSpin_0"])
+.. _halo_containers:
+
+Halo Data Containers
+^^^^^^^^^^^^^^^^^^^^
+
Halo member particles are accessed by creating halo data containers with the
type of halo ("Group" or "Subhalo") and the halo id. Scalar values for halos
can be accessed in the same way. Halos also have mass, position, and velocity
@@ -1431,8 +1503,8 @@
^^^^^^^^^^^^^^^^
OWLS halo catalogs have a very similar structure to regular Gadget halo catalogs.
-The two field types are "FOF" and "SUBFIND". At this time, halo member particles
-cannot be loaded.
+The two field types are `FOF` and `SUBFIND`. See :ref:`gadget_fof` for more
+information. At this time, halo member particles cannot be loaded.
.. code-block:: python
@@ -1442,19 +1514,7 @@
# The halo mass
print(ad["FOF", "particle_mass"])
-Rockstar
-^^^^^^^^
-
-Rockstar halo catalogs are loaded by providing the path to one of the .bin files.
-The single field type available is "halos".
-
-.. code-block:: python
-
- import yt
- ds = yt.load("rockstar_halos/halos_0.0.bin")
- ad = ds.all_data()
- # The halo mass
- print(ad["halos", "particle_mass"])
+.. _loading-pyne-data:
PyNE Data
---------
diff -r 77c1b9653da76332bfe6baccb489f1973ee3c0b1 -r baec4945cd28a161c1b7b42c63840c9626da7174 yt/analysis_modules/halo_analysis/halo_catalog.py
--- a/yt/analysis_modules/halo_analysis/halo_catalog.py
+++ b/yt/analysis_modules/halo_analysis/halo_catalog.py
@@ -98,7 +98,7 @@
See Also
--------
- add_callback, add_filter, add_finding_method, add_quantity
+ add_callback, add_filter, add_quantity, add_recipe
"""
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