Commit 84ac95e5 authored by Matthieu Schaller's avatar Matthieu Schaller
Browse files

Merge branch 'fof_documentation' into 'master'

Fof documentation

See merge request !846
parents acf71dda 6c638ba1
.. 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.
.. 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:
.. 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.
.. 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):
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
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.
.. 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.
......@@ -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:
......@@ -21,6 +21,7 @@ difference is the parameter file that will need to be adapted for SWIFT.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment