Skip to content
GitLab
Commit 2a739caf authored by Folkert Nobels's avatar Folkert Nobels Committed by Matthieu Schaller
Browse files

VELOCIraptor documentation update

parent f241e5ea
Hide whitespace changes
Inline Side-by-side
doc/RTD/source/VELOCIraptorInterface/index.rst
View file @ 2a739caf
......@@ -4,173 +4,21 @@
VELOCIraptor Interface
======================
In SWIFT it is possible to run a cosmological simulation and at the same time
do on the fly halo finding at specific predefined intervals. Because of this
we will explain on this page how we can set up an simulation using VELOCIraptor
(formerly STructure Finder). After this we will explain what the outputs of
VELOCIraptor will be.
This section includes information on the VELOCIraptor interface implemented in
SWIFT. There are mainly four subsection; the first section explains shortly
how VELOCIraptor works, the second subsection explains how to configure SWIFT
with VELOCIraptor, the third subsection explains how to configure a standalone
version of VELOCIraptor and the last subsection explains how the output format
of VELOCIraptor works.
Configuring SWIFT
-----------------
.. toctree::
:maxdepth: 2
:caption: Contents:
In the following three paragraphs we will explain how to setup VELOCIraptor,
how to compile it and how to compile SWIFT with VELOCIraptor.
whatis
stfwithswift
stfalone
output
Setting up VELOCIraptor
~~~~~~~~~~~~~~~~~~~~~~~
Before we can run SWIFT with VELOCIraptor we first need to download
VELOCIraptor. This can be done by cloning the repository on GitHub_::
git clone https://github.com/pelahi/VELOCIraptor-STF
Currently the best version that works with SWIFT is the swift-interface branch
of VELOCIraptor, to get this branch use::
cd VELOCIraptor-STF git fetch git checkout swift-interface
To get the default that works with SWIFT simply copy the SWIFT template file in
the ``Makefile.config``::
cd stf cp Makefile.config.SWIFT-template Makefile.config
Depending on your compiler you want to change the first 20 lines of your
``Makefile.config`` to work with your compiler and whether you want to use MPI
or not.
Compiling VELOCIraptor
~~~~~~~~~~~~~~~~~~~~~~
After we downloaded the files and made a configuration file we can compile
VELOCIraptor as follows::
make lib make libstf
After the compilation of your code, there is an additional folder created in
the ``VELOCIraptor-stf/stf`` directory called ``lib`` this directory has the
libary of VELOCIraptor and is required to run SWIFT with
VELOCIraptor. Note that VELOCIraptor needs a serial version of the
HDF5 library, not a parallel build.
Compiling SWIFT
~~~~~~~~~~~~~~~
The next part is compiling SWIFT with VELOCIraptor and assumes you already
downloaded SWIFT from the GitLab_, this can be done by running::
./autogen.sh ./configure
--with-velociraptor=/path/to/VELOCIraptor-STF/stf/lib make
In which ``./autogen.sh`` only needs to be run once after the code is cloned
from the GitLab_, and ``/path/to/`` is the path to the ``VELOCIraptor-STF``
directory on your machine. In general ``./configure`` can be run with other
options as desired. After this we can run SWIFT with VELOCIraptor, but for this
we first need to add several lines to the yaml file of our simulation::
#structure finding options
StructureFinding:
config_file_name: stf_input_6dfof_dmonly_sub.cfg
basename: ./stf
output_time_format: 1
scale_factor_first: 0.02
delta_time: 1.02
In which we specify the ``.cfg`` file that is used by VELOCIraptor. In the case
of the Small Cosmological Volume DMO example we can run a simulation with halo
finder as::
cd examples/SmallCosmoVolume_DM
../swift -c -s -G -x -t 8 small_cosmo_volume_dm.yml
In which there is an additional ``-x`` option which activates the VELOCIraptor
interface.
VELOCIraptor Output
-------------------
In general VELOCIraptor outputs six files per snapshot, of which 2 files are
for unbound particles specifically. In this part we will explain what is
inside the different files.
Catalog_groups file
~~~~~~~~~~~~~~~~~~~
The first file that is output by VELOCIraptor is the ``.catalog_group`` file,
this file contains all the information that is group specific, the interesting
data in the ``.catalog_group`` files are:
+ The ``group_size``: gives a list of all the halos and the number of particles
in the halo, this list is numbered from 0 until the number of groups minus
one.
+ The ``Num_of_groups`` or ``Total_num_of_groups``: gives the total number of
groups in the snapshot.
+ The ``Offset`` list: This list gives the offset off the particles. In the
output of VELOCIraptor there is no file which has an ID for every particle
and a corresponding group, rather the particles are ordered according to in
which group they are. So if we want to access the particles in group 0, we
need to look at the particles from ``Offset[0]`` until ``Offset[1]`` in the
``.catalog_particles`` hdf5 file. In general this means that for group N we
need to look at particles ``Offset[N]`` until ``Offset[N+1]``.
+ The ``Offset_unbound`` list: This list works exactly the same as the
``Offset`` list only this list is for the gravitational unbound particles.
Catalog_particles file
~~~~~~~~~~~~~~~~~~~~~~
The second file that is produced by VELOCIraptor is the ``.catalog_particles``
file, this file contains mainly all the IDs of the particles and mainly has two
interesting things:
+ The ``Num_of_particles_in_groups`` and ``Num_of_particles_in_groups``
parameter: Gives the total number of particles in the file or which are found
in the halo.
+ The ``Particle_IDs``: The list of particles as sorted by halo, in which halo
the individual particles are present can be found by using the
``.catalog_group`` file and the corresponding ``Offset`` list.
Besides the ``.catalog_particles`` file, there is also a
``.catalog_particles.unbound`` file, this file contains the same information
but only for the unbound particles, a particle can only be present in one of
these two lists.
Catalog_parttypes file
~~~~~~~~~~~~~~~~~~~~~~
The third file that is produced by VELOCIraptor is the ``.catalog_parttypes``
file, this file contains the information what type of particle every particle
is, ordered the same as in ``Particle_IDs`` in ``.catalog_particles``. There
are only two interesting parameters of the file which are:
+ The ``Num_of_particles_in_groups`` parameter: Gives the total number of
particles in the file which are in a halo.
+ The ``Particle_types`` list: Gives a list of particles types similar to the
snap shots (0 - gas, 1 - dm, 4 - stars).
Besides the ``.catalog_parttypes`` file, there is also a
``.catalog_parttypes.unbound`` file, this file contains this information for
the unbound particles.
Properties file
~~~~~~~~~~~~~~~
The Fourth file is the ``.properties`` file, this file contains mainly physical
useful information of the corresponding halos. Some usefull physical parameters
are:
+ ``Mass_200crit``: The mass of a halo with an overdensity on average of
:math:`\Delta=200` based on the critical density of the Universe.
+ ``Mass_200mean``: The mass of a halo with an overdensity on average of
:math:`\Delta=200` based on the mean density of the Universe.
+ ``Mass_FOF``: The friends-of-friends mass of the halos.
+ ``Mvir``: The viral mass of the halos.
+ ``Other parameters``: Soon
.. _GitHub: https://github.com/pelahi/VELOCIraptor-STF
.. _GitLab: https://gitlab.cosma.dur.ac.uk/swift/swiftsim
doc/RTD/source/VELOCIraptorInterface/output.rst 0 → 100644
View file @ 2a739caf
.. VELOCIraptor output
Folkert Nobels 12th of October
VELOCIraptor Output
===================
.. toctree::
:maxdepth: 2
:hidden:
:caption: Contents:
In general VELOCIraptor outputs six files per snapshot, of which 2 files are
for unbound particles specifically. In this part we will explain what is
inside the different files.
Catalog_groups file
-------------------
The first output file of VELOCIraptor is the ``.catalog_group`` file,
this file contains all the information that is group specific, and does not go
into depth of physical properties but only on numbers of particles and
group sizes, the interesting data in the ``.catalog_group`` files are:
+ The ``group_size``: gives a list of all the halos and the number of particles
in the halo, this list is numbered from 0 until the number of groups minus
one. It is important that the groups are not ordered in any way [#order]_
+ The ``Num_of_groups`` or ``Total_num_of_groups``: gives the total number of
groups in the snapshot.
+ The ``Offset`` list: This list gives the offset off the particles. In the
output of VELOCIraptor there is no file which has an ID for every particle
and a corresponding group, rather the particles are ordered according to in
which group they are. So if we want to access the particles in group 0, we
need to look at the particles from ``Offset[0]`` until ``Offset[1]`` in the
``.catalog_particles`` hdf5 file. In general this means that for group N we
need to look at particles ``Offset[N]`` until ``Offset[N+1]``.
+ The ``Offset_unbound`` list: This list works exactly the same as the
``Offset`` list only this list is for the gravitational unbound particles.
Catalog_particles file
----------------------
The second file that is produced by VELOCIraptor is the ``.catalog_particles``
file, this file contains mainly all the IDs of the particles and has two
interesting parameters:
+ The ``Num_of_particles_in_groups`` and ``Num_of_particles_in_groups``
parameter: Gives the total number of particles in the file or the total
number of particles that are in halos.
+ The ``Particle_IDs``: The list of particles as sorted by halo, in which halo
the individual particles are present can be found by using the
``.catalog_group`` file and the corresponding ``Offset`` list.
Besides the ``.catalog_particles`` file, there is also a
``.catalog_particles.unbound`` file, this file contains the same information
but only for the unbound particles, a particle can only be present in one of
these two lists.
Catalog_parttypes file
----------------------
The third file that is produced by VELOCIraptor is the ``.catalog_parttypes``
file, this file contains the information what type of particle every particle
is, it is ordered the same as the ``Particle_IDs`` in ``.catalog_particles``.
There are only two interesting parameters of the file which are:
+ The ``Num_of_particles_in_groups`` parameter: Gives the total number of
particles in the file which are in a halo.
+ The ``Particle_types`` list: Gives a list of particles types similar to the
snap shots (0 - gas, 1 - dm, 4 - stars).
Besides the ``.catalog_parttypes`` file, there is also a
``.catalog_parttypes.unbound`` file, this file contains this information for
the unbound particles.
Properties file
---------------
The Fourth file is the ``.properties`` file, this file contains many physical
useful information of the corresponding halos. This can be divided in several
useful groups of physical parameters, on this page we have divided the several
variables which are present in the ``.properties`` file. This file has most
physical interesting parameters of the halos.
Mass-Radius determination:
^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``.properties`` file contains many ways to determine the size and mass
of the halos, in this subsection we will list several available variables in
the output of VELOCIraptor and we list several mass and radius parameters in
the output which are not classified as a mass-radius pair.
Critical Density related:
"""""""""""""""""""""""""
+ ``Mass_200crit``: The mass of a halo with an over density on average of
:math:`\Delta=200` based on the critical density of the Universe
(:math:`M_{200}`).
+ ``R_200crit``: The :math:`R_{200}` radius of the halo based on the
critical density of the Universe
Mean Density related:
"""""""""""""""""""""
+ ``Mass_200mean``: The mass of a halo with an over density on average of
:math:`\Delta=200` based on the mean density of the Universe
(:math:`M_{200}`).
+ ``R_200mean``: The :math:`R_{200}` radius of the halo based on the
mean density ofthe Universe.
Virial properties:
""""""""""""""""""
+ ``Mvir``: The virial mass of the halos.
+ ``Rvir``: The virial radius of the halo (:math:`R_{vir}`).
Bryan and Norman 1998 properties:
"""""""""""""""""""""""""""""""""
+ ``Mass_BN98``, The Bryan and Norman (1998) determination of the mass of the
halo [#BN98]_.
+ ``R_BN98``, the Bryan and Norman (1998) corresponding radius[#BN98]_.
Several Mass types:
"""""""""""""""""""
This is a list of masses which cannot be categorized as easy as the other
properties.
+ ``Mass_FOF``: The friends-of-friends mass of the halos.
+ ``M_gas``: The gas mass in the halo.
+ ``Mass_tot``: The total mass of the halo
+ ``M_gas_30kpc``: The gas mass within 30 kpc of the halo centre.
+ ``M_gas_500c``: The gas mass of the overdensity of 500 times the critical
density
+ ``M_gas_Rvmax``: The gas mass within the maximum rotation velocity.
Several Radius types:
"""""""""""""""""""""
+ ``R_HalfMass``: Radius of half the mass of the halo.
+ ``R_HalfMass_gas``: Radius of half the gas mass of the halo.
+ ``R_size``:
+ ``Rmax``:
Mass Structure of the Halos:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In this subsection we listed the properties of the halos that are determining
the mass structure of the halo, so the exact profile and the inertia tensor.
NFW profile properties:
"""""""""""""""""""""""
+ ``cNFW``: The concentration of the halo.
+ ``Xc``, ``Yc`` and ``Zc``: The x,y and z centre positions of the halos
[#center]_.
+ ``Xc_gas``, ``Yc_gas``, ``Zc_gas``: The offset of the centre positions of
the halo based on the gas, to find the position of the gas the offsets
need to be added to ``Xc``, ``Yc`` and ``Zc``.
+ ``VXc``, ``VYc`` and ``VZc`` are the velocities in the centre of the halo
[#check]_.
+ ``VXc_gas``, ``VYc_gas`` and ``VZc_gas`` are the velocities of the gas in
the centre of the halo [#check]_.
Intertia Tensor properties:
"""""""""""""""""""""""""""
+ ``eig_ij``: Are the normalized eigenvectors of the inertia tensor.
+ The eigenvalue ratios:
1. ``q`` is the semi-major over major;
2. ``s`` is the minor over major.
+ ``eig_ij_gas``: Are the normalized eigenvectors of the inertia tensor for
only the gas particles.
+ The eigenvalue ratios for only the gas, similar to all particles:
1. ``q_gas`` is the semi-major over major for only gas;
2. ``s_gas`` is the minor over major for only gas.
Dynamical Structure of the Halos:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In this subsection we list several properties that determine the dynamical
structure of the halo, like the angular momentum and the velocity dispersion
tensor.
Angular momentum and spin parameters:
"""""""""""""""""""""""""""""""""""""
+ ``lambda_b`` is the bullock spin parameter, see the paper by Bullock et al.
(2001) [#Bullock]_.
+ ``Lx``, ``Ly`` and ``Lz`` are the angular momentum of the halos, the
calculation includes all the particle types.
+ ``Lx_gas``, ``Ly_gas`` and ``Lz_gas`` are the angular momentum for only
the gas particles in the snapshot.
Velocity Dispersion related:
""""""""""""""""""""""""""""
+ The complete velocity dispersion tensor (:math:`\sigma_{ij}`) which has
an array per component which gives the value for all the halos. In
general these components are called ``veldisp_ij`` in which i and j are
given by ``x``, ``y`` or ``z``. This means that there are nine
components stored in the ``.properties`` file. This omits the fact
that the dispersion tensor by nature is a symmetric tensor. All the
components are given by:
``veldisp_xx``, ``veldisp_xy``, ``veldisp_xz``, ``veldisp_yx``,
``veldisp_yy``, ``veldisp_yz``, ``veldisp_zx``, ``veldisp_zy``,
and ``veldisp_zz`` [#velodisp]_.
+ ``sigV``, the scalar velocity dispersion which corresponds with the
trace of the velocity dispersion tensor
(:math:`\sigma = \text{Tr}(\sigma_{ij})`).
Energy properties of the halos:
"""""""""""""""""""""""""""""""
+ ``Ekin``, the kinetic energy of the halo.
+ ``Epot``, the potential energy of the halo.
+ ``Krot``, the rotational energy of the halo.
+ ``Krot_gas``, the rotational energy of the gas in the halo.
Halo and subhalo abstract variables:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In this subsection we list the ID convention for subhalos and halos and
some other abstract quantities of the halo which are not physical but
rather properties of the simulations.
Structure types:
""""""""""""""""
+ ``ID`` is the halo ID.
+ ``Structuretype`` is the parameter that indicates what kind of structure
the current halo is. Halos have a structure type of ``10`` and subhalos
have a structure type of ``15``.
+ ``hostHaloID``, indicates the halo ID number of the host halo, in the case
that the halo has no parent (e.g. is the largest halo), the hostHaloID will
be ``-1``.
+ ``numSubStruct``, the number of substructures or subhalos in the halo.
Particle types:
"""""""""""""""
+ ``npart`` is the number of particles in the halo (all types of particles).
+ ``n_gas`` is the number of gas particles in the halo.
Not specified parameters:
^^^^^^^^^^^^^^^^^^^^^^^^^
In this section we list parameters which cannot specifically be classified
in a group.
Most Bound Particle (MBP):
""""""""""""""""""""""""""
+ ``ID_mbp``, the ID of the most bound particle in the halo.
+ ``Xcmbp``, ``Ycmbp`` and ``Zcmbp`` are the positions of the most bound
halo particle [#check]_.
+ ``VXcmbp``, ``VYcmbp`` and ``VZcmbp`` are the velocities of the most bound
halo particle [#check]_.
.. [#order] In most cases more massive groups appear earlier in the list, but
this is not guaranteed for larger simulations. The order of the groups is
more a matter of the way that VELOCIraptor searches instead of a physical
reason.
.. [#center] This is not the average positions of the halos particles, but
the halo position found by the VELOCIraptor algorithm. This includes a
fit for all the parameters including the gas particles or other types of
particles.
.. [#velodisp] In the velocity dispersion tensor ( :math:`\sigma_{ij}` )
the following relations are satisfied between components:
+ :math:`\sigma_{xy}=\sigma_{yx}`
+ :math:`\sigma_{xz}=\sigma_{zx}`
+ :math:`\sigma_{yz}=\sigma_{yz}`
.. [#Bullock] The Bullock spin parameter is given by
:math:`\lambda = \frac{J}{\sqrt{2}MVR}`, for more information see
https://arxiv.org/abs/astro-ph/0011001.
.. [#BN98] The Bryan and Norman (1998) paper can be found here:
https://arxiv.org/abs/astro-ph/9710107
.. [#check] Needs to be checked.
doc/RTD/source/VELOCIraptorInterface/stfalone.rst 0 → 100644
View file @ 2a739caf
.. VELOCIraptor stand alone
Folkert Nobels 12th October 2018
Stand alone VELOCIraptor configuration
======================================
.. toctree::
:maxdepth: 2
:hidden:
:caption: Contents:
Besides running VELOCIraptor on the fly when using SWIFT, it is also possible
to run VELOCIraptor alone without using SWIFT. In this section we explain how
VELOCIraptor can be run stand alone without using SWIFT.
Setting up VELOCIraptor
-----------------------
The first step is setting up VELOCIraptor, this requires us to download the
git repository as::
git clone https://github.com/pelahi/VELOCIraptor-STF
Similar to the SWIFT with VELOCIraptor configuration, we can use the
swift-interface branch to analyse individual snapshots. We can use this branch
by doing::
cd VELOCIraptor-STF
git fetch
git checkout swift-interface
Again we need to copy the default SWIFT config file to a other config file by
doing::
cd stf
cp Makefile.config.SWIFT-template Makefile.config
Similar to configuring VELOCIraptor with swift we need to change the first 20
lines of ``Makefile.config`` to work with our compiler, but we also need to
change the fact that we do not use the swift-interface but the standalone
version of the code, so change ``SWIFTINTERFACE="on"`` to
``SWIFTINTERFACE="off"``.
Compiling VELOCIraptor
----------------------
Compoling goes completely different as compared to the on the fly halo finder
configuration with SWIFT. In this case we can compile the code as::
make
After this an additional folder is created in ``VELOCIraptor-stf/stf`` called
``bin``, in which the binary files of ``stf-gas`` is present (assuming you
run a simulation with SPH [#nosph]_)
Running VELOCIraptor on a Snapshot
----------------------------------
After the code is compile the next step is using VELOCIraptor on a single
snapshot of a simulation. The code has several options which can be used, which
can be displayed by running a terminal command of an invalid letter like::
./stf-gas -h
which gives the information about the usage of the command::
USAGE:
-C <configuration file (overrides other options)>
-I <input format [Gadget (Default) 1, HDF (if implemented)2, TIPSY 3, RAMSES 4, HDF 2, NCHILADA 5>
-i <input file>
-s <number of files per output for gadget input 1 [default]>
-Z <number of threads used in parallel read (1)>
-o <output filename>
===== EXTRA OPTIONS FOR GADGET INPUT ======
-g <number of extra sph/gas blocks for gadget>
-s <number of extra star blocks for gadget>
-b <number of extra bh blocks for gadget>
===== EXTRA OPTIONS REQUIRED FOR RAMSES INPUT ======
-t <ramses snapnumber>
After this we can run a VELOCIraptor on a snapshot as::
./stf-gas -i input -o output -C configfile.txt
.. [#nosph] In the case that in the ``Makefile.config`` it is indicate that the
simulation does only contain dark matter this will reflect back on the
generated binary file. So ``stf-gas`` will change to ``stf`` in the case of
a dark matter only simulation.
doc/RTD/source/VELOCIraptorInterface/stfwithswift.rst 0 → 100644
View file @ 2a739caf
.. SWIFT with VELOCIraptor
Folkert Nobels 12th October 2018
Configuring SWIFT with VELOCIraptor
===================================
.. toctree::
:maxdepth: 2
:hidden:
:caption: Contents:
In the following three paragraphs we will explain how to setup VELOCIraptor,
how to compile it and how to compile SWIFT with VELOCIraptor.
Setting up VELOCIraptor
-----------------------
Before we can run SWIFT with VELOCIraptor we first need to download
VELOCIraptor. This can be done by cloning the repository on GitHub_::
git clone https://github.com/pelahi/VELOCIraptor-STF
Currently the best version that works with SWIFT is the swift-interface branch
of VELOCIraptor, to get this branch use::
cd VELOCIraptor-STF
git fetch
git checkout swift-interface
To get the default that works with SWIFT simply copy the SWIFT template file in
the ``Makefile.config``::
cd stf
cp Makefile.config.SWIFT-template Makefile.config
Depending on your compiler you want to change the first 20 lines of your
``Makefile.config`` to work with your compiler and whether you want to use MPI
or not.
Compiling VELOCIraptor
----------------------
After we downloaded the files and made a configuration file we can compile
VELOCIraptor as follows::
make lib
make libstf
After the compilation of your code, there is an additional folder created in
the ``VELOCIraptor-stf/stf`` directory called ``lib`` this directory has the
library of VELOCIraptor and is required to run SWIFT with
VELOCIraptor. Note that VELOCIraptor needs a serial version of the
HDF5 library, not a parallel build.
Compiling SWIFT
---------------
The next part is compiling SWIFT with VELOCIraptor and assumes you already
downloaded SWIFT from the GitLab_, this can be done by running::
./autogen.sh
./configure --with-velociraptor=/path/to/VELOCIraptor-STF/stf/lib
make
In which ``./autogen.sh`` only needs to be run once after the code is cloned
from the GitLab_, and ``/path/to/`` is the path to the ``VELOCIraptor-STF``