Fof documentation

doc/RTD/source/FriendsOfFriends/algorithm_description.rst

+.. Friends Of Friends
+   Matthieu Schaller 15th June 2019
+
+.. _fof_algorithm_description_label:
+
+Friends-Of-Friends Algorithm
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Friends-Of-Friends (FOF) is a common tool used to identify groups of
+particles in a simulation. This can, for instance, be used to identify
+haloes in a cosmological simulation.
+
+In practice, this is done by using a *linking length* ``l`` and
+demanding that any particle that finds another particle within a
+distance ``l`` is linked to it to form a group. A particle is linked
+directly to all other particles within a distance ``l`` (its
+*friends*) and indirectly to all particles that are linked to its
+friends (its *friends-of-friends*). This creates networks of linked particles
+which are called *groups*. The size (or length) of
+a group is the number of particles in that group. If a particle does not
+find any other particle within ``l`` then it forms its own group of
+size 1. For a given distribution of particles the resulting list of
+groups is unique and unambiguously defined.
+
+Small groups are typically discarded, the final catalogue only contains
+objects with a length above a minimal threshold, typically of the
+order of ``20`` particles. Smaller groups can often be spurious.
+
+Once the groups have been identified, properties can be computed for
+each of them. The total mass or the centre of mass are common
+examples. These are then stored in catalogues alongside a unique
+identifier for each group.
+
+SWIFT implements FOF using a Union-Find approach. It also exploits the
+domain decomposition and tree structure that is created for the other
+parts of the code. The tree can be easily used to find neighbours of
+particles within the linking length.
+
+Depending on the application, the choice of linking length and
+minimal group size can vary. For cosmological applications, bound
+structures (dark matter haloes) are traditionally identified using a
+linking length expressed as :math:`0.2` of the mean inter-particle
+separation :math:`d` in the simulation which is given by :math:`d =
+\sqrt[3]{\frac{V}{N}}`, where :math:`N` is the number of particles in
+the simulation and :math:`V` is the simulation (co-moving)
+volume. Usually only dark matter particles are considered for the
+number :math:`N`. Other particle types are linked but do not
+participate in the calculation of the linking length. Experience shows
+that this produces groups that are similar to the commonly adopted
+(but much more complex) definition of virialised haloes. A minimal
+group length of :math:`32` is often adopted in order to get a robust
+catalogue of haloes and compute a good halo mass function.
+
+For non-cosmological applications of the FOF algorithm, the choice of
+the linking length is more difficult and left to the user. The choice
+of the minimal group size to consider is also application dependent.
+
+In SWIFT, FOF is also used to identify haloes in which to seed black
+holes in a cosmological run. When used in this mode, the code does not
+produce any outputs but uses the catalogue internally to convert some
+gas particles into black hole particles.
+

doc/RTD/source/FriendsOfFriends/index.rst

+.. Friends Of Friends
+   Matthieu Schaller 15th June 2019
+
+.. _Friends_Of_Friends_label:
+
+Friends-Of-Friends (FOF) Halo Finder
+====================================
+
+This section describes the Friends-Of-Friends group
+finder and related parameters
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   algorithm_description
+   stand_alone_fof
+   on_the_fly_fof
+   parameter_description
+

doc/RTD/source/FriendsOfFriends/on_the_fly_fof.rst

+.. Friends Of Friends
+   Matthieu Schaller 15th June 2019
+
+.. _fof_on_the_fly_label:
+
+On-the-fly Friends-Of-Friends and Black Hole seeding
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The main purpose of the on-the-fly FOF is to identify haloes during a
+cosmological simulation in order to seed some of them with black holes
+based on physical considerations.
+
+**In this mode, no group catalogue is written to the disk. The resulting list
+of haloes is only used internally by SWIFT.**
+
+Once the haloes have been identified by the FOF code, SWIFT will iterate
+over the list of groups and will check whether each halo obeys the
+following criteria:
+
+  * Is above a user-specified mass threshold (typically
+    :math:`10^{10}~\rm{M}_\odot` or more).
+  * Contains *at least* one gas particle.
+  * Does *not* contain any already existing black hole particle.
+
+If a group satisfies all these requirements then the *densest* gas particle
+(based on their SPH density) in the group will be converted to a black
+hole. In practice this means that the gas particle is removed and a black
+hole particle with the same dynamical mass is inserted at the same position
+in the domain and with the same velocity. Additional properties are copied
+from the gas particle to the black hole particle depending on the specifics
+of the sub-grid model in use (see :ref:`subgrid`).
+
+Given that the halo mass considered for seeding black holes is usually many
+hundred times the mass of a single particle, it can be advantageous to
+raise the minimal group length required for a halo to appear in the catalogue
+of objects. This reduces the number of groups that are kept in memory and
+speeds up the seeding procedure by removing haloes that are obviously too
+small. For instance, in the case of EAGLE-like runs, the dark matter
+particle mass is around :math:`10^7\rm~{M}_\odot` and the minimal halo mass
+considered for seeding a black hole is of order
+:math:`10^{10}~\rm{M}_\odot`. Groups will hence need to have at least 1000
+particles to pass the first criterion outlined above. In this case, using a
+minimal group length of order 500 is beneficial over the more traditional
+value of 32 as it will reduce the number of haloes to consider by about a
+factor 10 (assuming a normal cosmology) whilst still being far enough from
+the actual user-defined mass limit to be safe.

doc/RTD/source/FriendsOfFriends/parameter_description.rst

+.. Friends Of Friends
+   Matthieu Schaller 15th June 2019
+
+.. _Fof_Parameter_Description_label:
+
+Friends-Of-Friends Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``FOF`` section of the parameter file contains all the options related
+to the group finder. Some parameters only make sense in the stand-alone
+version and some only in the on-the-fly version of the module.
+
+The main parameter is the linking length that will be used. The easiest way
+to define it is to set the ratio of the linking length to the mean *dark
+matter* inter-particle separation (irrespective of whether there are other
+kinds of particles present in the run). This is done using the parameter
+``linking_length_ratio`` and the typical value used is
+``0.2``. Users can optionally overwrite the linking length by imposing an
+absolute value using the parameter ``absolute_linking_length``. This is
+expressed in internal units. This value will be ignored (and the ratio of
+the mean inter-particle separation will be used) when set to ``-1``.
+
+The second important parameter is the minimal size of groups to retain in
+the catalogues. This is given in terms of number of particles (of all types)
+via the parameter ``min_group_size``. When analysing simulations, to
+identify haloes, the common practice is to set this to ``32`` in order to
+not plague the catalogue with too many small, likely unbound, structures.
+When using the FOF code on-the-fly for black hole seeding, larger values
+are recommended as there is no need to store groups much smaller than the
+minimal halo mass (see below).
+
+------------------------
+
+In the case of black holes seeding, we run the FOF module on-the-fly during
+a cosmological simulation. The time of the first FOF call is controlled by
+the following two options:
+
+  * Time of the first FOF call (non-cosmological runs): ``time_first``,
+  * Scale-factor of the first FOF call (cosmological runs):
+    ``scale_factor_first``.
+
+One of those two parameters has to be provided depending on the type of
+run. In the case of non-cosmological runs, the time of the first FOF call
+is expressed in the internal units of time. Users also have to provide the
+difference in time (or scale-factor) between consecutive outputs:
+
+  * Time difference between consecutive outputs: ``delta_time``.
+
+The last parameter relevant to the on-the-fly FOF module is the minimal
+halo (group) mass considered for seeding black holes. This is specified by
+the parameter ``black_hole_seed_halo_mass_Msun`` which is expressed in
+solar masses.
+
+------------------------
+
+In the case of the stand-alone module, the four seeding parameters
+described above are ignored but an additional one needs to be
+specified. This is the name of the file in which the catalogue of groups will
+be written. This is specified by the parameter ``fof_output``. The linking
+length and minimal group to keep are set in the way described above.
+
+There are two additional optional parameters that can be used to modify
+details of the stand-alone FOF code. The ``GroupID`` of the particles that
+do not belong to any groups is by default set to 2147483647
+(i.e. :math:`2^{31}-1`). A different value can be specified by changing the
+optional parameter ``group_id_default``. Similarly, the first group in the
+catalogue (i.e. the largest group) carries the ``GroupID`` 1. This can be
+changed by tweaking the optional parameter ``group_id_offset``.
+
+
+------------------------
+
+A full FOF section of the YAML parameter file looks like:
+
+.. code:: YAML
+
+    # Parameters of the Friends-Of-Friends module
+    FOF:
+       basename:                        fof_output  # Filename for the FOF outputs.
+       scale_factor_first:              0.91        # Scale-factor of first FoF black hole seeding calls.
+       time_first:                      0.2         # Time of first FoF black hole seeding calls.
+       delta_time:                      1.005       # Time between consecutive FoF black hole seeding calls.
+       min_group_size:                  256         # The minimum no. of particles required for a group.
+       linking_length_ratio:            0.2         # Linking length in units of the main inter-particle separation.
+       black_hole_seed_halo_mass_Msun:  1.5e10      # Minimal halo mass in which to seed a black hole (in solar masses).
+       absolute_linking_length:         -1.         # (Optional) Absolute linking length (in internal units).
+       group_id_default:                2147483647  # (Optional) Sets the group ID of particles in groups below the minimum size.
+       group_id_offset:                 1           # (Optional) Sets the offset of group ID labelling. Defaults to 1 if unspecified.

doc/RTD/source/FriendsOfFriends/stand_alone_fof.rst

+.. Friends Of Friends
+   Matthieu Schaller 15th June 2019
+
+.. _fof_stand_alone_label:
+
+Stand-Alone Friends-Of-Friends
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The stand-alone version of the Friends-Of-Friends module can be
+compiled by configuring the code with the option
+``--enable-stand-alone-fof``. The ``fof`` and ``fof_mpi`` executables
+will then be generated alongside the regular SWIFT ones.
+
+The executable takes a parameter file as an argument. It will then
+read the snapshot specified in the parameter file and extract all
+the dark matter particles by default. FOF is then run on these
+particles and a catalogue of groups is written to disk. Additional
+particle types can be read and processed by the stand-alone FOF
+code by adding any of the following runtime parameters to the
+command line:
+
+ * ``--hydro``: Read and process the gas particles,
+ * ``--stars``: Read and process the star particles,
+ * ``--black-holes``: Read and process the black hole particles.
+
+The group catalogues contain a unique identifier for each group as
+well as the number of particles in each group and their total mass (in
+internal units). The FOF code will also write a snapshot with an
+additional field for each particle. This contains the ``GroupID`` of
+each particle and can be used to find all the particles in a given
+halo and to link them to the information stored in the catalogue.

doc/RTD/source/ParameterFiles/parameter_description.rst

@@ -517,6 +517,14 @@ following pages:
 * :ref:`Output_list_label` (to have snapshots not evenly spaced in time),
 * :ref:`Output_selection_label` (to select what particle fields to write).
 
+.. _Parameters_fof:
+
+Friends-Of-Friends (FOF)
+------------------------
+
+The parameters are described separately on the page
+:ref:`Fof_Parameter_Description_label` within the more general
+:ref:`Friends_Of_Friends_label` description.
 
 .. _Parameters_statistics:
 

doc/RTD/source/index.rst

@@ -21,6 +21,7 @@ difference is the parameter file that will need to be adapted for SWIFT.
    Snapshots/index
    HydroSchemes/index
    SubgridModels/index
+   FriendsOfFriends/index
    EquationOfState/index
    ExternalPotentials/index
    NewOption/index