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 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 1. It is also important to note that the group size includes both the bound and unbound particles; always use the Offset and Offset_unbound data when reading from the catalog_particles files.

  • 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 Total_num_of_particles_in_all_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.

Extracting the particles in a given halo

The .catalog_particles file returns particle IDs that need to be matched with those in your snapshot to find the particles in the file that you wish to extract. The python snippet below should give you an idea of how to go about doing this for the bound particles.

First, we need to extract the offset from the .catalog_group file, and work out how many _bound_ particles are in our halo. We can do this by looking at the next offset. Then, we can ID match those with the snapshot file, and get the mask for the _positions_ in the file that correspond to our bound particles. (Note this requires numpy > 1.15.0).

 1import numpy as np
 2import h5py
 4snapshot_file = h5py.File("swift_snapshot.hdf5", "r")
 5group_file = h5py.File("velociraptor_output.catalog_group", "r")
 6particles_file = h5py.File("velociraptor_output.catalog_particles", "r")
 8halo = 100
 9# Grab the start position in the particles file to read from
10halo_start_position = group_file["Offset"][halo]
11halo_end_position = group_file["Offset"][halo + 1]
12# We're done with that file now, best to close earlier rather than later
15# Get the relevant particle IDs for that halo; this includes particles
16# of _all_ types.
17particle_ids_in_halo = particles_file["Particle_IDs"][
18    halo_start_position:halo_end_position
20# Again, we're done with that file.
23# Now, the tricky bit. We need to create the correspondence between the
24# positions in the snapshot file, and the ids.
26# Let's look for the dark matter particles in that halo.
27particle_ids_from_snapshot = snapshot_file["PartType1/ParticleIDs"][...]
29_, indices_v, indices_p = np.intersect1d(
30    particle_ids_in_halo,
31    particle_ids_from_snapshot,
32    assume_unique=True,
33    return_indices=True,
36# indices_p gives the positions in the particle file where we will find
37# the co-ordinates that we're looking for! To get the positions of all of
38# those particles,
39particle_positions_in_halo = snapshot_file["PartType1/Coordinates"][indices_p]

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.

Virial properties:

  • Mvir: The virial mass of the halos.

  • Rvir: The virial radius of the halo (\(R_{vir}\)).

Bryan and Norman 1998 properties:

  • Mass_BN98, The Bryan and Norman (1998) determination of the mass of the halo 5.

  • R_BN98, the Bryan and Norman (1998) corresponding radius 5.

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 over-density 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:

  • Xc, Yc and Zc: The x,y and z centre positions of the halos.

    Centres are calculated using first all particles belonging to the structure and then VELOCIraptor uses shrinking spheres to iterate to a centre, stopping once the sphere contains <10% of all the particles (this value can be changed to smaller amounts and there is also a minimum particle number which can also be changed).

  • 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.

  • cNFW: The concentration of the halo.

    This is calculated using Vmax and Vvir, not using a fitted profile.

  • VXc, VYc and VZc are the velocities in the centre of the halo 6.

  • VXc_gas, VYc_gas and VZc_gas are the velocities of the gas in the centre of the halo 6.

Inertia 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) 4.

  • 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.

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 6.

  • VXcmbp, VYcmbp and VZcmbp are the velocities of the most bound halo particle 6.


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.


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.


In the velocity dispersion tensor ( \(\sigma_{ij}\) ) the following relations are satisfied between components:

  • \(\sigma_{xy}=\sigma_{yx}\)

  • \(\sigma_{xz}=\sigma_{zx}\)

  • \(\sigma_{yz}=\sigma_{yz}\)


The Bullock spin parameter is given by \(\lambda = \frac{J}{\sqrt{2}MVR}\), for more information see


The Bryan and Norman (1998) paper can be found here:


Needs to be checked.