amep.order.voronoi_density

amep.order.voronoi_density(coords: ndarray | None, box_boundary: ndarray | None, radius: float | ndarray | None = None, mass: float | ndarray | None = None, width: float | None = None, pbc: bool = True, vor: Voronoi | None = None, ids: ndarray | None = None, enforce_nd: int | None = None, mode: str = 'number', verbose: bool = False) → ndarray

Calculates the local mass or number density or the local packing fraction by using Voronoi tessellation.

If the radius of the particles is specified, the local packing fraction of each Voronoi cell is returned (assuming the particles to be spherical). If the mass is specified, the local density is returned. If neither radius nor mass is specified, the local number density is returned.

Examples of the Voronoi tessellation used, can be found in [1] and [2]

References

[1]

B. Steffen, A. Seyfried, “Methods for measuring pedestrian density, flow, speed and direction with minimal scatter”, Physica A: Statistical Mechanics and its Applications, Volume 389, Pages 1902-1910, 2010.

[2]

Chaoming Song, Ping Wang, Yuliang Jin, Hernán A. Makse, “Jamming I: A volume function for jammed matter”, Physica A: Statistical Mechanics and its Applications, Volume 389, Issue 21, Pages 4497-4509, 2010.

Parameters:

• coords (np.ndarray) – Coordinates of the particles for the voronoi tessellation. If None, the user has to specify the Voronoi tessellation with the keyword vor (and ids for pbc=True).

• box_boundary (np.ndarray of shape (3,2) or None) – Boundary of the simulation box in the form of np.array([[xmin, xmax], [ymin, ymax], [zmin, zmax]]). If None, the user has to specify the Voronoi tessellation with the keyword vor (and ids for pbc=True).

• radius (float or np.ndarray or None) – Radius of the particles for calculating the local packing fraction. Default is None.

• mass (float or np.ndarray or None) – Mass of the particles for calculating the local mass density. Default is None.

• width (float, optional) – Relative width (to the box) of the periodic images and mirrors used. For very low densities, this value might have to be set to a larger value than the default. For higher densities, this value can easily be set to 0.3 or 0.1 or even smaller. Please check the Voronoi plot to ensure the correct calculation. Range: [0,1]. Default is 0.5.

• vor (scipy.spatialcor.Voronoi or None) – If a Voronoi object vor (and indices ids for periodic boundary conditions pbc=True) are supplied, the Voronoi tessellation is not re-calculated. Default is None.

• ids (np.ndarray or None) – IDs of the points inside the box when using periodic boundaries. If the Voronoi tessellation and the ids are supplied, the Voronoi tessellation is not re-calculated. Default is None.

• enforce_nd (int, None, optional) – enforces the number of dimensions. 2 for 2d, 3 for 3d. If None is supplied, a best guess is used by checking if all particles have the same dimension in the last coordinate. See utils.dimension()

• verbose (bool, optional) – If True, runtime information is printed. The default is False.

Returns:

Local densities for each Voronoi cell.

Return type:

np.ndarray

Examples

>>> import amep
>>> traj = amep.load.traj("../examples/data/lammps.h5amep")
>>> frame = traj[-1]
>>> ld = amep.order.voronoi_density(
...     frame.coords(), frame.box, radius=frame.radius(),
...     pbc=True, mode="packing"
... )
>>> fig, axs = amep.plot.new(figsize=(3.6,3))
>>> mp = amep.plot.particles(
...     axs, frame.coords(), frame.box, frame.radius(),
...     values=ld
... )
>>> cax = amep.plot.add_colorbar(
...     fig, axs, mp, label="local packing fraction"
... )
>>> axs.set_xlabel(r"$x$")
>>> axs.set_ylabel(r"$y$")
>>> fig.savefig("./figures/order/order-voronoi_density.png")