[Yt-svn] commit/yt-doc: sskory: Adding information about the treecode for gravitational boundedness.

[Bitbucket]

1 new changeset in yt-doc:

http://bitbucket.org/yt_analysis/yt-doc/changeset/23073650dd29/
changeset:   r51:23073650dd29
user:        sskory
date:        2011-03-28 21:42:49
summary:     Adding information about the treecode for gravitational boundedness.
affected #:  1 file (3.5 KB)

--- a/source/analysis_modules/clump_finding.rst	Fri Mar 25 01:05:59 2011 -0400
+++ b/source/analysis_modules/clump_finding.rst	Mon Mar 28 13:42:49 2011 -0600
@@ -24,3 +24,94 @@
 Once the clump-finder has finished, the user can write out a set of quantities for each clump in the 
 hierarchy.  Additional info items can also be added.  We also provide a recipe
 for finding clumps in :ref:`cookbook-find_clumps`.
+
+Treecode Optimization
+---------------------
+
+.. sectionauthor:: Stephen Skory <s at skory.us>
+.. versionadded:: 2.1
+
+As mentioned above, the user has the option to limit clumps to those that are
+gravitationally bound.
+The correct and accurate way to calculate if a clump is gravitationally
+bound is to do the full double sum:
+
+.. math::
+
+  PE = \Sigma_{i=1}^N \Sigma_{j=i}^N \frac{G M_i M_j}{r_{ij}}
+
+where PE is the gravitational potential energy of N cells, G is the
+gravitational constant, M_i is the mass of cell i, and r_{ij} is the distance
+between cell i and j. The number of calculations required for this calculation
+grows with the square of N. Therefore, for large clumps with many cells, the
+test for boundedness can take a significant amount of time.
+
+An effective way to greatly speed up this calculation with minimal error
+is to use the treecode approximation pioneered by
+`Barnes and Hut (1986) <http://adsabs.harvard.edu/abs/1986Natur.324..446B>`_.
+This method of calculating gravitational potentials works by
+grouping individual masses that are located close together into a larger conglomerated
+mass with a geometric size equal to the distribution of the individual masses.
+For a mass cell that is sufficiently distant from the conglomerated mass,
+the gravitational calculation can be made using the conglomerate, rather than
+each individual mass, which saves time.
+
+The decision whether or not to use a conglomerate depends on the accuracy control
+parameter ``opening_angle``. Using the small-angle approximation, a conglomerate
+may be used if its geometric size subtends an angle no greater than the
+``opening_angle`` upon the remote mass. The default value is
+``opening_angle = 1``, which gives errors well under 1%. A value of 
+``opening_angle = 0`` is identical to the full O(N^2) method, and larger values
+will speed up the calculation and sacrifice accuracy.
+
+The treecode method is iterative. Conglomerates may themselves form larger
+conglomerates. And if a larger conglomerate does not meet the ``opening_angle``
+criterion, the smaller conglomerates are tested as well. This iteration of 
+conglomerates will
+cease once the level of the original masses is reached (this is what happens
+if ``opening_angle = 0``).
+
+Below are some examples of how to control the usage of the treecode.
+
+This example will calculate the ratio of the potential energy to kinetic energy
+for a spherical clump using the treecode method with an opening angle of 2.
+The default opening angle is 1.0:
+
+.. python::
+  
+  from yt.mods import *
+  
+  pf = load("DD0000")
+  sp = pf.h.sphere([0.5, 0.5, 0.5], radius=0.1)
+  
+  ratio = sp.quantities["IsBound"](truncate=False, include_thermal_energy=True,
+      treecode=True, opening_angle=2.0)
+
+This example will accomplish the same as the above, but will use the full
+N^2 method.
+
+.. python::
+  
+  from yt.mods import *
+  
+  pf = load("DD0000")
+  sp = pf.h.sphere([0.5, 0.5, 0.5], radius=0.1)
+  
+  ratio = sp.quantities["IsBound"](truncate=False, include_thermal_energy=True,
+      treecode=False)
+
+Here the treecode method is specified for clump finding (this is default).
+Please see the link above for the full example of how to find clumps (the
+trailing backslash is important!):
+
+.. python::
+  
+  function_name = 'self.data.quantities["IsBound"](truncate=True, \
+      include_thermal_energy=True, treecode=True, opening_angle=2.0) > 1.0'
+  master_clump = amods.level_sets.Clump(data_source, None, field,
+      function=function_name)
+
+To turn off the treecode, of course one should turn treecode=False in the
+example above.
+
+

Repository URL: https://bitbucket.org/yt_analysis/yt-doc/

--

This is a commit notification from bitbucket.org. You are receiving
this because you have the service enabled, addressing the recipient of
this email.