Commits

Britton Smith committed 1069ec9

Updating halo profiler docs for expanded parallelism and to discuss
the analyze_halo_spheres function.

Comments (0)

Files changed (1)

source/analysis_modules/halo_profiling.rst

 become the hosts for galaxies and galaxy clusters.
 
 The halo profiler performs two primary functions: radial profiles and projections.  
-With only a few exceptions discussed below, all of the halo profiler's machinery can 
-be run in parallel, with `mpi4py <http://code.google.com/p/mpi4py/>`_ installed, by running 
+The halo profiler can be run in parallel, with `mpi4py
+<http://code.google.com/p/mpi4py/>`_ installed, by running 
 your script inside an mpirun call with the --parallel flag at the end.
 
 Configuring the Halo Profiler
 
 .. code-block:: python
 
-  import yt.analysis_modules.halo_profiler.api as HP
-  hp = HP.HaloProfiler("DD0242/DD0242")
+  from yt.analysis_modules.halo_profiler.api import *
+  hp = HaloProfiler("DD0242/DD0242")
 
 Most of the halo profiler's options are configured with keyword arguments given at 
 instantiation.  These options are:
    options are:
    - ["bulk", "halo"] (Default): the velocity provided in the halo list
    - ["bulk", "sphere"]: the bulk velocity of the sphere centered on the halo center.
-   - ["max", field]: the velocity of the cell that is the location of the maximum of the field specified (used only when halos set to single).
+   - ["max", field]: the velocity of the cell that is the location of the maximum of the field specified.
 
  * **filter_quantities** (*list*): quantities from the original halo list
    file to be written out in the filtered list file.  Default: ['id','center'].
    overdensity is with respect to mean matter density, which is lower by a factor 
    of Omega_M.  Default: False.
 
-
-.. warning:: The halo profiler runs in parallel in a round-robin style, evenly
-   distributing the list of halos among all processors.  Hence, the halo profiler will not work in parallel when **halos** is set to single.
-
 Profiles
 --------
 
   hp.add_profile('TotalMassMsun', weight_field=None, accumulation=True)
   hp.add_profile('Density', weight_field=None, accumulation=False)
   hp.add_profile('Temperature', weight_field='CellMassMsun', accumulation=False)
-  hp.make_profiles()
+  hp.make_profiles(njobs=-1)
 
-The :meth:`make_profiles` method will begin the profiling.
+The :meth:`make_profiles` method will begin the profiling.  Use the
+**njobs** keyword to control the number of jobs over which the
+profiling is divided.  Setting to -1 results in a single processor per
+halo.  Setting to 1 results in all available processors working on the
+same halo.
 
 .. image:: _images/profiles.png
    :width: 500
   hp.add_projection('Density', weight_field=None)
   hp.add_projection('Temperature', weight_field='Density')
   hp.add_projection('Metallicity', weight_field='Density')
-  hp.make_projections(axes=[0, 1, 2], save_cube=True, save_images=True, halo_list="filtered")
+  hp.make_projections(axes=[0, 1, 2], save_cube=True, save_images=True, 
+                                    halo_list="filtered", njobs=-1)
 
 If **save_cube** is set to True, the projection data
 will be written to a set of hdf5 files 
 the filtered list ("filtered"), or 
 an entirely new list given in the form of a file name.
 See :ref:`filter_functions` for a 
-discussion of filtering halos.
+discussion of filtering halos.  Use the **njobs** keyword to control
+the number of jobs over which the profiling is divided.  Setting to -1
+results in a single processor per halo.  Setting to 1 results in all
+available processors working on the same halo.
 
 .. image:: _images/projections.png
    :width: 500
    virial mass.
 
 Recentering the Halo For Analysis
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
 
 It is possible to move the center of the halo to a new point using an
 arbitrary function for making profiles.
 
 .. code-block:: python
 
-   hp = amods.halo_profiler.HaloProfiler("data0092",
-       recenter="Max_Dark_Matter_Density")
+   hp = HaloProfiler("data0092", recenter="Max_Dark_Matter_Density")
 
 
   * *Min_Dark_Matter_Density* - Recenter on the point of minimum dark matter
        ma, mini, mx, my, mz, mg = sphere.quantities['MinLocation']('Temperature')
        return [mx,my,mz]
    
-   hp = amods.halo_profiler.HaloProfiler("data0092",
-       recenter=find_min_temp)
+   hp = HaloProfiler("data0092", recenter=find_min_temp)
 
 It is possible to make more complicated functions. This example below extends
 the example above to include a distance control that prevents the center from
        if d > 5.: return [-1, -1, -1]
        return [mx,my,mz]
    
-   hp = amods.halo_profiler.HaloProfiler("data0092",
-       recenter=find_min_temp_dist)
+   hp = HaloProfiler("data0092", recenter=find_min_temp_dist)
 
 .. warning::
 
    If the halo profiler is run in parallel, and a recentering function is used
    that is user-defined, two flags need to be set in the ``quantities`` call
-   as in the example below. These need to be set explicitly because the defaults
-   will lead to crashes. The built-in recentering functions have these flags
-   set already.
+   as in the example below. The built-in recentering functions have
+   these flags set already.
    
    .. code-block:: python
       
       ma, mini, mx, my, mz, mg = sphere.quantities['MinLocation']('Temperature',
-        lazy_reader=False, preload=False)
+        lazy_reader=True, preload=False)
 
+
+Custom Halo Analysis
+------------------
+
+Besides radial profiles and projections, the halo profiler has the
+ability to run custom analysis functions on each halo.  Custom halo
+analysis functions take two arguments: a halo dictionary containing
+the id, center, etc; and a sphere object.  The example function shown
+below creates a 2D profile of the total mass in bins of density and
+temperature for a given halo.
+
+.. code-block:: python
+
+   from yt.mods import *
+   from yt.data_objects.profiles import BinnedProfile2D
+
+   def halo_2D_profile(halo, sphere):
+       "Make a 2D profile for a halo."
+       my_profile = BinnedProfile2D(sphere,
+             128, 'Density', 1e-30, 1e-24, True,
+             128, 'Temperature', 1e2, 1e7, True,
+             lazy_reader=True, end_collect=False)
+       my_profile.add_fields('CellMassMsun', weight=None, fractional=False)
+       my_filename = os.path.join(sphere.pf.fullpath, '2D_profiles', 
+             'Halo_%04d.h5' % halo['id'])
+       my_profile.write_out_h5(my_filename)
+
+Using the  :meth:`analyze_halo_spheres` function, the halo profiler
+will create a sphere centered on each halo, and perform the analysis
+from the custom routine.
+
+.. code-block:: python
+
+    hp.analyze_halo_sphere(halo_2D_profile, halo_list='filtered',
+        analysis_output_dir='2D_profiles', njobs=-1)
+
+Just like with the :meth:`make_projections` function, the keyword,
+**halo_list**, can be used to select between the full list of halos
+("all"), the filtered list ("filtered"), or an entirely new list given
+in the form of a file name.  If the **analysis_output_dir** keyword is
+set, the halo profiler will make sure the desired directory exists in
+a parallel-safe manner.  Use the **njobs** keyword to control the
+number of jobs over which the profiling is divided.  Setting to -1
+results in a single processor per halo.  Setting to 1 results in all
+available processors working on the same halo.