Calculate the pairwise radial velocity dispersion as a function of absolute distance, or as a function of $$s = r / R_{\rm vir}$$.

Example calls to this function appear in the documentation below.

Parameters:
sample1array_like

Numpy array of shape (npts1, 3) containing the 3-D positions of points.

velocities1array_like

Numpy array of shape (npts1, 3) containing the 3-D velocities.

rbins_absolutearray_like, optional

Array of shape (num_rbins+1, ) defining the boundaries of bins in which dispersion profile is computed.

Either rbins_absolute must be passed, or rbins_normalized and normalize_rbins_by must be passed.

Length units are comoving and assumed to be in Mpc/h, here and throughout Halotools.

rbins_normalizedarray_like, optional

Array of shape (num_rbins+1, ) defining the bin boundaries x, where $$x = r / R_{\rm vir}$$, in which dispersion profile is computed. The quantity $$R_{\rm vir}$$ can vary from point to point in sample1 and is passed in via the normalize_rbins_by argument. While scaling by $$R_{\rm vir}$$ is common, you are not limited to this normalization choice; in principle you can use the rbins_normalized and normalize_rbins_by arguments to scale your distances by any length-scale associated with points in sample1.

Default is None, in which case the rbins_absolute argument must be passed.

normalize_rbins_byarray_like, optional

Numpy array of shape (npts1, ) defining how the distance between each pair of points will be normalized. For example, if normalize_rbins_by is defined to be the virial radius of each point in sample1, then the input numerical values x stored in rbins_normalized will be interpreted as referring to bins of $$x = r / R_{\rm vir}$$.

Default is None, in which case the input rbins_absolute argument must be passed instead of rbins_normalized.

Pay special attention to length-units in whatever halo catalog you are using: while Halotools-provided catalogs will always have length units pre-processed to be Mpc/h, commonly used default settings for ASCII catalogs produced by Rockstar return the Rvir column in kpc/h units, but halo centers in Mpc/h units.

sample2array_like, optional

Numpy array of shape (npts2, 3) containing the 3-D positions of points.

velocities2array_like, optional

Numpy array of shape (npts2, 3) containing the 3-D velocities.

periodarray_like, optional

Length-3 array defining periodic boundary conditions. If only one number, Lbox, is specified, period is assumed to be [Lbox, Lbox, Lbox]. Default is None, for no PBCs.

number of threads to use in calculation. Default is 1. A string ‘max’ may be used to indicate that the pair counters should use all available cores on the machine.

approx_cell1_sizearray_like, optional

Length-3 array serving as a guess for the optimal manner by how points will be apportioned into subvolumes of the simulation box. The optimum choice unavoidably depends on the specs of your machine. Default choice is to use max(rbins) in each dimension, which will return reasonable result performance for most use-cases. Performance can vary sensitively with this parameter, so it is highly recommended that you experiment with this parameter when carrying out performance-critical calculations.

approx_cell2_sizearray_like, optional

Analogous to approx_cell1_size, but for sample2. See comments for approx_cell1_size for details.

Returns:
sigma_12numpy.array

Numpy array of shape (num_rbins, ) containing the dispersion of the pairwise radial velocity, $$\sigma_{12}(r)$$, computed in each of the bins defined by rbins.

Notes

The pairwise velocity, $$v_{12}(r)$$, is defined as:

$v_{12}(r) = \vec{v}_{\rm 1, pec} \cdot \vec{r}_{12}-\vec{v}_{\rm 2, pec} \cdot \vec{r}_{12}$

where $$\vec{v}_{\rm 1, pec}$$ is the peculiar velocity of object 1, and $$\vec{r}_{12}$$ is the radial vector connecting object 1 and 2.

$$\sigma_{12}(r)$$ is the standard deviation of this quantity in radial bins.

For radial separation bins in which there are zero pairs, function returns zero.

Examples

For demonstration purposes we will work with halos in the FakeSim. Here we’ll just demonstrate basic usage, referring to Galaxy Catalog Analysis Example: Mean infall velocity into cluster BCGs for a more detailed demo.

>>> from halotools.sim_manager import FakeSim
>>> halocat = FakeSim()

>>> x = halocat.halo_table['halo_x']
>>> y = halocat.halo_table['halo_y']
>>> z = halocat.halo_table['halo_z']


We transform our x, y, z points into the array shape used by the pair-counter by taking the transpose of the result of numpy.vstack. This boilerplate transformation is used throughout the mock_observables sub-package:

>>> sample1 = np.vstack((x,y,z)).T


We will do the same to get a random set of velocities.

>>> vx = halocat.halo_table['halo_vx']
>>> vy = halocat.halo_table['halo_vy']
>>> vz = halocat.halo_table['halo_vz']
>>> velocities1 = np.vstack((vx,vy,vz)).T

>>> rbins = np.logspace(-1, 1, 10)
>>> sigma_12 = radial_pvd_vs_r(sample1, velocities1, rbins_absolute=rbins, period=halocat.Lbox)