A useful python package to measure the 3/4 PCFs of discrete periodic data in NlogN time. This is done using Fast Fourier Transforms.

Installation:

The package is available on PyPi via the command pip install sarabande. To check if the code is working properly after pip installation, run

import sarabande

sarabande.check_install()

which will display a message stating if the package was properly installed.

Basic Usage:

import sarabande

NPCF_obj = sarabande.measure(**kwargs)
sarabande.calc_zeta(NPCF_obj)
zeta = NPCF_obj.zeta

Where **kwargs can be any of the arguments to the measure constructor function. The possible arguments are:

Args:

• nPCF ([int]): Must be either 3 or 4. Determines how many points we use in our nPCF.

• projected ([bool]): Flag to determine whether the user wants a projected 3/4 PCF or the Full. Defaults to False.

  • if projected:
    • m_max ([int]): If user chooses projected, we set an m_max (similar to the ell_max in 3D)
  • if not projected:
    • ell_max ([int]): If user choosees not projected (full nPCF) then ell_max is the highest order for calculation.

• density_field_data ([ndarray]): A square ndarray of data that is periodic. Must be 2D for projected and 3D for full.

• save_dir ([string]): A string to tell the algorithm where to save and store files. All temporary files will be stored here.

• save_name ([string]): A string to tell the algorithm what to name the files.

• nbins ([int]): Number of bins to be used in nPCF calculation.

• bin_spacing ([string]): A string to determine the spacing of bins. Options are 'LIN', 'INV', or 'LOG'

• bin_min ([int]): The lower bound of the inner most bin. Default is 1. Optional.

• physical_boxsize ([float]): An optional parameter if using a physical scale. The length of one side of the data.

• rmin ([float]): minimum calculation distance (determins bin_min)

• rmax ([float]): maximum calculation distance (determins bin_max)

• normalize ([bool]): A boolean flag to normalize the 3/4 PCFs. Defaults to True. Can't use normalize without giving a physical_boxsize, rmin, and rmax first.

• particles_on_grid ([bool]): An optional boolean flag to modify the normalization scheme slightly. This is recommended if you are working with particles on the grid mesh where a given cell corresponds to a particle.

We note that the calc_zeta method has an optional boolean argument verbose_flag which can be turned on and off depending on if the user wants to see the steps of the code printed. We also add an optional boolean argument parallelized which can be turned on and off if the user wishes to compute the Full 4PCF serially. This is added due to the instability of concurrent.futures and parallel processing in python across different machines.

We also provide an implementation of the connected 4PCF, this will be further documented in a future paper.

For an example, please visit the demo notebook in the analysis notebooks folder: notebooks/Application_Example.ipynb

Workflow:

The map of SARABANDE is as follows:

For more information about each algorithm, please read Sunseri et al. 2022

Coverage

We provide a sunburst plot of the code coverage for sarabande below provided by codecov.io. The inner-most circle is the entire project, moving away from the center are folders then, finally, a single file. The size and color of each slice is representing the number of statements and the coverage, respectively.