diff --git a/doc/RTD/source/VELOCIraptorInterface/index.rst b/doc/RTD/source/VELOCIraptorInterface/index.rst index e2582107eefed09b6bfd94d6cf208197d2e82e0f..3ae17f04b9950d30d1484ac5117b65063b7739c6 100644 --- a/doc/RTD/source/VELOCIraptorInterface/index.rst +++ b/doc/RTD/source/VELOCIraptorInterface/index.rst @@ -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 - diff --git a/doc/RTD/source/VELOCIraptorInterface/output.rst b/doc/RTD/source/VELOCIraptorInterface/output.rst new file mode 100644 index 0000000000000000000000000000000000000000..d3c5ea087b8251347d3e90e20076084a5a7bef6f --- /dev/null +++ b/doc/RTD/source/VELOCIraptorInterface/output.rst @@ -0,0 +1,284 @@ +.. 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. diff --git a/doc/RTD/source/VELOCIraptorInterface/stfalone.rst b/doc/RTD/source/VELOCIraptorInterface/stfalone.rst new file mode 100644 index 0000000000000000000000000000000000000000..113cff53a51e446d321f6a912222c565f2bdb38e --- /dev/null +++ b/doc/RTD/source/VELOCIraptorInterface/stfalone.rst @@ -0,0 +1,92 @@ +.. 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. + diff --git a/doc/RTD/source/VELOCIraptorInterface/stfwithswift.rst b/doc/RTD/source/VELOCIraptorInterface/stfwithswift.rst new file mode 100644 index 0000000000000000000000000000000000000000..ac8dcc5b0b3c4b6b77dbd5dc79be2613eae0edc6 --- /dev/null +++ b/doc/RTD/source/VELOCIraptorInterface/stfwithswift.rst @@ -0,0 +1,95 @@ +.. 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`` +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 and the +other parameters which SWIFT needs to use. 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. + + +.. _GitHub: https://github.com/pelahi/VELOCIraptor-STF +.. _GitLab: https://gitlab.cosma.dur.ac.uk/swift/swiftsim diff --git a/doc/RTD/source/VELOCIraptorInterface/whatis.rst b/doc/RTD/source/VELOCIraptorInterface/whatis.rst new file mode 100644 index 0000000000000000000000000000000000000000..e7f067ec4723e41da0f3a95dddad8f55d9897e85 --- /dev/null +++ b/doc/RTD/source/VELOCIraptorInterface/whatis.rst @@ -0,0 +1,65 @@ +.. What is VELOCIraptor + Folkert Nobels 12th October 2018 + + +What is VELOCIraptor? +===================== + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Contents: + +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. For finding the +Halos SWIFT uses VELOCIraptor (Elahi, Thacker and Widrow; 2011) [#velo]_, this +is a C++ halo finder that can use MPI. It differs from other halo finder +algorithms in the sense that it uses the velocity distributions of the +particles in the simulations and the the positions of the particles to get +a better estimate of which particles are part of a specific halo and +whether there are substructures in halos. + +The Algorithm +------------- + +The VELOCIraptor algorithm consist basically off the following steps [#ref]_: + +1. A kd-tree is constructed based on the maximization of the Shannon-entropy, + this means that every level in the kd-tree an equal number of particles + are distributed between the 8 lower nodes. This is based on their position + and their corresponding density, this results in more equal density + distributed nodes. This is also the implicit step in the algorithm that + takes into account the absolute positions of the particles. +2. The next part is calculating the the centre of mass velocity and the + velocity distribution for every individual node in the kd-tree. +3. Than the algorithm estimates the background velocity density function for + every particle based on the cell of the particle and the six nearest + neighbour cells. This prevents the background velocity density function + to be over sensitive for variations between different cells due to dominant + halo features in the velocity density function. +4. After this the algorithm searches for the nearest velocity neighbours + (:math:`N_v`) from a set of nearest position neighbours (:math:`N_x>N_v`). + The position neighbours do not need to be in the cell of the particles, in + general the set of nearest position neighbours is substantially larger than + the nearest velocity neighbours, the default is set as :math:`N_x=32 N_v`. +5. The individual local velocity density function is calculated for every + particle. +6. The fractional difference is calculated between the local velocity density + function and the background velocity density function. +7. Based on the calculated ratio outliers are picked and the outliers are + grouped together in halos and subhalos. + + + +.. Every halo finder has limitations, the limitations of VELOCIraptor are: + +.. 1. The algorithm is mostly sensitive to substructures that are on the tail + of the Gaussian velocity density function, this means that VELOCIraptor + is most sensitive for subhalos which are cold (slow ratating) but have + a large bulk velocity + + +.. _Velociraptor: http://adsabs.harvard.edu/abs/2011MNRAS.418..320E +.. [#velo] For technical information regarding VELOCIraptor see: Velociraptor_ +.. [#ref] This part is based on the explanation given in the Elahi, Thacker and + Widrow (2011) paper (Velociraptor_)