Calculate the mean pairwise velocity, $$\bar{v}_{12}(r)$$.

Example calls to this function appear in the documentation below. See the Formatting your xyz coordinates for Mock Observables calculations documentation page for instructions on how to transform your coordinate position arrays into the format accepted by the sample1 and sample2 arguments.

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 mean radial velocities are 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 mean radial velocity 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:
v_12numpy.array

Array of shape (num_rbins, ) containing the mean pairwise radial velocity

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.

$$\bar{v}_{12}(r)$$ is the mean of that quantity calculated 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']
>>> velocities = np.vstack((vx,vy,vz)).T

>>> rbins = np.logspace(-1, 1, 10)
>>> v_12 = mean_radial_velocity_vs_r(sample1, velocities, rbins_absolute=rbins, period=halocat.Lbox)