API Reference

The full list of nbodykit modules is available here. We summarize the most important aspects of the API below.

The nbodykit lab

To make things easier for users, we import all of the classes and modules needed to do cool science into a single module:

nbodykit.lab

The nbodykit lab, containing all of the necessary ingredients to use nbodykit.

Cosmology (nbodykit.cosmology)

The main cosmology object relies on the functionality of the classylss package, which provides a binding of the CLASS CMB Boltzmann code. The syntax largely follows that used by CLASS. Below, we list the main cosmology class, as well as its attributes and methods:

Cosmology([h, T0_cmb, Omega0_b, Omega0_cdm, …])

A cosmology calculator based on the CLASS binding in classylss.

Attributes

Methods

There are several transfer functions available to the user:

CLASS(cosmo, redshift)

The linear matter transfer function using the CLASS Boltzmann code.

EisensteinHu(cosmo, redshift)

The linear matter transfer function using the Eisenstein & Hu (1998) fitting formula with BAO wiggles.

NoWiggleEisensteinHu(cosmo, redshift)

Linear power spectrum using the Eisenstein & Hu (1998) fitting formula without BAO wiggles.

There are several power spectrum classes

LinearPower(cosmo, redshift[, transfer])

An object to compute the linear power spectrum and related quantities, using a transfer function from the CLASS code or the analytic Eisenstein & Hu approximation.

HalofitPower(cosmo, redshift)

Nonlinear power spectrum computed using HaloFit via CLASS.

ZeldovichPower(cosmo, redshift[, transfer, nmax])

The matter power spectrum in the Zel’dovich approximation.

And a correlation function class and functions for transforming between power spectra and correlation functions

CorrelationFunction(power)

Evaluate the correlation function by Fourier transforming a power spectrum object, with automatic re-scaling with redshift and sigma8.

xi_to_pk(r, xi[, ell, extrap])

Return a callable function returning the power spectrum multipole of degree \(\ell\), as computed from the Fourier transform of the input \(r\) and \(\xi_\ell(r)\) arrays.

pk_to_xi(k, Pk[, ell, extrap])

Return a callable function returning the correlation function multipole of degree \(\ell\), as computed from the Fourier transform of the input \(k\) and \(P_\ell(k)\) arrays.

We also have a class for computing LPT background calculations:

PerturbationGrowth(*args, **kwargs)

The built-in cosmologies are:

Name

Source

\(H_0\)

\(\Omega_{m,0}\)

Flat

WMAP5

Komatsu et al. 2009

70.2

0.277

Yes

WMAP7

Komatsu et al. 2011

70.4

0.272

Yes

WMAP9

Hinshaw et al. 2013

69.3

0.287

Yes

Planck13

Planck Collab 2013, Paper XVI

67.8

0.307

Yes

Planck15

Planck Collab 2015, Paper XIII

67.7

0.307

Yes

Transforming Catalog Data (nbodykit.transform)

ConcatenateSources(*sources, **kwargs)

Concatenate CatalogSource objects together, optionally including only certain columns in the returned source.

StackColumns(*cols)

Stack the input dask arrays vertically, column by column.

ConstantArray(value, size[, chunks])

Return a dask array of the specified size holding a single value.

SkyToUnitSphere(ra, dec[, degrees, frame])

Convert sky coordinates (ra, dec) to Cartesian coordinates on the unit sphere.

SkyToCartesian(ra, dec, redshift, cosmo[, …])

Convert sky coordinates (ra, dec, redshift) to a Cartesian Position column.

HaloConcentration(mass, cosmo, redshift[, mdef])

Return halo concentration from halo mass, based on the analytic fitting formulas presented in Dutton and Maccio 2014.

HaloRadius(mass, cosmo, redshift[, mdef])

Return proper halo radius from halo mass, based on the specified mass definition.

Data Sources

Discrete Objects

Base class:

CatalogSource(comm)

An abstract base class representing a catalog of discrete particles.

And subclasses:

CSVCatalog(path, *args, **kwargs)

A CatalogSource that uses CSVFile to read data from disk.

BinaryCatalog(path, *args, **kwargs)

A CatalogSource that uses BinaryFile to read data from disk.

BigFileCatalog(path, *args, **kwargs)

A CatalogSource that uses BigFile to read data from disk.

TPMBinaryCatalog(path, *args, **kwargs)

A CatalogSource that uses TPMBinaryFile to read data from disk.

HDFCatalog(path, *args, **kwargs)

A CatalogSource that uses HDFFile to read data from disk.

FITSCatalog(path, *args, **kwargs)

A CatalogSource that uses FITSFile to read data from disk.

Gadget1Catalog(path, *args, **kwargs)

A CatalogSource that uses Gadget1File to read data from disk.

ArrayCatalog(data[, comm])

A CatalogSource initialized from an in-memory dict, structured numpy.ndarray, or astropy.table.Table.

HaloCatalog(source, cosmo, redshift[, mdef, …])

A CatalogSource of objects that represent halos, which can be populated using analytic models from halotools.

LogNormalCatalog(Plin, nbar, BoxSize, Nmesh)

A CatalogSource containing biased particles that have been Poisson-sampled from a log-normal density field.

UniformCatalog(nbar, BoxSize[, seed, dtype, …])

A CatalogSource that has uniformly-distributed Position and Velocity columns.

RandomCatalog(csize[, seed, comm])

A CatalogSource that can have columns added via a collective random number generator.

FKPCatalog(data, randoms[, BoxSize, BoxPad, …])

An interface for simultaneous modeling of a data CatalogSource and a randoms CatalogSource, in the spirit of Feldman, Kaiser, and Peacock, 1994.

MultipleSpeciesCatalog(names, *species, **kwargs)

A CatalogSource interface for handling multiples species of particles.

DemoHaloCatalog(simname, halo_finder, redshift)

Create a demo catalog of halos using one of the built-in halotools catalogs.

Interpolating Objects to a Mesh

For simple object catalogs:

CatalogMesh(source, Nmesh, BoxSize, Position)

A mesh generated by resampling a Catalog with the given parameters.

And Multiple Species

MultipleSpeciesCatalogMesh(source, Nmesh, …)

A subclass of CatalogMesh designed to paint the density field from a sum of multiple types of particles.

And Survey Catalogs with a window / mask:

FKPCatalogMesh(source, BoxSize, BoxCenter, …)

A subclass of MultipleSpeciesCatalogMesh designed to paint a FKPCatalog to a mesh.

Data Directly on a Mesh

Base class:

MeshSource(comm, Nmesh, BoxSize, dtype)

Base class for a source in the form of data on an input grid.

And subclasses:

BigFileMesh(path, dataset[, comm])

A MeshSource object that reads a mesh from disk using bigfile.

LinearMesh(Plin, BoxSize, Nmesh[, seed, …])

A MeshSource object that generates a RealField density mesh from a linear power spectrum function \(P(k)\).

FieldMesh(field)

A MeshSource initialized from an in-memory Field object, either a pmesh.pm.RealField or pmesh.pm.ComplexField.

ArrayMesh(array, BoxSize[, comm, root])

A MeshSource initalized from an in-memory numpy array.

Algorithms (nbodykit.algorithms)

Clustering Statistics

FFTPower(first, mode[, Nmesh, BoxSize, …])

Algorithm to compute the 1d or 2d power spectrum and/or multipoles in a periodic box, using a Fast Fourier Transform (FFT).

ProjectedFFTPower(first[, Nmesh, BoxSize, …])

The power spectrum of a field in a periodic box, projected over certain axes.

ConvolvedFFTPower(first, poles[, second, …])

Algorithm to compute power spectrum multipoles using FFTs for a data survey with non-trivial geometry.

FFTCorr(first, mode[, Nmesh, BoxSize, …])

Algorithm to compute the 1d or 2d correlation and/or multipoles in a periodic box, using a Fast Fourier Transform (FFT).

SimulationBoxPairCount(mode, first, edges[, …])

Count (weighted) pairs of objects in a simulation box as a function of \(r\), \((r,\mu)\), \((r_p, \pi)\), or \(\theta\) using the Corrfunc package.

SurveyDataPairCount(mode, first, edges[, …])

Count (weighted) pairs of objects from a survey data catalog as a function of \(r\), \((r,\mu)\), \((r_p, \pi)\), or \(\theta\) using the Corrfunc package.

SimulationBox2PCF(mode, data1, edges[, Nmu, …])

Compute the two-point correlation function for data in a simulation box as a function of \(r\), \((r,\mu)\), \((r_p, \pi)\), or \(\theta\) using pair counting.

SurveyData2PCF(mode, data1, randoms1, edges)

Compute the two-point correlation function for observational survey data as a function of \(r\), \((r,\mu)\), \((r_p, \pi)\), or \(\theta\) using pair counting.

SimulationBox3PCF(source, poles, edges[, …])

Compute the multipoles of the isotropic, three-point correlation function in configuration space for data in a simulation box.

SurveyData3PCF(source, poles, edges, cosmo)

Compute the multipoles of the isotropic, three-point correlation function in configuration space for observational survey data.

Grouping Methods

FOF(source, linking_length, nmin[, …])

A friends-of-friends halo finder that computes the label for each particle, denoting which halo it belongs to.

CylindricalGroups(source, rankby, rperp, rpar)

Compute groups of objects using a cylindrical grouping method.

FiberCollisions(ra, dec[, collision_radius, …])

Run an angular FOF algorithm to determine fiber collision groups from an input catalog, and then assign fibers such that the maximum amount of object receive a fiber.

Miscellaneous

KDDensity(source[, margin])

Estimate a proxy density based on the distance to the nearest neighbor.

RedshiftHistogram(source, fsky, cosmo[, …])

Compute the mean number density as a function of redshift \(n(z)\) from an input CatalogSource of particles.

Managing Multiple Tasks (TaskManager)

TaskManager(cpus_per_task[, comm, debug, …])

An MPI task manager that distributes tasks over a set of MPI processes, using a specified number of independent workers to compute each task.

TaskManager.iterate(tasks)

A generator that iterates through a series of tasks in parallel.

TaskManager.map(function, tasks)

Like the built-in map() function, apply a function to all of the values in a list and return the list of results.

Analyzing Results (BinnedStatistic)

BinnedStatistic(dims, edges, data[, …])

Lightweight class to hold statistics binned at fixed coordinates.

BinnedStatistic.from_json(filename[, key, …])

Initialize a BinnedStatistic from a JSON file.

BinnedStatistic.to_json(filename)

Write a BinnedStatistic from a JSON file.

BinnedStatistic.copy([cls])

Returns a copy of the BinnedStatistic, optionally change the type to cls.

BinnedStatistic.rename_variable(old_name, …)

Rename a variable in data from old_name to new_name.

BinnedStatistic.average(dim, **kwargs)

Compute the average of each variable over the specified dimension.

BinnedStatistic.reindex(dim, spacing[, …])

Reindex the dimension dim by averaging over multiple coordinate bins, optionally weighting by weights.

BinnedStatistic.sel([method])

Return a new BinnedStatistic indexed by coordinate values along the specified dimension(s).

BinnedStatistic.squeeze([dim])

Squeeze the BinnedStatistic along the specified dimension, which removes that dimension from the BinnedStatistic.

The IO Library (nbodykit.io)

Base class:

FileType(dtype, size)

An abstract base class representing a file object.

Subclasses available from the nbodykit.io module:

BigFile(path[, exclude, header, dataset])

A file object to handle the reading of columns of data from a bigfile file.

BinaryFile(path, dtype[, offsets, …])

A file object to handle the reading of columns of data from a binary file.

CSVFile(path, names[, blocksize, dtype, …])

A file object to handle the reading of columns of data from a CSV file.

FITSFile(path[, ext])

A file object to handle the reading of FITS data using the fitsio package.

HDFFile(path[, dataset, exclude, header, root])

A file object to handle the reading of columns of data from a h5py HDF5 file.

FileStack(filetype, path, *args, **kwargs)

A file object that offers a continuous view of a stack of subclasses of FileType instances.

TPMBinaryFile(path[, precision])

Read snapshot binary files from Martin White’s TPM simulations.

Gadget1File(path[, columndefs, hdtype, ptype])

Read snapshot binary files from Volkers Gadget 1/2/3 simulations.

Internal Nuts and Bolts

MPI Utilities

nbodykit.CurrentMPIComm()

A class to faciliate getting and setting the current MPI communicator.

nbodykit.CurrentMPIComm.enable(func)

Decorator to attach the current MPI communicator to the input keyword arguments of func, via the comm keyword.

nbodykit.CurrentMPIComm.get()

Get the default current MPI communicator.

nbodykit.CurrentMPIComm.set(comm)

Set the current MPI communicator to the input value.

nbodykit.utils.GatherArray(data, comm[, root])

Gather the input data array from all ranks to the specified root.

nbodykit.utils.ScatterArray(data, comm[, …])

Scatter the input data array across all ranks, assuming data is initially only on root (and None on other ranks).

General Utilities

nbodykit.setup_logging([log_level])

Turn on logging, with the specified level.

nbodykit.set_options(**kwargs)

Set global configuration options.

nbodykit.utils.JSONEncoder(*[, skipkeys, …])

A subclass of json.JSONEncoder that can also handle numpy arrays, complex values, and astropy.units.Quantity objects.

nbodykit.utils.JSONDecoder(*args, **kwargs)

A subclass of json.JSONDecoder that can also handle numpy arrays, complex values, and astropy.units.Quantity objects.

Generating Mock Data

nbodykit.mockmaker.gaussian_complex_fields(pm, …)

Make a Gaussian realization of a overdensity field, \(\delta(x)\).

nbodykit.mockmaker.gaussian_real_fields(pm, …)

Make a Gaussian realization of a overdensity field in real-space \(\delta(x)\).

nbodykit.mockmaker.poisson_sample_to_points(…)

Poisson sample the linear delta and displacement fields to points.