# Painting Catalogs to a Mesh¶

The MeshSource.paint() function produces the values of the field on the mesh, returning either a RealField or ComplexField. In this section, we focus on the process of interpolating a set of discrete objects in a CatalogSource on to a mesh and how users can customize this procedure.

## The Painted Field¶

The compute() function paints mass-weighted (or equivalently, number-weighted) fields to a mesh. So, when painting a CatalogSource to a mesh, the field $$F(\vx)$$ that is painted is:

$F(\vx) = \left[ 1 + \delta'(\vx) \right] V(\vx),$

where $$V(\vx)$$ represents the field value painted to the mesh and $$\delta'(\vx)$$ is the (weighted) overdensity field, given by:

$\delta'(\vx) = \frac{n(\vx)'}{\bar{n}'} - 1,$

where $$\bar{n}'$$ is the weighted mean number density of objects. Here, quantities denoted with a prime ($$'$$) indicate weighted quantities. The unweighted number density field $$n(\vx)$$ is related to its weighted counterpart via $$n'(\vx) = W(\vx) n(\vx)$$, where $$W(\vx)$$ are the weights.

Users can control the behavior of the value $$V(\vx)$$ and the weights $$W(\vx)$$ when converting a CatalogSource object to a mesh via the to_mesh() function. Specifically, the weight and value keywords allow users to indicate the name of the column in the CatalogSource to use for $$W(\vx)$$ and $$V(\vx)$$. See Additional Mesh Configuration Options for more details on these keywords.

## Operations¶

The painted field is an instance of pmesh.pm.RealField. Methods are provided for Fourier transforms (to a pmesh.pm.ComplexField object), and transfer functions on both the Real and Complex fields:

field = mesh.compute()

def tf(k, v):
return 1j * k[2] / k.normp(zeromode=1) ** 0.5 * v

The underlying numerical values of the field can be accessed via indexing. A RealField is distributed across the entire MPI communicator of the mesh object, and in general each single rank in the MPI communicator only sees a region of the field.

• numpy methods (e.g. field[…].std() that operates on the local field values only compute the results on a single rank, thus only correct when a single rank is used:

• collective methods provide the correct result that has been reduced on the entire MPI communicator. For example, to compute the standard deviation of the field in a script that runs on sevearl MPI ranks, we shall use ((field ** 2).cmean() - field.cmean() ** 2) ** 0.5 instead of field[...].std().

The positions of the grid points on which the field value resides can be obtained from

field = mesh.compute()

grid = field.pm.generate_uniform_particle_grid(shift=0)

A low resolution projected preview of the field can be obtained (the example is along x-y plain)

field = mesh.compute()

imshow(field.preview(Nmesh=64, axes=[0, 1]).T,
origin='lower',
extent=(0, field.BoxSize[0], 0, field.BoxSize[1]))

## Shot-noise¶

The shot-noise level of a weighted field is given by

$SN = L^3 \frac{\sum W^2}{(\sum W)^2}$

where L^3 is the total volume of the box, and W is the weight of individual objects. We see in the limit where W=1 everywhere, the shotnoise is simply $$1 / \bar{n}$$.

## Default Behavior¶

The default behavior is $$W(\vx) = 1$$ and $$V(\vx) = 1$$, in which case the painted field is given by:

$F^\mathrm{default}(\vx) = 1 + \delta(\vx).$

In the CatalogSource.to_mesh() function, the default values for the value and weight keywords are the Value and Weight columns, respectively. These are default columns that are in all CatalogSource objects that are set to unity by default.

## More Examples¶

The Painting Recipes section of the cookbook contains several more examples that change the default behavior to paint customized fields to the mesh.

For example, users can set $$V(\vx)$$ to a column holding a component of the velocity field, in which case the painted field $$F(\vx)$$ would represent the momentum (mass-weighted velocity) field. See the Painting the Line-of-sight Momentum Field recipe for further details.

Another common example is setting the weights $$W(\vx)$$ to a column representing mass and painting multiple species of particles to the same mesh using the MultipleSpeciesCatalog object. See the Painting Multiple Species of Particles recipe for more details.