DEMutilities.postprocessing.analysistools.spatial. rdf

The rdf module implements a time-efficient algorithm to compute radial distribution functions based on a given set of positions x. This implementation uses a multigrid contact detector, to speed up the computation of pair-wise distance with an upper limit. As such, the algorithm will be reasonably fast as long as the rdf histogram has a cut-off in r which is much smaller than the system size (usually true).

This module serves to replace the partially deprecated module of RadialDistributionFunction. For now, only un-weighted distributions are implemented, but adding weights is a trivial addition.

Example usage, making use of mpacts post-processing utilities:

import DEMutilities.postprocessing.analysistools.spatial.rdf as rdf
import DEMutilities.postprocessing.operators.operators as op
import as ds
import DEMutilities.numeric_functions as nf
import numpy as np

max_radius = 1.
r_max = 10
number_density = 10#Number of spheres per volume in the simulation.
edges = np.linspace(0, max_radius, 20)
keep_distance = max_radius#Sane default to choose!

rdff = rdf.RadialDistributionFunction( verbose=True )

a = op.AnalysisContainer()
dr = ds.DataReader( "simulation", folder='./')
x = op.GetData( a, 'spheres/x')
#Select only center spheres:
r = op.Function(a, nf.mag, x)
x_center = op.Filter( a, x, r < r_max)
x_outer = op.Filter(a, x, r >= r_max)

rdf_func = op.Function(a, rdff, x_center, x_outer, edges, keep_distance, number_density, 3 )

a.loop( dr )

print( rdf_func() )

In order to be able to use this module import it like this:

import DEMutilities.postprocessing.analysistools.spatial.rdf
#or assign it to a shorter name
import DEMutilities.postprocessing.analysistools.spatial.rdf as rdf


class DEMutilities.postprocessing.analysistools.spatial.rdf.RadialDistributionFunction(verbose=False, rmin=0)

Bases: object

Class for computing radial distribution functions, making use of mpacts’ grid-based contact detection.

The central idea is that two arrays of points are to be provided: a set of ‘internal’ points, denoted ‘x’ and a set of ‘external’ points (denoted ‘x_ext’). The goal is then to compute the rdf wrt the internal points ‘x’, but taking into account the external points, as well as the internal points for computing pair-wise interactions. With this concept, one can easily make a ‘sub-selection’ of your positions towards which you want the rdf to be computed, and then just include the other points in the x_ext array. This is useful, for example when only computing rdf for particles sufficiently far away from a boundary (yet, pair-wise) interactions should be computed still wrt particles in the boundary. One can also set self_interactions to False. In that case, the interactions will only be computed between x and x_ext (but not within x). This is useful, for example to compute the partial rdf between particles of a certain distinct type or property. RadialDistributionFunction is meant to be used in combination with post-processing operators. One would instantiate an instance of this class, and then feed it to a Function operator, which calls the () operator, giving ‘function-like’ behavior. The following parameters are accepted by the () operator.

  • x: list of ‘internal’ points (see above)
  • x_ext: list of ‘external’ points (see above)
  • bin_edges: list specifying the edges of bins for which the rdf histogram will be computed.
  • keep_distance (float): maximal distance to be taken into account by the contact detector. If not given, will set it to a sane default based on the highest value in bin_edges
  • number_density (float): Number of particles per unit of volume in the domain that will be analyzed. This value is needed for proper ‘weighting’ of the rdf. For example, in 3D, one would divide each bin by (4piR^2 dr * number_density) If not given, the value is taken to be ‘1’. In this case, the resulting rdf will be in units of number density (points/unit of volume).
  • Ndim (int): Number of dimensions. This is needed for choosing the proper ‘weighting’ function to renormalize the rdf. Set at ‘-1’ for the raw histogram counts of pair-wise interactions. Default: Ndim=3
  • self_interactions (bool): If False, pair-wise interaction within x will not be computed. Useful e.g. to compute partial rdf between different particle ‘types’. Default: True.


The last value of the returned frequency count also includes all values of interaction that ‘over-shoot’ the range. Usually, it is best to omit this ‘leftover’ value in further analysis, and anticipate this by selecting bin_edges to be ‘one bin’ larger than needed.

RadialDistributionFunction(name, parent, **kwargs)

Actually add the contact models, with given keep_distance as specified.

Parameters:keep_distance (float) – maximal distance to include for the contact detection algorithm

Resets the count of the histogram and executes the contained command list


From the bin edges, compute the edge midpoints, which are used for the weighting in __call__.


Executes the contained command list, thereby computing counts. If verbose is True, this will also print some information about the RDF computation process.


calling ‘execute’ will NOT reset the count. Hence, you should probably not call ‘execute’ this directly.


Set the bin edges to a given array

Parameters:edges_array (list) – list of bin edges for the histogram
set_positions(x, x_ext)

Clear the current manager and re-set it with given ‘x’ and ‘x_ext’

  • x – list of ‘internal’ positions
  • x_ext – list of ‘external’ positions
DEMutilities.postprocessing.analysistools.spatial.rdf._compare_points(x, x_ext, dmin)