Corrfunc.theory package¶
Wrapper for all clustering statistic calculations on galaxies in a simulation volume.

Corrfunc.theory.
DD
(autocorr, nthreads, binfile, X1, Y1, Z1, weights1=None, periodic=True, boxsize=None, X2=None, Y2=None, Z2=None, weights2=None, verbose=False, output_ravg=False, xbin_refine_factor=2, ybin_refine_factor=2, zbin_refine_factor=1, max_cells_per_dim=100, copy_particles=True, enable_min_sep_opt=True, c_api_timer=False, isa=u'fastest', weight_type=None)[source]¶ Calculate the 3D paircounts corresponding to the realspace correlation function, \(\xi(r)\).
If
weights
are provided, the mean pair weight is stored in the"weightavg"
field of the results array. The raw pair counts in the"npairs"
field are not weighted. The weighting scheme depends onweight_type
.Note
This module only returns pair counts and not the actual correlation function \(\xi(r)\). See
Corrfunc.utils.convert_3d_counts_to_cf
for computing \(\xi(r)\) from the pair counts returned.Parameters:  autocorr (boolean, required) – Boolean flag for auto/crosscorrelation. If autocorr is set to 1, then the second set of particle positions are not required.
 nthreads (integer) – The number of OpenMP threads to use. Has no effect if OpenMP was not enabled during library compilation.
 binfile (string or an list/array of floats) –
For string input: filename specifying the
r
bins forDD
. The file should contain whitespace separated values of (rmin, rmax) for eachr
wanted. The bins need to be contiguous and sorted in increasing order (smallest bins come first).For arraylike input: A sequence of
r
values that provides the binedges. For example,np.logspace(np.log10(0.1), np.log10(10.0), 15)
is a valid input specifying 14 (logarithmic) bins between 0.1 and 10.0. This array does not need to be sorted.  X1/Y1/Z1 (array_like, real (float/double)) – The array of X/Y/Z positions for the first set of points. Calculations are done in the precision of the supplied arrays.
 weights1 (array_like, real (float/double), optional) – A scalar, or an array of weights of shape (n_weights, n_positions) or
(n_positions,).
weight_type
specifies how these weights are used; results are returned in theweightavg
field. If only one of weights1 and weights2 is specified, the other will be set to uniform weights.  periodic (boolean) – Boolean flag to indicate periodic boundary conditions.
 boxsize (double, required if
periodic=True
) –The sidelength of the cube in the cosmological simulation. Present to facilitate exact calculations for periodic wrapping. If boxsize is 0., then the wrapping is done based on the maximum difference within each dimension of the X/Y/Z arrays.
Changed in version 2.4.0: Required if
periodic=True
.  X2/Y2/Z2 (arraylike, real (float/double)) – Array of XYZ positions for the second set of points. Must be the same
precision as the X1/Y1/Z1 arrays. Only required when
autocorr==0
.  weights2 (arraylike, real (float/double), optional) – Same as weights1, but for the second set of positions
 verbose (boolean (default false)) – Boolean flag to control output of informational messages
 output_ravg (boolean (default false)) –
Boolean flag to output the average
r
for each bin. Code will run slower if you set this flag.Note: If you are calculating in singleprecision,
ravg
will suffer from numerical loss of precision and can not be trusted. If you need accurateravg
values, then pass in double precision arrays for the particle positions.  (xyz)bin_refine_factor (integer, default is (2,2,1); typically within [13]) – Controls the refinement on the cell sizes. Can have up to a 20% impact on runtime.
 max_cells_per_dim (integer, default is 100, typical values in [50300]) – Controls the maximum number of cells per dimension. Total number of
cells can be up to (max_cells_per_dim)^3. Only increase if
rmax
is too small relative to the boxsize (and increasing helps the runtime).  copy_particles (boolean (default True)) –
Boolean flag to make a copy of the particle positions If set to False, the particles will be reordered inplace
New in version 2.3.0.
 enable_min_sep_opt (boolean (default true)) –
Boolean flag to allow optimizations based on min. separation between pairs of cells. Here to allow for comparison studies.
New in version 2.3.0.
 c_api_timer (boolean (default false)) – Boolean flag to measure actual time spent in the C libraries. Here to allow for benchmarking and scaling studies.
 isa (string (default
fastest
)) –Controls the runtime dispatch for the instruction set to use. Options are: [
fastest
,avx512f
,avx
,sse42
,fallback
]Setting isa to
fastest
will pick the fastest available instruction set on the current computer. However, if you setisa
to, say,avx
andavx
is not available on the computer, then the code will revert to usingfallback
(even thoughsse42
might be available). Unless you are benchmarking the different instruction sets, you should always leaveisa
to the default value. And if you are benchmarking, then the string supplied here gets translated into anenum
for the instruction set defined inutils/defs.h
.  weight_type (string, optional. Default: None.) – The type of weighting to apply. One of [“pair_product”, None].
Returns:  results (Numpy structured array) – A numpy structured array containing [rmin, rmax, ravg, npairs,
weightavg] for each radial bin specified in the
binfile
. Ifoutput_ravg
is not set, thenravg
will be set to 0.0 for all bins; similarly forweightavg
.npairs
contains the number of pairs in that bin and can be used to compute the actual \(\xi(r)\) by combining with (DR, RR) counts.  api_time (float, optional) – Only returned if
c_api_timer
is set.api_time
measures only the time spent within the C library and ignores all python overhead.
Example
>>> from __future__ import print_function >>> import numpy as np >>> from os.path import dirname, abspath, join as pjoin >>> import Corrfunc >>> from Corrfunc.theory.DD import DD >>> binfile = pjoin(dirname(abspath(Corrfunc.__file__)), ... "../theory/tests/", "bins") >>> N = 10000 >>> boxsize = 420.0 >>> nthreads = 4 >>> autocorr = 1 >>> seed = 42 >>> np.random.seed(seed) >>> X = np.random.uniform(0, boxsize, N) >>> Y = np.random.uniform(0, boxsize, N) >>> Z = np.random.uniform(0, boxsize, N) >>> weights = np.ones_like(X) >>> results = DD(autocorr, nthreads, binfile, X, Y, Z, weights1=weights, ... weight_type='pair_product', output_ravg=True, ... boxsize=boxsize, periodic=True) >>> for r in results: print("{0:10.6f} {1:10.6f} {2:10.6f} {3:10d} {4:10.6f}". ... format(r['rmin'], r['rmax'], r['ravg'], ... r['npairs'], r['weightavg'])) # doctest: +NORMALIZE_WHITESPACE 0.167536 0.238755 0.000000 0 0.000000 0.238755 0.340251 0.000000 0 0.000000 0.340251 0.484892 0.000000 0 0.000000 0.484892 0.691021 0.000000 0 0.000000 0.691021 0.984777 0.945372 2 1.000000 0.984777 1.403410 1.340525 10 1.000000 1.403410 2.000000 1.732968 36 1.000000 2.000000 2.850200 2.549059 52 1.000000 2.850200 4.061840 3.559061 210 1.000000 4.061840 5.788530 4.996275 670 1.000000 5.788530 8.249250 7.124926 2156 1.000000 8.249250 11.756000 10.201393 5990 1.000000 11.756000 16.753600 14.517498 17736 1.000000 16.753600 23.875500 20.716714 50230 1.000000

Corrfunc.theory.
DDrppi
(autocorr, nthreads, pimax, binfile, X1, Y1, Z1, weights1=None, periodic=True, boxsize=None, X2=None, Y2=None, Z2=None, weights2=None, verbose=False, output_rpavg=False, xbin_refine_factor=2, ybin_refine_factor=2, zbin_refine_factor=1, max_cells_per_dim=100, copy_particles=True, enable_min_sep_opt=True, c_api_timer=False, isa=u'fastest', weight_type=None)[source]¶ Calculate the 3D paircounts corresponding to the realspace correlation function, \(\xi(r_p, \pi)\) or \(\wp(r_p)\). Pairs which are separated by less than the
rp
bins (specified inbinfile
) in the XY plane, and less thanpimax
in the Zdimension are counted.If
weights
are provided, the mean pair weight is stored in the"weightavg"
field of the results array. The raw pair counts in the"npairs"
field are not weighted. The weighting scheme depends onweight_type
.Note
that this module only returns pair counts and not the actual correlation function \(\xi(r_p, \pi)\) or \(wp(r_p)\). See the utilities
Corrfunc.utils.convert_3d_counts_to_cf
andCorrfunc.utils.convert_rp_pi_counts_to_wp
for computing \(\xi(r_p, \pi)\) and \(wp(r_p)\) respectively from the pair counts.Parameters:  autocorr (boolean, required) – Boolean flag for auto/crosscorrelation. If autocorr is set to 1, then the second set of particle positions are not required.
 nthreads (integer) – The number of OpenMP threads to use. Has no effect if OpenMP was not enabled during library compilation.
 pimax (double) –
A doubleprecision value for the maximum separation along the Zdimension.
Distances along the :math:
\pi
direction are binned with unit depth. For instance, ifpimax=40
, then 40 bins will be created along thepi
direction.Note: Only pairs with
0 <= dz < pimax
are counted (no equality).  binfile (string or an list/array of floats) –
For string input: filename specifying the
rp
bins forDDrppi
. The file should contain whitespace separated values of (rpmin, rpmax) for eachrp
wanted. The bins need to be contiguous and sorted in increasing order (smallest bins come first).For arraylike input: A sequence of
rp
values that provides the binedges. For example,np.logspace(np.log10(0.1), np.log10(10.0), 15)
is a valid input specifying 14 (logarithmic) bins between 0.1 and 10.0. This array does not need to be sorted.  X1/Y1/Z1 (arraylike, real (float/double)) – The array of X/Y/Z positions for the first set of points. Calculations are done in the precision of the supplied arrays.
 weights1 (array_like, real (float/double), optional) – A scalar, or an array of weights of shape (n_weights, n_positions) or
(n_positions,).
weight_type
specifies how these weights are used; results are returned in theweightavg
field. If only one of weights1 and weights2 is specified, the other will be set to uniform weights.  periodic (boolean) – Boolean flag to indicate periodic boundary conditions.
 boxsize (double, required if
periodic=True
) –The sidelength of the cube in the cosmological simulation. Present to facilitate exact calculations for periodic wrapping. If boxsize is 0., then the wrapping is done based on the maximum difference within each dimension of the X/Y/Z arrays.
Changed in version 2.4.0: Required if
periodic=True
.  X2/Y2/Z2 (arraylike, real (float/double)) – Array of XYZ positions for the second set of points. Must be the same
precision as the X1/Y1/Z1 arrays. Only required when
autocorr==0
.  weights2 (arraylike, real (float/double), optional) – Same as weights1, but for the second set of positions
 verbose (boolean (default false)) – Boolean flag to control output of informational messages
 output_rpavg (boolean (default false)) –
Boolean flag to output the average
rp
for each bin. Code will run slower if you set this flag.Note: If you are calculating in singleprecision,
rpavg
will suffer from numerical loss of precision and can not be trusted. If you need accuraterpavg
values, then pass in double precision arrays for the particle positions.  (xyz)bin_refine_factor (integer, default is (2,2,1); typically within [13]) – Controls the refinement on the cell sizes. Can have up to a 20% impact on runtime.
 max_cells_per_dim (integer, default is 100, typical values in [50300]) – Controls the maximum number of cells per dimension. Total number of
cells can be up to (max_cells_per_dim)^3. Only increase if
rpmax
is too small relative to the boxsize (and increasing helps the runtime).  copy_particles (boolean (default True)) –
Boolean flag to make a copy of the particle positions If set to False, the particles will be reordered inplace
New in version 2.3.0.
 enable_min_sep_opt (boolean (default true)) –
Boolean flag to allow optimizations based on min. separation between pairs of cells. Here to allow for comparison studies.
New in version 2.3.0.
 c_api_timer (boolean (default false)) – Boolean flag to measure actual time spent in the C libraries. Here to allow for benchmarking and scaling studies.
 isa (string (default
fastest
)) –Controls the runtime dispatch for the instruction set to use. Options are: [
fastest
,avx512f
,avx
,sse42
,fallback
]Setting isa to
fastest
will pick the fastest available instruction set on the current computer. However, if you setisa
to, say,avx
andavx
is not available on the computer, then the code will revert to usingfallback
(even thoughsse42
might be available). Unless you are benchmarking the different instruction sets, you should always leaveisa
to the default value. And if you are benchmarking, then the string supplied here gets translated into anenum
for the instruction set defined inutils/defs.h
.  weight_type (string, optional. Default: None.) – The type of weighting to apply. One of [“pair_product”, None].
Returns:  results (Numpy structured array) – A numpy structured array containing [rpmin, rpmax, rpavg, pimax,
npairs, weightavg] for each radial bin specified in the
binfile
. Ifoutput_rpavg
is not set, thenrpavg
will be set to 0.0 for all bins; similarly forweightavg
.npairs
contains the number of pairs in that bin and can be used to compute \(\xi(r_p, \pi)\) by combining with (DR, RR) counts.  api_time (float, optional) – Only returned if
c_api_timer
is set.api_time
measures only the time spent within the C library and ignores all python overhead.
Example
>>> from __future__ import print_function >>> import numpy as np >>> from os.path import dirname, abspath, join as pjoin >>> import Corrfunc >>> from Corrfunc.theory.DDrppi import DDrppi >>> binfile = pjoin(dirname(abspath(Corrfunc.__file__)), ... "../theory/tests/", "bins") >>> N = 10000 >>> boxsize = 420.0 >>> nthreads = 4 >>> autocorr = 1 >>> pimax = 40.0 >>> seed = 42 >>> np.random.seed(seed) >>> X = np.random.uniform(0, boxsize, N) >>> Y = np.random.uniform(0, boxsize, N) >>> Z = np.random.uniform(0, boxsize, N) >>> weights = np.ones_like(X) >>> results = DDrppi(autocorr, nthreads, pimax, binfile, ... X, Y, Z, weights1=weights, weight_type='pair_product', ... output_rpavg=True, boxsize=boxsize, periodic=True) >>> for r in results[519:]: print("{0:10.6f} {1:10.6f} {2:10.6f} {3:10.1f}" ... " {4:10d} {5:10.6f}".format(r['rmin'], r['rmax'], ... r['rpavg'], r['pimax'], r['npairs'], r['weightavg'])) ... # doctest: +NORMALIZE_WHITESPACE 11.756000 16.753600 14.388268 40.0 1142 1.000000 16.753600 23.875500 20.451822 1.0 2602 1.000000 16.753600 23.875500 20.603847 2.0 2366 1.000000 16.753600 23.875500 20.526435 3.0 2426 1.000000 16.753600 23.875500 20.478537 4.0 2460 1.000000 16.753600 23.875500 20.462300 5.0 2528 1.000000 16.753600 23.875500 20.535332 6.0 2524 1.000000 16.753600 23.875500 20.445645 7.0 2420 1.000000 16.753600 23.875500 20.476452 8.0 2358 1.000000 16.753600 23.875500 20.422480 9.0 2508 1.000000 16.753600 23.875500 20.466759 10.0 2474 1.000000 16.753600 23.875500 20.486209 11.0 2402 1.000000 16.753600 23.875500 20.371804 12.0 2418 1.000000 16.753600 23.875500 20.655139 13.0 2382 1.000000 16.753600 23.875500 20.563170 14.0 2420 1.000000 16.753600 23.875500 20.530697 15.0 2452 1.000000 16.753600 23.875500 20.578696 16.0 2378 1.000000 16.753600 23.875500 20.475367 17.0 2342 1.000000 16.753600 23.875500 20.537281 18.0 2498 1.000000 16.753600 23.875500 20.528432 19.0 2506 1.000000 16.753600 23.875500 20.509429 20.0 2498 1.000000 16.753600 23.875500 20.512102 21.0 2546 1.000000 16.753600 23.875500 20.476031 22.0 2436 1.000000 16.753600 23.875500 20.437518 23.0 2350 1.000000 16.753600 23.875500 20.558304 24.0 2466 1.000000 16.753600 23.875500 20.532998 25.0 2476 1.000000 16.753600 23.875500 20.570077 26.0 2352 1.000000 16.753600 23.875500 20.532271 27.0 2370 1.000000 16.753600 23.875500 20.512475 28.0 2516 1.000000 16.753600 23.875500 20.484714 29.0 2456 1.000000 16.753600 23.875500 20.603416 30.0 2386 1.000000 16.753600 23.875500 20.505218 31.0 2480 1.000000 16.753600 23.875500 20.484996 32.0 2532 1.000000 16.753600 23.875500 20.515608 33.0 2548 1.000000 16.753600 23.875500 20.489220 34.0 2530 1.000000 16.753600 23.875500 20.494801 35.0 2384 1.000000 16.753600 23.875500 20.481582 36.0 2360 1.000000 16.753600 23.875500 20.369323 37.0 2544 1.000000 16.753600 23.875500 20.450425 38.0 2460 1.000000 16.753600 23.875500 20.587416 39.0 2396 1.000000 16.753600 23.875500 20.504153 40.0 2492 1.000000

Corrfunc.theory.
wp
(boxsize, pimax, nthreads, binfile, X, Y, Z, weights=None, weight_type=None, verbose=False, output_rpavg=False, xbin_refine_factor=2, ybin_refine_factor=2, zbin_refine_factor=1, max_cells_per_dim=100, copy_particles=True, enable_min_sep_opt=True, c_api_timer=False, c_cell_timer=False, isa=u'fastest')[source]¶ Function to compute the projected correlation function in a periodic cosmological box. Pairs which are separated by less than the
rp
bins (specified inbinfile
) in the XY plane, and less thanpimax
in the Zdimension are counted.If
weights
are provided, the resulting correlation function is weighted. The weighting scheme depends onweight_type
.Note
Pairs are doublecounted. And if
rpmin
is set to 0.0, then all the selfpairs (i’th particle with itself) are added to the first bin => minimum number of pairs in the first bin is the total number of particles.Parameters:  boxsize (double) – A doubleprecision value for the boxsize of the simulation
in same units as the particle positions and the
rp
bins.  pimax (double) –
A doubleprecision value for the maximum separation along the Zdimension.
Note: Only pairs with
0 <= dz < pimax
are counted (no equality).  nthreads (integer) – Number of threads to use.
 binfile (string or an list/array of floats) –
For string input: filename specifying the
rp
bins forwp
. The file should contain whitespace separated values of (rpmin, rpmax) for eachrp
wanted. The bins need to be contiguous and sorted in increasing order (smallest bins come first).For arraylike input: A sequence of
rp
values that provides the binedges. For example,np.logspace(np.log10(0.1), np.log10(10.0), 15)
is a valid input specifying 14 (logarithmic) bins between 0.1 and 10.0. This array does not need to be sorted.  X/Y/Z (arraytype, real (float/double)) –
Particle positions in the 3 axes. Must be within [0, boxsize] and specified in the same units as
rp_bins
and boxsize. All 3 arrays must be of the same floatingpoint type.Calculations will be done in the same precision as these arrays, i.e., calculations will be in floating point if XYZ are single precision arrays (C float type); or in doubleprecision if XYZ are double precision arrays (C double type).
 weights (array_like, real (float/double), optional) – A scalar, or an array of weights of shape (n_weights, n_positions) or
(n_positions,).
weight_type
specifies how these weights are used; results are returned in theweightavg
field.  verbose (boolean (default false)) – Boolean flag to control output of informational messages
 output_rpavg (boolean (default false)) –
Boolean flag to output the average
rp
for each bin. Code will run slower if you set this flag.Note: If you are calculating in singleprecision,
rpavg
will suffer from numerical loss of precision and can not be trusted. If you need accuraterpavg
values, then pass in double precision arrays for the particle positions.  (xyz)bin_refine_factor (integer, default is (2,2,1); typically within [13]) – Controls the refinement on the cell sizes. Can have up to a 20% impact on runtime.
 max_cells_per_dim (integer, default is 100, typical values in [50300]) – Controls the maximum number of cells per dimension. Total number of
cells can be up to (max_cells_per_dim)^3. Only increase if
rpmax
is too small relative to the boxsize (and increasing helps the runtime).  copy_particles (boolean (default True)) –
Boolean flag to make a copy of the particle positions If set to False, the particles will be reordered inplace
New in version 2.3.0.
 enable_min_sep_opt (boolean (default true)) –
Boolean flag to allow optimizations based on min. separation between pairs of cells. Here to allow for comparison studies.
New in version 2.3.0.
 c_api_timer (boolean (default false)) – Boolean flag to measure actual time spent in the C libraries. Here to allow for benchmarking and scaling studies.
 c_cell_timer (boolean (default false)) – Boolean flag to measure actual time spent per cellpair within the C libraries. A very detailed timer that stores information about the number of particles in each cell, the thread id that processed that cellpair and the amount of time in nanoseconds taken to process that cell pair. This timer can be used to study the instruction set efficiency, and loadbalancing of the code.
 isa (string (default
fastest
)) –Controls the runtime dispatch for the instruction set to use. Options are: [
fastest
,avx512f
,avx
,sse42
,fallback
]Setting isa to
fastest
will pick the fastest available instruction set on the current computer. However, if you setisa
to, say,avx
andavx
is not available on the computer, then the code will revert to usingfallback
(even thoughsse42
might be available). Unless you are benchmarking the different instruction sets, you should always leaveisa
to the default value. And if you are benchmarking, then the string supplied here gets translated into anenum
for the instruction set defined inutils/defs.h
.  weight_type (string, optional. Default: None.) – The type of weighting to apply. One of [“pair_product”, None].
Returns:  results (Numpy structured array) – A numpy structured array containing [rpmin, rpmax, rpavg, wp, npairs,
weightavg] for each radial specified in the
binfile
. Ifoutput_rpavg
is not set thenrpavg
will be set to 0.0 for all bins; similarly forweightavg
.wp
contains the projected correlation function whilenpairs
contains the number of unique pairs in that bin. If using weights,wp
will be weighted whilenpairs
will not be.  api_time (float, optional) – Only returned if
c_api_timer
is set.api_time
measures only the time spent within the C library and ignores all python overhead.  cell_time (list, optional) – Only returned if
c_cell_timer
is set. Contains detailed stats about each cellpair visited during paircounting, viz., number of particles in each of the cells in the pair, 1D cellindices for each cell in the pair, time (in nanoseconds) to process the pair and the threadid for the thread that processed that cellpair.
Example
>>> from __future__ import print_function >>> import numpy as np >>> from os.path import dirname, abspath, join as pjoin >>> import Corrfunc >>> from Corrfunc.theory.wp import wp >>> binfile = pjoin(dirname(abspath(Corrfunc.__file__)), ... "../theory/tests/", "bins") >>> N = 10000 >>> boxsize = 420.0 >>> pimax = 40.0 >>> nthreads = 4 >>> seed = 42 >>> np.random.seed(seed) >>> X = np.random.uniform(0, boxsize, N) >>> Y = np.random.uniform(0, boxsize, N) >>> Z = np.random.uniform(0, boxsize, N) >>> results = wp(boxsize, pimax, nthreads, binfile, X, Y, Z, weights=np.ones_like(X), weight_type='pair_product') >>> for r in results: ... print("{0:10.6f} {1:10.6f} {2:10.6f} {3:10.6f} {4:10d} {5:10.6f}". ... format(r['rmin'], r['rmax'], ... r['rpavg'], r['wp'], r['npairs'], r['weightavg'])) ... # doctest: +NORMALIZE_WHITESPACE 0.167536 0.238755 0.000000 66.717143 18 1.000000 0.238755 0.340251 0.000000 15.786045 16 1.000000 0.340251 0.484892 0.000000 2.998470 42 1.000000 0.484892 0.691021 0.000000 15.779885 66 1.000000 0.691021 0.984777 0.000000 11.966728 142 1.000000 0.984777 1.403410 0.000000 9.699906 298 1.000000 1.403410 2.000000 0.000000 11.698771 588 1.000000 2.000000 2.850200 0.000000 3.848375 1466 1.000000 2.850200 4.061840 0.000000 0.921452 2808 1.000000 4.061840 5.788530 0.000000 0.454851 5802 1.000000 5.788530 8.249250 0.000000 1.428344 11926 1.000000 8.249250 11.756000 0.000000 1.067885 23478 1.000000 11.756000 16.753600 0.000000 0.553319 47994 1.000000 16.753600 23.875500 0.000000 0.086433 98042 1.000000
 boxsize (double) – A doubleprecision value for the boxsize of the simulation
in same units as the particle positions and the

Corrfunc.theory.
xi
(boxsize, nthreads, binfile, X, Y, Z, weights=None, weight_type=None, verbose=False, output_ravg=False, xbin_refine_factor=2, ybin_refine_factor=2, zbin_refine_factor=1, max_cells_per_dim=100, copy_particles=True, enable_min_sep_opt=True, c_api_timer=False, isa=u'fastest')[source]¶ Function to compute the projected correlation function in a periodic cosmological box. Pairs which are separated by less than the
r
bins (specified inbinfile
) in 3D real space.If
weights
are provided, the resulting correlation function is weighted. The weighting scheme depends onweight_type
.Note
Pairs are doublecounted. And if
rmin
is set to 0.0, then all the selfpairs (i’th particle with itself) are added to the first bin => minimum number of pairs in the first bin is the total number of particles.Parameters:  boxsize (double) – A doubleprecision value for the boxsize of the simulation
in same units as the particle positions and the
r
bins.  nthreads (integer) – Number of threads to use.
 binfile (string or an list/array of floats) –
For string input: filename specifying the
r
bins forxi
. The file should contain whitespace separated values of (rmin, rmax) for eachr
wanted. The bins need to be contiguous and sorted in increasing order (smallest bins come first).For arraylike input: A sequence of
r
values that provides the binedges. For example,np.logspace(np.log10(0.1), np.log10(10.0), 15)
is a valid input specifying 14 (logarithmic) bins between 0.1 and 10.0. This array does not need to be sorted.  X/Y/Z (arraytype, real (float/double)) –
Particle positions in the 3 axes. Must be within [0, boxsize] and specified in the same units as
rp_bins
and boxsize. All 3 arrays must be of the same floatingpoint type.Calculations will be done in the same precision as these arrays, i.e., calculations will be in floating point if XYZ are single precision arrays (C float type); or in doubleprecision if XYZ are double precision arrays (C double type).
 weights (array_like, real (float/double), optional) – A scalar, or an array of weights of shape (n_weights, n_positions) or
(n_positions,).
weight_type
specifies how these weights are used; results are returned in theweightavg
field.  verbose (boolean (default false)) – Boolean flag to control output of informational messages
 output_ravg (boolean (default false)) –
Boolean flag to output the average
r
for each bin. Code will run slower if you set this flag.Note: If you are calculating in singleprecision,
rpavg
will suffer from numerical loss of precision and can not be trusted. If you need accuraterpavg
values, then pass in double precision arrays for the particle positions.  (xyz)bin_refine_factor (integer, default is (2,2,1); typically within [13]) – Controls the refinement on the cell sizes. Can have up to a 20% impact on runtime.
 max_cells_per_dim (integer, default is 100, typical values in [50300]) – Controls the maximum number of cells per dimension. Total number of
cells can be up to (max_cells_per_dim)^3. Only increase if
rmax
is too small relative to the boxsize (and increasing helps the runtime).  copy_particles (boolean (default True)) –
Boolean flag to make a copy of the particle positions If set to False, the particles will be reordered inplace
New in version 2.3.0.
 enable_min_sep_opt (boolean (default true)) –
Boolean flag to allow optimizations based on min. separation between pairs of cells. Here to allow for comparison studies.
New in version 2.3.0.
 c_api_timer (boolean (default false)) – Boolean flag to measure actual time spent in the C libraries. Here to allow for benchmarking and scaling studies.
 isa (string (default
fastest
)) –Controls the runtime dispatch for the instruction set to use. Options are: [
fastest
,avx512f
,avx
,sse42
,fallback
]Setting isa to
fastest
will pick the fastest available instruction set on the current computer. However, if you setisa
to, say,avx
andavx
is not available on the computer, then the code will revert to usingfallback
(even thoughsse42
might be available). Unless you are benchmarking the different instruction sets, you should always leaveisa
to the default value. And if you are benchmarking, then the string supplied here gets translated into anenum
for the instruction set defined inutils/defs.h
.  weight_type (string, optional, Default: None.) – The type of weighting to apply. One of [“pair_product”, None].
Returns:  results (Numpy structured array) – A numpy structured array containing [rmin, rmax, ravg, xi, npairs,
weightavg] for each radial specified in the
binfile
. Ifoutput_ravg
is not set thenravg
will be set to 0.0 for all bins; similarly forweightavg
.xi
contains the correlation function whilenpairs
contains the number of pairs in that bin. If using weights,xi
will be weighted whilenpairs
will not be.  api_time (float, optional) – Only returned if
c_api_timer
is set.api_time
measures only the time spent within the C library and ignores all python overhead.
Example
>>> from __future__ import print_function >>> import numpy as np >>> from os.path import dirname, abspath, join as pjoin >>> import Corrfunc >>> from Corrfunc.theory.xi import xi >>> binfile = pjoin(dirname(abspath(Corrfunc.__file__)), ... "../theory/tests/", "bins") >>> N = 100000 >>> boxsize = 420.0 >>> nthreads = 4 >>> seed = 42 >>> np.random.seed(seed) >>> X = np.random.uniform(0, boxsize, N) >>> Y = np.random.uniform(0, boxsize, N) >>> Z = np.random.uniform(0, boxsize, N) >>> weights = np.ones_like(X) >>> results = xi(boxsize, nthreads, binfile, X, Y, Z, weights=weights, weight_type='pair_product', output_ravg=True) >>> for r in results: print("{0:10.6f} {1:10.6f} {2:10.6f} {3:10.6f} {4:10d} {5:10.6f}" ... .format(r['rmin'], r['rmax'], ... r['ravg'], r['xi'], r['npairs'], r['weightavg'])) ... # doctest: +NORMALIZE_WHITESPACE 0.167536 0.238755 0.226592 0.205733 4 1.000000 0.238755 0.340251 0.289277 0.176729 12 1.000000 0.340251 0.484892 0.426819 0.051829 40 1.000000 0.484892 0.691021 0.596187 0.131853 106 1.000000 0.691021 0.984777 0.850100 0.049207 336 1.000000 0.984777 1.403410 1.225112 0.028543 1052 1.000000 1.403410 2.000000 1.737153 0.011403 2994 1.000000 2.000000 2.850200 2.474588 0.005405 8614 1.000000 2.850200 4.061840 3.532018 0.014098 24448 1.000000 4.061840 5.788530 5.022241 0.010784 70996 1.000000 5.788530 8.249250 7.160648 0.001588 207392 1.000000 8.249250 11.756000 10.207213 0.000323 601002 1.000000 11.756000 16.753600 14.541171 0.000007 1740084 1.000000 16.753600 23.875500 20.728773 0.001595 5028058 1.000000
 boxsize (double) – A doubleprecision value for the boxsize of the simulation
in same units as the particle positions and the

Corrfunc.theory.
vpf
(rmax, nbins, nspheres, numpN, seed, X, Y, Z, verbose=False, periodic=True, boxsize=None, xbin_refine_factor=1, ybin_refine_factor=1, zbin_refine_factor=1, max_cells_per_dim=100, copy_particles=True, c_api_timer=False, isa=u'fastest')[source]¶ Function to compute the countsincells on 3D realspace points.
Returns a numpy structured array containing the probability of a sphere of radius up to
rmax
containing [0, numpN1] galaxies.Parameters:  rmax (double) – Maximum radius of the sphere to place on the particles
 nbins (integer) – Number of bins in the countsincells. Radius of first shell is rmax/nbins
 nspheres (integer (>= 0)) – Number of random spheres to place within the particle distribution. For a small number of spheres, the error is larger in the measured pN’s.
 numpN (integer (>= 1)) –
Governs how many unique pN’s are to returned. If
numpN
is set to 1, then only the vpf (p0) is returned. FornumpN=2
, p0 and p1 are returned.More explicitly, the columns in the results look like the following:
numpN Columns in output 1 p0 2 p0 p1 3 p0 p1 p2 4 p0 p1 p2 p3 and so on…
Note:
p0
is the vpf  seed (unsigned integer) – Random number seed for the underlying GSL random number generator. Used to draw centers of the spheres.
 X/Y/Z (arraytype, real (float/double)) –
Particle positions in the 3 axes. Must be within [0, boxsize] and specified in the same units as
rp_bins
and boxsize. All 3 arrays must be of the same floatingpoint type.Calculations will be done in the same precision as these arrays, i.e., calculations will be in floating point if XYZ are single precision arrays (C float type); or in doubleprecision if XYZ are double precision arrays (C double type).
 verbose (boolean (default false)) – Boolean flag to control output of informational messages
 periodic (boolean) – Boolean flag to indicate periodic boundary conditions.
 boxsize (double, required if
periodic=True
) –The sidelength of the cube in the cosmological simulation. Present to facilitate exact calculations for periodic wrapping. If boxsize is 0., then the wrapping is done based on the maximum difference within each dimension of the X/Y/Z arrays.
Changed in version 2.4.0: Required if
periodic=True
.  (xyz)bin_refine_factor (integer, default is (1,1,1); typically within [13]) –
Controls the refinement on the cell sizes. Can have up to a 20% impact on runtime.
Note: Since the counts in spheres calculation is symmetric in all 3 dimensions, the defaults are different from the clustering routines.
 max_cells_per_dim (integer, default is 100, typical values in [50300]) – Controls the maximum number of cells per dimension. Total number of
cells can be up to (max_cells_per_dim)^3. Only increase if
rmax
is too small relative to the boxsize (and increasing helps the runtime).  copy_particles (boolean (default True)) –
Boolean flag to make a copy of the particle positions If set to False, the particles will be reordered inplace
New in version 2.3.0.
 c_api_timer (boolean (default false)) – Boolean flag to measure actual time spent in the C libraries. Here to allow for benchmarking and scaling studies.
 isa (string (default
fastest
)) –Controls the runtime dispatch for the instruction set to use. Options are: [
fastest
,avx512f
,avx
,sse42
,fallback
]Setting isa to
fastest
will pick the fastest available instruction set on the current computer. However, if you setisa
to, say,avx
andavx
is not available on the computer, then the code will revert to usingfallback
(even thoughsse42
might be available). Unless you are benchmarking the different instruction sets, you should always leaveisa
to the default value. And if you are benchmarking, then the string supplied here gets translated into anenum
for the instruction set defined inutils/defs.h
.
Returns: results – A numpy structured array containing [rmax, pN[numpN]] with
nbins
elements. Each row contains the maximum radius of the sphere and thenumpN
elements in thepN
array. Each element of this array contains the probability that a sphere of radiusrmax
contains exactlyN
galaxies. For example, pN[0] (p0, the void probibility function) is the probability that a sphere of radiusrmax
contains zero galaxies.if
c_api_timer
is set, then the return value is a tuple containing (results, api_time).api_time
measures only the time spent within the C library and ignores all python overhead.Return type: Numpy structured array
Example
>>> from __future__ import print_function >>> import numpy as np >>> from Corrfunc.theory.vpf import vpf >>> rmax = 10.0 >>> nbins = 10 >>> nspheres = 10000 >>> numpN = 5 >>> seed = 1 >>> N = 100000 >>> boxsize = 420.0 >>> seed = 42 >>> np.random.seed(seed) >>> X = np.random.uniform(0, boxsize, N) >>> Y = np.random.uniform(0, boxsize, N) >>> Z = np.random.uniform(0, boxsize, N) >>> results = vpf(rmax, nbins, nspheres, numpN, seed, X, Y, Z, ... boxsize=boxsize, periodic=True) >>> for r in results: ... print("{0:10.1f} ".format(r[0]), end="") ... # doctest: +NORMALIZE_WHITESPACE ... for pn in r[1]: ... print("{0:10.3f} ".format(pn), end="") ... # doctest: +NORMALIZE_WHITESPACE ... print("") # doctest: +NORMALIZE_WHITESPACE 1.0 0.995 0.005 0.000 0.000 0.000 2.0 0.955 0.044 0.001 0.000 0.000 3.0 0.858 0.129 0.012 0.001 0.000 4.0 0.696 0.252 0.047 0.005 0.001 5.0 0.493 0.347 0.127 0.028 0.005 6.0 0.295 0.363 0.219 0.091 0.026 7.0 0.141 0.285 0.265 0.178 0.085 8.0 0.056 0.159 0.227 0.229 0.161 9.0 0.019 0.066 0.135 0.191 0.193 10.0 0.003 0.019 0.054 0.105 0.150

Corrfunc.theory.
DDsmu
(autocorr, nthreads, binfile, mu_max, nmu_bins, X1, Y1, Z1, weights1=None, periodic=True, boxsize=None, X2=None, Y2=None, Z2=None, weights2=None, verbose=False, output_savg=False, fast_divide_and_NR_steps=0, xbin_refine_factor=2, ybin_refine_factor=2, zbin_refine_factor=1, max_cells_per_dim=100, copy_particles=True, enable_min_sep_opt=True, c_api_timer=False, isa=u'fastest', weight_type=None)[source]¶ Calculate the 2D paircounts corresponding to the redshiftspace correlation function, \(\xi(s, \mu)\) Pairs which are separated by less than the
s
bins (specified inbinfile
) in 3D, and less thans*mu_max
in the Zdimension are counted.If
weights
are provided, the mean pair weight is stored in the"weightavg"
field of the results array. The raw pair counts in the"npairs"
field are not weighted. The weighting scheme depends onweight_type
.Note
This module only returns pair counts and not the actual correlation function \(\xi(s, \mu)\). See the utilities
Corrfunc.utils.convert_3d_counts_to_cf
for computing \(\xi(s, \mu)\) from the pair counts.New in version 2.1.0.
Parameters:  autocorr (boolean, required) – Boolean flag for auto/crosscorrelation. If autocorr is set to 1, then the second set of particle positions are not required.
 nthreads (integer) – The number of OpenMP threads to use. Has no effect if OpenMP was not enabled during library compilation.
 binfile (string or an list/array of floats) –
For string input: filename specifying the
s
bins forDDsmu_mocks
. The file should contain whitespace separated values of (smin, smax) specifying eachs
bin wanted. The bins need to be contiguous and sorted in increasing order (smallest bins come first).For arraylike input: A sequence of
s
values that provides the binedges. For example,np.logspace(np.log10(0.1), np.log10(10.0), 15)
is a valid input specifying 14 (logarithmic) bins between 0.1 and 10.0. This array does not need to be sorted.  mu_max (double. Must be in range (0.0, 1.0]) –
A doubleprecision value for the maximum cosine of the angular separation from the line of sight (LOS). Here, LOS is taken to be along the Z direction.
Note: Only pairs with \(0 <= \cos(\theta_{LOS}) < \mu_{max}\) are counted (no equality).
 nmu_bins (int) – The number of linear
mu
bins, with the bins ranging from from (0, \(\mu_{max}\))  X1/Y1/Z1 (arraylike, real (float/double)) – The array of X/Y/Z positions for the first set of points. Calculations are done in the precision of the supplied arrays.
 weights1 (array_like, real (float/double), optional) – A scalar, or an array of weights of shape (n_weights, n_positions) or
(n_positions,).
weight_type
specifies how these weights are used; results are returned in theweightavg
field. If only one of weights1 and weights2 is specified, the other will be set to uniform weights.  periodic (boolean) – Boolean flag to indicate periodic boundary conditions.
 boxsize (double, required if
periodic=True
) –The sidelength of the cube in the cosmological simulation. Present to facilitate exact calculations for periodic wrapping. If boxsize is 0., then the wrapping is done based on the maximum difference within each dimension of the X/Y/Z arrays.
Changed in version 2.4.0: Required if
periodic=True
.  X2/Y2/Z2 (arraylike, real (float/double)) – Array of XYZ positions for the second set of points. Must be the same
precision as the X1/Y1/Z1 arrays. Only required when
autocorr==0
.  weights2 (arraylike, real (float/double), optional) – Same as weights1, but for the second set of positions
 verbose (boolean (default false)) – Boolean flag to control output of informational messages
 output_savg (boolean (default false)) – Boolean flag to output the average
s
for each bin. Code will run slower if you set this flag. Also, note, if you are calculating in singleprecision,s
will suffer from numerical loss of precision and can not be trusted. If you need accurates
values, then pass in double precision arrays for the particle positions.  fast_divide_and_NR_steps (integer (default 0)) – Replaces the division in
AVX
implementation with an approximate reciprocal, followed byfast_divide_and_NR_steps
of NewtonRaphson. Can improve runtime by ~1520% on older computers. Value of 0 uses the standard division operation.  (xyz)bin_refine_factor (integer (default (2,2,1) typical values in [13])) – Controls the refinement on the cell sizes. Can have up to a 20% impact on runtime.
 max_cells_per_dim (integer (default 100, typical values in [50300])) – Controls the maximum number of cells per dimension. Total number of
cells can be up to (max_cells_per_dim)^3. Only increase if
rmax
is too small relative to the boxsize (and increasing helps the runtime).  copy_particles (boolean (default True)) –
Boolean flag to make a copy of the particle positions If set to False, the particles will be reordered inplace
New in version 2.3.0.
 enable_min_sep_opt (boolean (default true)) –
Boolean flag to allow optimizations based on min. separation between pairs of cells. Here to allow for comparison studies.
New in version 2.3.0.
 c_api_timer (boolean (default false)) – Boolean flag to measure actual time spent in the C libraries. Here to allow for benchmarking and scaling studies.
 isa (string (default
fastest
)) –Controls the runtime dispatch for the instruction set to use. Options are: [
fastest
,avx512f
,avx
,sse42
,fallback
]Setting isa to
fastest
will pick the fastest available instruction set on the current computer. However, if you setisa
to, say,avx
andavx
is not available on the computer, then the code will revert to usingfallback
(even thoughsse42
might be available). Unless you are benchmarking the different instruction sets, you should always leaveisa
to the default value. And if you are benchmarking, then the string supplied here gets translated into anenum
for the instruction set defined inutils/defs.h
.  weight_type (str, optional) – The type of pair weighting to apply. Options: “pair_product”, None; Default: None.
Returns:  results (A python list) – A python list containing
nmu_bins
of [smin, smax, savg, mu_max, npairs, weightavg] for each spatial bin specified in thebinfile
. There will be a total ofnmu_bins
ranging from [0,mu_max
) per spatial bin. Ifoutput_savg
is not set, thensavg
will be set to 0.0 for all bins; similarly forweight_avg
.npairs
contains the number of pairs in that bin.  api_time (float, optional) – Only returned if
c_api_timer
is set.api_time
measures only the time spent within the C library and ignores all python overhead.
Example
>>> from __future__ import print_function >>> import numpy as np >>> from os.path import dirname, abspath, join as pjoin >>> import Corrfunc >>> from Corrfunc.theory.DDsmu import DDsmu >>> binfile = pjoin(dirname(abspath(Corrfunc.__file__)), ... "../theory/tests/", "bins") >>> N = 10000 >>> boxsize = 420.0 >>> nthreads = 4 >>> autocorr = 1 >>> mu_max = 1.0 >>> seed = 42 >>> nmu_bins = 10 >>> np.random.seed(seed) >>> X = np.random.uniform(0, boxsize, N) >>> Y = np.random.uniform(0, boxsize, N) >>> Z = np.random.uniform(0, boxsize, N) >>> weights = np.ones_like(X) >>> results = DDsmu(autocorr, nthreads, binfile, mu_max, nmu_bins, ... X, Y, Z, weights1=weights, weight_type='pair_product', ... output_savg=True, boxsize=boxsize, periodic=True) >>> for r in results[100:]: print("{0:10.6f} {1:10.6f} {2:10.6f} {3:10.1f}" ... " {4:10d} {5:10.6f}".format(r['smin'], r['smax'], ... r['savg'], r['mu_max'], r['npairs'], r['weightavg'])) ... # doctest: +NORMALIZE_WHITESPACE 5.788530 8.249250 7.149762 0.1 230 1.000000 5.788530 8.249250 7.158884 0.2 236 1.000000 5.788530 8.249250 7.153403 0.3 210 1.000000 5.788530 8.249250 7.091504 0.4 254 1.000000 5.788530 8.249250 7.216417 0.5 182 1.000000 5.788530 8.249250 7.120980 0.6 222 1.000000 5.788530 8.249250 7.086361 0.7 238 1.000000 5.788530 8.249250 7.199075 0.8 170 1.000000 5.788530 8.249250 7.128768 0.9 208 1.000000 5.788530 8.249250 6.973382 1.0 206 1.000000 8.249250 11.756000 10.147488 0.1 590 1.000000 8.249250 11.756000 10.216417 0.2 634 1.000000 8.249250 11.756000 10.195979 0.3 532 1.000000 8.249250 11.756000 10.248775 0.4 544 1.000000 8.249250 11.756000 10.091439 0.5 530 1.000000 8.249250 11.756000 10.282170 0.6 642 1.000000 8.249250 11.756000 10.245368 0.7 666 1.000000 8.249250 11.756000 10.139694 0.8 680 1.000000 8.249250 11.756000 10.190839 0.9 566 1.000000 8.249250 11.756000 10.241730 1.0 606 1.000000 11.756000 16.753600 14.553911 0.1 1736 1.000000 11.756000 16.753600 14.576144 0.2 1800 1.000000 11.756000 16.753600 14.595632 0.3 1798 1.000000 11.756000 16.753600 14.477071 0.4 1820 1.000000 11.756000 16.753600 14.479887 0.5 1740 1.000000 11.756000 16.753600 14.492835 0.6 1748 1.000000 11.756000 16.753600 14.546800 0.7 1720 1.000000 11.756000 16.753600 14.467235 0.8 1750 1.000000 11.756000 16.753600 14.541123 0.9 1798 1.000000 11.756000 16.753600 14.445188 1.0 1826 1.000000 16.753600 23.875500 20.722545 0.1 5088 1.000000 16.753600 23.875500 20.730212 0.2 5000 1.000000 16.753600 23.875500 20.717056 0.3 5166 1.000000 16.753600 23.875500 20.727119 0.4 5014 1.000000 16.753600 23.875500 20.654365 0.5 5094 1.000000 16.753600 23.875500 20.695877 0.6 5082 1.000000 16.753600 23.875500 20.729774 0.7 4900 1.000000 16.753600 23.875500 20.718821 0.8 4874 1.000000 16.753600 23.875500 20.750061 0.9 4946 1.000000 16.753600 23.875500 20.723266 1.0 5066 1.000000